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.

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 name is one of the following:

• mitail for MiTail,
• minitail for MiTail Mini,
• flutter for FlutterWings, and
• EG2 for 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.

The Blue LED (D4) has five states:

1. Off when powered off.
2. Blink on-off when BLE is disconnected.
3. Fade-off when BLE is disconnected and Autonomous Mode (either iOS Casual Mode or No-phone Mode, see below) is active.
4. Constant on when BLE is connected.
5. Fade-on when BLE is connected and Autonomous Mode is active.
6. 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.
7. 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.

For v3.2 through v3.5 tail-series controller hardware, the Red LED (D5) has four states:

1. Off during normal operation.
2. Breathing while charging.
3. Constant on when charging is complete.
4. 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:

1. Off when charging is disconnected and when charging complete.
2. Constant on when charging.

For the EarGear 2, the Red LED has two states:

1. Off when charging is disconnected.
2. Constant on when charging.

Note: Unlike the DIGITAiL, MiTail, MiTail Mini, and FlutterWings devices can be used while charging.

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:

1. Constant on is charge in progress.
2. Off is charge completed.
3. Blink on-off indicates a fault condition.

The EarGear 2 does not have a Green LED.

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.

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.

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.

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<easeType₁>F<easeType₁>] A<point₁>B<point₁> L<numticks₁>M<numticks₁> [H{0|1}]

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 E130F130 A1B7 L75M75 H1
DSSP A1B7 L75M75 H1

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<easeType₁>F<easeType₁> … E<easeType_n>F<easeType_n>] A<point₁>B<point₁> … A<point_n>B<point_n> L<numticks₁>M<numticks₁> … L<numticks_n>M<numticks_n> [H{0|1}]

USERLEDS U<preset> P<numpoints> N<numcycles> A<point₁> … A<point_n> [S|L]<numticks₁> … [S|L]<numticks_n>

Notes:

• Parameters of type A, B, E, F, H, L, M, and S can appear in any order (e.g., `EEAABBSS`, `ABAEBESS`, etc.).
• 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.
• Note the upper limit on the P parameter (and the consequential limit of moves in a move or LED pattern).
• There is a 128-character limit on the serial input buffer.

Position limits on the tail can be visualized as such:

Both servos move from 143° to 41° (position 7 to 1) and back, for 3 times; each cycle is (75 + 75) * 20 ms = 3 s long.

USERMOVE U1 P2 N3 E0E66 F0F66 A7A1 B7B1 L75L75 M75M75 H1

• U1 Store into user preset 1
• P2 The move consists of 2 points
• N3 Perform the sequence 3 times
• E0E66 Servo 1 move to Position 1 has no easing, move to Position 2 uses EASE_CUBIC_OUT (0x42)
• F0F66 Servo 2 move to Position 1 has no easing, move to Position 2 uses EASE_CUBIC_OUT (0x42)
• A7A1 Servo 1 moves from 7 to 1 (143° to 41°)
• B7B1 Servo 2 moves exactly as Servo 1
• L75L75 Position 2 is reached in 75 * 20 ms = 1.5 s; return to Position 1 in the same time
• L75L75 Position 2 is reached in 75 * 20 ms = 1.5 s; return to Position 1 in the same time
• H1 Home at end of move

Moves servos in steps of 90° every 2 seconds; Servo 2 is delayed by 90°.

USERMOVE U2 P4 N3 A4A8A4A0 B4B8B4B0 L100L100L100L100 M100M100M100M100 H1 TAILU2

• U2 Store into user preset 2
• P4 The move consists of 4 points
• N3 Perform the sequence 3 times
• A0A4A8A4 Move Servo 1 90° at a time, starting from 0°
• B4B8B4B0 Move Servo 2 90° at a time, starting from 90°
• L100L100L100L100 Each Servo 1 move takes 100 * 20 ms = 2 s to complete
• M100M100M100M100 Each Servo 2 move takes 100 * 20 ms = 2 s to complete
• H1 Home at end of move

The Glow Tip LEDs light up for 100 ms every 1 s (Airbus A320 tail strobe).

USERLEDS U1 P2 N5 A8A0 S5S50 LEDUS1

• U1 Store into user preset 1
• P2 The pattern consists of 2 brightness points
• N5 Perform the pattern 5 times
• A8A0 Start at full brightness, then turn off
• S5S95 On for 5 * 20 ms = 100 ms; off for 50 * 20ms = 1 s

The Glow Tip LEDs light up slowly, then dim until completely off; this is performed 3 times.

USERLEDS U2 P2 N3 A0A8 L100L100

• U2 Store into user preset 2
• P2 The pattern consists of 2 brightness points
• N3 Perform the pattern 3 times
• A0A8 Start off, finish at full brightness
• L100L100 Each brightness point is reached in 100 * 20 ms = 2 s

Defines a sequence of random moves, selected from any of three groups as below; interval between moves varies randomly from T1 to T2.

AUTOMODE G<n>[G<n> … [G<n>]] T<nnn>T<nnn>T<nnn>

The tail will select a random move from the specified group(s), pausing for a random number of seconds between each move (min and max specified by the first and second T parameter, respectively). The tail will stop completely after the time passed by the 3rd T parameter.

Autonomous Mode is ended (after completing any ongoing move) if a BLE connection is made.

