====== TAIL PROTOCOL ====== Command list for The Tail Company DIGITAiL Firmware Ver 2.21 (05Nov2019). ===== Command List ===== **NOTE:** Commands are all case insensitive ==== Tail Moves ==== | TAILHM | HoMe position | | TAILS1 | Slow wag 1 | | TAILS2 | Slow wag 2 | | TAILS3 | Slow wag 3 | | TAILFA | FAst wag | | TAILSH | SHort wag | | TAILHA | HAppy wag | | TAILER | ERect | | TAILEP | Erect Pulse | | TAILT1 | Tremble 1 | | TAILT2 | Tremble 2 | | TAILET | Erect Trem | | TAILU1 | User defined 1 | | TAILU2 | User defined 2 | | TAILU3 | User defined 3 | | TAILU4 | User defined 4 | ==== Led Patterns ==== | LEDOFF | LEDs off | | LEDREC | Blink 1 second on, 1 second off | | LEDTRI | Fade in 1 second – Fade out 1 second | | LEDSAW | Fade in 2 seconds – off | | LEDSOS | Morse SOS | | LEDBEA | Beacon (100ms on every 2 seconds) | | LEDFLA | Flame | | LEDSTR | Strobo | | LEDUS1 | User defined 1 | | LEDUS2 | User defined 2 | | LEDUS3 | User defined 3 | | LEDUS4 | User defined 4 | ==== Other Commands ==== | PING | Returns ‘OK’ | | VER | Returns the Firmware version number | | SHUTDOWN | Switches off the unit (will lose the BT connection!) | | USERMOVE | See below | | USERLEDS | See below | | AUTOMOVE | See below | ===== Send User Defined Tail Moves and LEDs Patterns ===== Up to 4 user-defined move definitions and 4 LED patterns can be sent over the BT connection and assigned to user 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 LED pattern definition follow the same syntax and consist in a 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). **USERMOVE U P N A A … A B B … B S S … S**\\ **USERLEDS U P N A A … A S S … S**\\ //// 1-digit number //// 1- or 2-digit number //// 1- to 3-digit number ^ Letter prefix ^ Parameter type ^ Range of values for moves ^ Range of values for LED patterns ^ | U User preset number | 1..4 | 1..4 | | P | Number of Points in the move or LED pattern | 1..5 | 1..32 | | N | Number of cycles (times the pattern will be repeated) | 0..255 | 0..255 | | A | Point for servo 1 or brightness point for the LEDS | 0..8\\ 0 -> 0 degrees\\ 1 -> 22.5 degrees\\ 2 -> 45 degrees\\ …\\ 8 -> 180 degrees\\ || 0..8\\ 0 -> LEDs off\\ …\\ 4 -> 50% intensity\\ …\\ 8-> LEDs max intensity | | B | Point for servo 2 | 0..8\\ (same as A) | N/A | | S/L | Time between the current point and the next (in 20ms 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 x 20ms | 0..127\\ Time x 20ms | **NOTES:** * Parameters of type A, B, S and L 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 {{ :en:dev:usermove_graphical_example.jpg?nolink |}} ==== USERTAIL Examples ==== === Example 1 – Slow Wag 1 (same as the TAILS1 command) === Both servos move from 22.5° to 157.5° (position 1 to 7) and back, for 3 times; each cycle is (68+68)*20ms = 2.72s long **USERMOVE U1P2N3A1A7B1B7L68L68** U1 -> Store into user preset 1\\ P2 -> The move consists of 2 points\\ N3 Repeat the sequence 3 times\\ A1A7 Servo1 moves from 1 to 7 (157.5° to 22.5°)\\ B1B7 Servo2 moves exactly as servo1\\ S68S68 Position 2 is reached in 68*20ms = 1.36s; return to position 1 in the same time\\ === Example 2 – Test Servos === Moves servos in steps of 90° every 2 seconds; servo2 is delayed by 90° **USERMOVE U2P4N3 A0A4A8A4 B4B8B4B0 S100S100S100S100** U2 Store into user preset 2\\ P4 The move consists of 4 points\\ N3 Repeat the sequence 3 times\\ A0A4A8A4 Move servo1 90° at a time, starting from 0°\\ B4B8B4B0 Move servo2 90° at a time, starting from 90°\\ S100S100S100S100 Each position is held for 100*20ms = 2s\\ ==== USERLEDS Examples ==== === Example 1 – Beacon (same as the LEDBEA command) === The led strip lights up for 100ms every 2s **USERLEDS U1P2N5A8A0S5S95** U1 Store into user preset 1\\ P2 The pattern consists of 2 brightness points\\ N5 Repeat pattern 5 times\\ A8A0 Start at full brightness, then turn off\\ S5S95 On for 5*20ms = 100ms; Off for 95*20ms = 1.9s (total time = 2 seconds)\\ === Example 2 – Fade in/out (similar to LEDTRI) === The led strip lights up slowly, then dims until completely off; this is repeated 3 times **USERLEDS U2P2N3 A0A8 L100L100** U2 Store into user preset 2\\ P2 The pattern consists of 2 brightness points\\ N3 Repeat pattern 3 times\\ A0A8 Start off, finish at full brightness\\ L100L100 Each brightness point is reached in 100*20ms = 2s\\ ===== Random Moves (Auto) ===== Defines a sequence of random moves, selected from any of 3 groups as below; interval between moves varies randomly from T1 and T2, while ^ Move Group ^ List of moves in the group ^ | Calm and Relaxed | Slow Wag 1, Slow Wag 2, Slow Wag 3 | | Fast and Excited | Fast Wag, Short Wag, Happy Wag, Erect | | Frustrated and Tense | Tremble 1, Tremble 2, Tremble Erect, High Wag | ==== Commands ==== **AUTOMODE G GG T TT STOPAUTO** The tail will pause 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. Stopauto will abort the current ‘auto mode’ session after completing any ongoing move. ^ Letter prefix ^ Parameter type ^ Range of values ^ | G | Move Group (see table above) | 1..3 | | T | Time in 1 sec increments | 15..240 (15s .. 4min)\\ 1st parameter – min random pause between moves\\ 2nd parameter – max random pause between moves\\ 3rd parameter – total duration | The parameter order is not important, except that the 3 T parameters are interpreted in the above order. === Example === **AUTOMODE T15 T60 T240 G1 G2** == Copyright 2023 © The Mechanical Tail Company Limited contact@thetailcompany.com. All Rights Reserved. ==