Trace:

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
en:dev:tailcontrol-command-protocol [2025/02/04 00:29] – [EarGear 2-only Commands] darkgrueen:dev:tailcontrol-command-protocol [2025/02/05 03:23] (current) – darkgrue
Line 1: Line 1:
-====== TailCoNTROL Command Protocol ======+====== 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.+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. 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.
  
 <WRAP round todo 90%> <WRAP round todo 90%>
-**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.+**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.
 </WRAP> </WRAP>
  
Line 35: Line 35:
  
 <WRAP round todo 90%> <WRAP round todo 90%>
-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).+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'': +The BLE Device Service for TailControl is ''19F8ADE2-D0C6-4C0A-912A-30601D9B3060'': 
-  * RX Characteristic is ''5e4d86ac-ef2f-466f-a857-8776d45ffbc2'' and +  * RX Characteristic is ''5E4D86AC-EF2F-466F-A857-8776D45FFBC2''. 
-  * TX Characteristic is ''567a99d6-a442-4ac0-b676-4993bf95f805''. +  * TX Characteristic is ''567A99D6-A442-4AC0-B676-4993BF95F805'', and the 
-  * Under the standard Device Information Service (DIS, ''0x180A'') is +  * Battery Voltage is ''E818BDA3-88A7-43C0-8509-6E0BBB6F55D9''.
-    * 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''.+
 </WRAP> </WRAP>
  
Line 55: Line 47:
 </WRAP> </WRAP>
  
-===== TailCoNTROL Device Indicators =====+===== TailControl Device Indicators =====
  
 ==== Blue LED ==== ==== Blue LED ====
