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/10/19 15:02] – [Directly Set Servo Position] darkgrueen:dev:tailcontrol-command-protocol [2024/11/09 17:09] (current) – darkgrue
Line 6: Line 6:
 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.
  
 +<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 at this time, especially EarGear 2 features. **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>
  
 ===== Bluetooth Low Energy (BLE) ===== ===== Bluetooth Low Energy (BLE) =====
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'' and
 +  * TX Characteristic is ''567A99D6-A442-4AC0-B676-4993BF95F805''.
 +  * Under the standard Device Information Service (DIS, ''0x180A'') is
 +    * Manufacturer Name ''0x2A29'' (''The Mechanical Tail Company Limited''),
 +    * Model Number ''0x2A24'',
 +    * Firmware Revision ''0x2A26'', and
 +    * Hardware Revision ''0x2A27''.
 +  * Under the standard Battery Service UUID (''0x180F'') is
 +    * Battery Percentage ''0x2A19'',
 +    * Battery Voltage is ''E818BDA3-88A7-43C0-8509-6E0BBB6F55D9'', and the
 +    * Charging State (if hardware supported) is ''5073792e-4fc0-45a0-b0a5-78b6c1756c91''.
 +</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 =====
Line 183: Line 203:
  
 ^ 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.\\ 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 (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 215: Line 235:
 ^ 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 228: Line 248:
 | **U** | User preset number | <1 ... 4> | | **U** | User preset number | <1 ... 4> |
 | **P** | Number of points in the Glow Tip pattern | <1 ... 32> | | **P** | Number of points in the Glow Tip pattern | <1 ... 32> |
-| **N** | Number of cycles (times the pattern will be repeated) | <0 ... 255> |+| **N** | Number of cycles (times the pattern will be performed) | <0 ... 255> |
 | **A** | Brightness point for Glow Tip | <0 ... 8>\\ 0 -> LEDs off\\ ...\\ 4 -> 50% intensity\\ ...\\ 8-> LEDs max intensity | | **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) | | **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) |
Line 237: Line 257:
   * Note the upper limit on the **P** parameter (and the consequential limit of moves in a move or LED pattern).   * 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.   * 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 ==== ==== USERMOVE Examples ====
Line 244: Line 268:
 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** Perform 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 266: Line 290:
   * **U2** Store into user preset 2     * **U2** Store into user preset 2  
   * **P4** The move consists of 4 points     * **P4** The move consists of 4 points  
-  * **N3** Repeat the sequence 3 times  +  * **N3** Perform the sequence 3 times  
   * **A0A4A8A4** Move Servo 1 90° at a time, starting from 0°     * **A0A4A8A4** Move Servo 1 90° at a time, starting from 0°  
   * **B4B8B4B0** Move Servo 2 90° at a time, starting from 90°     * **B4B8B4B0** Move Servo 2 90° at a time, starting from 90°  
Line 273: Line 297:
   * **H1** Home at end of move   * **H1** Home at end of move
  
-Note: because no easing parameters (''E'' or ''F'') are specified, no easing is used by default.+<WRAP round info 90%> 
 +Because no easing parameters (''E'' or ''F'') are specified, no easing is used by default. 
 +</WRAP> 
 ==== USERLEDS Examples ==== ==== USERLEDS Examples ====
  
Line 285: Line 312:
   * **U1** Store into user preset 1     * **U1** Store into user preset 1  
   * **P2** The pattern consists of 2 brightness points     * **P2** The pattern consists of 2 brightness points  
-  * **N5** Repeat pattern 5 times  +  * **N5** Perform the pattern 5 times  
   * **A8A0** Start at full brightness, then turn off     * **A8A0** Start at full brightness, then turn off  
   * **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  
Line 291: Line 318:
 === 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 performed 3 times.
  
 **USERLEDS U2 P2 N3 A0A8 L100L100** **USERLEDS U2 P2 N3 A0A8 L100L100**
Line 297: Line 324:
   * **U2** Store into user preset 2     * **U2** Store into user preset 2  
   * **P2** The pattern consists of 2 brightness points     * **P2** The pattern consists of 2 brightness points  
-  * **N3** Repeat pattern 3 times  +  * **N3** Perform the pattern 3 times  
   * **A0A8** Start off, finish at full brightness     * **A0A8** Start off, finish at full brightness  
   * **L100L100** Each brightness point is reached in 100 * 20 ms = 2 s   * **L100L100** Each brightness point is reached in 100 * 20 ms = 2 s
Line 335: Line 362:
 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.
  
 ==== Enabling Conference Mode (Pairing and Binding) ==== ==== Enabling Conference Mode (Pairing and Binding) ====
Line 367: Line 394:
       - 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).
  
 +<WRAP round info 90%>
 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).
  
   * 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 ===== ===== iOS Casual Mode =====
  
-[This feature is pending removal in a future release.]+<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):
Back to top