The parameter order is not important, except that the three T parameters are interpreted in the order specified below.

STOPAUTO

STOPAUTO will abort the current Autonomous Mode after completing any ongoing move.

Conference mode pairs the user's phone with the TailCoNTROL device and establishes a bond that performs long-term storage of encryption info (particularly keys) so that the devices “know” each other and can easily reconnect in an encrypted way. This protects your device in a number of different ways:

• Authentication: verifying the identity of the device connecting.
• MITM (Man In The Middle): process by which a third device impersonates the other two legitimate devices, in order to fool them into connecting to it. Both BLE central and peripheral will connect to the malicious device, which in turn routes the communication between the other two devices. The malicious device intercepts all data being sent and can inject false data or remove data before it reaches its recipient.
• Replay Attack: a type of network attack in which an attacker captures a valid network transmission and then retransmits it later. The main objective is to trick the system into accepting the retransmission of the data as legitimate.

Pairing is performed with a 6-digit number entered on each of the devices. In the case of TailCoNTROL, the passkey is set on the device in a “safe” location and saved to the firmware configuration.

SETPUSSKEY <nnnnnn>

The device will then reboot in 3 seconds. Conference Mode is then enabled, and pairing proceeds. The user's phone (or other device) will prompt for the passkey (which was set earlier), and the bond will be established on both devices. After that, the passkey or a previous bond (up to 3 can be stored) will be required to connect to the device.

Conference Mode can be disabled by sending the STOPPASSKEY command. This disables Conference Mode, and sets the stored and running configuration passkey to the default (123456).

STOPPUSSKEY

The device will then reboot in 3 seconds. If the bond needs to be removed or reset, see Unbinding, below.

Resetting/removing bonds requires two separate actions: resetting the TailCoNTROL device, and removing the bond on the phone or other device.

There are two different methods of factory-resetting a TailCoNTROL device (which resets all persistent options to defaults and removes all bonding information):

• Sending a FORMATNVS command to the TailCoNTROL console. This will factory-reset and reboot.
• Performing a factory reset using the single button:
  1. Press and hold the power button.
  2. At approximately 3 seconds, the blue LED will flash three times and turn off. Continue to hold without releasing the button. If you Wish to cancel the factory reset, release at any time before the next step and the device will power off.
  3. Ten seconds after the triple-flash (13 seconds total of continuous holding), the blue LED will blink quickly continuously, release to perform the factory reset. The blue LED will go solid, then the ESP will restart, with the blue LED flashing slowly (ready to connect).

Because the CRUMPET application is not currently permitted to manage the tail while the iOS application is in the background, the application uses the AUTOMODE command to have the tail emulate the Casual Mode behavior on-board the tail (Note there is a typo in the string the iOS app sends: there is no space between the command and the first parameter):

AUTOMODEG1 T15 T100 T240

Note that the G and the first two T parameters will depend on the selections made in the app.

Important! The minimum random pause cannot be less that 15 seconds.

AUTOMODE T15T60T240 G1G2

• T15 15-second minimum random pause between moves
• T60 60-second (1 minute) maximum random pause between moves
• T240 3600-second (240 * 15 = 3600 s = 1 hour) total duration of Autonomous Mode
• G1G2 Randomly select a move from groups 1 and 2

Listen Mode is only available on the EarGear 2. When Listen Mode is active, a detected sound above ambient will trigger a random move and a LISTEN BANG message will be sent back to the client. If listenModeMovEn is set (default), then the firmware move will be triggered, otherwise the controlling app will be expected to send a move (if desired).

Development support for basic sound localization for future hardware is supported, replacing the LISTEN BANG response with LISTEN BANG CENTER, LISTEN BANG LEFT, and LISTEN BANG RIGHT, respectively.

LISTEN ARMED is sent to the debug console (but not currently to the BLE terminal) after all conditions to re-trigger have been met.

Triggering by Listen Mode is inhibited when the ears are in motion, as well as a 3-second counter that runs once a sound trigger has finished executing a move.

No-phone mode is a feature exclusive of MiTail firmware 4.0.0 or greater or TailCoNTROL.

AUTOMODE G<n>[G<n>[G<n>]] T<nnn>T<nnn>T<251 … 254>

No-phone Mode (NPM) will cause the tail to delay one to four minutes (based on the setting of the third T parameter of 251 through 254) to wait for a BLE connection. If no BLE connection is made during that time, the tail will select a random move from the specified group(s), pausing for a random number of seconds between each move (min and max specified by the first and second T parameter, respectively).

No-phone Mode is suspended (after completing any ongoing move) if a BLE connection is made. It will resume after BLE is disconnected.

STOPNPM

Stops No-phone mode and disables it in NVS configuration.

Tilt Mode is only available on the EarGear 2. When Listen Mode is active, a detected sound above ambient will trigger a random move and a TILT FORWARD, TILT BACKWARD, TILT LEFT, or TILT RIGHT message (depending on the tilt direction) will be sent back to the client. If tiltModeMovesEnabled is set (default), then the firmware move will be triggered, otherwise the controlling app will be expected to send a move (if desired).

Triggering by Tilt Mode is inhibited when the ears are in motion, as well as a 3-second counter that runs once a sound trigger has finished executing a move AND the EarGear 2 has returned to the neutral tilt position during that time. This prevents tilt re-triggering if the user stays in the tilt position for an extended time.