Z-Wave Serial API#

Modules#

serial_api_setup_cmd_get_region_info_answer_t

Frame Types

GET_INIT_DATA_FLAG

FUNC_ID

Enumerations#

enum
eSerialAPISetupCmd {
SERIAL_API_SETUP_CMD_UNSUPPORTED
SERIAL_API_SETUP_CMD_SUPPORTED = 1
SERIAL_API_SETUP_CMD_TX_STATUS_REPORT = 2
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET = 4
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET = 8
SERIAL_API_SETUP_CMD_TX_GET_MAX_PAYLOAD_SIZE = 16
SERIAL_API_SETUP_CMD_RF_REGION_GET = 32
SERIAL_API_SETUP_CMD_RF_REGION_SET = 64
SERIAL_API_SETUP_CMD_NODEID_BASETYPE_SET = 128
SERIAL_API_SETUP_CMD_MAX_LR_TX_PWR_SET = 3
SERIAL_API_SETUP_CMD_MAX_LR_TX_PWR_GET = 5
SERIAL_API_SETUP_CMD_TX_GET_MAX_LR_PAYLOAD_SIZE = 17
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET_16_BIT = 18
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET_16_BIT = 19
SERIAL_API_SETUP_CMD_GET_SUPPORTED_REGION = 21
SERIAL_API_SETUP_CMD_GET_REGION_INFO = 22
}
enum
eSerialAPISetupNodeIdBaseType {
SERIAL_API_SETUP_NODEID_BASE_TYPE_8_BIT = 1
SERIAL_API_SETUP_NODEID_BASE_TYPE_16_BIT
SERIAL_API_SETUP_NODEID_BASE_TYPE_LAST
SERIAL_API_SETUP_NODEID_BASE_TYPE_DEFAULT = SERIAL_API_SETUP_NODEID_BASE_TYPE_8_BIT
}
enum
nvm_backup_restore_addr_size_t {
NVM_BACKUP_RESTORE_ADDR_SIZE = 2
NVM_EXT_BACKUP_RESTORE_ADDR_SIZE = 4
}

size of the address field of NVM_BACKUP_RESTORE or NVM_EXT_BACKUP_RESTORE frames.

enum
power_lock_type_t {
POWER_LOCK_TYPE_RADIO = 0
POWER_LOCK_TYPE_IO = 1
}

Power Lock Type enumeration.

Variables#

Functions#

void
func_id_serial_api_get_init_data(uint8_t inputLength, const uint8_t *pInputBuffer, uint8_t *pOutputBuffer, uint8_t *pOutputLength)

Must be called upon receiving a "Node List Command".

void
func_id_serial_api_get_nls_nodes(uint8_t const inputLength, uint8_t const *const pInputBuffer, uint8_t *pOutputBuffer, uint8_t *pOutputLength)

Returns bitmask of NLS node IDs.

void
func_id_serial_api_get_LR_nodes(uint8_t inputLength, const uint8_t *pInputBuffer, uint8_t *pOutputBuffer, uint8_t *pOutputLength)

Returns bitmask of LR node IDs.

void
func_id_serial_api_setup(uint8_t inputLength, const uint8_t *pInputBuffer, uint8_t *pOutputBuffer, uint8_t *pOutputLength)

Must be called upon receiving a "Serial API Setup Command".

void
func_id_serial_api_get_nvr(uint8_t inputLength, const uint8_t *pInputBuffer, uint8_t *pOutputBuffer, uint8_t *pOutputLength)

Must be called upon receiving a "Serial API NVR get".

void
func_id_zw_get_protocol_version(uint8_t inputLength, const uint8_t *pInputBuffer, uint8_t *pOutputBuffer, uint8_t *pOutputLength)

Must be called upon receiving a "Serial API ZW Get protocol version".

void
func_id_ZW_RemoveNodeIDFromNetwork(uint8_t inputLength, uint8_t *pInputBuffer, const uint8_t *pOutputBuffer, const uint8_t *pOutputLength)

Remove a specific node from the network The node is identified by node ID.

bool
InitiateShutdown(ZW_Void_Callback_t pCallback)

Initiate device graceful shutdown.

Macros#

#define
GET_NODEID (pData, idx)
#define
GET_16BIT_VALUE (pData)
#define
SAPI_SETUP_GET_REGION_INFO_RX_IDX_REGION (1)

Index of the region in received buffer.

#define
MORE_NODES 0x80
#define
NO_MORE_NODES 0x00
#define
SOF 0x01

Start Of Frame.

#define
ACK 0x06

Acknowledge successful frame reception.

#define
NAK 0x15

Not Acknowledge successful frame reception - please retransmit...

#define
CAN 0x18

Frame received (from host) was dropped - waiting for ACK.

Enumeration Documentation#

eSerialAPISetupCmd#

eSerialAPISetupCmd
Enumerator
SERIAL_API_SETUP_CMD_UNSUPPORTED

