Trace:

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 [2024/06/13 00:22] – darkgrueen:dev:tailcontrol-command-protocol [2025/06/21 14:27] (current) – [Conference Mode] darkgrue
Line 1: Line 1:
-====== TailCoNTROL Command Protocol ======+====== TailControl Command Protocol ======
  
  
-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 MiTail, MiTail Mini, FlutterWings, and EarGear 2, 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.
  
-**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 at this time, especially EarGear 2 features.+<WRAP round todo 90%> 
 +**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>
  
 ===== Bluetooth Low Energy (BLE) ===== ===== Bluetooth Low Energy (BLE) =====
  
-The hardware platform uses the "Just Works" Bluetooth Low Energy (BLE) pairing method to connect.+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.
  
  
Line 26: Line 28:
   * TX Characteristic is ''c6612b64-0087-4974-939e-68968ef294b0'', and the   * TX Characteristic is ''c6612b64-0087-4974-939e-68968ef294b0'', and the
   * Battery Voltage is ''b08fed02-0584-40ef-b006-aff7e0d24e13''.   * Battery Voltage is ''b08fed02-0584-40ef-b006-aff7e0d24e13''.
- 
-**Note:** For tail-series v3.6 controller hardware, the battery charging characteristic is unset (charging state is not available). 
  
 The BLE Device Service for the EarGear 2 is ''927dee04-ddd4-4582-8e42-69dc9fbfae66'': The BLE Device Service for the EarGear 2 is ''927dee04-ddd4-4582-8e42-69dc9fbfae66'':
Line 34: Line 34:
   * Battery Voltage is ''54fa919d-e8a8-4841-b280-c5461161304f''.   * 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''.
 +</WRAP>
 +
 +<WRAP round important 90%>
 +For tail-series (MiTail, MiTail Mini, and FlutterWings) v3.6 controller hardware, the battery charging characteristic is unset (charging state is not available).
 +</WRAP>
  
-===== TailCoNTROL Device Indicators =====+===== TailControl Device Indicators =====
  
 ==== Blue LED ==== ==== Blue LED ====
Line 83: Line 95:
 ==== Automatic Actions ==== ==== Automatic Actions ====
  
