Frame Layout#
The host and the Z-Wave chip (ZW) communicate through a simple protocol, which uses ACK, NAK, CAN, and Data frame types.
ACK Frame#
The ACK frame indicates that the receiving end has received a valid Data frame.
The host MUST wait for an ACK frame after transmitting a Data frame to the Z-Wave chip. If transmission errors or race conditions occur, the host may receive other frames or no frames at all. The host MUST be robust to handle such events. The host SHOULD queue up requests for processing once the expected ACK frame is received or timed out. The host MUST wait 1500 ms before timing out waiting for the ACK frame.
A receiving Z-Wave chip MUST return an ACK frame in response to a valid Data frame.
7 (MSB) | 6 | 5 | 4 | 3 | 2 | 1 | 0 (LSB) |
|---|---|---|---|---|---|---|---|
ACK (0x06) | |||||||
NAK Frame#
The NAK frame indicates that the receiving end has received a Data frame with errors.
If a transmitting host or Z-Wave chip receives a NAK frame in response to a Data frame, it MAY retransmit the Data frame.
7 (MSB) | 6 | 5 | 4 | 3 | 2 | 1 | 0 (LSB) |
|---|---|---|---|---|---|---|---|
NAK (0x15) | |||||||
A transmitting host or Z-Wave chip receiving a NAK frame MUST wait for a while before retransmitting the Data frame. See Retransmission.
CAN Frame#
The CAN frame indicates that the receiving end has discarded an otherwise valid Data frame. The CAN frame is used to resolve race conditions, where both ends send a Data frame and subsequently expects an ACK frame from the other end.
7 (MSB) | 6 | 5 | 4 | 3 | 2 | 1 | 0 (LSB) |
|---|---|---|---|---|---|---|---|
CAN (0x18) | |||||||
If a Z-Wave chip expects to receive an ACK frame but receives a Data frame from the host, the Z-Wave chip SHOULD return a CAN frame. A host which receives a CAN frame MUST consider the Data frame lost. The host MUST wait for a while before retransmitting the Data frame. See Retransmission.
Data Frame#
Data frame contains the Serial API command including parameters for the command in question.
Each Data frame MUST consist of a Serial API command including parameters for the command prepended with Start of Frame (SOF), Length and Type fields, and a Checksum byte appended.
A transmitting host or Z-Wave chip may time out waiting for an ACK frame after transmitting a Data frame. The transmitting end MUST wait for ACK frame for a period. If no ACK frame is received, the Data frame MAY be retransmitted. See Retransmission.
7 (MSB) | 6 | 5 | 4 | 3 | 2 | 1 | 0 (LSB) |
|---|---|---|---|---|---|---|---|
SOF (0x01) | |||||||
Length | |||||||
Type | |||||||
Serial API Command ID | |||||||
Serial API Command Parameter 1 | |||||||
… | |||||||
Serial API Command Parameter n | |||||||
Checksum | |||||||
Start of Frame (SOF)#
The Start of Frame (SOF) field is used for synchronization. The SOF field MUST have a value of 0x01. A host or a Z-Wave chip waiting for new traffic MUST ignore all other byte values except 0x06 (ACK), 0x15 (NAK), 0x18 (CAN), or 0x01 (Data frame). This way, both receivers will flush garbage bytes from the receive buffer to get back in sync after a connection glitch or a firmware restart in one of the ends.
Length#
The Length field MUST report the number of bytes in the Data frame. The value of the Length Field MUST NOT include the SOF and Checksum fields. A host or a Z-Wave chip receiving a Data frame SHOULD validate the length field by comparing the number of received bytes and the Length field (expecting a difference of 2 bytes).
Type#
The Type field MUST indicate if the Data frame type is Request or Response.
| Value | Type | Description |
|---|---|---|
| 0x00 | REQ |
Request. This type MUST be used for unsolicited messages. API callback messages MUST use the Request type. |
| 0x01 | RES |
Response. This type MUST be used for messages that are responses to Requests. |
| 0x02..0xFF | Reserved |
Reserved values MUST NOT be used. A receiving end MUST ignore reserved Type values. |
Serial API Command ID#
The Serial API Command ID field MUST carry one of the valid API function codes defined in Serial API Commands. A host or Z-Wave chip MUST report the same Serial API Command ID in a response Data frame, as shown in the table above.
Serial API Command Parameters#
The Serial API Command Parameters field MAY have a variable number of bytes. The field MUST be at least one byte long. A receiving end MUST derive the actual number of bytes from the Length field. See Length above.
Information carried in the Serial API Command Parameters field MUST comply with the API function prototype for the Serial API Command ID carried in the Serial API Command ID field.
API function prototypes may be found in Serial API Commands7.
funcID Parameter#
Some Serial API calls contain a funcID parameter. Any funcID value different than zero is returned in the callback function making it possible to correlate the callback with the original request. Setting funcID to zero disables the callback function via serial API.
Checksum#
The Checksum field MUST carry a checksum to enable frame integrity checks. The checksum calculation MUST include the Length, Type, Serial API Command Data, and Serial API Command Parameters fields.
The checksum value MUST be calculated as an 8-bit Longitudinal Redundancy Check (LRC) value. The RECOMMENDED way to calculate the checksum is to initialize the checksum to 0xFF and then XOR each of the bytes of the fields mentioned above one at a time to the checksum value.
Checksum = 0xFF ⊕ Length ⊕ Type ⊕ Cmd ID ⊕ Cmd Parm[1] ⊕ … ⊕ Cmd Parm[n]A Data frame MUST be considered invalid if it is received with an invalid checksum. A host or Z-Wave chip MUST return a NAK frame in response to an invalid Data frame.