Erostek ET-312B

Introduction

This document is a specification for the serial communications protocol of the ET312 Electrostimulation box by Erostek. The following specifications are for v1.5 and v1.6 of the Erostek firmware, which it is assumed all modern boxes are running.

Communication via Link Cable

Serial Link (PC to ET-312)

Communicating with the ET312 box happens via an RS-232 Connection to the Link port of the box. The link cable consists of a 3.5mm TRS (stereo audio) jack, going to some sort of computer connection, be it Female DB-9 or a RS232-to-USB converter. The pin connections are as follows:

• 3.5mm Tip <-> RX (DB-9 Pin 2)
• 3.5mm Ring <-> TX (DB-9 Pin 3)
• 3.5mm Sleeve <-> Ground (DB-9 Pin 5)

Serial connections are 19200/8/N/1, or:

• 19200 baud
• Data Bits: 8
• Stop Bits: 1
• Partity: None

Handshake and Synchronization

Handshaking consists of a byte sent to the box, and a byte received back:

• 0x00 is sent to ET312
• 0x07 is read from ET312

This is done as a way to establish connection and synchronize the protocol.

If the box has been previously connected to and not powered off, the 0x00 sent to the ET312 will need to be encrypted with the key established during the previous session with the box, unless it was reset (see Key Resets section).

Similarly, if a connection is interrupted in the middle of a message, sending 0x0's until a 0x7 is received is a good way to re-synchronize the protocol. As the longest message possible with the ET-312 protocol is 11 bytes, up to 11 0x0s may need to be sent.

Key Exchange

After the handshake ends, you can then send "Read Byte" commands without performing a key exchange. If you wish to "Write Bytes" then XOR keys must be exchanged. This involves sending a 3 byte sequence to the box, and receiving 3 bytes back:

• [0x2f, 0xVV, 0xWW] sent to ET312
• [0x21, 0xXX, 0xYY] is read from ET312

Where:

• 0xVV is a random unsigned 8-bit number, chosen by the host, used as the first key. Note that the final key will have the nibbles of this value flipped (see Key Usage section).
• 0xXX is a random unsigned 8-bit number, chosen by the ET312, used as the second key.
• 0xWW/0xYY is a checksum, the 8-bit unsigned sum of the first two bytes, wrapped if the sum is > 255.

For instance:

• [0x2f, 0x04, 0x33] is sent to ET312
  • 0x04 is the host XOR key
  • 0x33 is the checksum (0x2f + 0x04)
• [0x21, 0xef, 0x10] is read from ET312, meaning
  • 0xef is the box XOR key
  • 0x10 is the checksum ((0x21 + 0xef) % 0x100)

Note that the key chosen by the host need never change, it can simply be hardcoded into the protocol implementation. Most implementations simply use 0 for the host key, which simplifies calculation of encryption.

Key Usage (Protocol Encryption)

Once the keys are agreed upon, all further communication going from host to ET312 is required to be encoded using the following scheme, using \^ as an XOR operator:

Data Byte \^ (Host Key with nibbles flipped \^ Box Key \^ 0x55)

The part of the expression in parenthesis will be constant after key exchange, and can be pre-calculated and stored.

The value sent as the host key in the key exchange will need to have the nibbles flipped when this final key is calculated. For instance, if the value sent to the ET312 during exchange is 0x12, when calculating the key, the value used should be 0x21.

Only data sent from host to ET312 requires encryption, all data received from the ET312 will be cleartext.

Master and Slave Link (ET-312 to ET-312)

Two ET312 boxes can be linked together using a cross-over cable.

• Box 1 3.5mm Tip <-> Box 2 3.5mm Ring
• Box 1 3.5mm Ring <-> Box 2 3.5mm Tip
• Box 1 3.5mm Sleeve <-> Box 2 3.5mmSleeve

A box becomes Master when you navigate in the menu options to the Link option. Once linked, a Slave unit A and B channels will follow those from the Master unit. The A and B pots still control the output levels for the Slave A and B.