The first 8 commands are given as bit-flags, and when all bits were consumed, a byte-array was created to give more room.

SERIAL_API_SETUP_CMD_SUPPORTED
SERIAL_API_SETUP_CMD_TX_STATUS_REPORT
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET
SERIAL_API_SETUP_CMD_TX_GET_MAX_PAYLOAD_SIZE
SERIAL_API_SETUP_CMD_RF_REGION_GET
SERIAL_API_SETUP_CMD_RF_REGION_SET
SERIAL_API_SETUP_CMD_NODEID_BASETYPE_SET
SERIAL_API_SETUP_CMD_MAX_LR_TX_PWR_SET

The below values are not flags and shall only be used with BITMASK_ADD_CMD() when generating the response for the command, SERIAL_API_SETUP_CMD_SUPPORTED.

SERIAL_API_SETUP_CMD_MAX_LR_TX_PWR_GET
SERIAL_API_SETUP_CMD_TX_GET_MAX_LR_PAYLOAD_SIZE
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET_16_BIT
SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET_16_BIT
SERIAL_API_SETUP_CMD_GET_SUPPORTED_REGION
SERIAL_API_SETUP_CMD_GET_REGION_INFO

eSerialAPISetupNodeIdBaseType#

eSerialAPISetupNodeIdBaseType
Enumerator
SERIAL_API_SETUP_NODEID_BASE_TYPE_8_BIT
SERIAL_API_SETUP_NODEID_BASE_TYPE_16_BIT
SERIAL_API_SETUP_NODEID_BASE_TYPE_LAST
SERIAL_API_SETUP_NODEID_BASE_TYPE_DEFAULT

nvm_backup_restore_addr_size_t#

nvm_backup_restore_addr_size_t

size of the address field of NVM_BACKUP_RESTORE or NVM_EXT_BACKUP_RESTORE frames.

Item value is the size in byte of the address field.

Enumerator
NVM_BACKUP_RESTORE_ADDR_SIZE

2 bytes for the legacy NVM backup & restore command

NVM_EXT_BACKUP_RESTORE_ADDR_SIZE

4 bytes for the extended NVM backup & restore command


power_lock_type_t#

power_lock_type_t

Power Lock Type enumeration.

Enumerator
POWER_LOCK_TYPE_RADIO

Radio power lock.

POWER_LOCK_TYPE_IO

IO power lock (requires Shutdown Manager)


Variable Documentation#

nodeIdBaseType#

eSerialAPISetupNodeIdBaseType nodeIdBaseType

Function Documentation#

func_id_serial_api_get_init_data#

void func_id_serial_api_get_init_data (uint8_t inputLength, const uint8_t * pInputBuffer, uint8_t * pOutputBuffer, uint8_t * pOutputLength)

Must be called upon receiving a "Node List Command".

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AinputLength

Length of data in input buffer.

const uint8_t *N/ApInputBuffer

Input buffer

uint8_t *N/ApOutputBuffer

Output buffer

uint8_t *N/ApOutputLength

Length of data in output buffer.


func_id_serial_api_get_nls_nodes#

void func_id_serial_api_get_nls_nodes (uint8_t const inputLength, uint8_t const *const pInputBuffer, uint8_t * pOutputBuffer, uint8_t * pOutputLength)

Returns bitmask of NLS node IDs.

Parameters
TypeDirectionArgument NameDescription
uint8_t const[in]inputLength

Length of data in input buffer.

uint8_t const *const[in]pInputBuffer

Input buffer. First byte should be requested range of nodes. Supported values: 0, 1, 2, etc that corresponds to offset 0, 128, 256, etc in bytes.

uint8_t *[out]pOutputBuffer

Output buffer, contained of: BITMASK_OFFSET | MORE_NODES | BITMASK_LEN | BITMASK_ARRAY

uint8_t *[out]pOutputLength

Length of data in output buffer.


func_id_serial_api_get_LR_nodes#

void func_id_serial_api_get_LR_nodes (uint8_t inputLength, const uint8_t * pInputBuffer, uint8_t * pOutputBuffer, uint8_t * pOutputLength)

Returns bitmask of LR node IDs.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AinputLength

Length of data in input buffer.

const uint8_t *N/ApInputBuffer

Input buffer. First byte should be requested range of nodes. Supported values: 0, 1, 2, 3 that corresponds to offset 0, 128, 256, 384.

uint8_t *N/ApOutputBuffer

Output buffer, contained of: MORE_NODES | BITMASK_OFFSET | BITMASK_LEN | BITMASK_ARRAY

uint8_t *N/ApOutputLength

Length of data in output buffer.


func_id_serial_api_setup#

void func_id_serial_api_setup (uint8_t inputLength, const uint8_t * pInputBuffer, uint8_t * pOutputBuffer, uint8_t * pOutputLength)

Must be called upon receiving a "Serial API Setup Command".

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AinputLength

Length of data in input buffer.