Line 103: Line 95:
 ==== Automatic Actions ==== ==== 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].+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 [[en:dev:tailcontrol-command-protocol#No-phone Mode|No-phone Mode]], below. Additional automatic actions are described in [[en:dev:tailcontrol-command-protocol#No-phone Mode|No-phone Mode]], below.
Line 118: Line 110:
 Easing functions are as per the ServoEasing libary [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]]. However, those functions are presented in Hexidecimal and must be converted to a Decimal number before being used in command syntax. The [[https://easings.net/|Easing Functions Cheat Sheet]] is useful to help visualize what easing functions do. Easing functions are as per the ServoEasing libary [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]]. However, those functions are presented in Hexidecimal and must be converted to a Decimal number before being used in command syntax. The [[https://easings.net/|Easing Functions Cheat Sheet]] is useful to help visualize what easing functions do.
  
-^ Command  ^ MiTail  ^ MiTail Mini  ^ FlutterWings  ^ Ear Gear 2  ^ +| **TAILHM** | **H**o**M**e position | 
-| **TAILHM** | **H**o**M**e position | **H**o**M**e position | **H**o**M**e position | **H**o**M**e position | +| **TAILS1** | **S**low wag **1** | 
-| **TAILS1** | **S**low wag **1** | **S**low wag **1** | Slow Full Flap | Slow Outward Turn | +| **TAILS2** | **S**low wag **2** | 
-| **TAILS2** | **S**low wag **2** | **S**low wag **2** | Slow Low Flap | Slow Left Ear Turn | +| **TAILS3** | **S**low wag **3** | 
-| **TAILS3** | **S**low wag **3** | **S**low wag **3** | Slow High Flap | Slow Right Ear Turn | +| **TAILFA** | **FA**st wag | 
-| **TAILFA** | **FA**st wag | **FA**st wag | Fast Full Flap | Left Tilt | +| **TAILSH** | **SH**ort wag | 
-| **TAILSH** | **SH**ort wag | N/A | Fast Low Flap | Right Tilt | +| **TAILHA** | **HA**ppy wag | 
-| **TAILHA** | **HA**ppy wag | N/A | Fast Asymmetrical Flap | Quick Outward Turn | +| **TAILER** | **ER**ect | 
-| **TAILER** | **ER**ect | N/A | Full Close | Right Twist, Left Twist | +| **TAILEP** | **E**rect **P**ulse | 
-| **TAILEP** | **E**rect **P**ulse | N/A | Low Pulse | Double Right Ear Twist | +| **TAILT1** | **T**remble **1** | 
-| **TAILT1** | **T**remble **1** | N/A | Slow Asymmetrical Flap | Flick Left Ear | +| **TAILT2** | **T**remble **2** | 
-| **TAILT2** | **T**remble **2** | N/A | Settle | Flick Right Ear | +| **TAILET** | **E**rect **T**rem | 
-| **TAILET** | **E**rect **T**rem | N/A | High Pulse | Double Left Ear Twist | +| **TAILU1** | **U**ser defined **1** | 
-| **TAILU1** | **U**ser defined **1** | **U**ser defined **1** | **U**ser defined **1** | **U**ser defined **1** | +| **TAILU2** | **U**ser defined **2** | 
-| **TAILU2** | **U**ser defined **2** | **U**ser defined **2** | **U**ser defined **2** | **U**ser defined **2** | +| **TAILU3** | **U**ser defined **3** | 
-| **TAILU3** | **U**ser defined **3** | **U**ser defined **3** | **U**ser defined **3** | **U**ser defined **3** | +| **TAILU4** | **U**ser defined **4** |
-| **TAILU4** | **U**ser defined **4** | **U**ser defined **4** | **U**ser defined **4** | **U**ser defined **4** |+
  
  
Line 191: Line 182:
 | **READNVS** | **READ** **CONF**iguration 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''] | | **READNVS** | **READ** **CONF**iguration 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'' | | **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'' | | **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'' | | **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'' |
Line 203: Line 196:
 **DSSP [E<easeType<sub>1</sub>>F<easeType<sub>1</sub>>] A<point<sub>1</sub>>B<point<sub>1</sub>> L<numticks<sub>1</sub>>M<numticks<sub>1</sub>> [H{0|1}]**   **DSSP [E<easeType<sub>1</sub>>F<easeType<sub>1</sub>>] A<point<sub>1</sub>>B<point<sub>1</sub>> L<numticks<sub>1</sub>>M<numticks<sub>1</sub>> [H{0|1}]**  
  
-^ Prefix  ^ Parameter Type  ^ Range of Values for Moves  ^+^ 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 [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]] (e.g., 0 = Linear, 129 = Quadratic in/out, 130 = Cubic in/out,  131 = Quartic in/out). | | **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 [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|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**) | | **F** | Easing function to apply to Servo 2 | (Same as **E**) |
Line 234: Line 227:
 **USERMOVE U<preset> P<numpoints> N<numcycles> [E<easeType<sub>1</sub>>F<easeType<sub>1</sub>> ... E<easeType<sub>n</sub>>F<easeType<sub>n</sub>>] A<point<sub>1</sub>>B<point<sub>1</sub>> ... A<point<sub>n</sub>>B<point<sub>n</sub>> L<numticks<sub>1</sub>>M<numticks<sub>1</sub>> ... L<numticks<sub>n</sub>>M<numticks<sub>n</sub>> [H{0|1}]**   **USERMOVE U<preset> P<numpoints> N<numcycles> [E<easeType<sub>1</sub>>F<easeType<sub>1</sub>> ... E<easeType<sub>n</sub>>F<easeType<sub>n</sub>>] A<point<sub>1</sub>>B<point<sub>1</sub>> ... A<point<sub>n</sub>>B<point<sub>n</sub>> L<numticks<sub>1</sub>>M<numticks<sub>1</sub>> ... L<numticks<sub>n</sub>>M<numticks<sub>n</sub>> [H{0|1}]**  
  
-^ Prefix  ^ Parameter Type  ^ Range of Values for Moves  ^+^ Prefix ^ Parameter Type  ^ Range of Values for Moves  ^
 | **U** | User preset number | <1 ... 4> | | **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 [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]] (e.g., 0 = Linear, 129 = Quadratic in/out, 130 = Cubic in/out,  131 = Quartic in/out). | | **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 [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]] (e.g., 0 = Linear, 129 = Quadratic in/out, 130 = Cubic in/out,  131 = Quartic in/out). |
