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/07/04 15:22] – darkgrueen:dev:tailcontrol-command-protocol [2026/09/25 20:24] (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 15: Line 15:
 The hardware platform uses the "Just Works" Bluetooth Low Energy (BLE) pairing method to connect. If Conference Mode ([[#Conference Mode|see below]]) is used, "Passkey" pairing is used. The hardware platform uses the "Just Works" Bluetooth Low Energy (BLE) pairing method to connect. If Conference Mode ([[#Conference Mode|see below]]) is used, "Passkey" pairing is used.
  
-==== Device Advertisement ====+ 
 +===== Device Advertisement =====
  
 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 49: Line 38:
  
 ===== TailControl Device Indicators ===== ===== TailControl Device Indicators =====
 +
  
 ==== Blue LED ==== ==== Blue LED ====
Line 61: Line 51:
   - **Blink fast three times** when the button is held for more than 3 seconds (but less than 13), indicates the device is ready to power off when the button is released.   - **Blink fast three times** when the button is held for more than 3 seconds (but less than 13), indicates the device is ready to power off when the button is released.
   - **Blink fast continuously** when the button is held for more than 13 seconds, indicates the device is ready to factory reset when the button is released.   - **Blink fast continuously** when the button is held for more than 13 seconds, indicates the device is ready to factory reset when the button is released.
 +
  
 ==== Red LED ==== ==== Red LED ====
Line 76: Line 67:
   - **Constant on** when charging.   - **Constant on** when charging.
      
-For the EarGear 2, the Red LED has two states:+For the ClawGear and EarGear 2, the Red LED has two states:
  
   - **Off** when charging is disconnected.   - **Off** when charging is disconnected.
   - **Constant on** when charging.   - **Constant on** when charging.
  
-**Note:** Unlike the DIGITAiL, MiTail, MiTail Mini, and FlutterWings devices **can** be used while charging.+**Note:** Unlike the DIGITAiL, ClawGear, EarGear 2, MiTail, MiTail Mini, and FlutterWings devices **can** be used while charging. 
  
 ==== Green LED ==== ==== Green LED ====
Line 91: Line 83:
   - **Blink on-off** indicates a fault condition.   - **Blink on-off** indicates a fault condition.
  
-The EarGear 2 does not have a Green LED.+The ClawGear and EarGear 2 does not have a Green LED.
  
  
-===== Automatic Actions =====+==== Automatic Actions ====
  
 TailControl will automatically shut down the device if there is no BLE connection for ''currConfig.minsToSleep'' (default 0, [[#Developer Commands (use at own risk)|see below]]) 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). TailControl will automatically shut down the device if there is no BLE connection for ''currConfig.minsToSleep'' (default 0, [[#Developer Commands (use at own risk)|see below]]) 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).
Line 101: 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 127: 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 151: 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 new with the introduction of the ClawGear, and support is experimental on other hardware.
-| **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'' |+
  
- +All **RGB**''xxx'' pattern commands below (except **RGBOFF**), accept an optional trailing **brightness** parameter, an integer from ''0'' to ''100'' representing the overall brightness of the string in percent (e.g., ''RGBRBW 50''). If omitted, brightness defaults to ''DEFAULT_RGB_BRIGHTNESS'' (100%).
-===== RGB LED Commands =====+
  
 | **RGBOFF** | **RGB** LEDs **OFF**, returns ''OK'' | | **RGBOFF** | **RGB** LEDs **OFF**, returns ''OK'' |
-| **RGBRBW** | **RGB** **R**ain**B**o**W** pattern, returns ''OK'' | +| **RGBBRT** | Set **RGB** **BR**igh**T**ness percentage in NVS and running configuration (e.g., ''RGBBRT 100''), returns ''OK'' | 
-| **RGBCLN** | **RGB** **CY**lo**N**; red dot sweeping back and forth, with fading trails, returns ''OK'' | +| **RGBCHS** | **RGB** **CH**a**S**e; theater marquee chase; optionally takes a hue color (in RGB Hexidecimal, otherwise default #7F7F7F is used) (e.g., ''RGBCHS'' [''7F7F7F''] [''brightness'']), returns ''OK'' | 
-| **RGBWPE** | **RGB** **W**i**PE**; color wipe, returns ''OK'' | +| **RGBCLN** | **RGB** **CY**lo**N**; color dot sweeping back and forth, with fading trails; optionally takes a hue color (in RGB Hexidecimal, otherwise default #FF0000 is used) (e.g., ''RGBCLN'' [''FF0000''] [''brightness'']); returns ''OK'' | 
-| **RGBCHS** | **RGB** **CH**a**S**e; theater marquee chase, returns ''OK'' | +| **RGBDMO** | **RGB** **DE**m**O**; cycle through all the preceding patterns, changing every 10 seconds (e.g., ''RGBDMO'' [''brightness'']); returns ''OK'' | 
-| **RGBTWK** | **RGB** **TW**in**K**le; random twinkle effect, returns ''OK'' | +| **RGBFDE** | **RGB** **F**a**DE**; fade in/out effect (e.g., ''RGBFDE'' [''brightness'']), returns ''OK'' | 
-| **RGBSNO** | **RGB** **SNO**w; snow effect, returns ''OK'' | +| **RGBFIR** | **RGB** **FIR**e; fire effect (e.g., ''RGBFIR'' [''brightness'']), returns ''OK'' | 
-| **RGBFIR** | **RGB** **FIR**e; fire effect, returns ''OK'' | +| **RGBRBW** | **RGB** **R**ain**B**o**W** pattern (e.g., ''RGBRBW'' [''brightness'']), returns ''OK'' | 
-| **RGBFDE** | **RGB** **F**a**DE**; fade in/out effect, returns ''OK'' | +| **RGBSLD** | **RGB** **S**o**L**i**D**; display a solid color (in RGB Hexidecimal) on all pixels (e.g., ''RGBSLD FFD700'' [''brightness'']), returns ''OK'' | 
-| **RGBDMO** | **RGB** **DE**m**O**; cycle through all the preceding patterns, changing every 10 seconds, returns ''OK'' | +| **RGBSNO** | **RGB** **SNO**w; snow effect; optionally takes a hue color (in RGB Hexidecimal, otherwise default #FFFFFF is used) (e.g., ''RGBSNO'' [''FFFFFF''] [''brightness'']), returns ''OK'' | 
-| **RGBTST** | **RGB** **TE**s**T**; color cycle the first and last pixel of the RGB string (endpoints test), returns ''OK'' | +| **RGBTST** | **RGB** **TE**s**T**; color cycle the first and last pixel of the RGB string (endpoints test) (e.g., ''RGBTST'' [''brightness'']), returns ''OK'' | 
-| **SETRGB** | **SET** **RGB** configuration; returns ''OK'' and restarts after 3 seconds; (e.g., ''SETRGB 325 12 2900'') [''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''] |+| **RGBTWK** | **RGB** **TW**in**K**le; random twinkle effect (e.g., ''RGBTWK'' [''brightness'']), returns ''OK'' | 
 +| **RGBWPE** | **RGB** **W**i**PE**; color wipe (e.g., ''RGBWPE'' [''brightness'']), returns ''OK'' | 
 + 
 + 
 +==== RGB Hardware Support ==== 
 + 
 +RGB LED support is provided through various headers, depending on the hardware. Certain hardware configurations require amounts of soldering and electronics design skill to modify, and can damage the board if current draw or other limits are exceeded. Mods are performed solely at user's risk. 
 + 
 + 
 +==== ClawGear ==== 
 + 
 +The ClawGear supports a **maximum** of 42, 5 VDC, WS2811-protocol RGB LED pixels on the Servo 2 connector: 
 + 
 +{{ :en:dev:clawgear_rgb_connections.png?200 |}} 
 + 
 + 
 +==== MiTail ==== 
 + 
 +The MiTail supports **externally-powered**, WS2811-protocol RGB LED pixels on the serial console connector. Note that a level-shifter may need to be used to address voltage-level disparities between the RGB strip and the controller. An [[https://www.adafruit.com/product/6066|Adafruit Pixel Shifter]] is an excellent choice for this. 
 + 
 +{{ :en:dev:mitail_rgb_connections.png?200 |}} 
 + 
 + 
 +==== MiTail Mini ==== 
 + 
 +The MiTail Mini supports a **maximum** of 42, 5 VDC, WS2811-protocol RGB LED pixels on the Servo 2 connector: 
 + 
 +{{ :en:dev:mitail_mini_rgb_connections.png?200 |}}
  
  
Line 194: Line 246:
  
 | **BATT** | **BATT**ery percentage, returns the integer value of estimated battery capacity remaining  (e.g., ''61'') | | **BATT** | **BATT**ery percentage, returns the integer value of estimated battery capacity remaining  (e.g., ''61'') |
-| **READCONF** | **READ** running **CONF**iguration; returns space-delimited running configuration parameters (e.g., ''READCONF 1 ABCDEF 5 0 15 40 3 8 0 0 1 3 0 1 0 1 1 495974 325 12 2900'') [''ver'' ''myColor'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey'' ''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''] | +| **READCONF** | **READ** running **CONF**iguration; returns space-delimited running configuration parameters (e.g., ''READCONF 1 5 0 15 40 3 8 0 0 1 3 0 1 0 1 1 495974 325 12 2900'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey'' ''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''] | 
-| **WRITECONF** | **WRITE** **CONF**iguration to NVS and set running configuration to match (e.g., ''WRITECONF 1 ABCDEF 5 0 15 40 3 8 0 0 1 3 0 1 0 1 1 495974 325 12 2900'') [''ver'' ''myColor'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey'' ''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''], returns ''OK'' |+| **WRITECONF** | **WRITE** **CONF**iguration to NVS and set running configuration to match (e.g., ''WRITECONF 1 5 0 15 40 3 8 0 0 1 3 0 1 0 1 1 495974 325 12 2900'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey'' ''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''], returns ''OK'' |
 | **SETDISCONNECTEDCOUNT** | **SET** BLE **DISCONNECTED** power off **COUNT**down parameter in NVS and running configuration (in minutes, ''SETDISCONNECTEDCOUNT 0'' disables automatic poweroff), returns ''OK'' | | **SETDISCONNECTEDCOUNT** | **SET** BLE **DISCONNECTED** power off **COUNT**down parameter in NVS and running configuration (in minutes, ''SETDISCONNECTEDCOUNT 0'' disables automatic poweroff), returns ''OK'' |
-| **SETHOLDONSTOP** | **SET** servo **HOLD** is maintained when the servos **STOP** (maintains servo PWM when not moving, default for EarGear 2); returns ''OK'' | +| **SETHOLDONSTOP** | **SET** whether servo **HOLD** is maintained when the servos **STOP** in NVS and running configuration (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** in NVS and running configuration (servo PWM is dropped when not moving, default for tail-based devices and ClawGear); 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'') in NVS and running configuration, **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 in NVS and running configuration; 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'' | +| **SETRGB** | **SET** **RGB** configuration in NVS and running configuration; returns ''OK'' and restarts after 3 seconds; (e.g., ''SETRGB 325 12 2900'') [''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''; **NOTE:** the ''nomRGBVolt'' and ''maxRGBmAmp'' are not currently utilized internally, but are required.] | 
-| **SETMYCOLOR** | **SET** **MYCOLOR** to persist in app UI display for this device (e.g., ''SETMYCOLOR FFD700''); returns ''OK'' | +| **UNSETLISTENMOVES** | **UNSET** internal **LISTEN** Mode **MOVES** to play on a listen event in NVS and running configuration, 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'' | 
-| **SETTILTMOVES** | **SET** internal **LISTEN** Mode **MOVES** to play on a tilt event in addition to sending event notifications; returns ''OK'' | +| **SETTILTMOVES** | **SET** internal **LISTEN** Mode **MOVES** to play on a tilt event in addition to sending event notifications in NVS and running configuration; returns ''OK'' | 
-| **UNSETTILTMOVES** | **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'' |+| **UNSETTILTMOVES** | **UNSET** internal **LISTEN** Mode **MOVES** to play on a listen event in NVS and running configuration, 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'' |
 | **OTA** | Starts firmware **O**ver **T**he **A**ir update process (e.g., ''OTA <expected size in bytes> <expected MD5>''); returns ''BEGIN OTA'' or ''ERR'' on failure to start, ''OTA SUCCESS'' on success, or ''OTA ERR'' on error during OTA process | | **OTA** | Starts firmware **O**ver **T**he **A**ir update process (e.g., ''OTA <expected size in bytes> <expected MD5>''); returns ''BEGIN OTA'' or ''ERR'' on failure to start, ''OTA SUCCESS'' on success, or ''OTA ERR'' on error during OTA process |
 | **FORMATNVS** | **FORMAT** **NVS** (erase all contents of the default NVS partition, including BLE bonds), returns ''OK'' and reboots after 3 seconds | | **FORMATNVS** | **FORMAT** **NVS** (erase all contents of the default NVS partition, including BLE bonds), returns ''OK'' and reboots after 3 seconds |
-| **READNVS** | **READ** **CONF**iguration from NVS; returns space-delimited configuration parameters stored in NVS (e.g., ''READNVS 1 ABCDEF 5 0 15 40 3 8 0 0 1 3 0 1 0 1 1 495974 325 12 2900'') [''ver'' ''myColor'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey'' ''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''] |+| **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 1 3 0 1 0 1 1 495974 325 12 2900'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey'' ''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''] |
 | **REBOOT** | **REBOOT**; returns ''OK'' and reboots after 3 seconds | | **REBOOT** | **REBOOT**; returns ''OK'' and reboots after 3 seconds |
 | **TASKU** | Prints to the hardware serial console the minimum amount of remaining stack space that was available to the task since the task started executing (high water mark), returns ''OK'' | | **TASKU** | Prints to the hardware serial console the minimum amount of remaining stack space that was available to the task since the task started executing (high water mark), returns ''OK'' |
Line 233: Line 285:
   * Parameters can be separated by any character that is not a number or a letter (e.g., space, comma, semicolon). However, the letters themselves act as separators, and it is recommended that no additional characters are used, as the serial buffer has a limited capacity and may not be able to store the whole instruction.   * Parameters can be separated by any character that is not a number or a letter (e.g., space, comma, semicolon). However, the letters themselves act as separators, and it is recommended that no additional characters are used, as the serial buffer has a limited capacity and may not be able to store the whole instruction.
   * Depending on the tail and position, it can sag out of the commanded position when servo power is released at the end of the DSSP move. This may cause a visual defect of jerking back into the previous position when the next move starts.   * Depending on the tail and position, it can sag out of the commanded position when servo power is released at the end of the DSSP move. This may cause a visual defect of jerking back into the previous position when the next move starts.
 +
  
 ==== DSSP Example ==== ==== DSSP Example ====
Line 279: Line 332:
  
 {{:en:dev:position_limits_visualization.png?400|}} {{:en:dev:position_limits_visualization.png?400|}}
 +
  
 ==== USERMOVE Examples ==== ==== USERMOVE Examples ====
 +
  
 === Example 1 – Slow Wag 1 (same as the ''TAILS1'' command) === === Example 1 – Slow Wag 1 (same as the ''TAILS1'' command) ===
Line 298: Line 353:
   * **L75L75** Position 2 is reached in 75 * 20 ms = 1.5 s; return to Position 1 in the same time     * **L75L75** Position 2 is reached in 75 * 20 ms = 1.5 s; return to Position 1 in the same time  
   * **H1** Home at end of move   * **H1** Home at end of move
 +
  
 === Example 2 – Test Servos === === Example 2 – Test Servos ===
Line 318: Line 374:
 Because no easing parameters (''E'' or ''F'') are specified, no easing is used by default. Because no easing parameters (''E'' or ''F'') are specified, no easing is used by default.
 </WRAP> </WRAP>
 +
  
 ==== USERLEDS Examples ==== ==== USERLEDS Examples ====
 +
  
 === Example 1 – Beacon (same as the ''LEDBEA'' command) === === Example 1 – Beacon (same as the ''LEDBEA'' command) ===
Line 345: Line 403:
   * **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
- 
- 
-===== Autonomous Mode ===== 
- 
-Defines a sequence of random moves, selected from any of three groups as below; interval between moves varies randomly 
-from T1 to T2. 
- 
-**AUTOMODE G<n>[G<n> ... [G<n>]] T<nnn>T<nnn>T<nnn>** 
- 
-The tail will select a random move from the specified group(s), pausing for a random number of seconds between each move (min and max specified by the first and second ''T'' parameter, respectively). The tail will stop completely after the time passed by the 3rd ''T'' parameter. 
- 
-Autonomous Mode is ended (after completing any ongoing move) if a BLE connection is made. 
- 
-^ Group  ^ Move Group Name  ^ Move List  ^ 
-| 1 | Calm and Relaxed | Slow Wag 1, Slow Wag 2, Slow Wag 3 | 
-| 2 | Fast and Excited | Fast Wag, Short Wag, Happy Wag, Erect | 
-| 3 | Frustrated and Tense | Tremble 1, Tremble 2, Tremble Erect, High Wag | 
- 
-The parameter order is not important, except that the three ''T'' parameters are interpreted in the order specified below. 
- 
-^ Prefix  ^ Parameter Type  ^ Range of Values  ^ 
-| **G** | Move Group (see table above) | <1 ... 3> | 
-| **T1** | Minimum random pause between moves in 1-second increments | <1 ... 240> (1 s ... 4 min) | 
-| **T2** | Maximum random pause between moves in 1-second increments | <1 ... 240> (1 s ... 4 min) | 
-| **T3** | Total duration in 15-second increments | <1 ... 240> (15 s ... 60 min); <251 ... 254> are reserved, see [[en:dev:tailcontrol-command-protocol#no-phone_mode|No-phone Mode]], below) | 
- 
-**STOPAUTO** 
- 
-''STOPAUTO'' will abort the current Autonomous Mode after completing any ongoing move. 
  
  
Line 386: Line 415:
 <WRAP round important 90%> <WRAP round important 90%>
 Do **NOT** attempt to use Conference Mode on TailControl firmware prior to 5.3.0, or a condition requiring repair of the control board can occur.</WRAP> Do **NOT** attempt to use Conference Mode on TailControl firmware prior to 5.3.0, or a condition requiring repair of the control board can occur.</WRAP>
 +
 +
 ==== Enabling Conference Mode (Pairing and Binding) ==== ==== Enabling Conference Mode (Pairing and Binding) ====
  
Line 393: Line 424:
  
 The device will then reboot after 3 seconds. Conference Mode is then enabled, and pairing proceeds. The user's phone (or other device) will prompt for the passkey (which was set earlier), and the bond will be established on both devices. After that, the passkey or a previous bond (up to 3 can be stored) will be required to connect to the device. The device will then reboot after 3 seconds. Conference Mode is then enabled, and pairing proceeds. The user's phone (or other device) will prompt for the passkey (which was set earlier), and the bond will be established on both devices. After that, the passkey or a previous bond (up to 3 can be stored) will be required to connect to the device.
 +
  
 ==== Disabling Conference Mode ==== ==== Disabling Conference Mode ====
Line 400: Line 432:
 **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 409: Line 442:
  
   * 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 423: Line 456:
  
  
-===== iOS Casual Mode =====+===== Listen Mode =====
  
-<WRAP round todo 90%> +Listen Mode is only available on the EarGear 2. When Listen Mode is active, a detected sound above ambient will send a ''LISTEN BANG CENTER'', ''LISTEN BANG LEFT'', or ''LISTEN BANG RIGHT'' message (depending on the detected sound direction) will be sent back to the client. If ''listenModeMovEn'' is set (default), then the firmware move will be triggered, otherwise the controlling app will be expected to send a move (if desired).
-This feature is pending removal in a future release. +
-</WRAP>+
  
-Because the CRUMPET application is not currently permitted to manage the tail while the iOS application is in the background, the application uses the ''AUTOMODE'' command to have the tail emulate the Casual Mode behavior on-board the tail (Note there is a typo in the string the iOS app sends: there is no space between the command and the first parameter):+''LISTEN ARMED'' is sent to the debug console (but not currently to the BLE terminal) after all conditions to re-trigger have been met.
  
-**AUTOMODEG1  T15 T100 T240**+Triggering by Listen Mode is inhibited when the ears are in motion, as well as a 3-second counter that runs once a sound trigger has finished executing a move.
  
-Note that the ''G'' and the first two ''T'' parameters will depend on the selections made in the app. 
  
-Important! The minimum random pause cannot be less that 15 seconds.+===== No-phone Mode =====
  
-==== iOS Casual Mode Example ====+Perform random moves while disconnected from a BLE client, selected from any of three groups as below; interval between moves varies randomly from T1 to T2. This feature is comparable to Casual Mode in the app.
  
-**AUTOMODE T15T60T240 G1G2**+**AUTOMODE G<n>[G<n>[G<n>]] T<1 ... 240>T<1 ... 240>T<251 ... 254>**
  
-  * **T15** 15-second minimum random pause between moves +The tail will select a random move from the specified group(s), pausing for a random number of seconds between each move (min and max specified by the first and second ''T'' parameter, respectively). The tail will stop completely after the time passed by the 3rd ''T'' parameter.
-  * **T60** 60-second (1 minute) maximum random pause between moves +
-  * **T240** 3600-second (240 * 15 = 3600 s = 1 hour) total duration of Autonomous Mode +
-  * **G1G2** Randomly select a move from groups 1 and 2+
  
 +No-phone Mode is suspended (after completing any ongoing move) if a BLE connection is made. It will resume after BLE is disconnected.
  
-===== Listen Mode =====+^ Group  ^ Move Group Name  ^ Move List  ^ 
 +| 1 | Calm and Relaxed | Slow Wag 1, Slow Wag 2, Slow Wag 3 | 
 +| 2 | Fast and Excited | Fast Wag, Short Wag, Happy Wag, Erect | 
 +| 3 | Frustrated and Tense | Tremble 1, Tremble 2, Tremble Erect, High Wag |
  
-Listen Mode is only available on the EarGear 2. When Listen Mode is active, a detected sound above ambient will trigger a random move and a ''LISTEN BANG'' message will be sent back to the client. If ''listenModeMovEn'' is set (default), then the firmware move will be triggered, otherwise the controlling app will be expected to send a move (if desired).+The parameter order is not important, except that the three ''T'' parameters are interpreted in the order specified below.
  
-Development support for basic sound localization for future hardware is supported, replacing the ''LISTEN BANG'' response with  +^ Prefix  ^ Parameter Type  ^ Range of Values  ^ 
-''LISTEN BANG CENTER'', ''LISTEN BANG LEFT'', and ''LISTEN BANG RIGHT'', respectively.+| **G** | Move Group (see table above) | <1 ... 3> | 
 +| **T1** | Minimum random pause between moves in 1-second increments | <1 ... 240> (1 s ... 4 min) | 
 +| **T2** | Maximum random pause between moves in 1-second increments | <1 ... 240> (1 s ... 4 min) | 
 +| **T3** | Delay to wait for BLE connection before starting NPM | <25**1** ... 25**4**> (1 ... 4 min) |
  
-''LISTEN ARMED'' is sent to the debug console (but not currently to the BLE terminal) after all conditions to re-trigger have been met.+No-phone Mode (NPM) will cause the tail to delay one to four minutes (based on the setting of the third ''T'' parameter of 25**1** through 25**4**) to wait for a BLE connection. If no BLE connection is made during that time, the tail will select a random move from the specified group(s), pausing for a random number of seconds between each move (min and max specified by the first and second ''T'' parameter, respectively).
  
-Triggering by Listen Mode is inhibited when the ears are in motion, as well as a 3-second counter that runs once a sound trigger has finished executing a move.+No-phone Mode is suspended (after completing any ongoing move) if a BLE connection is made. It will resume after BLE is disconnected.
  
 +**STOPNPM**
  
-===== No-phone Mode =====+Stops No-phone mode and disables it in NVS configuration.
  
-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>**+==== No-phone Mode Example ====
  
-No-phone Mode (NPM) will cause the tail to delay one to four minutes (based on the setting of the third ''T'' parameter of 25**1** through 25**4**) to wait for a BLE connection. If no BLE connection is made during that time, the tail will select a random move from the specified group(s), pausing for a random number of seconds between each move (min and max specified by the first and second ''T'' parameter, respectively).+**AUTOMODE T15T60T243 G1G2**
  
-No-phone Mode is suspended (after completing any ongoing move) if a BLE connection is made. It will resume after BLE is disconnected.+  * **T15** 15-second minimum random pause between moves 
 +  * **T60** 60-second (1 minute) maximum random pause between moves 
 +  * **T240** 3600-second (240 * 15 = 3600 s = 1 hour) total duration of Autonomous Mode 
 +  * **G1G2** Randomly select a move from groups 1 and 2
  
-**STOPNPM** 
  
-Stops No-phone mode and disables it in NVS configuration.+===== Tilt Mode =====
  
 +Tilt Mode is only available on the ClawGear and EarGear 2. When Listen Mode is active, a detected tilt will send a ''TILT FORWARD'', ''TILT BACKWARD'', ''TILT LEFT'', or ''TILT RIGHT'' message (depending on the tilt direction) will be sent back to the client. If ''tiltModeMovesEnabled'' is set (default), then the firmware move will be triggered, otherwise the controlling app will be expected to send a move (if desired).
 +
 +Triggering by Tilt Mode is inhibited when the ears are in motion, as well as a 3-second counter that runs once a sound trigger has finished executing a move AND the ClawGear/EarGear 2 has returned to the neutral tilt position during that time. This prevents tilt re-triggering if the user stays in the tilt position for an extended time.
 +
 +
 +==== Notes about ClawGear Tilt Mode ====
 +
 +The minimum tilt is 75° of pitch for up, and −75° for down. Pitch is ''atan2(ay, az)'' from the low-pass-filtered accelerometer data, where 0° means flat, a state triggers when that distance is 15° or less. The 5° gap between entering and exiting is hysteresis, which stops the state from flickering near the edge. Once UP or DOWN triggers, the pitch has to come back past ±70° before the state returns to NEUTRAL.
 +
 +Invalid readings: if ''sqrt(ay² + az²) < 0.10 g'' (the device is lying on its side), the classifier keeps the last state and doesn't reclassify.
 +
 +ClawGear does not have a cooldown timer enabled on it's Tilt Mode.
 +
 +
 +==== Notes about EarGear 2 Tilt Mode ====
  
-===== Tilt Mode ===== 
  
-Tilt Mode is only available on the EarGear 2. When Listen Mode is active, a detected sound above ambient will trigger a random move and a ''TILT FORWARD'', ''TILT BACKWARD'', ''TILT LEFT'', or ''TILT RIGHT'' message (depending on the tilt direction) will be sent back to the client. If tiltModeMovesEnabled is set (default), then the firmware move will be triggered, otherwise the controlling app will be expected to send a move (if desired).+In order to prevent erratic and constant movement of the ears while Tilt Mode is enabled, there is a reset and cooldown timer. The way it works is once the ears move out of the "dead zone," which is 14° off of center, the associated move is played. While the ears are moving, the tilt classifier is suspended (because the ear movement itself is tilting the ears). Once the ears have stopped moving, a 3000 ms (3 sec) cooldown is started. Once that timer has expired, the tilt triggers are re-enabled if the ears have EITHER returned to the center at any time during the cooldown timer OR have tilted to another trigger position other than the one that last triggered.
  
-Triggering by Tilt Mode is inhibited when the ears are in motion, as well as a 3-second counter that runs once a sound trigger has finished executing a move AND the EarGear 2 has returned to the neutral tilt position during that time. This prevents tilt re-triggering if the user stays in the tilt position for an extended time.+<code> 
 +[xx:xx:03]INFO recvWithEndMarker(): COM value: 'TILTMODE'.   
 +[xx:xx:03]OK   
 +[xx:xx:03]TILT BACKWARD   
 +[xx:xx:03]INFO setMove(): new command 'TAILHA'.   
 +[xx:xx:03]TAILHA BEGIN   
 +[xx:xx:07]INFO updateMove(): Cycle 0 move patterns complete.   
 +[xx:xx:07]All pattern cycles complete.   
 +[xx:xx:07]INFO updateMove(): Move sequence complete (3419 ms).   
 +[xx:xx:07]Move sequence complete (3419 ms).   
 +[xx:xx:08]Tilt cooldown countdown: 3000 ms.   
 +[xx:xx:09]Tilt cooldown countdown: 2500 ms.   
 +[xx:xx:09]Tilt cooldown countdown: 2000 ms.   
 +[xx:xx:10]Tilt cooldown countdown: 1500 ms.   
 +[xx:xx:10]Tilt cooldown countdown: 1000 ms.   
 +[xx:xx:11]Tilt cooldown countdown: 500 ms.   
 +[xx:xx:11]Tilt cooldown ended.   
 +[xx:xx:11]Returned to center, tilt holdoff released.   
 +</code>
  
  
 == 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. == == 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. ==