This is an old revision of the document!
TailCoNTROL Command Protocol
Command list for the Tail Company TailCoNTROL firmware. TailCoNTROL is the unified firmware platform (version 5.x.x and higher) for the MiTail, MiTail Mini, FlutterWings, and EarGear 2, and covers the shared features that exist across all those devices.
All commands are case-sensitive. Trailing whitespace (e.g., `NULL`, `CR`, etc.) are ignored. The space between a command keyword and the parameters is mandatory.
IMPORTANT NOTICE: TailCoNTROL and the TailCoNTROL Protocol is still under development. Some commands and features described here relate to a future release and are subject to change at this time, especially EarGear 2 features.
Bluetooth Low Energy (BLE)
The hardware platform uses the “Just Works” Bluetooth Low Energy (BLE) pairing method to connect. If Conference Mode (see below) is used, “Passkey” pairing is used.
Device Advertisement
Device name is one of the following:
mitailfor MiTail,minitailfor MiTail Mini,flutterfor FlutterWings, andEG2for EarGear 2.
The BLE Device Service for the MiTail, MiTail Mini, and FlutterWings is 3af2108b-d066-42da-a7d4-55648fa0a9b6:
- RX Characteristic is
5bfd6484-ddee-4723-bfe6-b653372bbfd6, - TX Characteristic is
c6612b64-0087-4974-939e-68968ef294b0, and the - Battery Voltage is
b08fed02-0584-40ef-b006-aff7e0d24e13.
The BLE Device Service for the EarGear 2 is 927dee04-ddd4-4582-8e42-69dc9fbfae66:
- RX Characteristic is
05e026d8-b395-4416-9f8a-c00d6c3781b9, - TX Characteristic is
0b646a19-371e-4327-b169-9632d56c0e84, and the - Battery Voltage is
54fa919d-e8a8-4841-b280-c5461161304f.
TailCoNTROL will use a new Service and Characteristics UUIDs going forward, to distinguish it from previous firmwares (and to further enforce the “forklift upgrade” required).
The BLE Device Service for TailCoNTROL is 19f8ade2-d0c6-4c0a-912a-30601d9b3060:
- RX Characteristic is
5e4d86ac-ef2f-466f-a857-8776d45ffbc2and - TX Characteristic is
567a99d6-a442-4ac0-b676-4993bf95f805. - Under the standard Device Information Service (DIS,
0x180A) is- Manufacturer Name
0x2A29(The Mechanical Tail Company Limited), - Model Number
0x2A24, - Firmware Revision
0x2A26, and - Hardware Revision
0x2A27.
- Under the standard Battery Service UUID (
0x180F) is- Battery Percentage
0x2A19, - Battery Voltage is
e818bda3-88a7-43c0-8509-6e0bbb6f55d9, and the - Charging State (if hardware supported) is
5073792e-4fc0-45a0-b0a5-78b6c1756c91.
For tail-series (MiTail, MiTail Mini, and FlutterWings) v3.6 controller hardware, the battery charging characteristic is unset (charging state is not available).
TailCoNTROL Device Indicators
Blue LED
The Blue LED (D4) has five states:
- Off when powered off.
- Blink on-off when BLE is disconnected.
- Fade-off when BLE is disconnected and Autonomous Mode (either iOS Casual Mode or No-phone Mode, see below) is active.
- Constant on when BLE is connected.
- Fade-on when BLE is connected and Autonomous Mode is active.
- Blink fast three times when the button is held for more than 3 seconds (but less than 13), indicates the device is ready to power off when the button is released.
- Blink fast continuously when the button is held for more than 13 seconds, indicates the device is ready to factory reset when the button is released.
Red LED
For v3.2 through v3.5 tail-series controller hardware, the Red LED (D5) has four states:
- Off during normal operation.
- Breathing while charging.
- Constant on when charging is complete.
- Short flash on, followed by pause to indicate a low (⇐ 10%) battery condition.
For v3.6 tail-series controller hardware, the Red LED (D5) has two states:
- Off when charging is disconnected and when charging complete.
- Constant on when charging.
For the EarGear 2, the Red LED has two states:
- Off when charging is disconnected.
- Constant on when charging.
Note: Unlike the DIGITAiL, MiTail, MiTail Mini, and FlutterWings devices can be used while charging.
Green LED
The Green LED (D8) is only present on v3.2 through v3.5 tail-series controller hardware, and is not visible from outside the device case. The LED is a visual indicator for the STAT pin of the battery charger:
- Constant on is charge in progress.
- Off is charge completed.
- Blink on-off indicates a fault condition.
The EarGear 2 does not have a Green LED.
Automatic Actions
TailCoNTROL will automatically shut down the device if there is no BLE connection for 5 minutes. This behavior is suspended if a PD-capable adapter is attached (to allow for charging and/or operating from a external battery) OR if the firmware is compiled with a compile-time option to disable the timer (to facilitate wired serial console control where BLE connectivity is not used) [Note: to be moved to a configuration option in NVS in a future release].
Additional automatic actions are described in No-phone Mode, below.
Tail Moves
Move commands return <movename> BEGIN upon start, and <movename> END upon completion. If the move is set to return home after completion (all firmware moves are), then it will be immediately followed by a TAILHM BEGIN and a TAILHM END as well.
A command will return LOWBATT and reject the command if the battery is less than 10%. ERR will be returned if the command can't be parsed or otherwise executed.
A new command that is received before the currently executing command is finished will immediately end the current command and start the new one.
Easing functions are as per the ServoEasing libary EaseTypes. However, those functions are presented in Hexidecimal and must be converted to a Decimal number before being used in command syntax. The Easing Functions Cheat Sheet is useful to help visualize what easing functions do.
| Command | MiTail | MiTail Mini | FlutterWings | Ear Gear 2 |
|---|---|---|---|---|
| TAILHM | HoMe position | HoMe position | HoMe position | HoMe position |
| TAILS1 | Slow wag 1 | Slow wag 1 | Slow Full Flap | Slow Outward Turn |
| TAILS2 | Slow wag 2 | Slow wag 2 | Slow Low Flap | Slow Left Ear Turn |
| TAILS3 | Slow wag 3 | Slow wag 3 | Slow High Flap | Slow Right Ear Turn |
| TAILFA | FAst wag | FAst wag | Fast Full Flap | Left Tilt |
| TAILSH | SHort wag | N/A | Fast Low Flap | Right Tilt |
| TAILHA | HAppy wag | N/A | Fast Asymmetrical Flap | Quick Outward Turn |
| TAILER | ERect | N/A | Full Close | Right Twist, Left Twist |
| TAILEP | Erect Pulse | N/A | Low Pulse | Double Right Ear Twist |
| TAILT1 | Tremble 1 | N/A | Slow Asymmetrical Flap | Flick Left Ear |
| TAILT2 | Tremble 2 | N/A | Settle | Flick Right Ear |
| TAILET | Erect Trem | N/A | High Pulse | Double Left Ear Twist |
| TAILU1 | User defined 1 | User defined 1 | User defined 1 | User defined 1 |
| TAILU2 | User defined 2 | User defined 2 | User defined 2 | User defined 2 |
| TAILU3 | User defined 3 | User defined 3 | User defined 3 | User defined 3 |
| TAILU4 | User defined 4 | User defined 4 | User defined 4 | User defined 4 |
Glow Tip LED Patterns
LED pattern commands return <movename> BEGIN upon start, and <movename> END upon completion.
A command will return LOWBATT and reject the command if the battery is less than 10%. ERR will be returned if the command can't be parsed or otherwise executed.
A new command that is received before the currently executing command is finished will immediately end the current command and start the new one.
| LEDOFF | LEDs OFF |
| LEDREC | RECtangle wave pattern (blink 1 second on, 1 second off) |
| LEDTRI | TRIangle wave pattern (fade in 1 second, fade out 1 second) |
| LEDSAW | SAWtooth wave pattern (fade in 2 seconds, off) |
| LEDSOS | Morse SOS pattern |
| LEDBEA | BEAcon (100ms on every 2 seconds) |
| LEDFLA | FLAme |
| LEDSTR | STRobe |
| LEDUS1 | USer defined 1 |
| LEDUS2 | USer defined 2 |
| LEDUS3 | USer defined 3 |
| LEDUS4 | USer defined 4 |
EarGear 2-only Commands
Other Commands
| AUTOMODE | AUTOnomous MOde; see below, returns OK |
| DSSP | Directly Set Servo Position; see below, returns OK |
| HWVER | Returns HardWare VERsion; returns HWVER LEGACY MITAIL or HWVER MITAIL x.x for tail-series controller hardware, HWVER EG2 x.x for EarGear 2 controller hardware |
| PING | Keepalive heartbeat (from application), returns PONG |
| SETPUSSKEY | SET PaSSKEY, enable Conference Mode, and restart after 3 seconds; see below, returns OK |
| SHUTDOWN | SHUT DOWN the unit (will lose the BLE connection), returns SHUTDOWN BEGIN or ERR if charger is attached |
| STOPAUTO | STOP AUTOnomous Mode, returns OK, followed by AUTO END |
| STOPNPM | STOP No-Phone Mode and disables it in NVS configuration; returns OK, followed by AUTO END |
| USERMOVE | See below, returns OK |
| STOPPUSSKEY | STOP PaSSKEY, disable Conference Mode and restart after 3 seconds; see below, returns OK |
| USERLEDS | See below, returns OK |
| VER | Returns the firmware VERsion number; VER x.x.x, followed by a second message: either GLOWTIP FALSE if a Glow Tip is not connected, or GLOWTIP TRUE if one is |
Developer Commands (use at own risk)
| BATT | BATTery percentage, returns the integer value of estimated battery capacity remaining (e.g., 61) | |||
| FORMATNVS | FORMAT NVS (erase all contents of the default NVS partition, including BLE bonds) and reboot | |||
| OTA | Starts firmware Over The Air update process (e.g., OTA <expected size in bytes> <expected MD5>); returns BEGIN OTA or ERR on failure to start, OTA SUCCESS on success, or OTA ERR on error during OTA process | |||
| READCONF | READ running CONFiguration; returns space-delimited running configuration parameters (e.g., READCONF 1 5 0 15 40 3 8 0 0 0 3 0 0 0 1 0 123456) [ver minsToSleep minsToNPM minNPMPauseSec maxNPMPauseSec groupsNPM servo1home servo2home listenModeNPMEnabled listenModeResponseOnly groupsLM tiltModeNPMEnabled tiltModeResponseOnly disconnectedCountdownEnabled homeOnAppPoweroff conferenceModeEnabled securityPasskey] | |||
| READNVS | READ CONFiguration from NVS; returns space-delimited configuration parameters stored in NVS (e.g., READNVS 1 5 0 15 40 3 8 0 0 0 3 0 0 0 1 0 123456) [ver minsToSleep minsToNPM minNPMPauseSec maxNPMPauseSec groupsNPM servo1home servo2home listenModeNPMEnabled listenModeResponseOnly groupsLM tiltModeNPMEnabled tiltModeResponseOnly disconnectedCountdownEnabled homeOnAppPoweroff conferenceModeEnabled securityPasskey] | |||
| REBOOT | REBOOT after 3 seconds, returns OK | |||
| RELEASEHOLDONSTOP | RELEASE servo HOLD when the servos STOP (default for tail-based devices); returns OK |
| SETHOLDONSTOP | SET servo HOLD is maintained when the servos STOP (default for EarGear 2); returns OK' |
| SETHOME | SET HOME position (0 through 8) for each servo (e.g., SETHOME 4 4), NOTE: only available on FlutterWings, and EarGear 2; returns OK |
| TASKU | Prints to the hardware serial console the minimum amount in words of remaining stack space that was available to the task since the task started executing, returns OK |
| WRITECONF | WRITE CONFiguration to NVS and set running configuration to match (e.g., WRITECONF 1 5 0 15 40 3 8 0 0 0 3 0 0 0 1 0 123456), returns OK [ver minsToSleep minsToNPM minNPMPauseSec maxNPMPauseSec groupsNPM servo1home servo2home listenModeNPMEnabled listenModeResponseOnly groupsLM tiltModeNPMEnabled tiltModeResponseOnly disconnectedCountdownEnabled homeOnAppPoweroff conferenceModeEnabled securityPasskey] |
===== Directly Set Servo Position =====
DSSP (Directly Set Servo Positions) allows a single-position move to be commanded and executed immediately. This is faster (and simpler) than defining a USERMOVE and then executing it. It also has the advantage of keeping the debug console output synchronous to the move flow, instead of interleaving the command and move flow responses.
The syntax is similar to USERMOVE, but fewer parameters:
DSSP [E<easeType1>F<easeType1>] A<point1>B<point1> L<numticks1>M<numticks1> [H{0 | 1}]
^ Prefix ^ Parameter Type ^ Range of Values for Moves ^
| E | Easing function to apply to Servo 1 | Default is Linear (no easing), if not specified. This is the decimal representation of the (hexadecimal) easing type enumeration, as per EaseTypes (e.g., 0 = Linear, 129 = Quadratic in/out, 130 = Cubic in/out, 131 = Quartic in/out). | | F | Easing function to apply to Servo 2 | (Same as E) | | A | Point for Servo 1 | <0 … 8> 0 → 25 degrees 1 → 41 degrees 2 → 58 degrees … 8 → 160 degrees | | B | Point for Servo 2 | (Same as A) | | L | Time between the current Servo 1 point and the next in ticks (in 20 ms increments) L will move from the current position to the next, over the time specified | 0 … 127 (time * 20 ms) | | M | Time between the current Servo 2 point and the next in ticks (in 20 ms increments) M will move from the current position to the next, over the time specified | (Same as L) | | H | Move to home position at end of move | 0 = false (default), 1 = true | Notes: * Parameters of type A, B, E, F, H, L, and M can appear in any order (e.g., AABBSS, ABABSS, ABSABS).
* Parameters can be separated by any character that is not a number or a letter (e.g., space, comma, semicolon). However, the letters themselves act as separators, and it is recommended that no additional characters are used, as the serial buffer has a limited capacity and may not be able to store the whole instruction.
* Depending on the tail and position, it can sag out of the commanded position when servo power is released at the end of the DSSP move. This may cause a visual defect of jerking back into the previous position when the next move starts.
==== DSSP Example ====
DSSP E130F130 A1B7 L75M75 H1DSSP A1B7 L75M75 H1 ===== User-defined Tail Moves and LEDs Patterns ===== Up to 4 user-defined move definitions and 4 LED patterns can be sent over the BT/BLE connection and assigned to user presets (callable with the TAILU1 … TAILU4 commands). These presets will be lost once the unit is powered off.
The two instructions used to send a tail move or a Glow Tip LED pattern definition follow the same syntax and consist of a
keyword (USERMOVE or USERLEDS) followed by a number of parameters. These are letter-number pairs, where the letter
defines the type of parameter (see table, below).
USERMOVE U<preset> P<numpoints> N<numcycles> [E<easeType1>F<easeType1> … E<easeTypen>F<easeTypen>] A<point1>B<point1> … A<pointn>B<pointn> L<numticks1>M<numticks1> … L<numticksn>M<numticksn> [H{0 | 1}]
^ Prefix ^ Parameter Type ^ Range of Values for Moves ^
| U | User preset number | <1 … 4> |
| E | Easing function to apply to Servo 1 | Default is Linear (no easing), if not specified. This is the decimal representation of the (hexadecimal) easing type enumeration, as per EaseTypes (e.g., 0 = Linear, 129 = Quadratic in/out, 130 = Cubic in/out, 131 = Quartic in/out). | | F | Easing function to apply to Servo 2 | (Same as E) | | A | Point for Servo 1 | <0 … 8> 0 → 25 degrees 1 → 41 degrees 2 → 58 degrees … 8 → 160 degrees | | B | Point for Servo 2 | (Same as A) | | L | Time between the current Servo 1 point and the next in ticks (in 20 ms increments) L will move from the current position to the next, over the time specified | 0 … 127 (time * 20 ms) | | M | Time between the current Servo 2 point and the next in ticks (in 20 ms increments) M will move from the current position to the next, over the time specified | (Same as L) | | H | Move to home position at end of move | 0 = false (default), 1 = true | USERLEDS U<preset> P<numpoints> N<numcycles> A<point1> … A<pointn> [S | L]<numticks1> … [S |
Ear Gear 2
The Ear Gear 2 uses the USB CDC, which may be accessed from the USB-C connector on the right ear.