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<n> P<n> N<nnn> A<n> A<n> … A<n> B<n> B<n> … B<n> S<nnn> S<nnn> … S<nnn>
USERLEDS U<n> P<nn> N<nnn> A<n> A<n> … A<n> S<nnn> S<nnn> … S<nnn>
<n> 1-digit number <nn> 1- or 2-digit number <nnn> 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
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<n> G<n>G<n> T<nnn> T<nnn>T<nnn> 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