Communication Interface#

The following sections describe the Serial API.

Communication Interface Versions#

Version 1-3#

The differences between serial API communication interface versions 1 to 3 is not documented.

Version 4#

The SDK 4.23-28 are based on the serial API communication interface version 4. This version introduces Serial API commands to better support a host application, especially the Serial API Capabilities Command. The Serial API Capabilities Command determines the Serial API functions that a specific Serial API Z-Wave Module supports.

Version 5#

The SDK 4.51-55, 5.03.00, 6.02.00, 6.11.00-01, and 6.51.00-06 versions are based on the serial API communication interface version 5. The destNode is appended to end of ApplicationCommandHandler REQ and promiscuously received frames are returned in a FUNC_ID_PROMISCUOUS_APPLICATION_COMMAND_HANDLER REQ.

Some of the SDKs introduce new Serial API functions, which can be determined by the Serial API Capabilities Command.

Version 6#

SDK 6.60.00 changes the Serial API communication interface to version 6 due to several extensions of the serial API [3] to better support installation and maintenance procedures (RSSI feedback, Routing algorithm feedback, and Network statistics). The interface is backward compatible with version 5, provided appended parameters in version 6 are ignored.

The ZW_SendData (and variations) callback parameters are changed and extended to include more information (transmission metrics) about the successful/unsuccessful transmission. The change affects the Serial API functionality FUNC_ID_ZW_SEND_DATA (and FUNC_ID_SEND_DATA_BRIDGE) because the transmission metrics are appended to the callback parameter list to ensure that an application, which ignores the extra data in the callback parameter list can function with no change. A Serial API functionality FUNC_ID_SERIAL_API_SETUP is implemented to enable or disable appending transmission metrics in the FUNC_ID_ZW_SEND_DATA callback.

The ApplicationCommandHandler (and ApplicationCommandHandler_Bridge) parameter list is changed and extended to also include the RSSI value with which the received frame is received. The change affects the Serial API functionality FUNC_ID_APPLICATION_COMMANDHANDLER (and FUNC_ID_APPLICATION_COMMAND_HANDLER_BRIDGE) because it appends the RSSI value to the functionality parameter for HOST implementations, which do not ignore the extra data.

In the Z-Wave protocol, the functions ZW_GetLastWorkingRoute and ZW_SetLastWorkingRoute are obsolete and replaced with ZW_GetPriorityRoute and ZW_SetPriorityRoute respectively. FUNC_ID_ZW_GET_LAST_WORKING_ROUTE and FUNC_ID_ZW_SET_LAST_WORKING_ROUTE functions are obsolete and replaced with FUNC_ID_ZW_GET_PRIORITY_ROUTE / FUNC_ID_ZW_SET_PRIORITY_ROUTE respectively.

End device enhanced-based Serial API targets is extended with two new functionalities to accommodate for the new protocol functionalities ZW_AssignPriorityReturnRoute and ZW_AssignPrioritySUCReturnRoute: FUNC_ID_ZW_ASSIGN_PRIORITY_SUC_RETURN_ROUTE and FUNC_ID_ZW_ASSIGN_PRIORITY_SUC_RETURN_ROUTE.

The new Z-Wave protocol function ZW_ExploreRequestExclusion is implemented in the Serial API with the funcID FUNC_ID_ZW_EXPLORE_REQUEST_EXCLUSION.

The new protocol functionalities ZW_GetNetworkStats and ZW_ClearNetworkStats is implemented in the Serial API with the funcIDs FUNC_ID_ZW_GET_NETWORK_STATS and FUNC_ID_ZW_CLEAR_NETWORK_STATS respectively.

New Serial API functionality (FUNC_ID_NVM_BACKUP_RESTORE) to back up and restore NVM contents is added to the serial API in all controllers and enhanced end devices.

The FUNC_ID_ZW_REDISCOVERY_NEEDED is obsolete.

SDK 6.70.00 introduces new Serial API functions for End Device Enhanced 232 library-based targets to enable HOSTs to leverage the new functionality.

Version 7#

SDK 6.71.0x changes the Serial API communication interface to version 7, enabling host software to ensure that this version of the serial API supports S2.

Version 8#

SDK 6.80.0x changes the Serial API communication interface to version 8 enabling the host software to ensure that this version of the serial API supports Smart Start.

Version 9#

SDK 7.14.x changer changes the Serial API communication interface to version 9 enabling the host software to ensure that this version of the serial API supports Z-Wave Long Range.

Communication Channel Settings#

RS-232 Serial Port#

A host communicating to a Serial API library via a serial port MUST use the following serial API RS-232 Parameters.

The least significant bit (LSB) b0 of each byte MUST be transmitted first on the physical wire.

USB Serial Port#

A host communicating to a Serial API library via a USB connection MUST follow the guidelines for the USB communications device class (USB CDC). In many cases, Linux® OS distributions and Mac OS releases will immediately present the Z-Wave chip USB interface as a serial port to applications.

Windows OS releases may need an .inf file structure to present the Z-Wave chip USB interface as a serial port to applications: