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 [2026/03/05 17:51] – [Unbinding] darkgrueen:dev:tailcontrol-command-protocol [2026/05/16 04:42] (current) – darkgrue
Line 2: Line 2:
  
  
-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 EarGear 2, FlutterWings, MiTail, MiTail Mini, and Paws with Claws (ClawGear); 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.
Line 20: Line 20:
 Device name is one of the following: Device name is one of the following:
  
-  * ''mitail'' for MiTail, +  * ''clawgear'' for ClawGear/Paws with Claws, 
-  * ''minitail'' for MiTail Mini, +  * ''EG2'' for EarGear 2, 
-  * ''flutter'' for FlutterWings, and +  * ''flutter'' for FlutterWings, 
-  * ''EG2'' for EarGear 2.+  * ''mitail'' for MiTail, and 
 +  * ''minitail'' for MiTail Mini.
  
-The BLE Device Service for the MiTail, MiTail Mini, and FlutterWings is ''3af2108b-d066-42da-a7d4-55648fa0a9b6'': +TailControl will uses the same Service and Characteristics UUIDs across all supported products: ''19F8ADE2-D0C6-4C0A-912A-30601D9B3060''.
-  * 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 ''5E4D86AC-EF2F-466F-A857-8776D45FFBC2'', 
-  * RX Characteristic is ''05e026d8-b395-4416-9f8a-c00d6c3781b9'', +  * TX Characteristic is ''567A99D6-A442-4AC0-B676-4993BF95F805'' and the
-  * TX Characteristic is ''0b646a19-371e-4327-b169-9632d56c0e84'', and the +
-  * Battery Voltage is ''54fa919d-e8a8-4841-b280-c5461161304f''. +
- +
-<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). +
- +
-The BLE Device Service for TailControl is ''19F8ADE2-D0C6-4C0A-912A-30601D9B3060'': +
-  * RX Characteristic is ''5E4D86AC-EF2F-466F-A857-8776D45FFBC2''. +
-  * TX Characteristic is ''567A99D6-A442-4AC0-B676-4993BF95F805'', and the+
   * Battery Voltage is ''E818BDA3-88A7-43C0-8509-6E0BBB6F55D9''.   * Battery Voltage is ''E818BDA3-88A7-43C0-8509-6E0BBB6F55D9''.
-</WRAP> 
  
 <WRAP round important 90%> <WRAP round important 90%>
Line 105: Line 93:
  
  
-===== Move Commands =====+===== Servo-Based Moves (ClawGear, EarGear 2, MiTail, MiTail Mini, FlutterWings) =====
  
