====== EarGear v1 Protocol ======

Command list for The Tail Company EarGear v1.

Each system command generates a specific unique response.


===== Device Advertisement =====

Device name is ''EarGear''.


===== Ear Moves =====

Each move command sent is ''<COMMAND>'' plus angle. It gets the same command returned from the ears with ''<COMMAND> <VALUE> BEGIN''. When the move is done, ''<COMMAND> <VALUE> END''. HOME defaults to 90 degrees.

All move commands sent with values outside ranges will be forced within range. Commands sent during a move will return ''BUSY''.

| **EARHOME** | Move servos to their **HOME** position |
| **LETWIST** | **LE**ft **TWIST** |
| **RITWIST** | **RI**ght **TWIST** |
| **BOTWIST** | **BO**th **TWIST** |
| **LETILT** | **LE**ft **TILT** |
| **RITILT** | **RI**ght **TILT** |
| **BOTILT** | **BO**th **TILT** |
| **DSSP** | **D**irectly **S**et **S**ervo **P**osition, followed by four values to send to all servos at once (e.g. ''DSSP aaa bbb ccc ddd'' where a = LETWIST, b = RITWIST, c = LETILT, d = RITILT). All four parameters must be sent. |
| **CASUAL MODE** | See Casual Mode, below. |
| **ENDCASUAL** | See Casual Mode, below. |
| **LISTEN IOS** | See Listen Mode, below. |
| **LISTEN FULL** | See Listen Mode, below. |
| **ENDLISTEN** | **END LISTEN** Mode. Returns ''LISTEN OFF''. |
| **MICBAL** | See Listen Mode, below. |
| **MICSWAP** | See Listen Mode, below. |


===== Other Commands =====

| **BATT** | **BATT**ery percentage, returns the integer value of estimated battery capacity remaining (e.g. ''61'') |
| **LTLIM** | **L**eft **T**wist **LIM**it. See Home and Limits, below. |
| **RTLIM** | **R**ight **T**wist **LIM**it. See Home and Limits, below. |  
| **LILIM** | **L**eft **T**ilt **LIM**it. See Home and Limits, below. |
| **RILIM** | **R**ight **T**ilt **LIM**it. See Home and Limits, below. |
| **PING** | Keepalive heartbeat (from application). Returns ''OK''. |
| **SET** | **SET** current servo position as Home. |
| **SHUTDOWN** | Switches off the unit (will lose the BLE connection). |
| **VER** | Returns the firmware **VER**sion number (e.g. ''VER'' plus firmware version.) |


===== Casual Mode =====

**CASUAL MODE T\<n\>T\<nn\>**

The tail will select a random move from the specified group(s), pausing for a random number of seconds between each move (min and max specified by the first and second ''T'' parameter, respectively).

**ENDCASUAL**

''ENDCASUAL'' will abort the current Casual Mode after completing any ongoing move.


===== Home and Limits =====

**LTLIM**  
**RTLIM**  
**LILIM**  
**RILIM**  

Without parameters, the above will return current low and high limits for corresponding servo. Acceptable limits are from 1 to 180 degrees.

**SET** saves the current positions of the servos as HOME position

**LTLIM \<xxx\> \<yyy\>**  
**RTLIM \<xxx\> \<yyy\>**  
**LILIM \<xxx\> \<yyy\>**  
**RILIM \<xxx\> \<yyy\>**  

Where _xxx_ and _yyy_ are low and high limits, respectively. Servos have limits set in firmware (25 to 160). Values outside this range are forced to the nearest maximum or minimum.


===== Auto Sleep =====

Ears sleep after 120 seconds (3 minutes) of inactivity. Power-off after 300 seconds (5 minutes) of inactivity.
Note: Switching Listening Mode on suspends timers until listening mode off is triggered.


===== Battery =====

Battery notifications are automatically sent every 5 percent. The ''BATT'' terminal command returns the numeric percentage. You can monitor the separate battery characteristic for 5 nice slices.


===== Listen Mode =====

**LISTEN IOS**

For iOS, with triggered moves. 6 second moving cycle (3 s twisted + 3 s at home).

**LISTEN FULL**

Verbose mode, no moves triggered. Update every 0.3 seconds. Negative values are right microphone, positive values are left.

**ENDLISTEN**

Stop Listen Mode, returns ''LISTEN OFF''.

**MICBAL**

Execute in a quiet room to re-baseline the microphone noise floor. Value stored in flash.

**MICSWAP**

Swaps L and R microphones.


== Copyright 2023 © The Mechanical Tail Company Limited contact@thetailcompany.com. All Rights Reserved. ==