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 [2024/12/15 23:40] – [Device Advertisement] 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 160: Line 152:
 ===== EarGear 2-only Commands ===== ===== EarGear 2-only Commands =====
  
-| **LISTENMODE** | Starts Listen Mode; [[#Listen Mode|see below]], returns ''OK'' | +| **LISTENMODE** (or **LISTEN FULL**) | Starts Listen Mode; [[#Listen Mode|see below]], returns ''OK'' | 
-| **STOPLISTEN** | Stops Listen Mode; [[#Listen Mode|see below]], returns ''OK'' | +| **STOPLISTEN** (or **ENDLISTEN**) | Stops Listen Mode; [[#Listen Mode|see below]], returns ''OK'' | 
-| **STOPTILT** | Stops Tilt Mode; [[#Tilt Mode|see below]], returns ''OK'' | +| **STOPTILT** (or **ENDTILTMODE**) | Stops Tilt Mode; [[#Tilt Mode|see below]], returns ''OK'' | 
-| **TILTMODE** | Starts Tilt Mode; [[#Tilt Mode|see below]], returns ''OK'' |+| **TILTMODE** (or **TILTMODE START**) | Starts Tilt Mode; [[#Tilt Mode|see below]], returns ''OK'' |
  
  
Line 190: 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 248: 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 272: 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 290: 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 312: 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 318: 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 324: 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 360: 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 368: 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 384: 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 441: 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 461: Line 455:
  
  
-== Copyright 2024 © The Mechanical Tail Company Limited contact@thetailcompany.com. All Rights Reserved. ==+== 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. ==
  
Back to top