Master-Slave communications are known to be a bit troublesome and can easily fail.

Handshake

Note: There is no encryption (xor bytes) used.

On selecting the menu item, the Master box will send a single byte on the serial port 0x0e. It expects to see a single byte back from the Slave 0x05.

After handshake is complete the master box will use the standard protocol as above to send memory locations to the slave.

The master will first send a 0x9d 0x40 0x04 followed by 6 bytes and a checksum.

When the slave sends an acknowledgement back (a single 0x06), the master will send a 0x9d 0x40 0x0a followed by 6 bytes.

When the master gets the next 0x06 back it will send the first 6 bytes again, forever, as fast as the slave processes them.

Locations $4004-$400f contain the processor registers r4-r15

Commands

Outside of the initial key setup, talking to the ET312 happens through 2 functions. These resemble peek and poke, except that developers can send between 1-8 bytes at a time. Only 1 byte may be read at a time. Both functions take 16 bit addresses, which map into a virtual memory space set up by the communications handler on the ET312. This memory space looks like:

Reading past the end of these ranges will just loop the last valid range.

All further documentation will use these ranges as reference, so when we mention writing/reading to, say, $4010, this means we're writing to byte 16 of the Register/RAM address space.

Also note that we do not have access to all of the RAM via this protocol. The CPU and IO registers take up the first 96 bytes of the address space we can access, and do not count as SRAM space. Since the virtual memory addressing cuts us off at $43ff, we cannot access the last 96 bytes of RAM. That said, the stack pointer never seems to move from 0x045f, which is gcc's RAM end.

Read Bytes

Reading a byte happens via a command with 3 byte length (plus checksum, the 8-bit unsigned sum of the first two bytes, wrapped if the sum is > 255.)

0x3c 0xGG 0xHH 0xCC

• 0xHH - High byte of address
• 0xII - Low byte of address
• 0xCC - Checksum

The box will then respond with two bytes (plus checksum, as above)

0x22 0xVV 0xCC

• 0xVV - Content of requested address
• 0xCC - Checksum

Write Bytes

Writing a byte happens via a command with 4 byte length (plus checksum)

0xGd 0xHH 0xII [0xJJ 0xKK...] 0xCC

• 0xGd - High nibble is amount of data to write to address plus 0x3, low nibble is always 0x0d
• 0xHH - High byte of address
• 0xII - Low byte of address
• [0xJJ 0xKK]... - Value(s) to set address to
• 0xCC - Checksum

The box will then respond with 0x06 (ACK).

For instance, if we wanted to write 2 bytes, 0xFE 0xFF, starting $4010, the command would look like

0x5d 0x40 0x10 0xfe 0xff 0xaa