Line 249: Line 242:
 | **U** | User preset number | <1 ... 4> | | **U** | User preset number | <1 ... 4> |
 | **P** | Number of points in the Glow Tip pattern | <1 ... 32> | | **P** | Number of points in the Glow Tip pattern | <1 ... 32> |
-| **N** | Number of cycles (times the pattern will be performed) | <0 ... 255> |+| **N** | Number of cycles (times the pattern will be repeated) | <0 ... 255> |
 | **A** | Brightness point for Glow Tip | <0 ... 8>\\ 0 -> LEDs off\\ ...\\ 4 -> 50% intensity\\ ...\\ 8-> LEDs max intensity | | **A** | Brightness point for Glow Tip | <0 ... 8>\\ 0 -> LEDs off\\ ...\\ 4 -> 50% intensity\\ ...\\ 8-> LEDs max intensity |
 | **S/L** | Time between the current point and the next (in 20 ms increments)\\ **S** will wait in the current position, then move to the next when the time has elapsed\\ **L** will gradually move from the current position to the next, over the time specified | 0 ... 127 (time * 20 ms) | | **S/L** | Time between the current point and the next (in 20 ms increments)\\ **S** will wait in the current position, then move to the next when the time has elapsed\\ **L** will gradually move from the current position to the next, over the time specified | 0 ... 127 (time * 20 ms) |
Line 273: Line 266:
   * **U1** Store into user preset 1     * **U1** Store into user preset 1  
   * **P2** The move consists of 2 points     * **P2** The move consists of 2 points  
-  * **N3** Perform the sequence 3 times  +  * **N3** Repeat the sequence 3 times  
   * **E0E66** Servo 1 move to Position 1 has no easing, move to Position 2 uses EASE_CUBIC_OUT (0x42)   * **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)   * **F0F66** Servo 2 move to Position 1 has no easing, move to Position 2 uses EASE_CUBIC_OUT (0x42)
Line 291: Line 284:
   * **U2** Store into user preset 2     * **U2** Store into user preset 2  
   * **P4** The move consists of 4 points     * **P4** The move consists of 4 points  
-  * **N3** Perform the sequence 3 times  +  * **N3** Repeat the sequence 3 times  
   * **A0A4A8A4** Move Servo 1 90° at a time, starting from 0°     * **A0A4A8A4** Move Servo 1 90° at a time, starting from 0°  
   * **B4B8B4B0** Move Servo 2 90° at a time, starting from 90°     * **B4B8B4B0** Move Servo 2 90° at a time, starting from 90°  
Line 313: Line 306:
   * **U1** Store into user preset 1     * **U1** Store into user preset 1  
   * **P2** The pattern consists of 2 brightness points     * **P2** The pattern consists of 2 brightness points  
-  * **N5** Perform the pattern 5 times  +  * **N5** Repeat pattern 5 times  
   * **A8A0** Start at full brightness, then turn off     * **A8A0** Start at full brightness, then turn off  
   * **S5S95** On for 5 * 20 ms = 100 ms; off for 50 * 20ms = 1 s     * **S5S95** On for 5 * 20 ms = 100 ms; off for 50 * 20ms = 1 s  
Line 319: Line 312:
 === Example 2 – Fade in/out (similar to ''LEDTRI'') === === Example 2 – Fade in/out (similar to ''LEDTRI'') ===
  
-The Glow Tip LEDs light up slowly, then dim until completely off; this is performed 3 times.+The Glow Tip LEDs light up slowly, then dim until completely off; this is repeated 3 times.
  
 **USERLEDS U2 P2 N3 A0A8 L100L100** **USERLEDS U2 P2 N3 A0A8 L100L100**