-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.+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 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.
Line 131: Line 119:
 | **TAILU3** | **U**ser defined **3** | | **TAILU3** | **U**ser defined **3** |
 | **TAILU4** | **U**ser defined **4** | | **TAILU4** | **U**ser defined **4** |
 +
 +
 +===== Stepper-Based Moves (Not Currently Used) =====
 +
 +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.
 +
 +| **TAILHM** | **H**o**M**e position |
 +| **MOVE1** | **MOVE** **1** |
 +| **MOVE2** | **MOVE** **2** |
 +| **MOVE3** | **MOVE** **3** |
 +| **MOVE4** | **MOVE** **4** |
 +| **MOVE5** | **MOVE** **5** |
 +| **MOVE6** | **MOVE** **6** |
 +| **MOVE7** | **MOVE** **7** |
 +| **MOVEU1** | **MOVE** **U**ser defined **1** |
 +| **MOVEU2** | **MOVE** **U**ser defined **2** |
 +| **MOVEU3** | **MOVE** **U**ser defined **3** |
 +| **MOVEU4** | **MOVE** **U**ser defined **4** |
 +
 +
 +===== ClawGear-only Commands =====
 +
 +| **CLAPMODE** | Starts Clap Mode (and disables Tilt Mode, if enabled), returns ''OK'' |
 +| **STOPCLAP** | Stops Clap Mode, returns ''OK'' |
 +| **STOPTILT** | Stops Tilt Mode, returns ''OK'' |
 +| **TILTMODE** | Starts Tilt Mode (and disables Clap Mode, if enabled), returns ''OK'' |
 +
 +===== EarGear 2-only Commands =====
 +
 +| **LISTENMODE** | Starts Listen Mode ([[#Listen Mode|see below]]), returns ''OK'' |
 +| **STOPLISTEN** | Stops Listen Mode ([[#Listen Mode|see below]]), returns ''OK'' |
 +| **STOPTILT** | Stops Tilt Mode ([[#Tilt Mode|see below]]), returns ''OK'' |
 +| **TILTMODE** | Starts Tilt Mode ([[#Tilt Mode|see below]]), returns ''OK'' |
  
  
Line 155: Line 180:
  
  
-===== EarGear 2-only Commands =====+===== RGB LED Commands =====
  
-| **LISTENMODE** (or **LISTEN FULL**) | Starts Listen Mode ([[#Listen Mode|see below]]), returns ''OK'' | +RGB support is experimental, and not included in production firmware.
-| **STOPLISTEN** (or **ENDLISTEN**) | Stops Listen Mode ([[#Listen Mode|see below]]), returns ''OK'' | +
-| **STOPTILT** (or **ENDTILTMODE**) | Stops Tilt Mode ([[#Tilt Mode|see below]]), returns ''OK'' | +
-| **TILTMODE** (or **TILTMODE START**) | Starts Tilt Mode ([[#Tilt Mode|see below]]), returns ''OK'' | +
- +
- +
-===== RGB LED Commands =====+
  
 | **RGBOFF** | **RGB** LEDs **OFF**, returns ''OK'' | | **RGBOFF** | **RGB** LEDs **OFF**, returns ''OK'' |
Line 188: Line 207:
 | **STOPNPM** | **STOP** **N**o-**P**hone **M**ode and disables it in NVS configuration; returns ''OK'', followed by ''AUTO END'' | | **STOPNPM** | **STOP** **N**o-**P**hone **M**ode and disables it in NVS configuration; returns ''OK'', followed by ''AUTO END'' |
 | **USERMOVE** | Set user-defined move ([[#User-defined Moves and Glow Tip Patterns|see below]]), returns ''OK'' | | **USERMOVE** | Set user-defined move ([[#User-defined Moves and Glow Tip Patterns|see below]]), returns ''OK'' |
-| **STOPPUSSKEY** | **STOP** **P**a**SSKEY**; disable Conference Mode, returns ''OK'', and restarts after 3 seconds ([[#Conference Mode|see below]]) :!: NOTE THE WARNING UNDER [[#Conference Mode]]!|+| **STOPPUSSKEY** | **STOP** **P**a**SSKEY**; disable Conference Mode, returns ''OK'', and restarts after 3 seconds ([[#Conference Mode|see below]]) |
 | **USERLEDS** | Set user-defined Glow Tip pattern ([[#User-defined Moves and Glow Tip Patterns|see below]]), returns ''OK'' | | **USERLEDS** | Set user-defined Glow Tip pattern ([[#User-defined Moves and Glow Tip Patterns|see below]]), returns ''OK'' |
 | **VER** | Returns the firmware **VER**sion number; (e.g., ''VER 5.0.0''); followed by a line that is either ''GLOWTIP TRUE'' if a Glow Tip is connected, or ''GLOWTIP FALSE'' if one is not; and a final line that is either ''RGB TRUE'' if a RGB LED strip is connected, or ''RGB FALSE'' if it is not | | **VER** | Returns the firmware **VER**sion number; (e.g., ''VER 5.0.0''); followed by a line that is either ''GLOWTIP TRUE'' if a Glow Tip is connected, or ''GLOWTIP FALSE'' if one is not; and a final line that is either ''RGB TRUE'' if a RGB LED strip is connected, or ''RGB FALSE'' if it is not |
Line 201: Line 220:
 | **SETHOLDONSTOP** | **SET** servo **HOLD** is maintained when the servos **STOP** (maintains servo PWM when not moving, default for EarGear 2); returns ''OK'' | | **SETHOLDONSTOP** | **SET** servo **HOLD** is maintained when the servos **STOP** (maintains servo PWM when not moving, default for EarGear 2); returns ''OK'' |
 | **UNSETHOLDONSTOP** | **UNSET** servo **HOLD** when the servos **STOP** (servo PWM is dropped when not moving, default for tail-based devices); returns ''OK'' | | **UNSETHOLDONSTOP** | **UNSET** servo **HOLD** when the servos **STOP** (servo PWM is dropped when not moving, default for tail-based devices); 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 eac2h servo (e.g., ''SETHOME 4 4''), **NOTE:** only available on FlutterWings, and EarGear 2; returns ''OK'' |
 | **SETLISTENMOVES** | **SET** internal **LISTEN** Mode **MOVES** to play on a listen event in addition to sending event notifications; returns ''OK'' | | **SETLISTENMOVES** | **SET** internal **LISTEN** Mode **MOVES** to play on a listen event in addition to sending event notifications; returns ''OK'' |
 | **UNSETLISTENMOVES** | **UNSET** internal **LISTEN** Mode **MOVES** to play on a listen event, only an event notification will be sent and it is the responsibility of the connected application to send commands to react to events; returns ''OK'' | | **UNSETLISTENMOVES** | **UNSET** internal **LISTEN** Mode **MOVES** to play on a listen event, only an event notification will be sent and it is the responsibility of the connected application to send commands to react to events; returns ''OK'' |
Line 381: Line 400:
 **STOPPUSSKEY** **STOPPUSSKEY**
  
-The device will then reboot after 3 seconds. If the bond needs to be removed or reset, see [[en:dev:tailcontrol-command-protocol#unbinding|Unbinding]], below.+The device will then reboot after 3 seconds. If the bond needs to be removed or reset, see [[en:dev:tailcontrol-command-protocol#Unbinding / Factory Reset|Unbinding / Factory Reset]], below.
  
  
Line 466: Line 485:
  
  
-== 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. ==+== Copyright 2024-2026 © 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. ==