Spinel: Free binary serial protocol – online parser

Do you use Spinel? Are you working on an implementation and need to quickly verify that your data packet is valid? The parser on this page will come in handy. Here is a simple Spinel parser and validator that finds Spinel packets in the text and lists them clearly. It can also generate a Spinel packet including a checksum. No need to install anything – it works online.

If you don’t know what we call Spinel, it’s a binary communication protocol that we’ve been using for years in a lot of our devices. It is free to use in your devices (including commercial use). For more information about the Spinel protocol, see the SpinelTerminal page, which is a desktop application for debugging Spinel communications. For developers, there is also a .NET SDK in C# available on GitHub (with descriptions only in Czech for now). Also, detailed information about the Spinel implementation is always provided in the manual for the specific device.

Spinel input form

In the following text box, enter text in one of the formats listed. For each format you can view a specific example by clicking on “example”. The found Spinel packets are updated in the Spinel packets section below each time the input field is changed.

• Spinel parser: Text containing Spinel packets with bytes written in 0xAB or ABH format. The delimiter can be a space or a comma. Numbers without a 0x prefix or H suffix will be recognized as decadic format. example 1
• Spinel parser: Text containing Spinel packets with bytes written in hexadecimal as character pairs (e.g. 05, A2, CB, etc.). The separator may be a space or a comma. example 2
• Spinel Generator: JSON formatted text containing basic parts of the Spinel packet. example 3 example 4

 

Spinel packets

The output contains valid packets or packets with an incorrect checksum. Errors are highlighted in red. Mouse over to display the correct value or a hint:

Customizing the view: labels, 0x0B, 0BH, 0B, 10 • copy all

1. PRE: 2AH FRM: 61H NUM: 0005H ADR: 01H SIG: 02H INST: 31H DATA: [  ] SUM: 3BH CR: 0DH link copy
2. PRE: 2AH FRM: 61H NUM: 0006H ADR: 01H SIG: 02H ACK: 00H DATA: [ C2H ] SUM: A8H CR: 0DH link copy

Spinel packet structure

Detailed description of the structure of the Spinel packet is always in the manual for the specific device. Here is only a basic description of the data format.

• PRE 1 Byte Prefix, 0x2A – asterisk (char “*“).
• FRM 1 Byte Format No. 97 (0x61).
• NUM 2 Bytes Number of bytes in instruction from next byte to end of message.
• ADR 1 Byte Device address to which the request is sent or which sends the response.
• SIG 1 Byte Message Signature. SIG byte sent in the query is returned in the response. It is thus possible to know which query the response belongs to.
• INST 1 Byte Instruction code (0x10 to 0xFF).
• ACK 1 Byte Acknowledge (0x00 to 0x0F) informs whether the query was received, an error occurred, it is an automatic message, …
• DATA x Bytes Data. Data length varies according to the instruction.
• SUM 1 Byte Checksum.
• CR 1 Byte Ending character (Carriage Return, 0x0D, \r).

NUM: Number of bytes from ADR (inclusive) up to and including CR. It is two bytes, so the NUM can be up to 65535. The minimum is 5, which corresponds to an instruction with no data. If the NUM is less than 5, the packet is not valid. The upper byte is the MSB, the lower byte is the LSB. If the number of bytes is less than 256, the upper byte is null.

ADR: The device address can be in the range 0x00 to 0xFD (253). The following addresses are reserved for special use:

• 0xFF (255) si broadcast. This means that if the device receives a message with this address, the device will execute the instruction but will not send any response. Configuration using this address is not possible.
• 0xFE (254) is universal address. If the device receives a message with this address, the device acts as if it were its own address, executes the instruction, and sends a response. The universal address can only be used if there is only one device on the communication link. Configuration cannot be done with this address. Configuration using this address is not possible.

ACK ACK in the same place as the INST byte in the query. It is in the range 0x00 to 0x0F. This byte is used to inform the device about the status of the last received instruction. The reserved ACKs are as follows:

• 0x00 Ok: The instruction was received and executed.
• 0x01 General error: Unspecified error.
• 0x02 Unknown instruction code: Device does not know instruction code.
• 0x03 Data error: DATA has an unexpected length or contains an unexpected value.
• 0x04 Not permitted for any of the following reasons:
  • Attempting to change settings without a previous Configuration Enable instruction.
  • Attempt to write to inaccessible memory.
  • Required device function cannot be performed because the conditions for this are not met. For example, a higher communication speed is required.
  • Access to password-protected memory.
• 0x05 Failure:
  • Device needs service.
  • Device internal memory or settings memory error.
  • Internal device peripheral error.
  • Any other error affecting the proper functioning of the device.
• 0x06 No data available: For example, shortly after powering up the device, readings from external sensors may not yet be available, etc.
• 0x0A to 0x0F are messages that the device has sent automatically without any request from the parent system. For example, notifications of changes in the input, periodic measurements, logs, etc..

SUM is the checksum. A message with an incorrect checksum is not responded to. The CR byte is waited for even if an incorrect checksum is received. It is calculated as follows: SUM = 0xFF – ((PRE + FRM + ((NUM & 0xFF00) >> 8) + (NUM & 0xFF) + ADR + SIG + ACK_INST + DATA) & 0xFF)