Trace: • tailcontrol-command-protocol • service-notes-for-mitail

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/09 01:16] – [Developer Commands (use at own risk)] darkgrueen:dev:tailcontrol-command-protocol [2024/06/28 15:43] (current) – darkgrue
Line 10: Line 10:
 ===== 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 150: Line 150:
 | **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 ''LEGACY MITAIL'' or ''MITAIL x.x'' for tail-series controller hardware, ''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'' |
Line 160: Line 160:
 | **USERLEDS** | [[#User-defined Tail Moves and LEDs Patterns|See below]], returns ''OK'' | | **USERLEDS** | [[#User-defined Tail Moves and LEDs 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 second message: either ''GLOWTIP FALSE'' if a Glow Tip is not connected, or ''GLOWTIP TRUE'' if one is |
-| **VERA** | Returns the firmware **VER**sion number for use by the iOS app; ''VER x.x.x GT0'', (''GT0'' if a Glow Tip is not connected, or ''GT1'' if one is) [This feature is pending removal in a future release.] | 
  
  
Line 168: Line 167:
 | **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 | | **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 |
-| **READCONF** | **READ** running **CONF**iguration; returns space-delimited configuration parameters (e.g., ''1 5 0 15 40 3 8 0 0 0 0 1 0 123456'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''tiltModeNPMEnabled'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey''] | +| **READCONF** | **READ** running **CONF**iguration; returns space-delimited running configuration parameters (e.g., ''1 5 0 15 40 3 8 0 0 0 3 0 0 0 1 0 123456'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''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 0 0 1 0 123456'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''tiltModeNPMEnabled'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey''] |+| **READNVS** | **READ** **CONF**iguration from NVS; returns space-delimited configuration parameters stored in NVS (e.g., ''1 5 0 15 40 3 8 0 0 0 3 0 0 0 1 0 123456'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''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'' | | **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 in words of remaining stack space that was available to the task since the task started executing, 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 0 0 1 0 123456''), +| **WRITECONF** | **WRITE** **CONF**iguration to NVS and set running configuration to match (e.g., ''WRITECONF 1 5 0 15 40 3 8 0 0 0 3 0 0 0 1 0 123456''), returns ''OK'' [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''listenModeResponseOnly'' ''groupsLM'' ''tiltModeNPMEnabled'' ''tiltModeResponseOnly'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey''] |
- returns ''OK'' [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''listenModeNPMEnabled'' ''tiltModeNPMEnabled'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey''] |+
  
 ===== Directly Set Servo Position ===== ===== Directly Set Servo Position =====
Line 190: Line 188:
 | **B** | Point for Servo 2 | (Same as **A**) | | **B** | Point for Servo 2 | (Same as **A**) |
 | **L** | Time between the current Servo 1 point and the next in ticks (in 20 ms increments)\\ **L** will move from the current position to the next, over the time specified | 0 ... 127 (time * 20 ms) | | **L** | Time between the current Servo 1 point and the next in ticks (in 20 ms increments)\\ **L** will move from the current position to the next, over the time specified | 0 ... 127 (time * 20 ms) |
-| **M** | Time between the current Servo 1 point and the next in ticks (in 20 ms increments)\\ **L** will move from the current position to the next, over the time specified | (Same as **L**) |+| **M** | Time between the current Servo 2 point and the next in ticks (in 20 ms increments)\\ **M** will move from the current position to the next, over the time specified | (Same as **L**) |
 | **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 |
  
Line 196: Line 194:
   * 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 214: Line 212:
  
 **USERMOVE U<preset> P<numpoints> N<numcycles> [E<easeType<sub>1</sub>>F<easeType<sub>1</sub>> ... E<easeType<sub>n</sub>>F<easeType<sub>n</sub>>] A<point<sub>1</sub>>B<point<sub>1</sub>> ... A<point<sub>n</sub>>B<point<sub>n</sub>> L<numticks<sub>1</sub>>M<numticks<sub>1</sub>> ... L<numticks<sub>n</sub>>M<numticks<sub>n</sub>> [H{0|1}]**   **USERMOVE U<preset> P<numpoints> N<numcycles> [E<easeType<sub>1</sub>>F<easeType<sub>1</sub>> ... E<easeType<sub>n</sub>>F<easeType<sub>n</sub>>] A<point<sub>1</sub>>B<point<sub>1</sub>> ... A<point<sub>n</sub>>B<point<sub>n</sub>> L<numticks<sub>1</sub>>M<numticks<sub>1</sub>> ... L<numticks<sub>n</sub>>M<numticks<sub>n</sub>> [H{0|1}]**  
 +
 +^ Prefix ^ Parameter Type  ^ Range of Values for Moves  ^
 +| **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 |
 +| **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 |
 +| **B** | Point for Servo 2 | (Same as **A**) |
 +| **L** | Time between the current Servo 1 point and the next in ticks (in 20 ms increments)\\ **L** will move from the current position to the next, over the time specified | 0 ... 127 (time * 20 ms) |
 +| **M** | Time between the current Servo 2 point and the next in ticks (in 20 ms increments)\\ **M** will move from the current position to the next, over the time specified | (Same as **L**) |
 +| **H** | Move to home position at end of move | 0 = false (default), 1 = true |
  
 **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>>**   **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 Moves  ^ Range of Values for Glow Tip LEDs  ^ +^ Prefix  ^ Parameter Type  ^ Range of Values for Glow Tip LEDs  ^ 
-| **U** | User preset number | <1 ... 4> | <1 ... 4> | +| **U** | User preset number | <1 ... 4> | 
-| **E** | Easing type [MiTail FW \>= 4.0.0, TailCoNTROL >= 5.0.0] | 0 = Linear (no easing), 1 = Quadratic, 2 = Cubic,  3 = Quartic | N/A | +| **P** | Number of points in the Glow Tip pattern | <1 ... 32> | 
-| **P** | Number of points in the move or Glow Tip pattern | <1 ... 5> | <1 ... 32> | +| **N** | Number of cycles (times the pattern will be repeated) | <0 ... 255> | 
-| **N** | Number of cycles (times the pattern will be repeated) | <0 ... 255> | <0 ... 255> | +| **A** | Brightness point for Glow Tip | <0 ... 8>\\ 0 -> LEDs off\\ ...\\ 4 -> 50% intensity\\ ...\\ 8-> LEDs max intensity | 
-| **A** | Point for Servo 1 or brightness point for Glow Tip | <0 ... 8>\\ 0 -> 25 degrees\\ 1 -> 41 degrees\\ 2 -> 58 degrees\\ ...\\ 8 -> 160 degrees | <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) |
-| **B** | Point for Servo 2 | <0 ... 8> | (same as **A**) | N/A | +
-| **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) | 0 ... 127 (time * 20 ms) | +
-| **H** | Move to home position at end of move | 0 = false, 1 = true (default) | N/A |+
  
 **Notes:** **Notes:**
Line 233: Line 238:
   * There is a **128-character limit** on the serial input buffer.   * There is a **128-character limit** on the serial input buffer.
  
 +==== USERMOVE Examples ====
  
-===== 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.
Line 253: Line 257:
   * **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 269: Line 273:
   * **H1** Home at end of move   * **H1** Home at end of move
  
 +==== USERLEDS Examples ====
  
-===== 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 285: Line 288:
   * **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 350: Line 353:
  
 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 ====
  
Line 368: Line 372:
  
  
-==== iOS Casual Mode ====+===== iOS Casual Mode =====
  
 [This feature is pending removal in a future release.] [This feature is pending removal in a future release.]
Line 379: Line 383:
  
 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 ====
Back to top