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:33] – [No-phone Mode] darkgrueen:dev:tailcontrol-command-protocol [2026/07/04 19:44] (current) – darkgrue
Line 9: Line 9:
 **IMPORTANT NOTICE:** TailControl and the TailControl Protocol is still under development. Some commands and features described here relate to a future release and are subject to change. **IMPORTANT NOTICE:** TailControl and the TailControl Protocol is still under development. Some commands and features described here relate to a future release and are subject to change.
 </WRAP> </WRAP>
 +
  
 ===== Bluetooth Low Energy (BLE) ===== ===== Bluetooth Low Energy (BLE) =====
Line 14: 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:
Line 46: Line 46:
 For tail-series (MiTail, MiTail Mini, and FlutterWings) v3.6 controller hardware, the battery charging characteristic is unset (charging state is not available). For tail-series (MiTail, MiTail Mini, and FlutterWings) v3.6 controller hardware, the battery charging characteristic is unset (charging state is not available).
 </WRAP> </WRAP>
 +
  
 ===== TailControl Device Indicators ===== ===== TailControl Device Indicators =====
Line 93: Line 94:
  
  
-==== 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 156: Line 157:
 | **STOPTILT** (or **ENDTILTMODE**) | Stops Tilt Mode ([[#Tilt 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'' | | **TILTMODE** (or **TILTMODE START**) | Starts Tilt Mode ([[#Tilt Mode|see below]]), returns ''OK'' |
 +
  
 ===== RGB LED Commands ===== ===== RGB LED Commands =====
 +
 +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'' | +| **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'' | 
-| **RGBRB2** | **RGB** **R**ain**B**ow pattern with random sparkly glitter, 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'' | 
-| **RGBCON** | **RGB** **CON**fetti; random-colored speckles that blink in and fade smoothly, returns ''OK'' | +| **RGBDMO** | **RGB** **DE**m**O**; cycle through all the preceding patterns, changing every 10 seconds (e.g., ''RGBDMO'' [''brightness'']); returns ''OK'' | 
-| **RGBSIN** | **RGB** **SIN**e; a colored dot sweeping back and forth, with fading trails, returns ''OK'' | +| **RGBFDE** | **RGB** **F**a**DE**; fade in/out effect (e.g., ''RGBFDE'' [''brightness'']), returns ''OK'' | 
-| **RGBJUG** | **RGB** **JUG**gle; eight colored dots, weaving in and out of sync with each other, returns ''OK'' | +| **RGBFIR** | **RGB** **FIR**e; fire effect (e.g., ''RGBFIR'' [''brightness'']), returns ''OK'' | 
-| **RGBBPM** | **RGB** **BPM**; colored stripes pulsing at a defined Beats-Per-Minute, returns ''OK'' | +| **RGBRBW** | **RGB** **R**ain**B**o**W** pattern (e.g., ''RGBRBW'' [''brightness'']), returns ''OK'' | 
-| **RGBDMO** | **RGB** **DE**m**O**; cycle through all the preceding patterns, changing every 10 seconds, 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'' | 
-| **RGBTST** | **RGB** **TE**s**T**; color cycle the first and last pixel of the RGB string (endpoints test), 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'' | 
-| **SETRGB** | **SET** **RGB** configuration; returns ''OK'' and restarts after 3 seconds; (e.g., ''SETRGB 325 12 2900'') [''numRGBLEDs'' ''maxRGBVolt'' ''maxRGBmAmp''] |+| **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'' | 
 +| **SETRGB** | **SET** **RGB** configuration; returns ''OK'' and restarts after 3 seconds; (e.g., ''SETRGB 325 12 2900'') [''numRGBLEDs'' ''nomRGBVolt'' ''maxRGBmAmp''] | 
  
 ===== Other Commands ===== ===== Other Commands =====
Line 189: Line 197:
  
 | **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 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''] | 
-| **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 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'' |
 | **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** servo **HOLD** is maintained when the servos **STOP** (maintains servo PWM when not moving, default for EarGear 2); returns ''OK'' |
Line 197: Line 205:
 | **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'' |
 +| **SETMYCOLOR** | **SET** **MYCOLOR** (in RGB Hexidecimal) to persist in app UI display for this device (e.g., ''SETMYCOLOR FFD700''); 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; 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, 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 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''] |
 | **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'' |
 +
 +
 ===== Directly Set Servo Position ===== ===== Directly Set Servo Position =====
  
Line 338: Line 349:
   * **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 401: Line 440:
 Important! The minimum random pause cannot be less that 15 seconds. Important! The minimum random pause cannot be less that 15 seconds.
  
 +==== iOS Casual Mode Example ====
  
 +**AUTOMODE T15T60T240 G1G2**
 +
 +  * **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
  
  
Line 420: Line 466:
 No-phone mode is a feature exclusive of MiTail firmware 4.0.0 or greater or TailControl. 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<1 ... 240>T<1 ... 240>T<251 ... 254>**+**AUTOMODE G<n>[G<n>[G<n>]] T<nnn>T<nnn>T<251 ... 254>**
  
 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). 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).
Line 429: Line 475:
  
 Stops No-phone mode and disables it in NVS configuration. Stops No-phone mode and disables it in NVS configuration.
- 
- 
-==== No-phone Mode Example ==== 
- 
-**AUTOMODE T15T60T243 G1G2** 
- 
-  * **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 
  
  
Line 448: Line 484:
  
  
-== 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. ==