-TailCoNTROL will automatically shut down the device if there is no BLE connection for 5 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) [Note: to be moved to a configuration option in NVS in a future release].+TailControl will automatically shut down the device if there is no BLE connection for 5 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) [Note: to be moved to a configuration option in NVS in a future release].
  
 Additional automatic actions are described in [[en:dev:tailcontrol-command-protocol#No-phone Mode|No-phone Mode]], below. Additional automatic actions are described in [[en:dev:tailcontrol-command-protocol#No-phone Mode|No-phone Mode]], below.
  
  
-===== Tail Moves =====+===== Move Commands =====
  
 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.
Line 140: Line 152:
 ===== EarGear 2-only Commands ===== ===== EarGear 2-only Commands =====
  
-| **LISTENMODE** | Starts Listen Mode; [[#Listen Mode|see below]], returns ''OK'' | +| **LISTENMODE** (or **LISTEN FULL**) | Starts Listen Mode ([[#Listen Mode|see below]]), returns ''OK'' | 
-| **STOPLISTEN** | Stops Listen Mode; [[#Listen Mode|see below]], returns ''OK'' | +| **STOPLISTEN** (or **ENDLISTEN**) | Stops Listen Mode ([[#Listen Mode|see below]]), returns ''OK'' | 
-| **STOPTILT** | Stops Tilt Mode; [[#Tilt Mode|see below]], returns ''OK'' | +| **STOPTILT** (or **ENDTILTMODE**) | Stops Tilt Mode ([[#Tilt Mode|see below]]), returns ''OK'' | 
-| **TILTMODE** | 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 =====
 +
 +| **RGBOFF** | **RGB** LEDs **OFF**, returns ''OK'' |
 +| **RGBRBO** | **RGB** **R**ain**B**ow pattern, returns ''OK'' |
 +| **RGBRB2** | **RGB** **R**ain**B**ow pattern with random sparkly glitter, returns ''OK'' |
 +| **RGBCON** | **RGB** **CON**fetti; random-colored speckles that blink in and fade smoothly, returns ''OK'' |
 +| **RGBSIN** | **RGB** **SIN**e; a colored dot sweeping back and forth, with fading trails, returns ''OK'' |
 +| **RGBJUG** | **RGB** **JUG**gle; eight colored dots, weaving in and out of sync with each other, returns ''OK'' |
 +| **RGBBPM** | **RGB** **BPM**; colored stripes pulsing at a defined Beats-Per-Minute, returns ''OK'' |
 +| **RGBDMO** | **RGB** **DE**m**O**; cycle through all the preceding patterns, changing every 10 seconds, returns ''OK'' |
 +| **RGBTST** | **RGB** **TE**s**T**; color cycle the first and last pixel of the RGB string (endpoints test), returns ''OK'' |
 +| **SETRGB** | **SET** **RGB** configuration and restart after 3 seconds; (e.g., ''SETRGB 325 12 2900''), returns ''OK'' [''numRGBLEDs'' ''maxRGBVolt'' ''maxRGBmAmp''] |
  
 ===== Other Commands ===== ===== Other Commands =====
  
-| **AUTOMODE** | **AUTO**nomous **MO**de; [[#Autonomous Mode|see below]], returns ''OK'' | +| **AUTOMODE** | **AUTO**nomous **MO**de ([[#Autonomous Mode|see below]]), returns ''OK'' | 
-| **DSSP** | **D**irectly **S**et **S**ervo **P**osition; [[#Directly Set Servo Position|see below]], returns ''OK'' |+| **DSSP** | **D**irectly **S**et **S**ervo **P**osition ([[#Directly Set Servo Position|see below]]), returns ''OK'' |
 | **HWVER** | Returns **H**ard**W**are **VER**sion; returns ''HWVER LEGACY MITAIL'' or ''HWVER MITAIL x.x'' for tail-series controller hardware, ''HWVER EG2 x.x'' for EarGear 2 controller hardware | | **HWVER** | Returns **H**ard**W**are **VER**sion; returns ''HWVER LEGACY MITAIL'' or ''HWVER MITAIL x.x'' for tail-series controller hardware, ''HWVER EG2 x.x'' for EarGear 2 controller hardware |
 | **PING** | Keepalive heartbeat (from application), returns ''PONG'' | | **PING** | Keepalive heartbeat (from application), returns ''PONG'' |
-| **SETPUSSKEY** | **SET** **P**a**SSKEY**, enable Conference Mode and restart after 3 seconds; [[#Conference Mode|see below]], returns ''OK'' |+| **SETPUSSKEY** | **SET** **P**a**SSKEY**, enable Conference Mode, and restart after 3 seconds ([[#Conference Mode|see below]]), returns ''OK'' |
 | **SHUTDOWN** | **SHUT DOWN** the unit (will lose the BLE connection), returns ''SHUTDOWN BEGIN'' or ''ERR'' if charger is attached | | **SHUTDOWN** | **SHUT DOWN** the unit (will lose the BLE connection), returns ''SHUTDOWN BEGIN'' or ''ERR'' if charger is attached |
 | **STOPAUTO** | **STOP AUTO**nomous Mode, returns ''OK'', followed by ''AUTO END'' | | **STOPAUTO** | **STOP AUTO**nomous Mode, 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'' | | **STOPNPM** | **STOP** **N**o-**P**hone **M**ode and disables it in NVS configuration; returns ''OK'', followed by ''AUTO END'' |
-| **USERMOVE** | [[#User-defined Tail Moves and LEDs 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 and restart after 3 seconds; [[#Conference Mode|see below]], returns ''OK'' | +| **STOPPUSSKEY** | **STOP** **P**a**SSKEY**, disable Conference Mode and restart after 3 seconds ([[#Conference Mode|see below]]), returns ''OK'' | 
-| **USERLEDS** | [[#User-defined Tail Moves and LEDs 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; ''VER x.x.x'', followed by a second message: either ''GLOWTIP FALSE'' if a Glow Tip is not connected, or ''GLOWTIP TRUE'' if one is |+| **VER** | Returns the firmware **VER**sion number; ''VER x.x.x''; 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 165: Line 189:
  
 | **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''] |
 +| **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''), returns ''OK'' [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey'' ''numRGBLEDs'' ''maxRGBVolt'' ''maxRGBmAmp''] |
 +| **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'' |
 +| **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'' |
 +| **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) and reboot | | **FORMATNVS** | **FORMAT** **NVS** (erase all contents of the default NVS partition, including BLE bonds) and reboot |
-| **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 | +| **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''] |
-| **READCONF** | **READ** running **CONF**iguration; returns space-delimited configuration parameters (e.g., ''1 5 0 15 40 3 8 0 0 1 0 123456'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey''] | +
-| **READNVS** | **READ** **CONF**iguration from NVS; returns space-delimited configuration parameters (e.g., ''1 5 0 15 40 3 8 0 0 1 0 123456'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey''] |+
 | **REBOOT** | **REBOOT** after 3 seconds, returns ''OK'' | | **REBOOT** | **REBOOT** after 3 seconds, 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'' | +| **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 in words of remaining stack space that was available to the task since the task started executing, 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 0 123456''), returns ''OK'' [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey''] | +
 ===== Directly Set Servo Position ===== ===== Directly Set Servo Position =====
  
Line 183: Line 209:
  
 ^ Prefix ^ Parameter Type  ^ Range of Values for Moves  ^ ^ Prefix ^ Parameter Type  ^ Range of Values for Moves  ^
-| **E** | Easing function to apply to Servo 1 | Default is Linear, if not specified.\\ As per [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]];\\ e.g., 0 = Linear (no easing), 129 = Quadratic, 130 = Cubic,  131 = Quartic |+| **E** | Easing function to apply to Servo 1 | Default is Linear (no easing), if not specified.\\ This is the decimal representation of the (hexadecimal) easing type enumeration, as per [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]] (e.g., 0 = Linear, 129 = Quadratic in/out, 130 = Cubic in/out,  131 = Quartic in/out). |
 | **F** | Easing function to apply to Servo 2 | (Same as **E**) | | **F** | Easing function to apply to Servo 2 | (Same as **E**) |
 | **A** | Point for Servo 1 | <0 ... 8>\\ 0 -> 25 degrees\\ 1 -> 41 degrees\\ 2 -> 58 degrees\\ ...\\ 8 -> 160 degrees | | **A** | Point for Servo 1 | <0 ... 8>\\ 0 -> 25 degrees\\ 1 -> 41 degrees\\ 2 -> 58 degrees\\ ...\\ 8 -> 160 degrees |
Line 194: Line 220:
   * Parameters of type **A**, **B**, **E**, **F**, **H**, **L**, and **M** can appear in any order (e.g., ''AABBSS'', ''ABABSS'', ''ABSABS'').   * Parameters of type **A**, **B**, **E**, **F**, **H**, **L**, and **M** can appear in any order (e.g., ''AABBSS'', ''ABABSS'', ''ABSABS'').
   * 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 jerking back into 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 202: Line 228:
  
  
-===== User-defined Tail Moves and LEDs Patterns =====+===== User-defined Moves and Glow Tip Patterns =====
  
-Up to 4 user-defined move definitions and 4 LED patterns can be sent over the BT/BLE connection and assigned to user+Up to 4 user-defined move definitions and 4 Glow Tip LED patterns can be sent over the BT/BLE connection and assigned to user
 presets (callable with the ''TAILU1'' ... ''TAILU4'' commands). These presets will be lost once the unit is powered off. presets (callable with the ''TAILU1'' ... ''TAILU4'' commands). These presets will be lost once the unit is powered off.
  
-The two instructions used to send a tail move or a Glow Tip LED pattern definition follow the same syntax and consist of a+The two instructions used to send a move or a Glow Tip LED pattern definition follow the same syntax and consist of a
 keyword (''USERMOVE'' or ''USERLEDS'') followed by a number of parameters. These are letter-number pairs, where the letter keyword (''USERMOVE'' or ''USERLEDS'') followed by a number of parameters. These are letter-number pairs, where the letter
 defines the type of parameter (see table, below). defines the type of parameter (see table, below).
Line 215: Line 241:
 ^ Prefix ^ Parameter Type  ^ Range of Values for Moves  ^ ^ Prefix ^ Parameter Type  ^ Range of Values for Moves  ^
 | **U** | User preset number | <1 ... 4> | | **U** | User preset number | <1 ... 4> |
-| **E** | Easing function to apply to Servo 1 | Default is Linear, if not specified.\\ As per [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]];\\ e.g., 0 = Linear (no easing), 129 = Quadratic, 130 = Cubic,  131 = Quartic |+| **E** | Easing function to apply to Servo 1 | Default is Linear (no easing), if not specified.\\ This is the decimal representation of the (hexadecimal) easing type enumeration, as per [[https://github.com/ArminJo/ServoEasing/blob/bb19cd4cfd9e92fed3b0f91b90a7b2f7dd83094a/src/ServoEasing.h#L296|EaseTypes]] (e.g., 0 = Linear, 129 = Quadratic in/out, 130 = Cubic in/out,  131 = Quartic in/out). |
 | **F** | Easing function to apply to Servo 2 | (Same as **E**) | | **F** | Easing function to apply to Servo 2 | (Same as **E**) |
 | **A** | Point for Servo 1 | <0 ... 8>\\ 0 -> 25 degrees\\ 1 -> 41 degrees\\ 2 -> 58 degrees\\ ...\\ 8 -> 160 degrees | | **A** | Point for Servo 1 | <0 ... 8>\\ 0 -> 25 degrees\\ 1 -> 41 degrees\\ 2 -> 58 degrees\\ ...\\ 8 -> 160 degrees |
Line 223: Line 249:
 | **H** | Move to home position at end of move | 0 = false (default), 1 = true | | **H** | Move to home position at end of move | 0 = false (default), 1 = true |
  
-===== USERMOVE Examples =====+**USERLEDS U<preset> P<numpoints> N<numcycles> A<point<sub>1</sub>> ... A<point<sub>n</sub>> [S|L]<numticks<sub>1</sub>> ... [S|L]<numticks<sub>n</sub>>**   
 + 
 +^ Prefix  ^ Parameter Type  ^ Range of Values for Glow Tip LEDs  ^ 
 +| **U** | User preset number | <1 ... 4> | 
 +| **P** | Number of points in the Glow Tip pattern | <1 ... 32> | 
 +| **N** | Number of cycles (times the pattern will be repeated) | <0 ... 255> | 
 +| **A** | Brightness point for Glow Tip | <0 ... 8>\\ 0 -> LEDs off\\ ...\\ 4 -> 50% intensity\\ ...\\ 8-> LEDs max intensity | 
 +| **S/L** | Time between the current point and the next (in 20 ms increments)\\ **S** will wait in the current position, then move to the next when the time has elapsed\\ **L** will gradually move from the current position to the next, over the time specified | 0 ... 127 (time * 20 ms) | 
 + 
 +**Notes:** 
 +  * Parameters of type **A**, **B**, **E**, **F**, **H**, **L**, **M**, and **S** can appear in any order (e.g., `EEAABBSS`, `ABAEBESS`, etc.). 
 +  * 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. 
 +  * Note the upper limit on the **P** parameter (and the consequential limit of moves in a move or LED pattern). 
 +  * There is a **128-character limit** on the serial input buffer. 
 + 
 +Position limits on the tail can be visualized as such: 
 + 
 +{{:en:dev:position_limits_visualization.png?400|}} 
 + 
 +==== USERMOVE Examples ====
  
-==== Example 1 – Slow Wag 1 (same as the ''TAILS1'' command) ====+=== Example 1 – Slow Wag 1 (same as the ''TAILS1'' command) ===
  
 Both servos move from 143° to 41° (position 7 to 1) and back, for 3 times; each cycle is (75 + 75) * 20 ms = 3 s long. Both servos move from 143° to 41° (position 7 to 1) and back, for 3 times; each cycle is (75 + 75) * 20 ms = 3 s long.
  
-**USERMOVE U1 P2 N3 E2E42 F2F42 A7A1 B7B1 L75L75 M75M75 H1**+**USERMOVE U1 P2 N3 E0E66 F0F66 A7A1 B7B1 L75L75 M75M75 H1**
  
   * **U1** Store into user preset 1     * **U1** Store into user preset 1  
   * **P2** The move consists of 2 points     * **P2** The move consists of 2 points  
   * **N3** Repeat the sequence 3 times     * **N3** Repeat the sequence 3 times  
-  * **E2E42** No easing   +  * **E0E66** Servo 1 move to Position 1 has no easing, move to Position 2 uses EASE_CUBIC_OUT (0x42) 
-  * **F2F42** No easing  +  * **F0F66** Servo 2 move to Position 1 has no easing, move to Position 2 uses EASE_CUBIC_OUT (0x42)
   * **A7A1** Servo 1 moves from 7 to 1 (143° to 41°)     * **A7A1** Servo 1 moves from 7 to 1 (143° to 41°)  
   * **B7B1** Servo 2 moves exactly as Servo 1     * **B7B1** Servo 2 moves exactly as Servo 1  
Line 242: Line 287:
   * **H1** Home at end of move   * **H1** Home at end of move
  
-==== Example 2 – Test Servos ====+=== Example 2 – Test Servos ===
  
 Moves servos in steps of 90° every 2 seconds; Servo 2 is delayed by 90°. Moves servos in steps of 90° every 2 seconds; Servo 2 is delayed by 90°.
Line 258: Line 303:
   * **H1** Home at end of move   * **H1** Home at end of move
  
-**USERLEDS U<preset> P<numpoints> N<numcycles> A<point<sub>1</sub>> ... A<point<sub>n</sub>> [S|L]<numticks<sub>1</sub>> ... [S|L]<numticks<sub>n</sub>>**  +<WRAP round info 90%> 
 +Because no easing parameters (''E'' or ''F'') are specified, no easing is used by default. 
 +</WRAP>
  
-^ Prefix  ^ Parameter Type  ^ Range of Values for Glow Tip LEDs  ^ +==== USERLEDS Examples ====
-| **U** | User preset number | <1 ... 4> | +
-| **P** | Number of points in the Glow Tip pattern | <1 ... 32> | +
-| **N** | Number of cycles (times the pattern will be repeated) | <0 ... 255> | +
-| **A** | Brightness point for Glow Tip | <0 ... 8>\\ 0 -> LEDs off\\ ...\\ 4 -> 50% intensity\\ ...\\ 8-> LEDs max intensity | +
-| **S/L** | Time between the current point and the next (in 20 ms increments)\\ **S** will wait in the current position, then move to the next when the time has elapsed\\ **L** will gradually move from the current position to the next, over the time specified | 0 ... 127 (time * 20 ms) | +
- +
-**Notes:** +
-  * Parameters of type **A**, **B**, **E**, **F**, **H**, **L**, **M**, and **S** can appear in any order (e.g., `EEAABBSS`, `ABAEBESS`, etc.). +
-  * 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. +
-  * Note the upper limit on the **P** parameter (and the consequential limit of moves in a move or LED pattern). +
-  * There is a **128-character limit** on the serial input buffer. +
- +
-===== USERLEDS Examples =====+
  
-==== Example 1 – Beacon (same as the ''LEDBEA'' command) ====+=== Example 1 – Beacon (same as the ''LEDBEA'' command) ===
  
 The Glow Tip LEDs light up for 100 ms every 1 s (Airbus A320 tail strobe). The Glow Tip LEDs light up for 100 ms every 1 s (Airbus A320 tail strobe).
Line 288: Line 322:
   * **S5S95** On for 5 * 20 ms = 100 ms; off for 50 * 20ms = 1 s     * **S5S95** On for 5 * 20 ms = 100 ms; off for 50 * 20ms = 1 s  
  
-==== Example 2 – Fade in/out (similar to ''LEDTRI'') ====+=== Example 2 – Fade in/out (similar to ''LEDTRI'') ===
  
 The Glow Tip LEDs light up slowly, then dim until completely off; this is repeated 3 times. The Glow Tip LEDs light up slowly, then dim until completely off; this is repeated 3 times.
Line 332: Line 366:
 ===== Conference Mode ===== ===== Conference Mode =====
  
-Conference mode pairs the user's phone with the TailCoNTROL device and establishes a bond that performs long-term storage of encryption info (particularly keys) so that the devices “know” each other and can easily reconnect in an encrypted way. This protects your device in a number of different ways:+Conference mode pairs the user's phone with the TailControl device and establishes a bond that performs long-term storage of encryption info (particularly keys) so that the devices “know” each other and can easily reconnect in an encrypted way. This protects your device in a number of different ways:
  
-  * Authentication: verifying the identity of the device connecting. +  * **Authentication:** verifying the identity of the device connecting. 
-  * MITM (Man In The Middle): process by which a third device impersonates the other two legitimate devices, in order to fool them into connecting to it. Both BLE central and peripheral will connect to the malicious device, which in turn routes the communication between the other two devices. The malicious device intercepts all data being sent and can inject false data or remove data before it reaches its recipient. +  * **MITM (Man In The Middle):** process by which a third device impersonates the other two legitimate devices, in order to fool them into connecting to it. Both BLE central and peripheral will connect to the malicious device, which in turn routes the communication between the other two devices. The malicious device intercepts all data being sent and can inject false data or remove data before it reaches its recipient. 
-  * Replay Attack: a type of network attack in which an attacker captures a valid network transmission and then retransmits it later. The main objective is to trick the system into accepting the retransmission of the data as legitimate.+  * **Replay Attack:** a type of network attack in which an attacker captures a valid network transmission and then retransmits it later. The main objective is to trick the system into accepting the retransmission of the data as legitimate.
  
 +<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>
 ==== Enabling Conference Mode (Pairing and Binding) ==== ==== Enabling Conference Mode (Pairing and Binding) ====
  
-Pairing is performed with a 6-digit number entered on each of the devices. In the case of TailCoNTROL, the passkey is set on the device in a "safe" location and saved to the firmware configuration.+Pairing is performed with a 6-digit number entered on each of the devices. In the case of TailControl, the passkey is set on the device in a "safe" location and saved to the firmware configuration.
  
 **SETPUSSKEY <nnnnnn>** **SETPUSSKEY <nnnnnn>**
Line 353: Line 389:
  
 The device will then reboot in 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 in 3 seconds. If the bond needs to be removed or reset, see [[en:dev:tailcontrol-command-protocol#unbinding|Unbinding]], below.
 +
 ==== Unbinding ==== ==== Unbinding ====
  
-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.
  
-There are two different methods of factory-resetting a TailCoNTROL device (which resets all persistent options to defaults and removes all bonding information):+There are two different methods of factory-resetting a TailControl device (which resets all persistent options to defaults and removes all bonding information):
  
-  * 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:
       - Press and hold the power button.       - Press and hold the power button.
Line 365: Line 402:
       - Ten seconds after the triple-flash (13 seconds total of continuous holding), the blue LED will blink quickly continuously, release to perform the factory reset. The blue LED will go solid, then the ESP will restart, with the blue LED flashing slowly (ready to connect).       - Ten seconds after the triple-flash (13 seconds total of continuous holding), the blue LED will blink quickly continuously, release to perform the factory reset. The blue LED will go solid, then the ESP will restart, with the blue LED flashing slowly (ready to connect).
  
-The bond will also need to be removed on the phone or other device as well, or it will attempt to continue to use the bond (which will fail, because those stored credentials will no longer be valid).+<WRAP round info 90%> 
 +Note that the bond will also need to be removed on the phone or other device as well, or it will attempt to continue to use the bond (which will fail, because those stored credentials are no longer valid).
  
   * On Android, enter Settings, Connections, Bluetooth and find the device to remove (e.g., "mitail"). Select the gear icon, and then select "Unpair". Confirm the dialog to unpair and forget the device.   * On Android, enter Settings, Connections, Bluetooth and find the device to remove (e.g., "mitail"). Select the gear icon, and then select "Unpair". Confirm the dialog to unpair and forget the device.
   * On iOS, enter Settings, Bluetooth and find the device to remove under "My Devices". Select the circle-i icon next to the device name, and then select "Forget This Device". Confirm by selecting "Forget Device".   * On iOS, enter Settings, Bluetooth and find the device to remove under "My Devices". Select the circle-i icon next to the device name, and then select "Forget This Device". Confirm by selecting "Forget Device".
  
 +</WRAP>
  
-==== iOS Casual Mode ==== 
  
-[This feature is pending removal in a future release.]+===== iOS Casual Mode ===== 
 + 
 +<WRAP round todo 90%> 
 +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): 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):
Line 382: Line 424:
  
 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 ==== ==== iOS Casual Mode Example ====
Line 396: Line 437:
 ===== 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.+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). 
 + 
 +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.
  
 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. 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.
Line 403: Line 449:
 ===== No-phone Mode ===== ===== No-phone Mode =====
  
-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<nnn>T<nnn>T<251 ... 254>** **AUTOMODE G<n>[G<n>[G<n>]] T<nnn>T<nnn>T<251 ... 254>**
Line 418: Line 464:
 ===== 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.+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).
  
 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. 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.
  
  
-== Copyright 2024 © The Mechanical Tail Company Limited contact@thetailcompany.com. All Rights Reserved. ==+== 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. ==
  
Back to top