SPI Protocol Data Format#

Data Format#

The data format, also referred to as a command, is the same for both the Command section and the Response section. The data format of the SPI Protocol is straightforward, as illustrated in the following figure.

The total length of a command must not exceed 136 bytes.

All commands must begin with the SPI Byte. Some commands are only two bytes—that is, they contain the SPI Byte and Frame Terminator only.

The Length Byte is only included if there is information in the Payload Frame and the Length Byte defines the length of just the Payload Frame. Therefore, if a command includes a Payload Frame, the Length Byte can have a value from 3 through 133 and the overall command size will be from 6 through 136 bytes. The SPI Byte can be a specific value indicating if there is a Payload Frame or not. If there is a Payload Frame, then the Length Byte can be expected.

The Error Byte is used by the error responses to provide additional information about the error and appears in place of the length byte. This additional information is described in the following sections.

The Payload Frame contains the data needed for operating EmberZNet PRO. The EZSP Frame and its format are explained in UG100: EZSP Reference Guide. The Payload Frame may also contain the data needed for operating the bootloader, which is called a Bootloader Frame. Refer to UG103.6: Bootloading Fundamentals, for more information on the bootloader.

The Frame Terminator is a special control byte used to mark the end of a command. The Frame Terminator byte is defined as 0xA7 and is appended to all Commands and Responses immediately after the final data byte. The purpose of the Frame Terminator is to provide a known byte the SPI Protocol can use to detect a corrupt command. For example, if the NCP resets during the Response Section, the Host will still clock out the correct number of bytes. But when the host attempts to verify the value 0xA7 at the end of the Response, it will see either the value 0x00 or 0xFF and know that the NCP just reset and the corrupt Response should be discarded.

Note: The Length Byte only specifies the length of the Payload Frame. It does not include the Frame Terminator.

SPI Bytes#

There are four primary SPI Bytes: SPI Protocol Version, SPI Status, Bootloader Frame, and EZSP Frame.

• SPI Protocol Version [0x0A]: Sending this command requests the SPI Protocol Version number from the SPI Interface. The response will always have bit 7 set and bit 6 cleared. In this current version, the response will be 0x82, because the version number corresponding to this set of Command-Response values is version number 2. The version number can be a value from 1 to 63 (0x81–0xBF).

• SPI Status [0x0B]: Sending this command asks for the NCP status. The response status byte will always have the upper 2 bits set. In this current version, the status byte only has one status bit [0], which is set if the NCP is alive and ready for commands.

• Bootloader Frame [0xFD]: This byte indicates that the current transaction is a Bootloader transaction and there is more data to follow. This SPI Byte will cause the transaction to look like the full data format illustrated in EZSP-SPI Protocol Data Format. The byte immediately after this SPI Byte will be a Length Byte, and it is used to identify the length of the Bootloader Frame. Refer to UG103.6: Bootloading Fundamentals, for more information on the bootloader. If the SPI Byte is 0xFD, the minimum transaction size is 4 bytes.

• EZSP Frame [0xFE]: This byte indicates that the current transaction is an EZSP transaction and there is more data to follow. This SPI Byte will cause the transaction to look like the full data format illustrated in EZSP-SPI Protocol Data Format. The byte immediately after this SPI Byte will be a Length Byte, and it is used to identify the length of the EZSP Frame. The EZSP Frame is defined in document UG100: EZSP Reference Guide. If the SPI Byte is 0xFE, the minimum transaction size is six bytes.

Only five SPI Byte values, 0x00–0x04, are ever used as error codes (see the following table). When the error condition occurs, any command sent to the NCP will be ignored and responded to with one of these codes. These special SPI Bytes must be trapped and dealt with. In addition, for each error condition, the Error Byte (instead of the Length Byte) is also sent with the SPI Byte. See section Error Bytes for more information.

The following table summarizes the possible commands and their responses in the SPI Byte.