| ECC1C 145-944-00

Communication

The serial communication is always in one of two modes – simple mode or protocol mode. In each of these modes, a different set of commands is supported. The default mode active on startup is simple mode. Brief descriptions of the commands available in each mode follow. To see a description of the pro mode error codes, see Error Codes.

Simple mode (ASCII based):

Simple mode is ASCII-based - every command is a sequence of ASCII characters. Every simple mode message (that is, every command to the firmware and every response from the firmware) should end in the sequence CR LF ("\r\n"), that is, two bytes with decimal values 13 and 10. The protocol is not case sensitive and all whitespace is ignored.

Simple mode commands

Simple mode commands | Description
--- | ---
START[CR][LF] | returns "OK", just a simple handshake command to confirm that the communication is working
STATUS[CR][LF] | returns the status register in hex format, which encodes the status and erros of the device. See Status
ACKNOWLEDGE[CR][LF] | clears history error flags in the status register. See Status
RESET[CR][LF] | resets the device
GOPRO[CR][LF] | switches the serial communication to pro mode with CRC turned off
GOPROCRC[CR][LF] | switches the serial communication to pro mode with CRC turned on
GETID[CR][LF] | get the firmware serial number
GETVERSION[CR][LF] | get the firmware version number
GETSN[CR][LF] | get the serial number of the board and the device
GETGITSHA1[CR][LF] | get the latest git commit hash value (to help identify the specific build)
GOTODFU[CR][LF] | Go to device firmware update mode
SETCURRENT=%f[CR][LF] | drive selected channel with a current of float milliamperes, float should be in the range: (-300, 300)
GETCURRENT[CR][LF] | get actual current setpoint value from selected channel
SETFP=%f[CR][LF] | drive selected channel with a focal power of float dioptre, float should be in the range: (-11, 12.5)
GETFP[CR][LF] | get actual focal power setpoint value from selected channel
GETFPMIN[CR][LF] | get focal power lower limit value
GETFPMAX[CR][LF] | get focal power upper limit value
GETTEMP[CR][LF] | get actual temperature for selected channel
SETTEMPLIM=%f[CR][LF] | set operational temperature limit for selected channel in degrees of Celsius
GETDEVICESN[CR][LF] | get active device serial number
DETECTDEVICE[CR][LF] | run autodetection of device on active channel, answers with device Name
SETCURLIMIT=%f;f[CR][LF] | set operational current limits for selected channel in mA. First argument is positive limit (0, Max current), second one is negative (- Max current, 0>.
GETCURLIMIT[CR][LF] | get operational current limits for selected channel in mA

Simple mode answers

Simple mode answers | Description
--- | ---
OK[CR][LF] | confirmation that the command was understood and performed
NO[CR][LF] | invalid command
OL[CR][LF] | command parameter value below lower limit
OU[CR][LF] | command parameter value over upper limit
ERROR[CR][LF] | Response of "START" command if there is an active error. Type status to get the status register.

Protocol mode:

Pro mode is a byte-based protocol inspired by HDLC. Individual messages are delimited with the "delimiter" byte, 0x7e. To avoid the delimiter byte appearing in the message data, an "escape byte", 0x7d, is also used, and byte stuffing is performed on every message before being sent out (so the receiver should then perform byte destuffing) as follows: Every appearance of the bytes 0x7e or 0x7d in the data (so in a role other than the delimiter or the escape byte) is replaced by the sequence 0x7d 0x5e or 0x7d 0x5d, respectively. In other words, every byte that needs to be escaped is escaped by being XORed with 0x20 and prepended with 0x7d. When destuffing, every instance of 0x7d should be treated as an escape byte - it should not be interpreted as a data byte, it only marks that the following byte should be XORed with 0x20 before being interpreted as another data byte.

Above the delimiting and stuffing layer, every pro mode message has the following format:

Reserved (slave address) | Command | Data size | Data (payload) | CRC
--- | --- | --- | --- | ---
1 byte | 1 byte | 1 byte | 0 - 50 bytes | 2 bytes

The semantics of the individual fields are as follows:

- Slave address – this field is currently unused
- Command – a 1-byte unique identifier of the selected command (see below)
- Data size – the number of bytes in the following data field
- Data – the data required by the command / response, limited to 50 bytes
- CRC – the CRC checksum calculated using CRC-16 CCITT algorithm (polynomial seed = 0x1021, initial value = 0xFFFF), present even if CRC is deactivated (the values can be ignored in that case) *

Available commands:

Command name | Code | Command payload | Response payload | Note
--- | --- | --- | --- | ---
Generic command | 0x00 | empty | empty | Used for special purposes, such as error responses to commands with unclear command code
Get firmware identification | 0x01 | empty | 32bits firmware ID | N/A
Get status | 0x02 | empty | 32bits status register | N/A
Start self-test | 0x03 | empty | empty | N/A
Load configuration | 0x04 | 1 byte snapshot id | empty | 2 snapshots are available. 0 is the factory snapshot id.
Store configuration | 0x05 | 1 byte snapshot id | empty | 2 snapshots are available. Factory snapshot 0 is read only. Snapshot 1 can be stored by the user
Set communication mode | 0x06 | 1 byte mode | empty | 0 for simple mode, unchanged otherwise
Set value | 0x10 | 2 bytes register id, 4 bytes value | empty | see Architecture for explanation of Systems and registers
Get value | 0x11 | 2 bytes register id | 4 bytes register value | see Architecture for explanation of Systems and registers
Set multiple values | 0x12 | 2 bytes value count = CNT, 2xCNT bytes register ids, 4xCNT bytes register values | empty | see Architecture for explanation of Systems and registers
Get multiple values | 0x13 | 2 bytes value count = CNT, 2xCNT bytes register ids | 2 bytes value count = CNT, 4xCNT bytes register values | see Architecture for explanation of Systems and registers
Set vector | 0x14 | 2 bytes vector id, 2 bytes index, 1 byte length = SIZE, SIZE bytes data | empty | see Architecture for explanation of Systems and vectors; SIZE bytes starting at the index given are rewritten
Get vector | 0x15 | 2 bytes vector id, 2 bytes index, 1 byte length = SIZE | SIZE bytes data | see Architecture for explanation of Systems and vectors; SIZE bytes starting at the index given are read

Responses:

Responses have the same format as the commands (possibly with different payload data, see above) with the command code of the response corresponding to the command code of the command being responded to. However, error responses are marked by the most significant bit being set in the command code (in other words, an 0x80 is added to the command code), and the payload should consist of a single 4 byte error flag, see Error Codes.