User's Guide

Getting Started
EZ-Serial BLE Firmware Platform User Guide, Doc. No. 002-11259 Rev. *E 16
2.4.2 Using the API Protocol in Binary Mode
EZ-Serial also implements a binary-format API protocol that allows the same control of the platform using compact binary
commands, responses, and events. This mode is typically preferable when controlling the EZ-Serial-based module from
an external microcontroller. The binary byte stream is much easier to parse and generate from MCU application code than
human-readable text strings.
The binary protocol uses a fixed packet structure for every transaction in either direction. This fixed structure comprises a
4-byte header followed by an optional payload, terminating with a checksum byte. The payload carries information related
to the command, response, or event. If present, this payload always comes immediately after the header and before the
checksum byte.
Table 2-4. Binary Packet Structure
Header Payload (optional) Checksum
[0]
Type
[1]
Length
[2]
Group
[3]
ID
[4...
N
-1]
Parameter(s)
[N]
Summation
The checksum byte is calculated by starting from 0x99 and adding the value of each header and payload byte, rolling
over back to 0 (instead of 256) to stay within the 8-bit boundary. The checksum byte itself is not included in the
summation process. For the example 4-byte binary packet for the system_ping (/PING, ID=2/1) API command:
C0 00 02 01
Calculate the checksum as follows:
0x99 + 0xC0 + 0x00 + 0x02 + 0x01 = 0x15C
Retain only the final lower 8 bits (0x5C) for the 1-byte checksum value. The final 5-byte packet (including checksum) is:
C0 00 02 01 5C
The structure above allows a packet parser implementation to know exactly how much data to expect in advance any time
a new packet begins to arrive, and to calculate the checksum as new bytes arrive.
The “Type” byte in the header contains information not only about the packet type (highest two bits), but also the memory
scope (where applicable), and the highest three bits of the 11-bit “Length” value. For details on the binary packet format
and flow, see the API structural definition in Section 7.1 (Protocol Structure and Communication Flow).
2.4.2.1 Binary Mode Protocol Characteristics
The binary mode protocol has the following general behavior:
• Commands sent from the host must begin with a properly formatted 4-byte header.
• Commands must contain the number of payload bytes specified in the Length field from the header.
• Commands must end with a valid checksum byte, but no additional termination such as NULL or carriage return.
• Commands are always immediately followed by a response, if they are parsed correctly.
• Commands require all arguments to be supplied in the binary payload according to the protocol structural
definition, in the right order (no arguments are optional).
• Commands with syntax errors are followed by a system_error (ERR, ID=2/2) API event with an error code
indicating the nature of the problem, rather than a response packet.
• Commands must be fully transmitted within one second of the first byte, or the parser will time out and return to
an idle state after triggering the system_error (ERR, ID=2/2) API event with a timeout error code.
• All multi-byte integer data is entered and expressed in little-endian byte order (e.g. 0x12345678 is [78 56 34 12]).
Note that this only applies to API method arguments and parameters with a fixed width—1, 2, or 4-byte integers,
and 6-byte MAC addresses.
• All multi-byte data passed inside a variable-length byte array (uint8a or longuint8a) remains in the original
order provided by the source. This includes UUID data found during GATT discovery. If unsure, consult the API
reference manual to verify the argument data type.
• Response payloads always begin with a 16-bit “result” value as the first parameter, indicating success or failure
of the command triggering the response.