Trace: • eargear-v2-protocol

Menu

Special Wiki Pages

Special Thanks!

This Wiki wouldn't be possible without @ToeiRei. Thank you for all of your help and guidance. Another special mention goes out to @Darkgrue, who writes and maintains the technical documentation.

Table of Contents

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

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 <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 EAR servos to their HOME position, returns EARHOME BEGIN followed by EARHOME END
LETWIST LEft TWIST, returns LETWIST BEGIN
RITWIST RIght TWIST, returns RITWIST BEGIN followed by RITWIST END
BOTWIST BOth TWIST, returns BOTWIST BEGIN followed by BOTWIST END
DSSP Directly Set Servo Position, 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 BATTery 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 HardWare VERsion
MICBAL Reserved
MICSWAP Reserved
OTA Starts firmware Over The Air update process; returns BEGIN OTA and sets TX characteristic to number of bytes recieved, starting at zero.
SERVOLIM Set SERVO LIMits 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 VERsion 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\<n\>T\<nn\>

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 <servoLTlow> <servoLThigh> <servoRTlow> <servoRThigh>

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

Back to top