• 0x5d is the write command with amount (0x3d + 0x20 since we're writing 2 bytes)
• 0x40 0x10 is our 16-bit address ($4010)
• 0xfe 0xff is the data we want to write to $4010 and $4011, respectively.
• 0xaa is the checksum

Memory Layout Tables

All entries in bold have been mapped and are useful.

Flash

RAM

EEPROM

Memory Address Descriptions

$0000:$0097 - String Table

Contains a portion of the string table used for the UI on the ET312 LCD. Each string is 8 bytes long, padded by spaces (0x20) if needed, with no null termination.

$0098:$00fb - Data Segment

$00fc - Box Version

For the ET312, this will always be 0x0c. (Checked in v1.5 and v1.6 firmware)

$00fd:$00ff - Firmware version

The Major, Minor, and Interval revision for the firmware on the ET312. Usually something like

0x01 0x06 0x00

For the v1.6 firmware

$400f - Register 15, ADC disable and other flags

Byte used for various functions

If bit 0 is set the ADC data is ignored, so effectively disabling the the front panel potentiometers. You can then send commands to change the A, B, and MA levels directly. Enabling again sets the unit back to the actual potentiometer values.

To set the A level write to $4064 (CurrentLevelA 0-255), to set the B level write to $4065 (CurrentLevel B 0-255), to set the MA write to $420D (Current Multi Adjust Value, range from min at $4086 to max at $4087).

$4010 - Register 16, flags

Byte used for various functions

$4011 - Register 17, flags

Byte used for various functions

$4029 - UBRRL I/O Register

The low byte of the Serial I/O Register.

By default, this is set to 0x19, with the U2X bit in $402b (UCSRA) set to 0, meaning that at the 8mhz clock, the serial port will run at 19200 baud. If this byte is set to 0x0c, the serial port will run at 38400 baud with no noticeable effects on the ET312.

Other non-standard, higher baud rates may be possible, but testing has not been successful thus far. See http://wormfood.net/avrbaudcalc.php for baud rate calculations, using the 8mhz table.

$402b - UCSRA I/O Register

Contains the U2X bit for doubling serial baud rates. Testing of setting the U2X bit has usually ended in ET312 communications no longer working properly (checksum errors).

$406D - Menu State

$4070 and $4071 - Box Command

Set $4070 to the value above for the command you want to execute. This location is checked in the main loop many times a second. If you want to give more than one command you need to have a short delay after writing to $4070 (>~18mS) to ensure the first command is actioned. If you want to execute two commands you can write a second command to $4071 and this location is checked immediately after $4070 is actioned.

Note: if a command needs parameters, r26 is read from $4182 and r27 is read from $4183

Note: Parameters for load module

Module number is read from $4182

Note: Parameters for set power level

Note: Parameters for the LCD write command

$407b - Box Modes

Note: To set mode

• Write New Mode Number to $407b
• Write 0x04 to $4070 (execute "exit menu")
• Write 0x12 to $4071 (execute "select new mode")
• Wait 18ms (lets box execute previous commands before you change mode again)

(Note you can write to two adjacent memory locations in one command so you can do a write of 0x4 0x12 to $4070 with the same effect)

$4083 - Phase, Front Panel, Mute/Mono/Stereo Control

Note: ErosLink uses the following masks:

• 0x00 - CONTROLFLAG~NORMALMASK~
• 0x04 - CONTROLFLAG~ALLOWOVERLAPMASK~
• 0x05 - CONTROLFLAG~PHASEMASK~
• 0x20 - CONTROLFLAG~DISABLESWITCHESMASK~

$4098-$409b - Current Channel Gate

The output for each channel can be gated (turned on and off continously) with a variable speed determined by the value of the Gate Select.

Select $409a:

If not other bits in Select are set then the on and off time come from $4098 (on, default 0x3e) and $4099 (off, default 0x3e)

$409c-$40bf - Main Variables

The box output is determined by a group of four variables: Ramp, Intensity, Frequency, Width. Each variable has several parameters that determine the current value and how to change that value. Once a module has set up these parameters, the variables get updated automatically as configured. The variables may get set to a static value, they may ramp or or down or loop over time, vary according to the other channel, or the MA knob.

Defaults when a mode starts:

Examples showing how these are used in Programs

Select

Absolute value when Bit 0 and Bit 1 are both 0:

Timer based updates when either Bit 0 or Bit 1 are 1:

Each time we reach the "rate" for the selected timer we add the step (can be negative) to the current value. We then look to see if we want to update the "min" value depending on the bits 2-4:

At Min / At Max

This byte specifies what to do when the current value reaches the end of the range (either the maximum or minimum depending on what variable is being used).

$41f4 - Power Levels

$4215 - Power status bits

Common Usages and Tricks

Key Resets

If you just close the connection to the box then the box won't be able to handshake again unless you remember the key you got given last time.

However if just before closing the connection to the box you clear out the current XOR key, future serial connections to the box will appear as new connections without needing the box to be power cycled.

Do this by sending command below to Write Bytes, setting location $4213 to 0x00.

Peeking before Key Exchange

Most client software performs a key handshake. However, if your application only wants to read bytes there is no need to perform a handshake and exchange keys.