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/11/04 16:46] – 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 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. ==