Line 325: Line 318:
   * **U2** Store into user preset 2     * **U2** Store into user preset 2  
   * **P2** The pattern consists of 2 brightness points     * **P2** The pattern consists of 2 brightness points  
-  * **N3** Perform the pattern 3 times  +  * **N3** Repeat pattern 3 times  
   * **A0A8** Start off, finish at full brightness     * **A0A8** Start off, finish at full brightness  
   * **L100L100** Each brightness point is reached in 100 * 20 ms = 2 s   * **L100L100** Each brightness point is reached in 100 * 20 ms = 2 s
Line 361: Line 354:
 ===== Conference Mode ===== ===== Conference Mode =====
  
-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:+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.   * **Authentication:** verifying the identity of the device connecting.
Line 369: Line 362:
 ==== Enabling Conference Mode (Pairing and Binding) ==== ==== Enabling Conference Mode (Pairing and Binding) ====
  
-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.+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>** **SETPUSSKEY <nnnnnn>**
Line 385: Line 378:
 ==== Unbinding ==== ==== Unbinding ====
  
-Resetting/removing bonds requires two separate actions: resetting the TailCoNTROL device, and removing the bond on the phone or other device.+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):+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.+  * Sending a ''FORMATNVS'' command to the TailControl console. This will factory-reset and reboot.
   * Performing a factory reset using the single button:   * Performing a factory reset using the single button:
       - Press and hold the power button.       - Press and hold the power button.
Line 442: Line 435:
 ===== No-phone Mode ===== ===== No-phone Mode =====
  
-No-phone mode is a feature exclusive of MiTail firmware 4.0.0 or greater or TailCoNTROL.+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>** **AUTOMODE G<n>[G<n>[G<n>]] T<nnn>T<nnn>T<251 ... 254>**
Line 462: Line 455:
  
  
-===== Debugging ===== +== Copyright 2024-2025 © The Mechanical Tail Company Limited contact@thetailcompany.com. All Rights Reserved. The Mechanical Tail Company Limited also claims trademark rights in the following: TailControl, MiTail, MiTail Mini, FlutterWings, and EarGear.  Any unauthorized use is expressly prohibited. ==
- +
-TailCoNTROL has ample output to the serial console that can be invaluable when debugging controllers. The device can also be commanded from the console as well. +
- +
-==== MiTail, MiTail Mini, FlutterWings ==== +
- +
-Hardware console can be accessed from unpopulated board connector (requires opening the case) with a 3.3 V USB to TTL interface. If you also wish to be able to hardware flash, make sure that it provides RXD, TXD, RTS (Ready to Send), and DTR (Data Terminal Ready) signals (i.e., a 6-pin connector with the appropriate signals). Numerous inexpensive USB to TTL cables and interfaces are not capable of doing this, check carefully before investing in a tool to perform this. +
- +
-The [[https://1bitsquared.com/products/tigard|Tigard Protocol Tool]] works very nicely, though it is massively overkill in that it has many more capabilities than are required. +
- +
-The interface pinout on the board is below. Pins are numbered counting from Pin 1, closest to the servo connector, on the component side of the controller board. +
- +
-{{ :en:esp32_uart0_connections.jpg?direct&400 |ESP32 UART0 Connections}} +
- +
-**Note:** USB to TTL interfaces are available with 5 V, 3.3 V, or selectable voltage. The ESP32 //must// be used with 3.3 V interfaces //only//! Ensure that your cable or device is configured for 3.3 V before connecting it to the controller board, or your ESP32 may be permanently damaged. +
- +
-==== Ear Gear 2 ==== +
- +
-The Ear Gear 2 uses the USB CDC, which may be accessed from the USB-C connector on the right ear. +
- +
- +
-== Copyright 2024 © The Mechanical Tail Company Limited contact@thetailcompany.com. All Rights Reserved. ==+
  
Back to top