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/02 06:08] – [Other Commands] 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.
  
  
-==== Unbinding ====+==== Unbinding / Factory Reset ====
  
 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.
Line 391: Line 410:
  
   * 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 (TailControl v5.1.0, forward):
       - Press and hold the power button.       - Press and hold the power button.
       - 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.       - 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.
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. ==