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/07 01:20] – [Unbinding] 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 46: Line 46:
   - **Constant on** when BLE is connected.   - **Constant on** when BLE is connected.
   - **Fade-on** when BLE is connected and Autonomous Mode is active.   - **Fade-on** when BLE is connected and Autonomous Mode is active.
 +  - **Blink fast three times** when the button is held for more than 3 seconds (but less than 13), indicates the device is ready to power off when the button is released.
 +  - **Blink fast continuously** when the button is held for more than 13 seconds, indicates the device is ready to factory reset when the button is released.
  
 ==== Red LED ==== ==== Red LED ====
Line 148: 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 158: 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 166: 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 1 0 123456'') [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''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 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 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 1 0 123456''), returns ''OK'' [''ver'' ''minsToSleep'' ''minsToNPM'' ''minNPMPauseSec'' ''maxNPMPauseSec'' ''groupsNPM'' ''servo1home'' ''servo2home'' ''disconnectedCountdownEnabled'' ''homeOnAppPoweroff'' ''conferenceModeEnabled'' ''securityPasskey''] |+| **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''] |
  
 ===== Directly Set Servo Position ===== ===== Directly Set Servo Position =====
Line 187: 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 193: 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 211: 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 230: 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 250: 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 266: 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 282: 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 347: 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 357: Line 364:
       - Press and hold the power button.       - Press and hold the power button.
       - At approximately 3 seconds, the blue LED will flash three times and turn off. Continue to hold without releasing the button. If you Wish to cancel the factory reset, release at any time before the next step and the device will power off.       - At approximately 3 seconds, the blue LED will flash three times and turn off. Continue to hold without releasing the button. If you Wish to cancel the factory reset, release at any time before the next step and the device will power off.
-      - Ten seconds after the triple-flash, 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). 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).
Line 365: 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 376: 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