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/05/16 04:42] – darkgrueen:dev:tailcontrol-command-protocol [2026/09/25 20:24] (current) – darkgrue
Line 67: 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.
  
  
Line 83: 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.
  
  
Line 182: Line 182:
 ===== RGB LED Commands ===== ===== RGB LED Commands =====
  
-RGB support is experimental, and not included in production firmware.+RGB support is new with the introduction of the ClawGear, and support is experimental on other hardware. 
 + 
 +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%).
  
 | **RGBOFF** | **RGB** LEDs **OFF**, returns ''OK'' | | **RGBOFF** | **RGB** LEDs **OFF**, returns ''OK'' |
-| **RGBRBO** | **RGB** **R**ain**B**ow pattern, returns ''OK'' | +| **RGBBRT** | Set **RGB** **BR**igh**T**ness percentage in NVS and running configuration (e.g., ''RGBBRT 100''), returns ''OK'' | 
-| **RGBRB2** | **RGB** **R**ain**B**ow pattern with random sparkly glitter, 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'' | 
-| **RGBCON** | **RGB** **CON**fetti; random-colored speckles that blink in and fade smoothly, 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'' | 
-| **RGBSIN** | **RGB** **SIN**e; a colored dot sweeping back and forth, with fading trails, returns ''OK'' | +| **RGBDMO** | **RGB** **DE**m**O**; cycle through all the preceding patterns, changing every 10 seconds (e.g., ''RGBDMO'' [''brightness'']); returns ''OK'' | 
-| **RGBJUG** | **RGB** **JUG**gle; eight colored dots, weaving in and out of sync with each other, returns ''OK'' | +| **RGBFDE** | **RGB** **F**a**DE**; fade in/out effect (e.g., ''RGBFDE'' [''brightness'']), returns ''OK'' | 
-| **RGBBPM** | **RGB** **BPM**; colored stripes pulsing at a defined Beats-Per-Minute, returns ''OK'' | +| **RGBFIR** | **RGB** **FIR**e; fire effect (e.g., ''RGBFIR'' [''brightness'']), returns ''OK'' | 
-| **RGBDMO** | **RGB** **DE**m**O**; cycle through all the preceding patterns, changing every 10 seconds, returns ''OK'' | +| **RGBRBW** | **RGB** **R**ain**B**o**W** pattern (e.g., ''RGBRBW'' [''brightness'']), returns ''OK'' | 
-| **RGBTST** | **RGB** **TE**s**T**; color cycle the first and last pixel of the RGB string (endpoints test), 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'' | 
-| **SETRGB** | **SET** **RGB** configuration; returns ''OK'' and restarts after 3 seconds; (e.g., ''SETRGB 325 12 2900'') [''numRGBLEDs'' ''maxRGBVolt'' ''maxRGBmAmp''] |+| **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) (e.g., ''RGBTST'' [''brightness'']), returns ''OK'' | 
 +| **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 215: 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 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'' ''maxRGBVolt'' ''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 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'' ''maxRGBVolt'' ''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 eac2h 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.] | 
-| **SETTILTMOVES** | **SET** internal **LISTEN** Mode **MOVES** to play on a tilt event in addition to sending event notifications; 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'' | 
-| **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'' |+| **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 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 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'' ''maxRGBVolt'' ''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 426: Line 458:
 ===== Listen Mode ===== ===== Listen Mode =====
  
-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). +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).
- +
-Development support for basic sound localization for future hardware is supported, replacing the ''LISTEN BANG'' response with  +
-''LISTEN BANG CENTER'', ''LISTEN BANG LEFT'', and ''LISTEN BANG RIGHT'', respectively.+
  
 ''LISTEN ARMED'' is sent to the debug console (but not currently to the BLE terminal) after all conditions to re-trigger have been met. ''LISTEN ARMED'' is sent to the debug console (but not currently to the BLE terminal) after all conditions to re-trigger have been met.
Line 480: Line 509:
 ===== 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).+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 ==== 
 + 
 + 
 +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. ==