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.

The hardware platform uses the “Just Works” Bluetooth Low Energy (BLE) pairing method to connect.

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.

Note: For tail-series v3.6 controller hardware, the battery charging characteristic is unset (charging state is not available).

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.

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 jerking back into 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.

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 E2E42 F2F42 A7A1 B7B1 L75L75 M75M75 H1

• U1 Store into user preset 1
• P2 The move consists of 2 points
• N3 Repeat the sequence 3 times
• E2E42 No easing
• F2F42 No easing
• 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 Repeat 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 Repeat 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 repeated 3 times.

USERLEDS U2 P2 N3 A0A8 L100L100

• U2 Store into user preset 2
• P2 The pattern consists of 2 brightness points
• N3 Repeat 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 twice 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 double-flash, 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).

The bond will also need to be removed on the phone or other device as well, or it will attempt to continue to use the bond (which will fail, because those stored credentials will no longer be valid).

• On Android, enter Settings, Connections, Bluetooth and find the device to remove (e.g., “mitail”). Select the gear icon, and then select “Unpair”. Confirm the dialog to unpair and forget the device.
• On iOS, enter Settings, Bluetooth and find the device to remove under “My Devices”. Select the circle-i icon next to the device name, and then select “Forget This Device”. Confirm by selecting “Forget Device”.

[This feature is pending removal in a future release.]

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.

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.

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.