====== EarGear v2 Protocol ====== Command list for The Tail Company EarGear v2. ===== Differences between v1 and v2 ===== The main difference between EarGear v1 and v2 is that v2 has no tilt servos, reducing the physical size of the gear significantly. This was done primarily to make the ears more versatile when dressing them. It also improves battery life and weight. All parts are now injection molded, and the microcontroller has been changed, requiring no external controller unit. Also, despite there being 2 mics on the PCB, EG2 does not do analysis of sound direction at this time. ===== Power button ===== A press of 2-3 seconds starts up and shuts down EarGear. Connecting a charger to the EarGear inhibits the ''ENABLE'' line of the 3.3 V regulator, which means the EarGear cannot be turned on while charging. ===== Device Advertisement ===== Device name is ''EG2''. The TailCoNTROL BLE Device Service is ''927dee04-ddd4-4582-8e42-69dc9fbfae66'': * the RX Characteristic is ''05e026d8-b395-4416-9f8a-c00d6c3781b9'', and * the TX Characteristic is ''0b646a19-371e-4327-b169-9632d56c0e84''. There is also a Battery Service at UUID 0x180F that provides: * Battery Percentage (0-100%), and * Battery Voltage (in Volts). ==== nRF Connect for Mobile ==== [[https://www.nordicsemi.com/Products/Development-tools/nrf-connect-for-mobile|nrf Connect for Mobile]] is a highly recommended tool for assisting with development and troubleshooting connectivity when developing your own controller or app software. ===== Ear Commands ===== Command list for **EarGear v2** Each system command generates a specific unique response. Each move command sent is '''' plus angle. It gets the same command returned from the ears with '' BEGIN''. When the move is done, '' 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 **EAR** servos to their **HOME** position, returns ''EARHOME BEGIN'' followed by ''EARHOME END'' | | **LETWIST** | **LE**ft **TWIST**, returns ''LETWIST BEGIN'' | | **RITWIST** | **RI**ght **TWIST**, returns ''RITWIST BEGIN'' followed by ''RITWIST END'' | | **BOTWIST** | **BO**th **TWIST**, returns ''BOTWIST BEGIN'' followed by ''BOTWIST END'' | | **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** | See Casual Mode, below; returns ''CASUAL ON'' | | **ENDCASUAL** | **END CASUAL** Mode, see Casual Mode, below; returns ''CASUAL OFF'' | | **LISTEN IOS** | See Listen Mode, below; returns ''LISTEN ON'' | | **LISTEN FULL** | See Listen Mode, below; returns ''LISTEN FULL ON'' | | **ENDLISTEN** | **END LISTEN** Mode, see Listen Mode, below; returns ''LISTEN OFF'' | | **TILTMODE START** | Enable **TILT MODE**, see Tilt Mode, below; returns ''TILTMODE ON'' | | **ENDTILTMODE** | **END TILT MODE**, see Tilt Mode, below; returns ''TILTMODE OFF'' | ===== Other Commands ===== | **PING** | Keepalive heartbeat (from application), returns ''PONG'' | | **SHUTDOWN** | **SHUT DOWN** the unit (will lose the BLE connection), returns ''SHUTDOWN BEGIN'' | | **SPEED FAST** | See Speed Control, below; returns ''SPEED FAST'' | | **SPEED SLOW** | See Speed Control, below; returns ''SPEED SLOW'' | | **SPEED SAVE** | See Speed Control, below; returns ''OK'' | | **SPEED LOAD** | See Speed Control, below; returns ''OK'' | ===== Developer Commands (use at own risk) ===== | **BATT** | **BATT**ery percentage, returns the integer value of estimated battery capacity remaining (e.g. ''61'') | | **FORMATNVS** | **FORMAT NVS** (erase all contents of the default NVS partition) and reboot | | **HWVER** | Returns **H**ard**W**are **VER**sion | | **MICBAL** | Reserved | | **MICSWAP** | Reserved | | **OTA** | Starts firmware **O**ver **T**he **A**ir update process; returns ''BEGIN OTA'' and sets TX characteristic to number of bytes recieved, starting at zero. | | **SERVOLIM** | Set **SERVO LIM**its and writes it to NVS configuration, see Home and Limits, below; returns ''OK'' | | **SETHOME** | **SET** servo **HOME** position at current (calculated) location and writes it to NVS configuration, returns ''OK'' | | **VER** | Returns the firmware **VER**sion number | ===== No Phone Mode ===== No Phone Mode starts immediately when EarGear is powered on. In this mode, both tilt sensing and sound sensing (iOS versions) are live. It is ended when the power goes off or a connection is made to the app. The blue LED blinks to indicate it is in No Phone Mode. EarGear will power off after 5 minutes of inactivity in No Phone Mode. ===== Why do we have iOS specific modes? ===== iOS doesn't like processes running in the background, when the app is minimized. So that wearers can continue to enjoy their gear in this situation, we ask EarGear to start, run and stop special modes until the app is foregrounded again. Android does not have this issue and can continue to talk to the gear via its service, even when backgrounded. For both iOS only modes to work, a table of moves needs to be created in EarGear. These moves are below ===== Internal Moves ===== "HeadTiltL" : "RITWIST 20, pause 1 second, EarHome"\\ "HeadTiltR" : "LETWIST 20, pause 1 second, EarHome"\\ "Sound" : "BOTWIST 30, pause 1 second, EarHome"\\ ===== iOS Casual Mode ===== **CASUAL T\T\** The Ears will select a random move from the internal move library, 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 ===== **SETHOME** Saves the current (calculated) servo position in NVE and makes it the default. **SETLIM ** 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 (5 minutes) of inactivity. Power-off after 300 seconds (5 minutes) of inactivity. ===== 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** In this mode, once a sound is detected, the firmware will automatically trigger a random move from the internal list. **LISTEN FULL** In this mode, no moves are triggered. Instead, the firmware responds to the apps with ''LISTEN_FULL BANG'', allowing the app to decide what move to send. **ENDLISTEN** Stop Listen Mode, returns ''LISTEN OFF''. ===== Speed Control ===== EarGear has a global speed control. ''SPEED SLOW'' is the default speed for all moves. There is a second faster mode, switched on by sending ''SPEED FAST''. Its a toggle and once changed, all moves after are at the new speed until reset. ''SPEED SAVE'' writes the value to NVM, and makes the current speed setting the default at startup. ''SPEED LOAD'' will set the current speed to what is written in NVM. Please note that inbuilt sound-reactive moves are always ''SPEED FAST''. ===== Tilt Mode ===== ''TILTMODE START'' turns on Tilt Mode, and ''ENDTILTMODE'' disables it. When the device starts up, it reads a number of accelerometer values over 5 seconds and averages them to be the "stable" position. After that, a tilt of 20 degrees from that position triggers a tilt / movement, which is one of the following moves: **TILT LEFT**\\ **TILT RIGHT**\\ **TILT FORWARD**\\ **TILT BACKWARD**\\ == Copyright 2023 © The Mechanical Tail Company Limited contact@thetailcompany.com. All Rights Reserved. ==