Serial API Commands#
Besides the Z-Wave API function calls described in “Z-Wave application programmers’ guide” the Serial API support a set of additional commands.
Application Node Information Command#
Starting with the Serial API protocol version 4, it is possible to call Serial API Application Node Information Command to store a new Node Information Frame (NIF). Prior to either starting or joining a Z-Wave network, the HOST needs to initially set up the Node Information Frame (NIF), which should define the type of Z-Wave node the Serial API module is supposed to be. To store the NIF in the protocol NVM area as well as in the application NVM area, the HOST needs to perform the following steps:
HOST->ZW: send SerialAPI_ApplicationNodeInformation() with NIF information.
HOST->ZW: send ZW_SetDefault().
| Serial API: |
|---|
| HOST->ZW: REQ | 0x03 | deviceOptionsMask | generic | specific | parmLength | nodeParm[ ] |
For more details, see the relevant Application Programming Guide [3].
Application Node Information Command Classes Command#
Starting with SDK 6.71.00, HOSTs connected to Serial API modules based on the End Device Routing or End Device Enhanced 232 library can set the Command Classes which should be supported in NOT Included, Insecurely Included, and Securely Included inclusion states. Supported command classes as set through the Serial API Application Node Information Command Classes Command with the
FUNC_ID_SERIAL_API_APPL_NODE_INFORMATION_CMD_CLASSES Serial API command.
| Serial API: |
|---|
|
HOST->ZW: REQ | 0x0C | unincluded_parmLength | unincluded_nodeParm[unincluded_parmLength] | included_unsecure_parmLength | included_unsecure_nodeParm[included_unsecure_parmLength] | included_secure_parmLength | included_secure_nodeParm[included_secure_parmLength] ZW->HOST: RES | 0x0C | status Status: 0x01: Success |
SDK 6.71.00 adds Security to the protocol in the End Device Routing and End Device Enhanced 232 libraries resulting in additional setup steps before entering the inclusion process. Prior to joining a Z-Wave network, the HOST needs to initially set up which Security keyclasses (S0, S2_UNATHENTICATED, S2_AUTHENTICATED, S2_ACCESS) the node should apply for (if any). Afterwards the Security Authentication method must be specified. The Node Information Frame (NIF) which should define the type of Z-Wave node the Serial API module should be defined with regard to Listening, FLiRS, Generic type, Specific Type. Finally, the supported Command Classes for the various inclusion states should be set up.
Serial API:
In the Serial API, the Security API functions are reached through the FUNC_ID_ZW_SECURITY_SETUP (0x9C). Serial API FUNC_ID makes it possible to set the Requested Security Keys and Requested Authentication method in a End Device Routing/Enhanced 232-based Serial API Node prior to inclusion (add). The protocol requests the Requested Security Keys and Authentication during S2 inclusion.
Set Security Inclusion Requested Keys (E_SECURITY_SETUP_CMD_SET_SECURITY_INCLUSION_REQUESTED_KEYS):
HOST->ZW: REQ | 0x9C | 5 | registeredSecurityKeysLen(1) | registeredSecurityKeys
ZW->HOST: RES | 0x9C | 5 | retValLen(1) | retVal
retVal == TRUE => success
Set Security Inclusion Requested Authentication (E_SECURITY_SETUP_CMD_SET_SECURITY_INCLUSION_REQUESTED_AUTHENTICATION):
HOST->ZW: REQ | 0x9C | 6 | registeredSecurityAuthenticationLen(1) | registeredSecurityAuthentication
ZW->HOST: RES | 0x9C | 6 | retValLen(1) | retVal
Or if unsupported
ZW->HOST: RES | 0x9C | 0xFF | retValLen(1) | retVal
retVal == TRUE => success
HOSTs, which are connected to a Serial API module based on either End Device Enhanced 232 or End Device Routing libraries should follow the list below for correct module setup prior to joining a Z-Wave network:
HOST->ZW: send SerialAPI_SetSecurityInclusionRequestedKeys
HOST->ZW: send SerialAPI_SetSecurityInclusionRequestedAuthentication
HOST->ZW: send SerialAPI_ApplicationNodeInformation() with NIF information (listening, generic, specific)
HOST->ZW: send SerialAPI_ApplicationNodeInformationCmdClasses
HOST->ZW: send ZW_SetDefault()
Capabilities Command#
Starting with the Serial API protocol version 4, users can call the Serial API Capabilities Command to determine which Serial API functions a specific Serial API Z-Wave Module supports with the FUNC_ID_SERIAL_API_GET_CAPABILITIES Serial API function:
| Serial API: |
|---|
|
HOST->ZW: REQ | 0x07 ZW->HOST: RES | 0x07 | SERIAL_APPL_VERSION | SERIAL_APPL_REVISION | SERIALAPI_MANUFACTURER_ID1 | SERIALAPI_MANUFACTURER_ID2 | SERIALAPI_MANUFACTURER_PRODUCT_TYPE1 | SERIALAPI_MANUFACTURER_PRODUCT_TYPE2 | SERIALAPI_MANUFACTURER_PRODUCT_ID1 | SERIALAPI_MANUFACTURER_PRODUCT_ID2 | FUNCID_SUPPORTED_BITMASK[ ] |
|
SERIAL_APPL_VERSION is the Serial API application Version number. SERIAL_APPL_REVISION is the Serial API application Revision number. SERIALAPI_MANUFACTURER_ID1 is the Serial API application manufacturer_id (MSB). SERIALAPI_MANUFACTURER_ID2 is the Serial API application manufacturer_id (LSB). SERIALAPI_MANUFACTURER_PRODUCT_TYPE1 is the Serial API application manufacturer product type (MSB). SERIALAPI_MANUFACTURER_PRODUCT_TYPE2 is the Serial API application manufacturer product type (LSB). SERIALAPI_MANUFACTURER_PRODUCT_ID1 is the Serial API application manufacturer product ID (MSB). SERIALAPI_MANUFACTURER_PRODUCT_ID2 is the Serial API application manufacturer product ID (LSB). FUNCID_SUPPORTED_BITMASK[ ] is a bitmask where every supported Serial API function ID has a corresponding bit in the bitmask set to '1'. All unsupported Serial API function IDs have their corresponding bit set to '0'. The first byte in bitmask corresponds to FuncIDs 1-8, where bit 0 corresponds to FuncID 1 and bit 7 corresponds to FuncID 8. The second byte in bitmask corresponds to FuncIDs 9-16, and so on. |
Node List Command#
Get Init Data#
Starting with the Serial API protocol version 4, users can call the Serial API Node List Command to determine the Serial API protocol version number, Serial API capabilities, nodes currently stored in the external NVM (only controllers), and a chip used in a specific Serial API Z-Wave Module with the FUNC_ID_SERIAL_API_GET_INIT_DATA Serial API function:
| Serial API: |
|---|
|
HOST->ZW: REQ | 0x02 (Controller) ZW->HOST: RES | 0x02 | ver | capabilities | 29 | nodes[29] | chip_type | chip_version (End Device) ZW->HOST: RES | 0x02 | ver | capabilities | 0 | chip_type | chip_version |
The parameter ver is the Serial API application Version number.
The parameter capabilities is a byte holding various flags describing the actual mode.
| Capabilities flags: |
|---|
| Bit 0: 0 = Controller API; 1 = End device API |
| Bit 1: 0 = Timer functions not supported; 1 = Timer functions supported. |
| Bit 2: 0 = Primary Controller; 1 = Secondary Controller |
| Bit 3: 0 = Not SIS; 1 = Controller is SIS |
| Bit 4-7: reserved |
Timer functions supported comprises of TimerStart, TimerRestart, and TimerCancel.
29 or 0 specifies the length of nodes[] array
nodes[29] is a node bitmask. The chip used can be determined as follows:
Z-Wave Chip | Chip_type | Chip_version |
|---|---|---|
ZW0102 | 0x01 | 0x02 |
ZW0201 | 0x02 | 0x01 |
ZW0301 | 0x03 | 0x01 |
ZM0401 | 0x04 | 0x01 |
ZM4102 | 0x04 | 0x01 |
SD3402 | 0x04 | 0x01 |
ZW050x | 0x05 | 0x00 |
ZGM130S | 0x07 | 0x00 |
ZG14 | 0x07 | 0x00 |
ZG23 | 0x08 | 0x00 |
ZGM230S | 0x08 | 0x00 |
Get Long Range Nodes#
In Z-Wave Long Range network, function FUNC_ID_SERIAL_API_GET_LR_NODES is used to obtain the list of Long Range nodes:
HOST->ZW: REQ | 0xDA | BITMASK_OFFSET
ZW->HOST: RES | 0xDA | MORE_NODES | BITMASK_OFFSET | BITMASK_LEN | BITMASK_ARRAY
MORE_NODES: byte, has value 1 if more nodes is available and the host can request the next chunk of the nodes bitmask array. Currently it always returns 0 as max supported number of LR nodes can fit in 128 bytes.
BITMASK_OFFSET: 16 bit value. Supported values: 0, 1, 2, 3 that corresponds to offset 0, 128, 256, 384. If BITMASK_OFFSET is not one of the values mentioned above it will be round down to the nearest value. Currently values higher than 0 won’t contain any nodes.
BITMASK_LEN: byte, hardcoded to 128 bytes.
BITMASK_ARRAY: an array of 128 bytes, with least significant bytes first, contains a bitmask of the available nodes in the network.
If bit N in byte J (J >= 0) is set to 1, then node with ID = BASE + 8*J + N + BITMASK_OFFET, where BASE = 256, exists in network.
Set Timeouts Command#
The timeout in the Serial API (starting with the Serial API version 4) can be set in 10 ms ticks by using the FUNC_ID_SERIAL_API_SET_TIMEOUTS Serial API function:
| Serial API: |
|---|
|
HOST->ZW: REQ | 0x06 | RXACKtimeout | RXBYTEtimeout ZW->HOST: RES | 0x06 | oldRXACKtimeout | oldRXBYTEtimeout |
Set up ZW_SendData Callback Parameters#
The callback parameter list extension (starting with the Serial API version 6) can be controlled by using FUNC_ID_SERIAL_API_SETUP Serial API function:
| Serial API: |
|---|
|
HOST->ZW: REQ | 0x0B | 0x02 | enableTxStatusReport ZW->HOST: RES | 0x0B | 0x02 | CmdRes[] enableTxStatusReport = 0, No extra parameters can be transmitted on callback enableTxStatusReport = 1, Extra parameters should be transmitted on callback (Default) Must be called after reset if none Default setting is required. |
Supported SERIAL_API_SETUP_CMD commands#
All supported SERIAL_API_SETUP commands can be obtained by using SERIAL_API_SETUP_CMD_SUPPORTED subcommand of SERIAL_API_SETUP_CMD
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_ SUPPORTED | |||||||
ZW -> Host:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_ SUPPORTED | |||||||
Supported flags | |||||||
Supported bitmask 0 | |||||||
Supported bitmask 1 | |||||||
… | |||||||
Supported bitmask 16 | |||||||
Supported flags
SERIAL_API_SETUP_CMD supported commands besides SERIAL_API_SETUP_CMD_SUPPORTED, represented as bitmask flag. Example: SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET | SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET | … Includes only commands with values 2^N. Newer commands that don’t have such value are reported in Supported Bitmask.
Supported bitmask
Array of bytes including all supported commands, represented as bitmask of values, with least significant bytes first. Example: (1 << SERIAL_API_SETUP_CMD_SUPPORTED) | (1<< SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET) | (1<< SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET) | …
Configuration of Default Tx Power Level#
By default, the transmit power level is hard coded in the Z-Wave image downloaded to the Z-Wave chip. However, hardware differences in products may require changing the Tx power. Changing the default Tx power will require the following steps:
Use the SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET command to set the power levels to desired values.
Use the FUNC_ID_SERIAL_API_SOFT_RESET command to restart the Z-Wave module so the new settings are activated.
Set Default Tx Power Level#
The Transmit power can be configured through Serial API (starting with Serial API version 7) by using FUNC_ID_SERIAL_API_SETUP Serial API function, subfunction SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET.
The power levels set by this function are first used by the Z-Wave protocol next time the module is restarted.
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET | |||||||
NormalTxPower | |||||||
Measured0dBmPower | |||||||
NormalTxPower
The power level used when transmitting frames at normal power. The power level is in deci dBm, for example 1 dBm output power will be 10 in NormalTxPower and -2 dBm will be -20 in NormalTxPower.
Measured0dBmPower
The output power measured from the antenna when NormalTxPower is set to 0 dBm. The power level is in deci dBm, for example 1d Bm output power will be 10 in Measured0dBmPower and -2 dBm will be -20 in Measured0dBmPower.
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET | |||||||
CmdRes | |||||||
CmdRes
Result of the command
CmdRes = 0 – Power levels was not set.
CmdRes = 1 – Power levels was set.
Get Default Tx Power Level#
The Transmit power can be read through the serial API (starting with Serial API version 7) by using FUNC_ID_SERIAL_API_SETUP Serial API function, subfunction SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET:
HOST->ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET | |||||||
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET | |||||||
NormalTxPower | |||||||
Measured0dBmPower | |||||||
NormalTxPower
The power level used when transmitting frames at normal power. The power level is in deci dBm, for example 1 dBm output power will be 10 in NormalTxPower and -2 dBm will be -20 in NormalTxPower
Measured0dBmPower
The output power measured from the antenna when NormalTxPower is set to 0 dBm. The power level is in deci dBm, for example 1 dBm output power will be 10 in Measured0dBmPower and -2 dBm will be -20 in Measured0dBmPower.
Get the Background RSSI Levels for each channel#
The command FUNC_ID_ZW_GET_BACKGROUND_RSSI returns the Background RSSI level for each valid channel. The command always returns four RSSI values expressed in dBm (8bit each): only the ones corresponding to valid channels contain the measured Background RSSI levels, the remaining are set to 0x7F (i.e., 127 dBm). The valid background RSSI levels range from -105 dBm and +30 dBm.
The number of valid channels depends on the region, the device type (controller/end device) and whether the end device node is included or not. In the following table there is a summary of the possible configurations. The four Background RSSI levels have assigned an index from 0 to 3 to identify them.
| Region | Device Type | Included (for End-devices) | Valid Background RSSI levels (index) |
|---|---|---|---|
| 2-channels | Controller/End-device | - |
0 (100kbps) 1 (9.6kbps) 2 (40kbps) |
| 3-channels | Controller/End-device | - |
0 (100kbps), 1 (100kbps), 2 (100kbps) |
| 4-channels (US_LR with ZW_LR_CHANNEL_A as 4th channel) | Controller | - |
0 (100kbps) 1 (9.6kbps) 2 (40kbps) 3 (ZW_LR_CHANNEL_A) |
| End-device | No |
0 (100kbps) 1 (9.6kbps) 2 (40kbps) 3 (ZW_LR_CHANNEL_A) |
|
| End-device | Yes |
0 (ZW_LR_CHANNEL_A) 1 (ZW_LR_CHANNEL_B) |
|
| 4-channel (US_LR with ZW_LR_CHANNEL_B as 4th channel) | Controller | - |
0 (100kbps) 1 (9.6kbps) 2 (40kbps) 3 (ZW_LR_CHANNEL_B) |
| End-device | No |
0 (100kbps) 1 (9.6kbps) 2 (40kbps) 3 (ZW_LR_CHANNEL_B) |
|
| End-device | Yes |
0 (ZW_LR_CHANNEL_A) 1 (ZW_LR_CHANNEL_B) |
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_ZW_GET_BACKGROUND_RSSI | |||||||
ZW -> Host:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_ZW_GET_BACKGROUND_RSSI | |||||||
RSSI[0] | |||||||
RSSI[1] | |||||||
RSSI[2] | |||||||
RSSI[3] | |||||||
RSSI:
The function returns the Background RSSI levels (8-bit signed values) for the valid channels, 0x7F otherwise (see Table above).
Configuration of the RF Region Setting#
Configuration Any Time#
To change the RF Region setting at any time, use the sequence of commands below:
Use the SERIAL_API_SETUP_CMD_RF_REGION_SET command to set the RF Region setting to the new value.
Use the FUNC_ID_SERIAL_API_SOFT_RESET command to restart the Z-Wave module so the new setting gets activated.
Set RF Region#
The RF Region setting can be configured through serial API (starting with the Serial API version 8) by using FUNC_ID_SERIAL_API_SETUP Serial API function, sub-function SERIAL_API_SETUP_CMD_RF_REGION_SET.
The RF Region set by this function is first used by the Z-Wave protocol next time the module is restarted.
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_RF_REGION_SET | |||||||
RfRegion | |||||||
RfRegion
The RF Region value to be set.
RF Region | Value |
|---|---|
Region EU | 0x00 |
Region US | 0x01 |
Region Australia/New Zealand | 0x02 |
Region Hong Kong | 0x03 |
Region Malaysia | 0x04 |
Region India | 0x05 |
Region Israel | 0x06 |
Region Russia | 0x07 |
Region China | 0x08 |
Region US (Z-Wave & Z-Wave Long Range) | 0x09 |
Region Japan | 0x20 |
Region Korea | 0x21 |
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_RF_REGION_SET | |||||||
CmdRes | |||||||
CmdRes
Result of the command
CmdRes = 0 – RF Region was not set (invalid value specified or error setting the value in firmware).
CmdRes = 1 – RF Region was successfully set.
Get RF Region#
The RF Region setting can be read through serial API (starting with the Serial API version 8) by using FUNC_ID_SERIAL_API_SETUP Serial API function, sub-function SERIAL_API_SETUP_CMD_RF_REGION_GET:
HOST->ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_RF_REGION_GET | |||||||
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET | |||||||
RfRegion | |||||||
RfRegion
The returned RF Region value
See the SERIAL_API_SETUP_CMD_RF_REGION_SET command (p. 36) for details about the valid RF Region values.
RfRegion = 0xFE – Error retrieving the RF Region value
DCDC Configuration Commands#
The current DCDC configuration can be updated or retrieved using Set DCDC Configuration and Get DCDC Configuration Commands, respectively.
Set DCDC Configuration Command#
The host CPU system can set the DCDC Configuration by using the Serial API function FUNC_ID_SET_DCDC_CONFIG (0xDF).
HOST->ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SET_DCDC_CONFIG | |||||||
DCDC Configuration | |||||||
DCDC Configuration (8 bit):
Value identifying one of the three possible setups for the DCDC Configuration
DCDC Configuration | Value |
|---|---|
EDCDCMODE_AUTO | 0x00 |
EDCDCMODE_BYPASS | 0x01 |
EDCDCMODE_DCDC_LOW_NOISE | 0x02 |
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SET_DCDC_CONFIG | |||||||
CmdRes |
CmdRes (8 bit):
Possible results of the command:
CmdRes | Value |
|---|---|
Set DCDC Configuration not successful | 0x00 |
Set DCDC Configuration successful | 0x01 |
Get DCDC Configuration Command#
The host CPU system can get the current DCDC Configuration by using the Serial API function FUNC_ID_GET_DCDC_CONFIG (0xDE).
HOST->ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_GET_DCDC_CONFIG | |||||||
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_GET_DCDC_CONFIG | |||||||
DCDC Configuration | |||||||
DCDC Configuration (8 bit):
Value identifying one of the three possible setups for the DCDC Configuration:
DCDC Configuration | Value |
|---|---|
EDCDCMODE_AUTO | 0x00 |
EDCDCMODE_BYPASS | 0x01 |
EDCDCMODE_DCDC_LOW_NOISE | 0x02 |
Ready Command#
The Ready Command is used by the host to inform the Z-Wave module that it is ready to receive a command on the UART.
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_READY | |||||||
[SerialLinkState] | |||||||
SerialLinkState (8 bit):
Set the Serial link state between HOST and the Serial API Z-Wave module.
SERIAL_LINK_DETACHED: The Serial link state should be DETACHED, or Serial API stops sending data to the HOST until either READY is transmitted again in connected state or any valid Serial API command is received from the HOST.
SERIAL_LINK_CONNECTED: The Serial link state should be CONNECTED, or Serial API sends data to the HOST when needed.
The Serial API Z-Wave module starts up after reset in the Serial link state DETACHED.
SerialLinkState define | Value |
|---|---|
SERIAL_LINK_DETACHED | 0x00 |
SERIAL_LINK_CONNECTED | 0x01 |
Get Maximum Payload Size#
The maximum supported payload size can be read through serial API (starting with the Serial API version 7) by using FUNC_ID_SERIAL_API_SETUP Serial API function, sub function SERIAL_API_SETUP_CMD_TX_GET_MAX_PAYLOAD_SIZE:
HOST->ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_TX_GET_MAX_PAYLOAD_SIZE | |||||||
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_TX_GET_MAX_PAYLOAD_SIZE | |||||||
MaxPayloadSize | |||||||
MaxPayloadSize
Maximum payload size supported by the Z-Wave protocol.
Set Node ID Base Type#
Command to set the Base Type of all Serial API Command Node ID fields. Introduced in Serial API version 9. The Node ID Base Type defines how all Serial API Command Node ID fields should be interpreted. The setting can be either 8 or 16 bits.
The 8 bits setting is the default (legacy) setting where the Node ID field is 1 byte wide as illustrated in the command frame below:
| Byte 1 | Byte 2 | Byte3 | Byte 4 | Byte 5 | ...
| SOF | Length | Type | Cmd | NodeID | ...The 16 bits setting means the Node ID field is 2 bytes wide, with the most significant byte (MSB) first, as illustrated in the command frame below:
| Byte 1 | Byte 2 | Byte3 | Byte 4 | Byte 5 | Byte 6 | ...
| SOF | Length | Type | Cmd | NodeID MSB | NodeID LSB | ...Note: The command is not persistent. Must be re-issued after a reset or power-cycle of the Serial API Controller; i.e., the Host should subscribe to the Serial API started Command to be notified of any Controller restart and re-issue the command accordingly.
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_NODEID_BASETYPE_SET | |||||||
BaseType | |||||||
BaseType
The Node ID Base Type value to be set.
BaseType | Value |
|---|---|
8 bits | 0x01 |
16 bits | 0x02 |
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SETUP | |||||||
SERIAL_API_SETUP_CMD_NODEID_BASETYPE_SET | |||||||
CmdRes | |||||||
CmdRes
Result of the command
CmdRes = 0: Command Error. The Node ID Base Type is set to default value (8 bit).
CmdRes = 1: Command OK. Requested Node ID Base Type successfully set.
Ready Command#
The Ready Command is used by the host to inform the Z-Wave module that it is ready to receive a command on the UART.
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_READY | |||||||
[SerialLinkState] | |||||||
SerialLinkState (8 bit):
Set the Serial link state between HOST and the Serial API Z-Wave module.
SERIAL_LINK_DETACHED: The Serial link state should be DETACHED, or Serial API stops sending data to the HOST until either READY is transmitted again in connected state or any valid Serial API command is received from the HOST.
SERIAL_LINK_CONNECTED: The Serial link state should be CONNECTED, or Serial API sends data to the HOST when needed.
The Serial API Z-Wave module starts up after reset in the Serial link state DETACHED.
SerialLinkState define | Value |
|---|---|
SERIAL_LINK_DETACHED | 0x00 |
SERIAL_LINK_CONNECTED | 0x01 |
Serial API started Command#
The Serial API will inform the host that is has been started by issuing the FUNC_ID_SERIAL_API_STARTED command.
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_STARTED | |||||||
WakeupReason | |||||||
WatchdogStarted | |||||||
deviceOptionMask | |||||||
GenericNodetype | |||||||
SpecificNodetype | |||||||
CommandClassLength | |||||||
CommandClass 1 | |||||||
… | |||||||
CommandClass x | |||||||
Capabilities | |||||||
WakeupReason
The reason for starting up the Z-Wave module.
SerialLinkState define | Description | Value |
|---|---|---|
ZW_WAKEUP_RESET | Module was reset | 0x00 |
ZW_WAKEUP_WUT | Module was started by a wake up timer | 0x01 |
ZW_WAKEUP_SENSOR | Module was started because it received a wakeup beam | 0x02 |
ZW_WAKEUP_WATCHDOG | Module was reset by the watchdog timer | 0x03 |
ZW_WAKEUP_EXT_INT | Module was started by external interrupt | 0x04 |
ZW_WAKEUP_POR | Module was reset by loss of power | 0x05 |
WatchdogStarted
0: Watchdog timer is not started.
1: Watchdog timer is started and kicked by the Serial API.
deviceOptionMask
The deviceoptionmask set by the SerialAPI_ApplicationNodeInformation command
GenericNodetype
The generic node typ set by the SerialAPI_ApplicationNodeInformation command
SpecificNodetype
The specific node type set by the SerialAPI_ApplicationNodeInformation command
CommandClassLength
The number of command classes in the Node information frame
CommandClass x
The command class number supported by the node
Capabilities
Bitfield with information of supported Serial API Controller features
Value | Description |
|---|---|
Bit 0 | Controller is Z-Wave Long Range capable |
Bit 1 – Bit 7 | Unused |
Softreset Command#
The host CPU system can make a software reset of the Z-Wave module by using the Softreset Command.
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SERIAL_API_SOFT_RESET | |||||||
Wait 1.5 seconds after reset to ensure that the module is ready for communication again.
Note: USB modules will disconnect - connect when this command is issued, which means that the module may get a new address on the USB bus. This will make the old file handle to the USB serial interface invalid.
Watchdog Commands#
Some PC-based applications cannot guarantee kicking the watchdog before timeout causing the Watchdog to reset the Z-Wave ASIC unintentionally. The following Watchdog Commands are therefore available to avoid this:
Stop Watchdog: Disable Watchdog and stop kick Watchdog in ApplicationPoll
Watchdog handling disabled when powered up and Sleep/FLiRS mode will temporary stop Watchdog.
The host CPU system can start Watchdog functionality by using the Serial API function FUNC_ID_ZW_WATCHDOG_START:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_ZW_WATCHDOG_START | |||||||
The host CPU system can stop Watchdog functionality by using the Serial API function FUNC_ID_ZW_WATCHDOG_STOP:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_ZW_WATCHDOG_STOP | |||||||
NVM Backup and Restore#
The host processor can make a backup or a restore of the Non-Volatile Memory (NVM) in the Z-Wave chip using the serial API.
Note: Only supported by the 500 series systems.
There is one command for doing both backup and restore.
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_NVM_BACKUP_RESTORE | |||||||
Operation | |||||||
Length | |||||||
Offset MSB | |||||||
Offset LSB | |||||||
Buffer[0] | |||||||
… | |||||||
.. | |||||||
Buffer[x] | |||||||
Operation (8bit):
The operation to be executed:
Operation | Value |
|---|---|
Open | 0x00 |
Read | 0x01 |
Write | 0x02 |
Close | 0x03 |
Read, Write, and Close operations are only valid after an Open operation has been executed.
Length (8bit)
A desired length of the read/write buffer
Offset (16bit)
An offset in the NVM where the write or read should be done.
Buffer (8bit*x)
The write buffer containing the data that should be written to NVM when restoring NVM.
ZW -> Host:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_NVM_BACKUP_RESTORE | |||||||
Return Value | |||||||
Length | |||||||
Offset MSB | |||||||
Offset LSB | |||||||
Buffer[0] | |||||||
… | |||||||
.. | |||||||
Buffer[x] | |||||||
Return Value (8bit)
The result of the requested operation.
| Return Value | Value |
|---|---|
| Ok | 0x00 |
| Error | 0x01 |
|
ErrorOperationMismatch (Error mixing read and write) |
0x02 |
|
ErrorOperationDisturbed (Error read operation disturbed by another write) |
0x03 |
| End Of File | 0xFF |
Length (8bit)
An actual length of the read/write buffer.
Offset (16bit)
An offset in the NVM where the write or read was done.
Buffer (8bit*x)
The read buffer containing the data that was read from NVM when backing up NVM.
Backing up NVM#
The backup and restore function is session-based because the Z-Wave protocol limits the access to the NVM while the backup and restore is being done. The host application should stop all other activity on the serial API while the backup is being done.
The correct sequence of commands for initiating a backup is the following:
FUNC_ID_NVM_BACKUP_RESTORE (open)
Returns the backup size.FUNC_ID_NVM_BACKUP_RESTORE (read, read, .)
Returns EOF if no more data or error if the backup is disturbed by other writes to the NVM.FUNC_ID_NVM_BACKUP_RESTORE (close)
Returns an error if backup was disturbed by other writes. Ok is returned if the backup was done without any writes to the NVM.If an error was returned, discard backed up data and try again.
Restoring NVM#
Restoring the NVM in the Z-Wave protocol requires a few more steps than the backup because the host needs to ensure that all old NVM data is deleted and that the new NVM is taken in use.
The correct sequence of commands for restoring NVM is the following:
FUNC_ID_ZW_SET_DEFAULT
Deletes all old NVM content.FUNC_ID_NVM_BACKUP_RESTORE (open)
Returns an unused value.FUNC_ID_NVM_BACKUP_RESTORE (write, write, ....)
Writes the whole NVM image to the NVM in the Z-Wave module.FUNC_ID_NVM_BACKUP_RESTORE (close)
Returns an unused value.FUNC_ID_SERIAL_API_SOFT_RESET
Activates the Z-Wave module with the new NVM image.Note that while the restore is taking place, the node will not be part of the network so all Z-Wave communication to the node will fail.
Restrictions on Functions Using Buffers#
The Serial API is implemented with buffers for queuing requests and responses. This restricts how much data that can be transferred through MemoryGetBuffer() and MemoryPutBuffer() compared to using them directly from the Z-Wave API.
The PC application should not try to get or put buffers larger than approximately 80 bytes.
If an application requests too much data through MemoryGetBuffer(), the buffer will be truncated, and the application will not be notified.
If an application tries to store too much data with MemoryPutBuffer(), the buffer will be truncated before the data is sent to the Z-Wave module, again without the application being notified.
Configuration of Z-Wave Long Range channel#
There are 2 rf-channels available for Z-Wave Long Range communication. A controller can only use one frequency at a time. The host can use the commands below to get and set the active Long Range channel.
Get Active Long Range channel#
Command to get the active Long Range rf-channel. Introduced in Serial API version 9.
HOST->ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_GET_LR_CHANNEL | |||||||
ZW->HOST:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_GET_LR_CHANNEL | |||||||
Channel | |||||||
Channel
The rf-channel that the controller uses for Long Range communication.
Channel | Value |
|---|---|
ZW_LR_CHANNEL_A | 0x01 |
ZW_LR_CHANNEL_B | 0x02 |
Set Active Long Range channel#
Command to set the active Long Range rf-channel. Introduced in Serial API version 9.
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_SET_LR_CHANNEL | |||||||
Channel | |||||||
Channel
The rf-channel to be set.
Channel | Value |
|---|---|
ZW_LR_CHANNEL_A | 0x01 |
ZW_LR_CHANNEL_B | 0x02 |
Configuration of Long Range virtual node IDs#
Four Long Range node IDs are reserved for virtual nodes. IDs: 4002, 4003, 4004 and 4005. By default, all frames with virtual node IDs are rejected by Z-wave controllers. To accept application level frames with a virtual node ID, that node ID must be enabled.
Command to enable virtual node IDs. Introduced in Serial API version 9.
Note: The command is not persistent. Must be re-issued after a reset or power-cycle of the Serial API Controller. I.e. the Host should subscribe to the Serial API Started Command to be notified of any Controller restart and re-issue the command accordingly.
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_ZW_SET_LR_VIRTUAL_IDS | |||||||
NodeIdBitmask | |||||||
NodeIdBitmask
Setting bits to 1 will enable node IDs. Setting bits to 0 will disable.
NodeIdBitmask | bit |
|---|---|
Ignored | b4-b7 |
Enable node ID: 4005 | b3 |
Enable node ID: 4004 | b2 |
Enable node ID: 4003 | b1 |
Enable node ID: 4002 | b0 |
ZW_SendData Function#
FUNC_ID_ZW_SEND_DATA:
HOST->ZW: nodeID | dataLength | pData[] | txOptions | funcID
ZW->HOST: RetVal
RetVal == false -> no callback
RetVal == true then callback returns with
ZW->HOST: txStatus | wTransmitTicksMSB | wTransmitTicksLSB | bRepeaters | rssi_values.incoming[0] | rssi_values.incoming[1] | rssi_values.incoming[2] | rssi_values.incoming[3] | rssi_values.incoming[4] | bRouteSchemeState | repeater0 | repeater1 | repeater2 | repeater3 | routespeed | bRouteTries | bLastFailedLink.from | bLastFailedLink.to | bUsedTxpower | bMeasuredNoiseFloor | bAckDestinationUsedTxPower | bDestinationAckMeasuredRSSI | bDestinationckMeasuredNoiseFloor
Fields
bUsedTxpower
bMeasuredNoiseFloor
bAckDestinationUsedTxPower
bDestinationAckMeasuredRSSI
bDestinationckMeasuredNoiseFloor
Are applicable for Z-Wave Long Range Network only. Otherwise they are set to RSSI_NOT_AVAILABLE
ApplicationCommandHandler_Bridge#
Function ApplicationCommandHandler_Bridge is triggered after SerialAPI receives the frame
On Long Range Network:
ZW->HOST: REQ | 0xA8 | rxStatus | destNode | sourceNode | cmdLength | pCmd[] | multiDestsOffset_NodeMaskLen | multiDestsNodeMask[] | rssiVal | securityKey | bSourceTxPower | bSourceNoiseFloor
Fields:
bSourceTxPower
bSourceNoiseFloor
are applicable for Z-Wave Long Range Network only. Otherwise they are set to RSSI_NOT_AVAILABLE.
Enable PTI Zniffer Functionality#
It is possible to enable/disable PTI Zniffer functionality for the 700 SoC as a startup option on SerialAPIControllers. This means that the nodes keep functioning as a normal SerialAPIControllers but in addition also provide Zniffer info via the Ethernet ports on the BRD4001A boards. PTI uses the ZG14 pins #21 and #20, which correspond to PB13 (FRC_DRAME) and PB12 (FRC_DOUT). Other pin configurations are not supported currently. PTI functionality is disabled by default.
Enable/disable PTI Zniffer#
Note that a node must be soft reset (7.17) after the command is sent to activate the setting.
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_ENABLE_RADIO_PTI | |||||||
Enable (0x01) / Disable (0x00) | |||||||
The node answers the host to verify the setting:
ZW -> Host:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_ENABLE_RADIO_PTI | |||||||
OK (0x01) / Failure (0x00) | |||||||
Get Radio PTI state#
To get if the PTI functionality is currently enabled or not.
Host -> ZW:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_GET_RADIO_PTI | |||||||
The node answers the host to verify the setting:
ZW -> Host:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
FUNC_ID_GET_RADIO_PTI | |||||||
Enabled (0x01) / Disabled (0x00) | |||||||
Serial API files
The Serial API embedded sample code is provided in the Z-Wave Developer’s Kit until SDK 6.81.0x. Only binaries are distributed starting with the SDK 7.00.00+. Note that altering the function IDs and frame formats in the Serial API embedded sample code can result in interoperability problems with the Z-Wave DLL supplied on the Developer’s Kit as well as commercially available GUI applications. To determine the current version of the Serial API protocol in the embedded sample code, see the API call ZW_Version.
The ProductPlus\SerialAPIPlus directory contains sample source code for controller/end device applications on a Z-Wave module. The application also uses several utility functions described in [2], depending on the SDK used.
Makefiles
MK.BAT
Make bat file for building the sample application in question. To only build applications using EU frequency enter: MK “FREQUENCY=EU” in the command prompt.
Makefile
This is the Makefile for the sample application in question defining the targets built. See [2] for additional details depending on SDK used.
Makefile.common_ZW0x0x_supported_functions
This makefile makes a text file showing the supported serial API functions for the given target.
Application
app_version.h
This header file contains defines for the application version.
config_app.h
This header file contains defines for Manufacturer-Specific Command Class and defines for Security settings.
conhandle.h / conhandle.c
Routines for handling Serial API protocol between PC and Z-Wave module.
eeprom.h / eeprom.c
NVM layout
make-supported-functions-include.bat
Windows batch script for generating Serial API defines for supported functions based on what exists in the library.
Prodtest_vars.c
Critical memory variables used for a production test.
serialapi-supported-func-list.txt
Template file for generating SerialAPI defines for supported functions based on what exists in the library. Enable/disable support of a given Serial API function in serialappl.h header file.
serialappl.h / serialappl.c
This module implements the handling of the Serial API protocol, which involves parsing the frames, calling the appropriate Z-Wave API library functions, returning results, and so on to the PC. Enable/disable support of a given Serial API function in serialappl.h header file.
Supported.bat
Batch file called by Makefile.common_ZW0x0x_supported_function to obtain delayed environment variable expansion when using SET in DOS prompt.