const uint8_t *N/ApInputBuffer

Input buffer

uint8_t *N/ApOutputBuffer

Output buffer

uint8_t *N/ApOutputLength

Length of data in output buffer.


func_id_serial_api_get_nvr#

void func_id_serial_api_get_nvr (uint8_t inputLength, const uint8_t * pInputBuffer, uint8_t * pOutputBuffer, uint8_t * pOutputLength)

Must be called upon receiving a "Serial API NVR get".

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AinputLength

Length of data in input buffer.

const uint8_t *N/ApInputBuffer

Input buffer

uint8_t *N/ApOutputBuffer

Output buffer

uint8_t *N/ApOutputLength

Length of data in output buffer.


func_id_zw_get_protocol_version#

void func_id_zw_get_protocol_version (uint8_t inputLength, const uint8_t * pInputBuffer, uint8_t * pOutputBuffer, uint8_t * pOutputLength)

Must be called upon receiving a "Serial API ZW Get protocol version".

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AinputLength

Length of data in input buffer.

const uint8_t *N/ApInputBuffer

Input buffer

uint8_t *N/ApOutputBuffer

Output buffer

uint8_t *N/ApOutputLength

Length of data in output buffer.


func_id_ZW_RemoveNodeIDFromNetwork#

void func_id_ZW_RemoveNodeIDFromNetwork (uint8_t inputLength, uint8_t * pInputBuffer, const uint8_t * pOutputBuffer, const uint8_t * pOutputLength)

Remove a specific node from the network The node is identified by node ID.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AinputLength

Length of data in input buffer.

uint8_t *N/ApInputBuffer

Input buffer

const uint8_t *N/ApOutputBuffer

Output buffer

const uint8_t *N/ApOutputLength

Length of data in output buffer.


InitiateShutdown#

bool InitiateShutdown (ZW_Void_Callback_t pCallback)

Initiate device graceful shutdown.

Parameters
TypeDirectionArgument NameDescription
ZW_Void_Callback_tN/ApCallback

pointer to notifcation callback function. Function is called just before deice go into deepsleep

Returns

  • true if Shutdown process start, else false


Macro Definition Documentation#

GET_NODEID#

#define GET_NODEID
Value:
( (nodeIdBaseType == SERIAL_API_SETUP_NODEID_BASE_TYPE_16_BIT) \
?((((uint8_t*)pData)[0] << 8) | ((uint8_t*)pData)[1]) /* 16 bit, MSB | LSB */ \
:((uint8_t*)pData)[0]); /* 8 bit */ \
do { \
if (nodeIdBaseType == SERIAL_API_SETUP_NODEID_BASE_TYPE_16_BIT) \
{ \
idx++; \
} \
} while (0)

GET_16BIT_VALUE#

#define GET_16BIT_VALUE
Value:
(pData)

SERIAL_API_SETUP_CMD_TX_STATUS_REPORT_CMD_LENGTH_MIN#

#define SERIAL_API_SETUP_CMD_TX_STATUS_REPORT_CMD_LENGTH_MIN
Value:
2

SERIAL_API_SETUP_CMD_RF_REGION_SET_CMD_LENGTH_MIN#

#define SERIAL_API_SETUP_CMD_RF_REGION_SET_CMD_LENGTH_MIN
Value:
2

SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET_CMD_LENGTH_MIN#

#define SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET_CMD_LENGTH_MIN
Value:
3

SERIAL_API_SETUP_CMD_NODEID_BASETYPE_SET_CMD_LENGTH_MIN#

#define SERIAL_API_SETUP_CMD_NODEID_BASETYPE_SET_CMD_LENGTH_MIN
Value:
2

SERIAL_API_SETUP_CMD_MAX_LR_TX_PWR_SET_CMD_LENGTH_MIN#

#define SERIAL_API_SETUP_CMD_MAX_LR_TX_PWR_SET_CMD_LENGTH_MIN
Value:
3

SAPI_SETUP_GET_REGION_INFO_RX_IDX_REGION#

#define SAPI_SETUP_GET_REGION_INFO_RX_IDX_REGION
Value:
(1)

Index of the region in received buffer.


MORE_NODES#

#define MORE_NODES
Value:
0x80

NO_MORE_NODES#

#define NO_MORE_NODES
Value:
0x00

SOF#

#define SOF
Value:
0x01

Start Of Frame.


ACK#

#define ACK
Value:
0x06

Acknowledge successful frame reception.


NAK#

#define NAK
Value:
0x15

Not Acknowledge successful frame reception - please retransmit...


CAN#

#define CAN
Value:
0x18

Frame received (from host) was dropped - waiting for ACK.


SAPI_COMMAND_STATUS_FAILURE#

#define SAPI_COMMAND_STATUS_FAILURE
Value:
0x00

SAPI_COMMAND_STATUS_SUCCESS#

#define SAPI_COMMAND_STATUS_SUCCESS
Value:
0x01