Low-level protocol
This document describes the low-level binary communication protocol used between SPORTident devices and the host (typically a PC or phone). The protocol is a packet-based serial communication protocol that operates over USB. The protocol is used by the BSM8 and BSM7 stations as well as by the SRR USB Dongle. The current version of the protocol has been in place since before 2012 and has seen no changes since then.
The earlier legacy protocol (command code <0x80, no length byte, no CRC) is longer documented and supported.
TODO
- Mention Config+ Debug mode
- Section on looking for the right USB devices
- Document typical connection procedure (instead of “station detection procedure”)
- Document slave mode
- Document set sysmem?
- USB devices are always baud rate 38400
- Document serial interface configuration (only relevant for old serial devices?)
- baud-rates: 4800 baud, 38400 baud
- bits: 8
- parity: no
- stop bits: 1
- hardware handshake: no
Packet structure
Basic frame format
All messages follow this structure:
[PRE] [STX] [CMD] [LEN] [DATA...] [CRC_HIGH] [CRC_LOW] [ETX]Field descriptions:
| Field | Size | Value | Description |
|---|---|---|---|
| PRE | 1 byte | 0xFF | Frame preamble |
| STX | 1 byte | 0x02 | Start marker |
| CMD | 1 byte | varies | Command |
| LEN | 1 byte | 0-255 | Length of DATA field (not including CMD, LEN, or CRC) |
| DATA | 0-255 bytes | varies | Command-specific payload data |
| CRC_HIGH | 1 byte | varies | CRC-16 high byte |
| CRC_LOW | 1 byte | varies | CRC-16 low byte |
| ETX | 1 byte | 0x03 | End marker |
Special control bytes
| Byte | Value | Name | Purpose |
|---|---|---|---|
| ACK | 0x06 | Acknowledge | Command understood |
| NAK | 0x15 | Negative Acknowledge | Command not recognized or failed |
CRC calculation
Station detection procedure
only really makes sense for serial devices (detecting different baudrates) — so write this in a different way
Commands
Set MS mode
Description: Configure the station’s Master/Slave mode for direct or remote operation.
Command code: 0xF0
Request (TX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0xF0 | Set MS Mode |
| 1 | LEN | 0x01 | |
| 2 | Mode | 0x4D or 0x53 | 0x4D = Direct mode0x53 = Remote mode |
Response (RX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0xF0 | Set MS Mode (echoed) |
| 1 | LEN | 0x03 | |
| 2 | CN1 | varies | Control number high byte |
| 3 | CN0 | varies | Control number low byte |
| 4 | Mode | varies | Current mode |
Set system values
Description: Write system configuration values to the device memory.
Command code: 0x82
Request (TX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0x82 | Set System Values |
| 1 | LEN | 1 + NUM | |
| 2 | ADR | varies | Memory address to write to |
| 3+ | DAT | varies | Data to write (NUM bytes) |
Response (RX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0x82 | Set System Values (echoed) |
| 1 | LEN | 0x03 | |
| 2 | CN1 | varies | Control number high byte |
| 3 | CN0 | varies | Control number low byte |
| 4 | ADR | varies | Memory address (echoed) |
Get system values
Description: Read system configuration values from the device memory.
Command code: 0x83
Request (TX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0x83 | Get System Values |
| 1 | LEN | 0x02 | |
| 2 | ADR | varies | Memory address to read from |
| 3 | NUM | 1-255 | Number of bytes to read |
Response (RX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0x83 | Get System Values (echoed) |
| 1 | LEN | 3 + NUM | |
| 2 | CN1 | varies | Control number high byte |
| 3 | CN0 | varies | Control number low byte |
| 4 | ADR | varies | Memory address (echoed) |
| 5+ | DAT | varies | Requested data (NUM bytes) |
Set baud rate
Description: Change the serial communication baud rate. Only meaningful for legacy serial devices, USB devices are always 38400 baud.
Command code: 0xFE
Request (TX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0xFE | Set Baud Rate |
| 1 | LEN | 0x01 | |
| 2 | BDR | 0x00 or 0x01 | 0x00 = 4800 baud0x01 = 38400 baud |
Response (RX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0xFE | Set Baud Rate (echoed) |
| 1 | LEN | 0x03 | |
| 2 | CN1 | varies | Control number high byte |
| 3 | CN0 | varies | Control number low byte |
| 4 | BDR | varies | Current baud rate |
Get backup data
Description: Read backup memory data from the device.
Command code: 0x81
Request (TX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0x81 | Get Backup Data |
| 1 | LEN | 0x04 | |
| 2 | ADR2 | varies | Address high byte |
| 3 | ADR1 | varies | Address middle byte |
| 4 | ADR0 | varies | Address low byte |
| 5 | NUM | 1-255 | Number of bytes to read |
Response (RX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0x81 | Get Backup Data (echoed) |
| 1 | LEN | 5 + NUM | |
| 2 | CN1 | varies | Control number high byte |
| 3 | CN0 | varies | Control number low byte |
| 4 | ADR2 | varies | Address high byte (echoed) |
| 5 | ADR1 | varies | Address middle byte (echoed) |
| 6 | ADR0 | varies | Address low byte (echoed) |
| 7+ | DAT | varies | Backup data (NUM bytes) |
Erase backup data
Description: Reset the backup memory pointer.
Command code: 0xF5
Request (TX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0xF5 | Erase Backup Data |
| 1 | LEN | 0x00 | No payload |
Response (RX)
| Offset | Field | Value | Description |
|---|---|---|---|
| 0 | CMD | 0xF5 | Erase Backup Data (echoed) |
| 1 | LEN | 0x02 | |
| 2 | CN1 | varies | Control number high byte |
| 3 | CN0 | varies | Control number low byte |
System memory
We document some of the parameters stored in the system memory. Do not overwrite unknown system memory locations as this can render the SPORTident station non-functional or — worse — change the functionality in subtle ways that you might not immediately notice.
| Offset | Field | Description |
|---|---|---|
| 0x1C | EP3 | Backup memory pointer byte 3 (highest) |
| 0x1D | EP2 | Backup memory pointer byte 2 |
| 0x21 | EP1 | Backup memory pointer byte 1 |
| 0x22 | EP0 | Backup memory pointer byte 0 (lowest) |
| 0x74 | CPC | Protocol configuration (see below) |
CPC (protocol configuration)
The CPC byte at offset 0x74 controls various protocol and operational modes of the device. Each bit has a specific function:
| Bit | Mask | Field Name | Description |
|---|---|---|---|
| 0 | 0x01 | Protocol Version | Always 1( 0 = Legacy protocol, 1 = Modern protocol) |
| 1 | 0x02 | AutoSend Mode | 0 = AutoSend disabled1 = AutoSend enabled |
| 2 | 0x04 | Communication Mode | Has to be 1 for operating mode readout, 0 otherwise( 1 handshake mode, 0 non-handshake mode) |
| 3 | 0x08 | Sprint Mode | 0 = Sprint mode disabled1 = Sprint mode enabled |
| 4 | 0x10 | Not used | Always 0(Used to be Password Protection) |
| 5 | 0x20 | Stop If Backup Full | 0 = Continue operation1 = Stop operation when backup is full |
| 6 | 0x40 | Not used | Always 0 |
| 7 | 0x80 | Not used | Always 0(Used to be Read Out After Punch) |
Backup memory
Memory access and navigation are done using the „Get backup data“ instruction. The navigation is based on the „memory pointer“ value. The memory pointer directs to the first non used memory location. The memory pointer value has to be read using the „Get system value“ (0x83) instruction.
The backup memory has a size of 128k byte = 0x200000. The lowest address is 0x100 or the backup memory pointer address - 128k. Data stored in the backup memory have to be read out by specifying the backup memory start address and the number of bytes to be read. The maximal record size is 128 bytes. In case of errors in the readout process it is recommended to reduce the record size. The record size NUM should be adapted according to the size of data packages stored in the stations memory:
- Card data (readout and printout operating modes): 128 bytes
- Punch data (all other operating modes): Multiple of 8 bytes
The backup memory is organized as a ring buffer. The backup memory address pointer increments automatically and the overflow resets the pointer to the start value. First data will be overwritten.
Punch record
| Offset | Field | Description |
|---|---|---|
| 0 | SI2 | SI-Card number 2 (highest) |
| 1 | SI1 | SI-Card number 1 |
| 2 | SI0 | SI-Card number 0 (lowest) |
| 3 | DATE1 | Date high byte year (bit 7 - 2) month (bit 1 - 0) |
| 4 | DATE0 | Date low byte month continued (bit 7 - 6) day of month (bit 5 - 1) am/pm (bit 0) |
| 5 | TH | Time high byte (in seconds, up to 12 hours) |
| 6 | TL | Time low byte (in seconds, up to 12 hours) |
| 7 | MS | Milliseconds in multiples of 1/256 second |