Instruction
Description:
Z-Ware Library & C API
Date CET Initials Name Justification
2018-05-02 15:24:27 NTJ Niels Thybo Johansen
This document is the property of Silicon Labs. The data contained herein, in whole or in
part, may not be duplicated, used or disclosed outside the recipient for any purpose. This
restriction does not limit the recipient's right to use information contained in the data if it
is obtained from another source without restriction.
Z-Ware Library User Guide
Document No.: INS14129
Version: 2
Written By: DCHOW;SAMBAT;YANYAN
Date: 2017-12-26
Reviewed By: YANYAN;KSUNDARAM;CRASMUSSEN
Restrictions: Partners Only
Approved by:
silabs.com | Building a more connected world.
Page ii of xxii
Doc. Ver.
Date
By
Pages affected
Brief description of changes
1
20171006
DCHOW
ALL
- Cloned from INS13172-9
- Support Smart Start and provisioning list management.
20171103
DCHOW
120-123
- v8.04
Parameters, zwif_prot_tmout_get Parameters
2
20180215
DCHOW
ALL
- v8.12
to support building of applications
xplain certain network operations cannot be
"ZW_ALRM_EVT_XXX", "ZW_ALRM_STS_XXX"
3
20180308
BBR
All
Added Silicon Labs template
4
20180418
SNA
105
Fixed zwif_battery_rpt_set doc
5
20180426
SNA
172
Updated platform memory requirements
INS14129-5 Z-Ware Library User Guide 2018-05-02
REVISION RECORD
- v8.03
-
Modified table ZW_SENSOR_TYPE_XXX, ZW_SENSOR_UNIT_XXX_YYY to fix
TO#07866
- Modified tables zwnet_notify_fn Parameters, zwnet_sts_t structure, zwnetd_t
structure, zwnet_init_t structure, zwconfig_t structure, ZW_THRMO_MD_XXX,
zwrep_thrmo_md_fn Parameters, zwif_thrmo_md_set Parameters,
ZW_THRMO_OP_STA_XXX,
Controlled Z Wave CCs, Node Update endpoint get/set CCs.
- Added tables zw_health_prg_t structure, zw_health_rpt_t structure,
zw_health_sts_t structure, pl_info_fn Parameters.
- Added sections Command Class Configuration, Smart Start, Network Health Check.
- Changed prekit whitelist APIs zwnet_wl_xxx to provisioning list APIs zwnet_pl_xxx
- Updated REFERENCES
- Support COMMAND_CLASS_CONFIGURATION version 2
- Support COMMAND_CLASS_THERMOSTAT_OPERATING_STATE version 2
- Support COMMAND_CLASS_THERMOSTAT_MODE version 3
- Modified tables zwrep_prot_fn Parameters, zwif_prot_get Parameters,
zwrep_prot_ec_fn Parameters, zwif_prot_ec_get Parameters, zwrep_prot_tmout_fn
- Modified tables Controlled CCs, Multi-level Sensor Type: ZW_SENSOR_TYPE_XXX,
Multi-level Sensor Unit, ZW_SENSOR_UNIT_XXX_YYY, ZW_ERR_XXX, if_rec_config_t,
zwrep_csc_cfg_fn Parameters, pl_info_t, pl_uuid_t, Node Update endpoint get/set
CCs
- Added tables if_rec_cfg_set_t, if_rec_cfg_info_t, pl_nw_sts_t
- Modified section JSON File Format with configuration parameter information.
- Modified section Building of sample applications
that link with shared libraries.
- Modified section Ubuntu Linux and added sections BBB and RPi3 to support
building of shared libraries.
- Added section Installation of sample applications, zwif_config_prm_reset,
zwif_config_info_get, zwif_config_info_free
- Added text in section zwnet_abort to e
undone completely at certain stage
- Added figure in section S2 on interaction between Z-Ware library & client
- Support COMMAND_CLASS_NOTIFICATION version 8
- Modified tables "Z Wave Alarm//Notification Type","ZW_ALRM_XXX",
silabs.com | Building a more connected world.
Page iii of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table of Contents
1 INTRODUCTION ...................................................................................................................... 1
1.1 Purpose ............................................................................................................................................. 1
1.2 Audience and prerequisites ........................................................................................................... 1
2 FEATURES .............................................................................................................................. 2
2.1 Role ................................................................................................................................................... 2
2.2 Network Operations ........................................................................................................................ 3
2.3 Device Control .................................................................................................................................. 3
2.4 CC Support ....................................................................................................................................... 4
2.5 Network Initialization ....................................................................................................................... 6
2.6 Node Update .................................................................................................................................... 7
2.7 Network Update ............................................................................................................................... 8
2.8 Background Polling ......................................................................................................................... 8
2.9 Post-Set Polling ............................................................................................................................... 9
2.10 Command Class Configuration ..................................................................................................... 9
3 TYPICAL USAGE .................................................................................................................. 10
3.1 Network Initialization .....................................................................................................................10
3.2 Network creation and tear down .................................................................................................10
3.3 Portal Usage ...................................................................................................................................11
3.3.1 Portal Initialization ...............................................................................................................11
3.3.2 Portal Shutdown ..................................................................................................................11
3.3.3 Portal Client Profile Management .....................................................................................12
3.4 Interface monitor/control ...............................................................................................................12
3.5 Node identification .........................................................................................................................13
3.6 Grouping .........................................................................................................................................14
3.7 Sleeping nodes ..............................................................................................................................14
3.8 Firmware update ............................................................................................................................14
3.9 Polling facility ..................................................................................................................................15
3.10 Device specific configuration and information database .........................................................15
3.11 Network and client preference storage ......................................................................................15
3.12 Security 2 (S2) ...............................................................................................................................16
3.13 SmartStart .......................................................................................................................................17
3.14 Network Health Check ..................................................................................................................17
4 API .......................................................................................................................................... 19
4.1 Error Codes ....................................................................................................................................19
4.2 Portal API ........................................................................................................................................21
4.2.1 zwportal_init .........................................................................................................................21
4.2.2 zwportal_shutdown .............................................................................................................23
4.2.3 zwportal_exit ........................................................................................................................23
4.2.4 zwportal_clnt_conn_close ..................................................................................................23
4.2.5 zwportal_clnt_add ...............................................................................................................23
silabs.com | Building a more connected world.
Page iv of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.2.6 zwportal_clnt_rm .................................................................................................................23
4.2.7 zwportal_clnt_find................................................................................................................24
4.2.8 zwportal_clnt_list_free ........................................................................................................24
4.2.9 zwportal_clnt_list_get .........................................................................................................24
4.3 Device Database API ....................................................................................................................25
4.3.1 zwdev_cfg_load ...................................................................................................................25
4.3.2 zwdev_cfg_free....................................................................................................................41
4.3.3 zwdev_global_sett_free ......................................................................................................41
4.3.4 zwdev_cfg_find ....................................................................................................................41
4.3.5 JSON File Format ................................................................................................................42
4.4 Network API ....................................................................................................................................49
4.4.1 zwnet_gw_discvr_start .......................................................................................................50
4.4.2 zwnet_gw_discvr_stop .......................................................................................................50
4.4.3 zwnet_ip_aton ......................................................................................................................51
4.4.4 zwnet_ip_ntoa ......................................................................................................................51
4.4.5 zwnet_local_addr_get .........................................................................................................51
4.4.6 zwnet_listen_port_get .........................................................................................................51
4.4.7 zwnet_init ..............................................................................................................................52
4.4.8 zwnet_exit .............................................................................................................................59
4.4.9 zwnet_get_desc ...................................................................................................................59
4.4.10 zwnet_add ............................................................................................................................60
4.4.11 zwnet_fail ..............................................................................................................................61
4.4.12 zwnet_migrate......................................................................................................................62
4.4.13 zwnet_initiate .......................................................................................................................62
4.4.14 zwnet_initiate_classic .........................................................................................................62
4.4.15 zwnet_update .......................................................................................................................63
4.4.16 zwnet_abort ..........................................................................................................................63
4.4.17 zwnet_reset ..........................................................................................................................63
4.4.18 zwnet_health_chk................................................................................................................63
4.4.19 zwnet_get_node ..................................................................................................................63
4.4.20 zwnet_get_node_ by_id .....................................................................................................64
4.4.21 zwnet_get_ep_ by_id ..........................................................................................................64
4.4.22 zwnet_get_if_ by_id ............................................................................................................64
4.4.23 zwnet_get_user ...................................................................................................................65
4.4.24 zwnet_send_nif ....................................................................................................................65
4.4.25 zwnet_all_node_sts_get .....................................................................................................65
4.4.26 zwnet_node_sts_get ...........................................................................................................65
4.4.27 zwnet_poll_rm ......................................................................................................................66
4.4.28 zwnet_poll_rm_mul .............................................................................................................66
4.4.29 zwnet_pref_set ....................................................................................................................66
4.4.30 zwnet_pref_get ....................................................................................................................66
4.4.31 zwnet_client_pref_set .........................................................................................................67
4.4.32 zwnet_client_pref_get .........................................................................................................67
4.4.33 zwnet_add_sec2_accept ....................................................................................................67
4.4.34 zwnet_add_sec2_grant_key ..............................................................................................67
silabs.com | Building a more connected world.
Page v of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.4.35 zwnet_sec2_get_dsk ..........................................................................................................68
4.4.36 zwnet_pl_add .......................................................................................................................68
4.4.37 zwnet_pl_get ........................................................................................................................71
4.4.38 zwnet_pl_del ........................................................................................................................72
4.4.39 zwnet_pl_list_get .................................................................................................................72
4.4.40 zwnet_pl_list_del .................................................................................................................72
4.5 Node API .........................................................................................................................................73
4.5.1 zwnoded_t ............................................................................................................................73
4.5.2 zwnode_get_net ..................................................................................................................74
4.5.3 zwnode_get_next ................................................................................................................74
4.5.4 zwnode_get_ep ...................................................................................................................74
4.5.5 zwnode_update ...................................................................................................................75
4.5.6 zwnode_cmd_q_ena_set ...................................................................................................75
4.5.7 zwnode_cmd_q_ena_get ...................................................................................................75
4.5.8 zwnode_cmd_q_cancel ......................................................................................................75
4.5.9 zwnode_cmd_q_get ............................................................................................................75
4.5.10 zwnode_mul_cmd_ctl_set ..................................................................................................76
4.5.11 zwnode_mul_cmd_ctl_get .................................................................................................76
4.5.12 zwnode_get_ext_ver ...........................................................................................................76
4.6 Endpoint API ..................................................................................................................................77
4.6.1 zwepd_t .................................................................................................................................77
4.6.2 zwep_get_node ...................................................................................................................77
4.6.3 zwep_get_next .....................................................................................................................78
4.6.4 zwep_get_if ..........................................................................................................................78
4.6.5 zwep_nameloc_set .............................................................................................................78
4.7 Interface API ...................................................................................................................................78
4.7.1 zwifd_t ...................................................................................................................................79
4.7.2 zwif_get_ep ..........................................................................................................................79
4.7.3 zwif_get_next .......................................................................................................................80
4.7.4 zwif_exec ..............................................................................................................................80
4.7.5 zwif_xxx_poll ........................................................................................................................80
4.8 Basic Interface API ........................................................................................................................81
4.8.1 zwif_basic_rpt_set ...............................................................................................................81
4.8.2 zwif_basic_get .....................................................................................................................82
4.8.3 zwif_basic_set......................................................................................................................82
4.9 Group Interface API ......................................................................................................................82
4.9.1 zwif_group_sup_get ............................................................................................................82
4.9.2 zwif_group_actv_get ...........................................................................................................83
4.9.3 zwif_group_get ....................................................................................................................83
4.9.4 zwif_group_add ...................................................................................................................84
4.9.5 zwif_group_del .....................................................................................................................84
4.9.6 zwif_group_info_get ............................................................................................................84
4.9.7 zwif_group_info_free ..........................................................................................................85
4.10 Switch Interface API ......................................................................................................................85
4.10.1 zwif_switch_rpt_set .............................................................................................................85
silabs.com | Building a more connected world.
Page vi of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.10.2 zwif_switch_get....................................................................................................................86
4.10.3 zwif_switch_set ....................................................................................................................87
4.11 Level Interface API ........................................................................................................................87
4.11.1 zwif_level_rpt_set ................................................................................................................87
4.11.2 zwif_level_sup_get ..............................................................................................................88
4.11.3 zwif_level_sup_cache_get .................................................................................................89
4.11.4 zwif_level_get ......................................................................................................................89
4.11.5 zwif_level_set .......................................................................................................................89
4.11.6 zwif_level_start ....................................................................................................................90
4.11.7 zwif_level_stop ....................................................................................................................90
4.12 Binary Sensor Interface API.........................................................................................................91
4.12.1 zwif_bsensor_rpt_set ..........................................................................................................91
4.12.2 zwif_bsensor_get ................................................................................................................91
4.12.3 zwif_bsensor_sup_get ........................................................................................................91
4.12.4 zwif_bsensor_sup_cache_get ...........................................................................................92
4.13 Sensor Interface API .....................................................................................................................92
4.13.1 zwif_sensor_rpt_set ............................................................................................................92
4.13.2 zwif_sensor_get ...................................................................................................................95
4.13.3 zwif_sensor_sup_get ..........................................................................................................96
4.13.4 zwif_sensor_unit_get ..........................................................................................................96
4.13.5 zwif_sensor_unit_cache_get .............................................................................................97
4.13.6 zwif_sensor_sup_cache_get .............................................................................................97
4.14 Group Command Interface API ...................................................................................................97
4.14.1 zwif_group_cmd_sup_get ..................................................................................................97
4.14.2 zwif_group_cmd_get ...........................................................................................................98
4.14.3 zwif_group_cmd_set ...........................................................................................................99
4.15 Wake Up Interface API .................................................................................................................99
4.15.1 zwif_wakeup_get .................................................................................................................99
4.15.2 zwif_wakeup_set ...............................................................................................................100
4.16 Configuration Interface API ........................................................................................................100
4.16.1 zwif_config_rpt_set ...........................................................................................................100
4.16.2 zwif_config_get ..................................................................................................................101
4.16.3 zwif_config_set ..................................................................................................................101
4.16.4 zwif_config_bulk_rpt_set ..................................................................................................101
4.16.5 zwif_config_bulk_get ........................................................................................................102
4.16.6 zwif_config_bulk_set .........................................................................................................102
4.16.7 zwif_config_prm_reset ......................................................................................................102
4.16.8 zwif_config_info_get .........................................................................................................103
4.16.9 zwif_config_info_free ........................................................................................................104
4.17 Pulse Meter Interface API ..........................................................................................................104
4.17.1 zwif_pulsemeter_rpt_set ..................................................................................................104
4.17.2 zwif_pulsemeter_get .........................................................................................................105
4.18 Battery Interface API ...................................................................................................................105
4.18.1 zwif_battery_rpt_set ..........................................................................................................105
4.18.2 zwif_battery_get ................................................................................................................105
silabs.com | Building a more connected world.
Page vii of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.19 AV Interface API ..........................................................................................................................106
4.19.1 zwif_av_set .........................................................................................................................106
4.19.2 zwif_av_caps......................................................................................................................106
4.20 Meter Interface API .....................................................................................................................107
4.20.1 zwif_meter_rpt_set ............................................................................................................107
4.20.2 zwif_meter_get ..................................................................................................................108
4.20.3 zwif_meter_sup_get ..........................................................................................................108
4.20.4 zwif_meter_sup_cache_get .............................................................................................109
4.20.5 zwif_meter_reset ...............................................................................................................110
4.20.6 zwif_meter_set_admin ......................................................................................................110
4.20.7 zwif_meter_get_desc ........................................................................................................110
4.21 Door Lock Interface API .............................................................................................................111
4.21.1 zwif_dlck_op_rpt_set ........................................................................................................111
4.21.2 zwif_dlck_op_get ...............................................................................................................112
4.21.3 zwif_dlck_op_set ...............................................................................................................112
4.21.4 zwif_dlck_cfg_set ..............................................................................................................112
4.21.5 zwif_dlck_cfg_get ..............................................................................................................113
4.22 User Code Interface API ............................................................................................................113
4.22.1 zwif_usrcod_get .................................................................................................................114
4.22.2 zwif_usrcod_set .................................................................................................................114
4.22.3 zwif_usrcod_sup_get ........................................................................................................114
4.22.4 zwif_usrcod_sup_cache_get ...........................................................................................115
4.23 Alarm/Notification Interface API ................................................................................................115
4.23.1 zwif_alrm_rpt_set ..............................................................................................................115
4.23.2 zwif_alrm_get .....................................................................................................................124
4.23.3 zwif_alrm_set .....................................................................................................................124
4.23.4 zwif_alrm_sup_get ............................................................................................................124
4.23.5 zwif_alrm_sup_cache_get ...............................................................................................125
4.23.6 zwif_alrm_sup_evt_get .....................................................................................................125
4.23.7 zwif_alrm_sup_evt_cache_get ........................................................................................126
4.23.8 zwif_alrm_vtype_sup_get ................................................................................................126
4.24 Thermostat Fan Mode Interface API ........................................................................................126
4.24.1 zwif_thrmo_fan_md_rpt_set ............................................................................................126
4.24.2 zwif_thrmo_fan_md_get ...................................................................................................127
4.24.3 zwif_thrmo_fan_md_set ...................................................................................................128
4.24.4 zwif_thrmo_fan_md_sup_get ..........................................................................................128
4.24.5 zwif_thrmo_fan_md_sup_cache_get .............................................................................128
4.25 Thermostat Fan State Interface API .........................................................................................129
4.25.1 zwif_thrmo_fan_sta_rpt_set ............................................................................................129
4.25.2 zwif_thrmo_fan_sta_get ...................................................................................................130
4.26 Thermostat Mode Interface API ................................................................................................130
4.26.1 zwif_thrmo_md_rpt_set ....................................................................................................130
4.26.2 zwif_thrmo_md_get ...........................................................................................................131
4.26.3 zwif_thrmo_md_set ...........................................................................................................131
4.26.4 zwif_thrmo_md_sup_get ..................................................................................................132
silabs.com | Building a more connected world.
Page viii of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.26.5 zwif_thrmo_md_sup_cache_get .....................................................................................132
4.27 Thermostat Operating State Interface API ..............................................................................132
4.27.1 zwif_thrmo_op_sta_rpt_set ..............................................................................................132
4.27.2 zwif_thrmo_op_sta_get ....................................................................................................133
4.27.3 zwif_thrmo_op_sta_log_sup_get ....................................................................................133
4.27.4 zwif_thrmo_op_sta_log_sup_cache_get .......................................................................134
4.27.5 zwif_thrmo_op_sta_log_rpt_set ......................................................................................134
4.27.6 zwif_thrmo_op_sta_log_get .............................................................................................135
4.28 Thermostat Setback Interface API ............................................................................................135
4.28.1 zwif_thrmo_setb_rpt_set ..................................................................................................135
4.28.2 zwif_thrmo_setb_get .........................................................................................................136
4.28.3 zwif_thrmo_setb_set .........................................................................................................136
4.29 Thermostat Setpoint Interface API ............................................................................................137
4.29.1 zwif_thrmo_setp_rpt_set ..................................................................................................137
4.29.2 zwif_thrmo_setp_get .........................................................................................................138
4.29.3 zwif_thrmo_setp_set .........................................................................................................138
4.29.4 zwif_thrmo_setp_sup_get ................................................................................................138
4.29.5 zwif_thrmo_setp_sup_cache_get ...................................................................................139
4.29.6 zwif_thrmo_setp_sup_range_get ....................................................................................139
4.29.7 zwif_thrmo_setp_sup_range_cache_get .......................................................................139
4.30 Clock Interface API ......................................................................................................................140
4.30.1 zwif_clock_rpt_set .............................................................................................................140
4.30.2 zwif_clock_get....................................................................................................................140
4.30.3 zwif_clock_set ....................................................................................................................141
4.31 Climate Control Schedule Interface API ..................................................................................141
4.31.1 zwif_clmt_ctl_schd_rpt_set ..............................................................................................141
4.31.2 zwif_clmt_ctl_schd_get ....................................................................................................142
4.31.3 zwif_clmt_ctl_schd_set .....................................................................................................142
4.31.4 zwif_clmt_ctl_schd_chg_rpt_set .....................................................................................142
4.31.5 zwif_clmt_ctl_schd_chg_get ............................................................................................143
4.31.6 zwif_clmt_ctl_schd_ovr_rpt_set ......................................................................................143
4.31.7 zwif_clmt_ctl_schd_ovr_get .............................................................................................143
4.31.8 zwif_clmt_ctl_schd_ovr_set .............................................................................................144
4.32 Protection Interface API ..............................................................................................................144
4.32.1 zwif_prot_rpt_set ...............................................................................................................144
4.32.2 zwif_prot_get ......................................................................................................................145
4.32.3 zwif_prot_set ......................................................................................................................145
4.32.4 zwif_prot_sup_get .............................................................................................................145
4.32.5 zwif_prot_sup_cache_get ................................................................................................146
4.32.6 zwif_prot_ec_rpt_set .........................................................................................................146
4.32.7 zwif_prot_ec_get ...............................................................................................................147
4.32.8 zwif_prot_ec_set................................................................................................................147
4.32.9 zwif_prot_tmout_rpt_set ...................................................................................................147
4.32.10 zwif_prot_tmout_get..........................................................................................................148
4.32.11 zwif_prot_tmout_set ..........................................................................................................148
silabs.com | Building a more connected world.
Page ix of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.33 Status Interface API ....................................................................................................................148
4.33.1 zwif_appl_busy_rpt_set ....................................................................................................148
4.33.2 zwif_appl_reject_rpt_set ..................................................................................................149
4.34 Indicator Interface API ................................................................................................................149
4.34.1 zwif_ind_rpt_set .................................................................................................................149
4.34.2 zwif_ind_get .......................................................................................................................150
4.34.3 zwif_ind_set........................................................................................................................150
4.35 Firmware Update Interface API .................................................................................................150
4.35.1 zwif_fw_info_get ................................................................................................................150
4.35.2 zwif_fw_updt_req ..............................................................................................................151
4.36 ZIPGW Interface API ..................................................................................................................153
4.36.1 zwif_gw_mode_set............................................................................................................153
4.36.2 zwif_gw_mode_get ...........................................................................................................154
4.36.3 zwif_gw_cfg_lock ..............................................................................................................155
4.36.4 zwif_gw_unsolicit_set .......................................................................................................155
4.36.5 zwif_gw_unsolicit_get .......................................................................................................155
4.37 Z/IP Portal Interface API .............................................................................................................156
4.37.1 zwif_gw_cfg_set ................................................................................................................156
4.37.2 zwif_gw_cfg_get ................................................................................................................156
4.38 Power level Interface API ...........................................................................................................157
4.38.1 zwif_power_level_rpt_set .................................................................................................157
4.38.2 zwif_power_level_get .......................................................................................................157
4.38.3 zwif_power_level_set ........................................................................................................158
4.38.4 zwif_power_level_test_rpt_set ........................................................................................158
4.38.5 zwif_power_level_test_get ...............................................................................................158
4.38.6 zwif_power_level_test_set ...............................................................................................159
4.39 Central Scene Interface API ......................................................................................................159
4.39.1 zwif_csc_rpt_set ................................................................................................................159
4.39.2 zwif_csc_sup_get ..............................................................................................................160
4.39.3 zwif_csc_cfg_rpt_set ........................................................................................................162
4.39.4 zwif_csc_cfg_get ...............................................................................................................162
4.39.5 zwif_csc_cfg_set ...............................................................................................................162
4.40 Alarm Sensor Interface API .......................................................................................................163
4.40.1 zwif_alrm_snsr_rpt_set ....................................................................................................163
4.40.2 zwif_alrm_snsr_get ...........................................................................................................164
4.40.3 zwif_alrm_snsr_sup_get ..................................................................................................164
4.40.4 zwif_alrm_snsr_sup_cache_get ......................................................................................164
4.41 Barrier Operator Interface API ...................................................................................................165
4.41.1 zwif_barrier_rpt_set ..........................................................................................................165
4.41.2 zwif_barrier_get .................................................................................................................165
4.41.3 zwif_barrier_set .................................................................................................................166
4.41.4 zwif_barrier_notif_sup_get ...............................................................................................166
4.41.5 zwif_barrier_notif_sup_cache_get ..................................................................................167
4.41.6 zwif_barrier_notif_rpt_set .................................................................................................167
4.41.7 zwif_barrier_notif_cfg_get ................................................................................................167
silabs.com | Building a more connected world.
Page x of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.41.8 zwif_barrier_notif_cfg_set ................................................................................................168
4.42 Color Switch Interface API .........................................................................................................168
4.42.1 zwif_color_sw_rpt_set ......................................................................................................168
4.42.2 zwif_color_sw_get .............................................................................................................169
4.42.3 zwif_color_sw_set .............................................................................................................169
4.42.4 zwif_color_sw_start ...........................................................................................................170
4.42.5 zwif_color_sw_stop ...........................................................................................................170
4.42.6 zwif_color_sw_sup_get ....................................................................................................170
4.42.7 zwif_color_sw_sup_cache_get .......................................................................................171
5 SYSTEM REQUIREMENTS ................................................................................................ 172
5.1 Target Platform ............................................................................................................................172
5.2 Build System ................................................................................................................................172
5.3 Build System Setup .....................................................................................................................173
5.3.1 Target Platform Ubuntu Linux .........................................................................................173
5.3.2 Target Platform BeagleBone Black and Raspberry Pi 3 .............................................173
6 BUILD & INSTALL............................................................................................................... 174
6.1 Ubuntu Linux ................................................................................................................................174
6.2 BeagleBone Black .......................................................................................................................175
6.3 Raspberry Pi 3 .............................................................................................................................175
7 SAMPLE APPLICATIONS (CE ONLY)............................................................................... 176
7.1 Getting Started .............................................................................................................................176
7.1.1 Prerequisites ......................................................................................................................176
7.1.2 Building of sample applications .......................................................................................176
7.1.3 Installation of sample applications ..................................................................................176
7.1.4 Configuration ......................................................................................................................177
7.2 Running Sample Applications ....................................................................................................177
7.2.1 ZIPGW Discovery ..............................................................................................................177
7.2.2 Reset Z/IP Network ...........................................................................................................178
7.2.3 Add Node into a Network .................................................................................................178
7.2.3.1 ZIPGW that supports Security 2 (S2) .....................................................................179
7.2.3.2 ZIPGW that does not support Security 2 (S2) .......................................................179
7.2.4 Remove Node from a Network ........................................................................................179
7.2.5 Binary Switch .....................................................................................................................180
7.2.6 Basic ....................................................................................................................................181
7.2.7 Binary Sensor ....................................................................................................................181
8 SOURCE CODE DOCUMENTATION ................................................................................. 183
8.1 Manual Generation of Documentation .....................................................................................183
8.2 Auto Generation of Documentation in Ubuntu Linux..............................................................183
REFERENCES ........................................................................................................................... 184
silabs.com | Building a more connected world.
Page xi of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table of Tables
Table 1 – Z-Wave example Device and Descriptors ........................................................................... 2
Table 2 – ZIPGW Versions vs Features as used by Z-Ware ............................................................. 2
Table 3 – Controlled Z-Wave CCs ......................................................................................................... 3
Table 4: ZIPGW SDK 2.8x Supported Z-Wave CCs ........................................................................... 4
Table 5: ZIPGW SDK 2.1x Supported Z-Wave CCs ........................................................................... 5
Table 6: ZIPGW SDK 2.0x Supported Z-Wave CCs ........................................................................... 5
Table 7 – Node Update get/set CCs ...................................................................................................... 8
Table 8 – Node Update endpoint get/set CCs ..................................................................................... 8
Table 9 – Network scanning APIs ........................................................................................................ 10
Table 10 – Network initialization API ................................................................................................... 10
Table 11 – Network creation and tear down APIs ............................................................................. 11
Table 12 – Portal initialization API ....................................................................................................... 11
Table 13 – Portal shut down APIs ........................................................................................................ 11
Table 14 – Portal client profile management APIs ............................................................................ 12
Table 15 – Interface Control APIs ........................................................................................................ 12
Table 16 – Node identification APIs ..................................................................................................... 13
Table 17 – Grouping APIs ..................................................................................................................... 14
Table 18 – Command Queuing APIs ................................................................................................... 14
Table 19 – Firmware update APIs ........................................................................................................ 15
Table 20 – Polling facility APIs ............................................................................................................. 15
Table 21 – Device specific configuration and information database APIs ..................................... 15
Table 22 – Network and client preference storage APIs .................................................................. 15
Table 23 – Security 2 APIs .................................................................................................................... 16
Table 24 – Smart Start provisioning list management APIs ............................................................. 17
Table 25 – Network health check API ................................................................................................. 18
Table 26 – Error Codes, ZW_ERR_XXX ............................................................................................ 19
Table 27 – Low-level Library Error Codes .......................................................................................... 20
Table 28 – zwportal_init Parameters ................................................................................................... 21
Table 29 – zwportal_init_t structure ..................................................................................................... 22
Table 30 – clnt_prof_t structure ............................................................................................................ 22
Table 31 – zwportal_cb_t Parameters ................................................................................................. 22
Table 32 – zwportal_shutdown Parameters ....................................................................................... 23
Table 33 – zwportal_exit Parameters .................................................................................................. 23
Table 34 – zwportal_clnt_conn_close Parameters ............................................................................ 23
Table 35 – zwportal_clnt_add Parameters ......................................................................................... 23
Table 36 – zwportal_clnt_rm Parameters ........................................................................................... 23
Table 37 – zwportal_clnt_find Parameters ......................................................................................... 24
Table 38 – zwportal_clnt_list_free Parameters .................................................................................. 24
Table 39 – clnt_prof_lst structure ......................................................................................................... 24
Table 40 – zwportal_clnt_list_get Parameters ................................................................................... 24
Table 41 – zwdev_cfg_load Parameters ............................................................................................. 25
Table 42 – dev_rec_t structure ............................................................................................................. 25
Table 43 – DEV_XXX meaning & values ............................................................................................ 25
silabs.com | Building a more connected world.
Page xii of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 44 – ep_rec_t structure ............................................................................................................... 26
Table 45 – redir_rec_t structure ........................................................................................................... 26
Table 46 – if_rec_t structure ................................................................................................................. 26
Table 47 – Interface Types: IF_REC_TYPE_XXX ............................................................................ 27
Table 48 – rec union ............................................................................................................................... 27
Table 49 – if_rec_grp_t structure ......................................................................................................... 27
Table 50 – if_rec_config_t structure .................................................................................................... 27
Table 51 – if_rec_cfg_set_t structure .................................................................................................. 28
Table 52 – if_rec_cfg_info_t structure ................................................................................................. 28
Table 53 – if_rec_bsnsr_t structure ..................................................................................................... 28
Table 54 – if_rec_bsnsr_match_t structure ........................................................................................ 28
Table 55 – if_rec_thrmo_setp_t structure ........................................................................................... 29
Table 56 – zwsetp_temp_range_t structure ....................................................................................... 29
Table 57 – Binary Sensor Types: ZW_BSENSOR_TYPE_XXX ..................................................... 29
Table 58 – Multi-level Sensor Type: ZW_SENSOR_TYPE_XXX ................................................... 29
Table 59 – Multi-level Sensor Unit ....................................................................................................... 31
Table 60 – Meter Type ........................................................................................................................... 34
Table 61 – Meter Supported Unit Bit-mask......................................................................................... 34
Table 62 – Z-Wave Alarm//Notification Type ...................................................................................... 34
Table 63 – Z-Wave Alarm/Notification Event ..................................................................................... 35
Table 64 – Z-Wave Alarm/Notification Event Parameter Type ........................................................ 38
Table 65 – Alarm Sensor Type ............................................................................................................. 38
Table 66 – if_rec_snsr_t structure ........................................................................................................ 39
Table 67 – if_rec_meter_t structure ..................................................................................................... 39
Table 68 – if_rec_alarm_match_t structure ........................................................................................ 39
Table 69 – if_rec_alarm_result_t structure ......................................................................................... 39
Table 70 – if_rec_alarm_rev_match_t structure ................................................................................ 40
Table 71 – if_rec_basic_match_t structure ......................................................................................... 40
Table 72 – if_rec_alrm_snsr_match_t structure................................................................................. 40
Table 73 – dev_cfg_error_t structure .................................................................................................. 40
Table 74 – zwdev_cfg_free Parameters ............................................................................................. 41
Table 75 – zwdev_global_sett_free Parameters ............................................................................... 41
Table 76 – zwdev_cfg_find Parameters .............................................................................................. 41
Table 77 – dev_rec_srch_key_t structure ........................................................................................... 41
Table 78 – zwnet_gw_discvr_start Parameters ................................................................................. 50
Table 79 – zwnet_gw_discvr_cb_t Parameters ................................................................................. 50
Table 80 – zwnet_gw_discvr_stop Parameters ................................................................................. 50
Table 81 – zwnet_ip_aton Parameters ................................................................................................ 51
Table 82 – zwnet_ip_ntoa Parameters ................................................................................................ 51
Table 83 – zwnet_local_addr_get Parameters................................................................................... 51
Table 84 – zwnet_listen_port_get Parameters................................................................................... 52
Table 85 – zwnet_init Parameters ........................................................................................................ 52
Table 86 – zwnet_init_t structure ......................................................................................................... 52
Table 87 – dev_cfg_usr_t structure ..................................................................................................... 54
Table 88 – zwnet_dev_rec_find_fn Parameters ................................................................................ 54
silabs.com | Building a more connected world.
Page xiii of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 89 – dev_global_sett_t structure ............................................................................................... 54
Table 90 – zwnet_xxx generic Parameters......................................................................................... 54
Table 91 – zwnet_unhandled_cmd_fn Parameters ........................................................................... 54
Table 92 – sup_cmd_cls_t structure .................................................................................................... 55
Table 93 – zwnet_notify_fn Parameters .............................................................................................. 55
Table 94 – zwnet_sts_t structure ......................................................................................................... 56
Table 95 – zw_health_prg_t structure ................................................................................................. 57
Table 96 – zw_health_rpt_t structure .................................................................................................. 57
Table 97 – zw_health_sts_t structure .................................................................................................. 57
Table 98 – zwnet_node_fn Parameters .............................................................................................. 58
Table 99 – zwnet_appl_fn Parameters ................................................................................................ 58
Table 100 – pl_info_fn Parameters ...................................................................................................... 58
Table 101 – zwnet_net_err_fn Parameters ........................................................................................ 58
Table 102 – print_fn Parameter ............................................................................................................ 58
Table 103 – zwnet_dev_rec_find_fn Parameter ................................................................................ 58
Table 104 – zwnet_exit Parameters .................................................................................................... 59
Table 105 – zwnet_get_desc Parameters .......................................................................................... 59
Table 106 – zwnetd_t structure ............................................................................................................ 59
Table 107 – zwnet_add Parameters .................................................................................................... 60
Table 108 – sec2_add_prm_t structure............................................................................................... 60
Table 109 – add_node_sec2_fn Parameters ..................................................................................... 60
Table 110 – sec2_add_cb_prm_t structure ........................................................................................ 61
Table 111 – sec2_keys_req_cb_prm_t structure............................................................................... 61
Table 112 – sec2_dsk_cb_prm_t structure......................................................................................... 61
Table 113 – zwnet_fail Parameters ..................................................................................................... 61
Table 114 – zwnet_initiate Parameters ............................................................................................... 62
Table 115 – zwnet_initiate_classic Parameters ................................................................................. 63
Table 116 – zwnet_get_node Parameters .......................................................................................... 64
Table 117 – zwnet_get_node_by_id Parameters .............................................................................. 64
Table 118 – zwnet_get_ep_by_id Parameters................................................................................... 64
Table 119 – zwnet_get_if_by_id Parameters ..................................................................................... 64
Table 120 – zwnet_get_user Parameters ........................................................................................... 65
Table 121 – zwnet_send_nif Parameters ........................................................................................... 65
Table 122 – zwnet_all_node_sts_get Parameters ............................................................................ 65
Table 123 – zwnet_node_sts_get Parameters................................................................................... 65
Table 124 – zwnet_poll_rm Parameters ............................................................................................. 66
Table 125 – zwnet_poll_rm_mul Parameters ..................................................................................... 66
Table 126 – zwnet_pref_set Parameters ............................................................................................ 66
Table 127 – zwnet_pref_get Parameters ............................................................................................ 66
Table 128 – zwnet_client_pref_set Parameters................................................................................. 67
Table 129 – zwnet_client_pref_get Parameters ................................................................................ 67
Table 130 – zwnet_add_sec2_accept Parameters ........................................................................... 67
Table 131 – zwnet_add_sec2_grant_key Parameters ..................................................................... 67
Table 132 – zwnet_sec2_get_dsk Parameters .................................................................................. 68
Table 133 – get_dsk_fn Parameters .................................................................................................... 68
silabs.com | Building a more connected world.
Page xiv of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 134 – zwnet_pl_add Parameters............................................................................................... 68
Table 135 – pl_info_t structure ............................................................................................................. 68
Table 136 – pl_prod_type_t structure .................................................................................................. 70
Table 137 – pl_prod_id_t structure ...................................................................................................... 70
Table 138 – pl_uuid_t structure ............................................................................................................ 70
Table 139 – pl_nw_sts_t structure ....................................................................................................... 71
Table 140 – zwnet_pl_get Parameters ................................................................................................ 71
Table 141 – pl_info_fn Parameters ...................................................................................................... 71
Table 142 – pl_lst_ent_t structure ........................................................................................................ 71
Table 143 – zwnet_pl_del Parameters ................................................................................................ 72
Table 144 – zwnet_pl_list_get Parameters......................................................................................... 72
Table 145 – pl_list_fn Parameters ....................................................................................................... 72
Table 146 – zwnet_pl_list_del Parameters ......................................................................................... 73
Table 147 – zwnoded_t structure ......................................................................................................... 73
Table 148 – NODE_PROPTY_XXX .................................................................................................... 73
Table 149 – dev_id_t structure ............................................................................................................. 74
Table 150 – zwnode_get_net Parameters .......................................................................................... 74
Table 151 – zwnode_get_next Parameters ........................................................................................ 74
Table 152 – zwnode_get_ep Parameters ........................................................................................... 74
Table 153 – zwnode_update Parameters ........................................................................................... 75
Table 154 – zwnode_cmd_q_ena_set Parameters ........................................................................... 75
Table 155 – zwnode_cmd_q_ena_get Parameters........................................................................... 75
Table 156 – zwnode_cmd_q_ena_cancel Parameters ..................................................................... 75
Table 157 – zwnode_cmd_q_get Parameters ................................................................................... 76
Table 158 – zwnode_mul_cmd_ctl_set Parameters ......................................................................... 76
Table 159 – zwnode_mul_cmd_ctl_get Parameters ......................................................................... 76
Table 160 – zwnode_get_ext_ver Parameters .................................................................................. 76
Table 161 – ext_ver_t structure ............................................................................................................ 76
Table 162 – zwepd_t structure ............................................................................................................. 77
Table 163 – zwplus_info_t structure .................................................................................................... 77
Table 164 – zwep_get_node Parameters ........................................................................................... 77
Table 165 – zwep_get_next Parameters ............................................................................................ 78
Table 166 – zwep_get_if Parameters .................................................................................................. 78
Table 167 – zwep_nameloc_set Parameters ..................................................................................... 78
Table 168 – zw_nameloc_t structure ................................................................................................... 78
Table 169 – zwifd_t structure ................................................................................................................ 79
Table 170 – zwif_get_ep Parameters .................................................................................................. 79
Table 171 – zwif_get_next Parameters ............................................................................................... 80
Table 172 – zwif_exec Parameters ...................................................................................................... 80
Table 173 – zwif_xxx_poll Parameters ................................................................................................ 80
Table 174 – zwpoll_req_t structure ...................................................................................................... 80
Table 175 – zwpoll_cmplt_fn Parameters ........................................................................................... 81
Table 176 – zwif_basic_rpt_set Parameters ..................................................................................... 81
Table 177 – zwrep_basic_fn Parameters ........................................................................................... 81
Table 178 – zwbasic_t structure ........................................................................................................... 81
silabs.com | Building a more connected world.
Page xv of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 179 – zwif_basic_get Parameters ............................................................................................. 82
Table 180 – zwif_basic_set Parameters ............................................................................................. 82
Table 181 – zwif_group_sup_get Parameters ................................................................................... 82
Table 182 – zwrep_group_sup_fn Parameters .................................................................................. 83
Table 183 – zwif_group_actv_get Parameters................................................................................... 83
Table 184 – zwrep_group_actv_fn Parameters ................................................................................. 83
Table 185 – zwif_group_get Parameters ............................................................................................ 83
Table 186 – zwrep_group_fn Parameters .......................................................................................... 83
Table 187 – grp_member_t structure .................................................................................................. 84
Table 188 – zwif_group_add Parameters ........................................................................................... 84
Table 189 – zwif_group_del Parameters ............................................................................................ 84
Table 190 – zwif_group_info_get Parameters ................................................................................... 84
Table 191 – if_grp_info_dat_t structure .............................................................................................. 85
Table 192 – zw_grp_info_t structure ................................................................................................... 85
Table 193 – grp_cmd_ent_t structure .................................................................................................. 85
Table 194 – zwif_group_info_free Parameters .................................................................................. 85
Table 195 – zwif_switch_rpt_set Parameters..................................................................................... 86
Table 196 – zwrep_switch_fn Parameters .......................................................................................... 86
Table 197 – zwswitch_t structure ......................................................................................................... 86
Table 198 – zwif_switch_get Parameters ........................................................................................... 86
Table 199 – ZWIF_GET_BMSK_XXX ................................................................................................. 86
Table 200 – zwif_switch_set Parameters ........................................................................................... 87
Table 201 – zw_postset_fn Parameters .............................................................................................. 87
Table 202 – zwif_level_rpt_set Parameters ....................................................................................... 87
Table 203 – zwrep_level_fn Parameters ............................................................................................ 88
Table 204 – zwlevel_dat_t structure .................................................................................................... 88
Table 205 – zwif_level_sup_get Parameters ..................................................................................... 88
Table 206 – zwrep_lvl_sup_fn Parameters ........................................................................................ 88
Table 207 – zwif_level_sup_cache_get Parameters ......................................................................... 89
Table 208 – zwif_level_get Parameters .............................................................................................. 89
Table 209 – zwif_level_set Parameters .............................................................................................. 89
Table 210 – zwif_level_start Parameters ............................................................................................ 90
Table 211 – zwlevel_t structure ............................................................................................................ 90
Table 212 – zwif_level_stop Parameters ............................................................................................ 90
Table 213 – zwif_bsensor_rpt_set Parameters ................................................................................. 91
Table 214 – zwrep_bsensor_fn Parameters....................................................................................... 91
Table 215 – zwif_bsensor_get Parameters ........................................................................................ 91
Table 216 – zwif_bsensor_sup_get Parameters ............................................................................... 91
Table 217 – zwrep_bsensor_sup_fn Parameters .............................................................................. 92
Table 218 – zwif_bsensor_sup_cache_get Parameters ................................................................... 92
Table 219 – zwif_sensor_rpt_set Parameters .................................................................................... 92
Table 220 – zwrep_sensor_fn Parameters ......................................................................................... 92
Table 221 – zwsensor_t structure ........................................................................................................ 93
Table 222 – ZW_SENSOR_TYPE_XXX, ZW_SENSOR_UNIT_XXX_YYY ................................. 93
Table 223 – zwif_sensor_get Parameters .......................................................................................... 95
silabs.com | Building a more connected world.
Page xvi of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 224 – zwif_sensor_sup_get Parameters .................................................................................. 96
Table 225 – zwrep_sensor_sup_fn Parameters ................................................................................ 96
Table 226 – zwif_sensor_unit_get Parameters .................................................................................. 96
Table 227 – zwrep_sensor_unit_fn Parameters ................................................................................ 96
Table 228 – zwif_sensor_unit_cache_get Parameters ..................................................................... 97
Table 229 – zwif_sensor_sup_cache_get Parameters ..................................................................... 97
Table 230 – if_sensor_data_t structure ............................................................................................... 97
Table 231 – zwif_group_cmd_sup_get Parameters .......................................................................... 98
Table 232 – zwrep_grp_cmd_sup_fn Parameters............................................................................. 98
Table 233 – zwgrp_cmd_cap_t structure ............................................................................................ 98
Table 234 – zwif_group_cmd_get Parameters .................................................................................. 98
Table 235 – zwrep_grp_cmd_fn Parameters ..................................................................................... 98
Table 236 – zwif_group_cmd_set Parameters................................................................................... 99
Table 237 – zwif_wakeup_get Parameters ........................................................................................ 99
Table 238 – zwrep_wakeup_fn Parameters ....................................................................................... 99
Table 239 – zwif_wakeup_t structure .................................................................................................. 99
Table 240 – zwif_wakeup_set Parameters ....................................................................................... 100
Table 241 – zwif_config_rpt_set Parameters .................................................................................. 100
Table 242 – zwrep_config_fn Parameters ........................................................................................ 100
Table 243 – zwconfig_t structure ....................................................................................................... 100
Table 244 – zwif_c onfig_get Parameters .......................................................................................... 101
Table 245 – zwif_config_set Parameters .......................................................................................... 101
Table 246 – zwif_config_bulk_rpt_set Parameters ........................................................................ 101
Table 247 – zwrep_cfg_bulk_fn Parameters .................................................................................... 101
Table 248 – zwcfg_bulk_t structure ................................................................................................... 101
Table 249 – zwif_config_bulk_get Parameters ................................................................................ 102
Table 250 – zwif_config_bulk_set Parameters ................................................................................ 102
Table 251 – zwif_config_prm_reset Parameters ............................................................................. 102
Table 252 – zwif_c onfig_i nfo_get Parameters ................................................................................. 103
Table 253 – zwcfg_info_cap_t structure ........................................................................................... 103
Table 254 – zwcfg_info_t structure .................................................................................................... 103
Table 255 – gen_dat_u union ............................................................................................................. 104
Table 256 – zwif_config_info_free Parameters ................................................................................ 104
Table 257 – zwif_pulsemeter_rpt_set Parameters ......................................................................... 104
Table 258 – zwrep_pulsemeter_fn Parameters .............................................................................. 105
Table 259 – zwif_pulsemeter_get Parameters................................................................................. 105
Table 260 – zwif_battery_rpt_set Parameters ................................................................................ 105
Table 261 – zwrep_ts_fn Parameters ................................................................................................ 105
Table 262 – zwif_battery_get Parameters ........................................................................................ 105
Table 263 – zwif_av_set Parameters ................................................................................................ 106
Table 264 – zwif_av_caps Parameters ............................................................................................. 106
Table 265 – zwrep_av_fn Parameters............................................................................................... 106
Table 266 – zwif_meter_rpt_set Parameters .................................................................................. 107
Table 267 – zwrep_meter_fn Parameters......................................................................................... 107
Table 268 – zwmeter_dat_t structure ................................................................................................ 107
silabs.com | Building a more connected world.
Page xvii of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 269 – ZW_METER_TYPE_XXX and ZW_METER_UNIT_XXX ......................................... 107
Table 270 – zwif_meter_get Par ameters .......................................................................................... 108
Table 271 – zwif_meter_sup_get Parameters ................................................................................. 108
Table 272 – zwrep_meter_sup_fn Parameters ................................................................................ 108
Table 273 – zwmeter_cap_t structure ............................................................................................... 109
Table 274 – ZW_METER_SUP_UNIT_XXX .................................................................................... 109
Table 275 – zwif_meter_sup_cache_get Parameters ..................................................................... 109
Table 276 – zwif_meter_reset Parameters ....................................................................................... 110
Table 277 – zwif_meter_set_admin Parameters ............................................................................. 110
Table 278 – zwif_meter_get_desc Parameters ............................................................................... 110
Table 279 – zwrep_meterd_fn Parameters ...................................................................................... 110
Table 280 – zwmeter_t structure ........................................................................................................ 110
Table 281 – zwif_dlck_op_rpt_set Parameters ............................................................................... 111
Table 282 – zwrep_dlck_op_fn Parameters ..................................................................................... 111
Table 283 – zwdlck_op_t structure ................................................................................................... 111
Table 284 – ZW_DOOR_XXX ............................................................................................................ 111
Table 285 – ZW_COND_XXX_MASK ............................................................................................... 112
Table 286 – zwif_dlck_op_get Parameters ...................................................................................... 112
Table 287 – zwif_dlck_op_set Parameters ....................................................................................... 112
Table 288 – zwif_dlck_cfg_set Parameters ..................................................................................... 112
Table 289 – zwdlck_cfg_t structure .................................................................................................. 113
Table 290 – zwif_d l ck_cfg_get P arameters ...................................................................................... 113
Table 291 – zwrep_dlck_cfg_fn Parameters ................................................................................... 113
Table 292 – zwif_usrcod_get Parameters ........................................................................................ 114
Table 293 – zwrep_usr_cod_fn Parameters .................................................................................... 114
Table 294 – zwusrcod_t structure ...................................................................................................... 114
Table 295 – zwif_usrcod_set Parameters ........................................................................................ 114
Table 296 – zwif_usrcod_sup_get Parameters ................................................................................ 114
Table 297 – zwrep_usr_sup_fn Parameters .................................................................................... 115
Table 298 – zwif_usrcod_sup_cache_get Parameters ................................................................... 115
Table 299 – zwif_alrm_rpt_set Parameters ..................................................................................... 115
Table 300 – zwrep_alrm_fn Parameters ........................................................................................... 115
Table 301 – zwalrm_t stru cture ......................................................................................................... 115
Table 302 – ZW_ALRM_STS_XXX ................................................................................................... 116
Table 303 – ZW_ALRM_XXX ............................................................................................................. 117
Table 304 – ZW_ALRM_EVT_XXX ................................................................................................... 117
Table 305 – zwif_alrm_get Parameters ............................................................................................ 124
Table 306 – zwif_alrm_set Parameters ............................................................................................. 124
Table 307 – zwif_alrm_sup_get Parameters ................................................................................... 124
Table 308 – zwrep_alrm_sup_fn Parameters ................................................................................. 125
Table 309 – zwif_alrm_sup_cache_get Parameters ....................................................................... 125
Table 310 – zwif_alrm_sup_evt_get Parameters ........................................................................... 125
Table 311 – zwrep_alrm_evt_fn Parameters .................................................................................. 126
Table 312 – zwif_alrm_sup_evt_cache_get Parameters ............................................................... 126
Table 313 – zwif_alrm_vtype_sup_get Parameters ....................................................................... 126
silabs.com | Building a more connected world.
Page xviii of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 314 – zwif_thrmo_fan_md_rpt_set Parameters .................................................................... 126
Table 315 – zwrep_thrmo_fan_md_fn Parameters ......................................................................... 127
Table 316 – ZW_THRMO_FAN_MD_XXX ....................................................................................... 127
Table 317 – zwif_thrmo_fan_md_get Parameters ........................................................................... 127
Table 318 – zwif_thrmo_fan_md_set Parameters ........................................................................... 128
Table 319 – zwif_thrmo_fan_md_sup_get Parameters .................................................................. 128
Table 320 – zwrep_thrmo_fan_md_sup_fn Parameters ................................................................ 128
Table 321 – zwif_thrmo_fan_md_sup_cache_get Parameters ..................................................... 129
Table 322 – zwif_thrmo_fan_sta_rpt_set Parameters .................................................................... 129
Table 323 – zwrep_thrmo_fan_sta_fn Parameters ......................................................................... 129
Table 324 – ZW_THRMO_FAN_STA_XXX ..................................................................................... 129
Table 325 – zwif_thrmo_fan_sta_get Parameters ........................................................................... 130
Table 326 – zwif_thrmo_md_rpt_set Parameters ............................................................................ 130
Table 327 – zwrep_thrmo_md_fn Parameters ................................................................................. 130
Table 328 – ZW_THRMO_MD_XXX ................................................................................................. 130
Table 329 – zwif_thrmo_md_get Parameters .................................................................................. 131
Table 330 – zwif_thrmo_md_set Parameters................................................................................... 131
Table 331 – zwif_thrmo_md_sup_get Parameters .......................................................................... 132
Table 332 – zwrep_thrmo_md_sup_fn Parameters ........................................................................ 132
Table 333 – zwif_thrmo_md_sup_cache_get Parameters ............................................................. 132
Table 334 – zwif_thrmo_op_sta_rpt_set Parameters ..................................................................... 132
Table 335 – zwrep_thrmo_op_sta_fn Parameters .......................................................................... 133
Table 336 – ZW_THRMO_OP_STA_XXX ........................................................................................ 133
Table 337 – zwif_thrmo_op_sta_get Parameters ............................................................................ 133
Table 338 – zwif_thrmo_op_sta_log_sup_get Parameters ............................................................ 133
Table 339 – zwrep_thrmo_op_sta_log_sup_fn Parameters .......................................................... 134
Table 340 – zwif_thrmo_op_sta_log_sup_cache_get Parameters ............................................... 134
Table 341 – zwif_thrmo_op_sta_log_rpt_set Parameters .............................................................. 134
Table 342 – zwrep_thrmo_op_sta_log_fn Parameters ................................................................... 134
Table 343 – zwthrmo_op_sta_log_t structure ................................................................................. 135
Table 344 – zwif_thrmo_op_sta_log_get Parameters .................................................................... 135
Table 345 – zwif_thrmo_setb_rpt_set Parameters .......................................................................... 135
Table 346 – zwrep_thrmo_setb_fn Parameters ............................................................................... 135
Table 347 – ZW_THRMO_SETB_TYP_XXX ................................................................................... 136
Table 348 – ZW_THRMO_SETB_STA_XXX ................................................................................... 136
Table 349 – zwif_thrmo_setb_get Parameters ................................................................................ 136
Table 350 – zwif_thrmo_setb_set Parameters................................................................................. 136
Table 351 – zwif_thrmo_setp_rpt_set Parameters .......................................................................... 137
Table 352 – zwrep_thrmo_setp_fn Parameters ............................................................................... 137
Table 353 – zwsetp_t structure ......................................................................................................... 137
Table 354 – ZW_THRMO_SETP_TYP_XXX ................................................................................... 137
Table 355 – ZW_THRMO_SETP_UNIT_XXX ................................................................................. 138
Table 356 – zwif_thrmo_setp_get Parameters ................................................................................ 138
Table 357 – zwif_thrmo_setp_set Parameters................................................................................. 138
Table 358 – zwif_thrmo_setp_sup_get Parameters ........................................................................ 138
silabs.com | Building a more connected world.
Page xix of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 359 – zwrep_thrmo_setp_sup_fn Parameters ...................................................................... 138
Table 360 – zwif_thrmo_setp_sup_cache_get Parameters ........................................................... 139
Table 361 – zwif_thrmo_setp_sup_range_get Parameters ........................................................... 139
Table 362 – zwrep_thrmo_setp_range_fn Parameters .................................................................. 139
Table 363 – zwif_thrmo_setp_sup_range_cache_get Parameters .............................................. 139
Table 364 – zwif_clock_rpt_set Parameters..................................................................................... 140
Table 365 – zwrep_clock_fn Parameters .......................................................................................... 140
Table 366 – ZW_CLOCK_XXX .......................................................................................................... 140
Table 367 – zwif_clo ck_get Parameters ........................................................................................... 140
Table 368 – zwif_clock_set Parameters ........................................................................................... 141
Table 369 – zwif_clmt_ctl_schd_rpt_set Parameters ..................................................................... 141
Table 370 – zwrep_clmt_ctl_schd_fn Parameters ........................................................................... 141
Table 371 – zwcc_shed_t structure .................................................................................................. 141
Table 372 – zwcc_shed_swpt_t structure ......................................................................................... 142
Table 373 – zwif_clmt_ctl_schd_get Parameters ............................................................................ 142
Table 374 – zwif_clmt_ctl_schd_set Parameters ............................................................................ 142
Table 375 – zwif_clmt_ctl_schd_chg_rpt_set Parameters ............................................................. 142
Table 376 – zwrep_clmt_ctl_schd_chg_fn Parameters .................................................................. 142
Table 377 – zwif_clmt_ctl_schd_chg_get Parameters ................................................................... 143
Table 378 – zwif_clmt_ctl_schd_ovr_rpt_set Parameters .............................................................. 143
Table 379 – zwrep_clmt_ctl_schd_ovr_fn Parameters ................................................................... 143
Table 380 – zwcc_shed_t structure .................................................................................................. 143
Table 381 – zwif_clmt_ctl_schd_ovr_get Parameters .................................................................... 143
Table 382 – zwif_clmt_ctl_schd_ovr_set Parameters ..................................................................... 144
Table 383 – zwif_prot_rpt_set Parameters ....................................................................................... 144
Table 384 – zwrep_prot_fn Parameters ............................................................................................ 144
Table 385 – ZW_LPROT_XXX ........................................................................................................... 144
Table 386 – ZW_RFPROT_XXX ........................................................................................................ 145
Table 387 – zwif_prot_get Parameters ............................................................................................. 145
Table 388 – zwif_prot_set Parameters .............................................................................................. 145
Table 389 – zwif_prot_sup_get Parameters ..................................................................................... 145
Table 390 – zwrep_prot_sup_fn Parameters ................................................................................... 146
Table 391 – zwprot_sup_t structure .................................................................................................. 146
Table 392 – zwif_prot_sup_cache_get Parameters ........................................................................ 146
Table 393 – zwif_prot_ec_rpt_set Parameters ................................................................................ 146
Table 394 – zwrep_prot_ec_fn Parameters ..................................................................................... 146
Table 395 – zwif_prot_ec_get Parameters ....................................................................................... 147
Table 396 – zwif_prot_ec_set Parameters ....................................................................................... 147
Table 397 – zwif_prot_tmout_rpt_set Parameters ........................................................................... 147
Table 398 – zwrep_prot_tmout_fn Parameters ................................................................................ 147
Table 399 – zwif_prot_tmout_get Parameters ................................................................................. 148
Table 400 – zwif_prot_tmout_set Parameters ................................................................................. 148
Table 401 – zwif_appl_busy_rpt_set Parameters ........................................................................... 148
Table 402 – zwrep_appl_busy_fn Parameters................................................................................. 148
Table 403 – ZW_BSY_STS_XXX ...................................................................................................... 149
silabs.com | Building a more connected world.
Page xx of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 404 – zwif_appl_reject_rpt_set Parameters .......................................................................... 149
Table 405 – zwrep_appl_reject_fn Parameters ............................................................................... 149
Table 406 – ZW_RJ_STS_XXX ......................................................................................................... 149
Table 407 – zwif_ind_rpt_set Parameters ........................................................................................ 149
Table 408 – zwrep_fn Parameters ..................................................................................................... 150
Table 409 – zwif_ind_get Parameters ............................................................................................... 150
Table 410 – zwif_ind_set Parameters ............................................................................................... 150
Table 411 – zwif_fw_inf o_get Pa rameters ........................................................................................ 150
Table 412 – zwrep_fw_info_fn Parameters ...................................................................................... 151
Table 413 – zwfw_info_t structure ..................................................................................................... 151
Table 414 – zwif_fw_updt_req Parameters ...................................................................................... 151
Table 415 – zwfw_updt_req_t structure ............................................................................................ 151
Table 416 – zwrep_fw_updt_sts_fn Parameters ............................................................................. 152
Table 417 – ZW_FW_UPDT_ERR_XXX .......................................................................................... 152
Table 418 – zwrep_fw_updt_cmplt_fn Parameters ......................................................................... 152
Table 419 – ZW_FW_UPDT_CMPLT_XXX ..................................................................................... 152
Table 420 – zwrep_fw_tgt_restart_fn Parameters ........................................................................... 153
Table 421 – ZW_FW_UPDT_ RESTART_XXX ............................................................................... 153
Table 422 – zwif_gw_mode_set Parameters ................................................................................... 153
Table 423 – zwgw_portal_prof_t structure ........................................................................................ 154
Table 424 – zwif_gw_mode_get Parameters ................................................................................... 154
Table 425 – zwrep_gw_mode_fn Parameters ................................................................................. 154
Table 426 – zwif_gw_mode_get Parameters ................................................................................... 155
Table 427 – zwif_gw_unsolicit_set Parameters ............................................................................... 155
Table 428 – zwif_gw_unsolicit_get Parameters............................................................................... 155
Table 429 – zwrep_gw_unsolicit_fn Parameters ............................................................................. 155
Table 430 – zwif_gw_cfg_set Parameters ........................................................................................ 156
Table 431 – zwportal_cfg_t structure ................................................................................................ 156
Table 432 – zwrep_cfg_st s_fn Parameters ...................................................................................... 156
Table 433 – zwif_gw_mode_get Parameters ................................................................................... 157
Table 434 – zwrep_gw_cfg_fn Parameters ...................................................................................... 157
Table 435 – zwif_power_level_rpt_set Parameters ....................................................................... 157
Table 436 – zwrep_power_level_fn Parameters ............................................................................. 157
Table 437 – zwif_power_level_get Parameters ............................................................................... 157
Table 438 – zwif_power_level_set Parameters ............................................................................... 158
Table 439 – zwif_power_level_test_rpt_set Parameters ............................................................... 158
Table 440 – zwrep_power_level_test_fn Parameters ..................................................................... 158
Table 441 – POWERLEVEL_TEST_XXX ......................................................................................... 158
Table 442 – zwif_power_level_test_get Parameters ...................................................................... 159
Table 443 – zwif_power_level_test_set Parameters ....................................................................... 159
Table 444 – zwif_csc_rpt_set Parameters ........................................................................................ 159
Table 445 – zwrep_csc_fn Parameters ............................................................................................. 159
Table 446 – zwcsc_notif_t structure ................................................................................................. 159
Table 447 – ZW_CSC_KEY_ATTRIB_XXX ..................................................................................... 160
Table 448– zwif_ csc_sup_get Pa rameters ....................................................................................... 160
silabs.com | Building a more connected world.
Page xxi of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 449 – zwrep_csc_sup_fn Parameters .................................................................................... 161
Table 450– zwif_csc_cfg_rpt_set Parameters ................................................................................. 162
Table 451 – zwrep_csc_cfg_fn Parameters ..................................................................................... 162
Table 452– zwif_csc_cfg_get Parameters ........................................................................................ 162
Table 453– zwif_csc_cfg_set Parameters ........................................................................................ 162
Table 454 – zwif_alrm_snsr_rpt_set Parameters ............................................................................ 163
Table 455 – zwrep_alrm_snsr_fn Parameters ................................................................................. 163
Table 456 – zw_alrm_snsr_t structure ............................................................................................. 163
Table 457 – ZW_ALRM_SNSR_TYPE_XXX ................................................................................... 163
Table 458 – zwif_alrm_snsr_get Parameters ................................................................................... 164
Table 459 – zwif_alrm_snsr_sup_get Parameters .......................................................................... 164
Table 460 – zwrep_alrm_snsr_sup_fn Parameters ......................................................................... 164
Table 461 – zwif_alrm_snsr_sup_cache_get Parameters ............................................................. 164
Table 462 – zwif_barrier_rpt_set Parameters .................................................................................. 165
Table 463 – zwrep_barrier_fn Parameters ....................................................................................... 165
Table 464 – ZW_BAR_STA_XXX ...................................................................................................... 165
Table 465 – zwif_barrier_get Parameters ......................................................................................... 165
Table 466 – zwif_barrier_set Parameters ......................................................................................... 166
Table 467 – zwif_barrier_notif_sup_get Parameters ...................................................................... 166
Table 468 – zwrep_barrier_notif_sup_fn Parameters ..................................................................... 166
Table 469 – ZW_BAR_NOTIF_TYP_XXX ........................................................................................ 166
Table 470 – zwif_barrier_notif_sup_cache_get Parameters ......................................................... 167
Table 471 – zwif_barrier_notif_rpt_set Parameters ........................................................................ 167
Table 472 – zwrep_barrier_subsys_fn Parameters......................................................................... 167
Table 473 – zwif_barrier_notif_cfg_get Parameters ....................................................................... 167
Table 474 – zwif_barrier_notif_cfg_set Parameters ........................................................................ 168
Table 475 – zwif_color_sw_rpt_set Parameters .............................................................................. 168
Table 476 – zwrep_color_sw_get_fn Parameters ........................................................................... 168
Table 477 – zwcolor_t structure ........................................................................................................ 168
Table 478 – COL_SW_COMP_ID_XXX ........................................................................................... 169
Table 479 – zwif_color_sw_get Parameters..................................................................................... 169
Table 480 – zwif_color_sw_set Parameters ..................................................................................... 169
Table 481 – zwif_color_sw_start Parameters .................................................................................. 170
Table 482 – zwcol_ctl_t structure ...................................................................................................... 170
Table 483 – COL_SW_LVL_XXX ...................................................................................................... 170
Table 484 – zwif_color_sw Parameters ............................................................................................ 170
Table 485 – zwif_color_sw_sup_get Parameters ............................................................................ 170
Table 486 – zwrep_color_sw_sup_fn Parameters .......................................................................... 171
Table 487 – zwif_color_sw_sup_cache_get Parameters ............................................................... 171
Table 488 – Base memory requirement ............................................................................................ 172
Table 489 – Per node memory requirement ..................................................................................... 172
Table 490 – Per Z-Wave network memory requirement ................................................................. 172
Table 491 – Build System Requirements .......................................................................................... 172
Table 492 – Files .................................................................................................................................. 174
Table 493 – Configuration file entries ................................................................................................ 177
silabs.com | Building a more connected world.
Page xxii of xxii
INS14129-5 Z-Ware Library User Guide 2018-05-02
silabs.com | Building a more connected world.
Page 1 of 184
INS14129-5 Z-Ware Library User Guide 2018-05-02
1 INTRODUCTION
1.1 Purpose
The Z-Ware Library is a Z/IP (Z-Wave for Internet Protocol) Gateway (ZIPGW) client and abstracts
Z-Wave Command Classes (CC) into controllable and monitorable interfaces over a C API (Application
Programming Interface) for easier development and certification of Z-Wave controller applications.
One such Z-Ware Library Client is the Z-Ware Web Server.
The Library can be compiled into Consumer Electronics (CE) or Portal mode. In Portal mode, multiple
ZIPGWs connect to the Library over TCP (Transmission Control Protocol) encrypted with TLS (Transport
Layer Security) where the Library Client is expected to run in the Cloud. In CE mode, the Library
connects to the ZIPGW via UDP (User Datagram Protocol) encrypted with DTLS (Datagram TLS) where
the Library Client is expected to run in the home.
This document describes the Library usage and API with clear differentiation between CE & Portal
modes where applicable.
1.2 Audience and prerequisites
This document is for Z-Wave Partners and assumes they are already comfortable with the Z-Wave
protocol and network installation. As such the document does not go into detail on these matters.
References are also made to the Device and Command Classes and the Z/IP API which are what this API
is built upon.
silabs.com | Building a more connected world.
Page 2 of 184
Node
Power strip
Endpoints
Power point
Power point
Interfaces
Switch
Meter
Switch
Meter
ZIPGW SDK
Mailbox
Security
N/W
Health
Smart Start
2.0x
Unused
S0
N.A.
N.A.
2.1x
Used
S0, S2
N.A.
N.A.
2.8x
Used
S0, S2
Used
Used
INS14129-5 Z-Ware Library User Guide 2018-05-02
2 FEATURES
The API deals with Z-Wave through descriptors for networks, nodes, endpoints and interfaces. A
Z-Wave Home Area Network (HAN) is uniquely identified by a Home ID encapsulated in a network
descriptor.
Nodes are Z-Wave devices in this HAN uniquely identified by a Node ID encapsulated in a node
descriptor. These nodes can be composite devices having multiple endpoints for e.g. a power strip with
multiple separately controllable power points. Each power point may have multiple interfaces allowing
control and/or monitoring, for e.g. a switch to set on and off; and perhaps a meter providing power
consumption information.
Table 1 – Z-Wave example Device and Descriptors
The API views the network through a ZIPGW attached controller which itself is a node in the network.
There can be multiple controllers in a network but only one primary, while the other nodes function as
slave that may be controlled or monitored by these controllers. The primary may serve as an inclusion
server in which case all secondary (i.e. non primary) controllers can also perform network maintenance
such as adding or removing nodes through the primary.
2.1 Role
Z-Ware is a Z-Wave Plus Security Enabled device in the Static PC Controller class, that is mainly used in
the role of a Static Update Controller (SUC) Identity Server (SIS), and the Z-Wave Plus role of a Central
Static Controller.
As a Z/IP secure remote client, it works in conjunction with a ZIPGW. Z-Ware sets itself as the (first)
unsolicited IP address of the ZIPGW that it is connected with. Z-Ware works with different versions of
ZIPGWs using the following features:
Table 2 – ZIPGW Versions vs Features as used by Z-Ware
silabs.com | Building a more connected world.
Page 3 of 184
CC
Ver
CC
Ver
ALARM_SENSOR
1
NW_MGMT_INCLUSION
3
APPLICATION_STATUS
1
NW_MGMT_INSTALLATION_MAINTENANCE*
1
ASSOCIATION
2
NW_MGMT_PROXY
2
ASSOCIATION_CMD_CFG
1
POWERLEVEL
1
ASSOCIATION_GRP_INFO
3
PROTECTION
2
BARRIER_OPERATOR
1
SECURITY
1
BASIC
2
SECURITY 2*
1
BATTERY
1
SENSOR_BINARY
2
CENTRAL_SCENE
3
SENSOR_MULTILEVEL
11
CLIMATE_CONTROL_SCHEDULE
1
SIMPLE_AV_CONTROL
1
CLOCK
1
SUPERVISION
1
INS14129-5 Z-Ware Library User Guide 2018-05-02
2.2 Network Operations
Z-Ware supports Inclusion, Exclusion, Reset (Set Default), Replace/Remove Failed Node, and Send NIF
(Node Information Frame). If it is assigned a primary controller role, it will always upgrade itself to an
SIS unless there is an SUC already present. Hence it cannot initiate controller shift as a primary.
Z-Ware supports Set Learn mode but this can only be performed when Z-Ware is not already in a
network and will typically make Z-Ware an Inclusion or Secondary Controller, in which case, some of its
facilities will not be available. Controller replication (Copy) is achieved through Inclusion and Set Learn
Mode.
Additionally it also supports Update Node and Update Network. Z-Ware discovers a Z-Wave node’s
capabilities during inclusion through a series of comprehensive queries. This process may take some
time, especially for a secure Frequently Listening Routing Slave (FLIRs) device. This operation may be
aborted at any time. Node Update re-queries the information that was obtained during inclusion. This
allows discovering any changes that were not made through this Z-Ware. Network Update requests
topology from an SUC if available, and then performs neighbor update if available or node update to
every node it is aware of.
Z-Ware supports SmartStart which uses a configurable provisioning list of devices to allow Z-Wave
network wide inclusion without having to manually configure a new node into Z-Wave learn mode. The
availability of this feature is dependent on the underlying ZIPGW and protocol.
2.3 Device Control
Z-Ware can be operated in any Z-Wave network with other Z-Wave certified devices from other
manufacturers. All non-battery operated nodes within the network will act as repeaters regardless of
vendor to increase reliability of the network.
Z-Ware is able to control/monitor Z-Wave-certified device of different categories from various vendors
through their CCs. CCs that are automatically handled are not exposed to the user. Z-Ware controls the
following CCs:
Table 3 – Controlled Z-Wave CCs
silabs.com | Building a more connected world.
Page 4 of 184
CONFIGURATION
4
SWITCH_ALL
1
CRC16_ENCAP
1
SWITCH_BINARY
2
DEVICE_RESET_LOCALLY
1
SWITCH_COLOR
3
DOOR_LOCK
3
SWITCH_MULTILEVEL
4
FIRMWARE_UPDATE_MD
5
THERMOSTAT_FAN_MODE
4
INDICATOR
1
THERMOSTAT_FAN_STATE
2
MANUFACTURER_SPECIFIC
2
THERMOSTAT_MODE
3
METER
3
THERMOSTAT_OPERATING_STATE
2
METER_PULSE
1
THERMOSTAT_SETBACK
1
METER_TBL_MONITOR
1
THERMOSTAT_SETPOINT
3
MULTI_CHANNEL
4
USER_CODE
1
MULTI_CHANNEL_ASSOCIATION
3
VERSION
2
MULTI_CMD
1
WAKE_UP
2
NO_OPERATION
1
ZIP 3 NODE_NAMING
1
ZIP_GATEWAY
1
NODE_PROVISIONING*
1
ZIP_ND
1
NOTIFICATION/ALARM
8
ZIP_PORTAL
1
NW_MGMT_BASIC
2
ZWAVEPLUS_INFO
2
CC
Ver
Not
Non-secure
Securely added
Non-Secure
Secure
APPLICATION_STATUS
1 X X X
ASSOCIATION *
2 X X
X ASSOCIATION_GRP_INFO *
3 X X
X
CRC_16_ENCAP
1 X X X
DEVICE_RESET_LOCALLY *
1 X X X
FIRMWARE_UPDATE_MD
5 X
INCLUSION_CONTROLLER **
1 X X X
MANUFACTURER_SPECIFIC
2 X X
MULTI_CMD *
1 X X
X NODE PROVISIONING
1 X
NW_MGMT_BASIC
2 X
NW_MGMT_INCLUSION **
2 X
INS14129-5 Z-Ware Library User Guide 2018-05-02
* Security 2, Network Management Installation Maintenance & Node Provisioning CCs only controlled if
the underlying ZIPGW supports them.
2.4 CC Support
Z-Ware does nothing on receiving Basic CC Set or Get. Z-Ware supports only 1 Association group
supporting 1 node for Lifeline. This node will receive the Device Reset Locally command.
For easier reference during certification the associated ZIPGW supported CCs are tabularized below.
Table 4: ZIPGW SDK 2.8x Supported Z-Wave CCs
added
added
silabs.com | Building a more connected world.
Page 5 of 184
NW_MGMT_INSTALLATION_MAINTENANCE
1 X
NW_MGMT_PROXY
2 X
POWERLEVEL
1 X X
SECURITY
1
X X
SECURITY_2
1 X X X
SUPERVISION
1 X X X
TRANSPORT_SERVICE
2 X X X
VERSION
2 X X
ZWAVEPLUS_INFO
2 X X X
CC
Ver
Not
Non-secure
Securely added
Non-Secure
Secure
APPLICATION_STATUS
1 X X X
ASSOCIATION *
2 X X
X ASSOCIATION_GRP_INFO *
3 X X
X CRC_16_ENCAP
1 X X X
DEVICE_RESET_LOCALLY *
1 X X X
FIRMWARE_UPDATE_MD
5 X
INCLUSION_CONTROLLER **
1 X X X
MANUFACTURER_SPECIFIC
2 X X
MULTI_CMD *
1 X X
X NW_MGMT_BASIC
2 X
NW_MGMT_INCLUSION **
2 X
NW_MGMT_INSTALLATION_MAINTENANCE
1 X
NW_MGMT_PROXY
2 X
POWERLEVEL
1 X
SECURITY
1 X X X
SECURITY_2
1 X X X
SUPERVISION
1 X X X
TRANSPORT_SERVICE
2 X X X
VERSION
2 X X
ZWAVEPLUS_INFO
2 X X X
Ver
Not
Non Secure
Securely Added
Non Secure
Secure
SECURITY
1 X X X
TRANSPORT SERVICE
2 X X X
CRC16
1 X X X
MULTI CMD *
1 X X X
NW MGMT BASIC
2 X
NW MGMT INCLUSION **
2 X
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 5: ZIPGW SDK 2.1x Supported Z-Wave CCs
added
added
CC
Table 6: ZIPGW SDK 2.0x Supported Z-Wave CCs
Added
Added
silabs.com | Building a more connected world.
Page 6 of 184
Ver
Not
Non Secure
Securely Added
Non Secure
Secure
NW MGMT PROXY
2 X
NW MGMT INSTALLATION MAINTENANCE
1 X
DEVICE RESET LOCALLY *
1 X X X
ZIP 3 X ZIP PORTAL
1 X
ZIP GATEWAY
1 X
ZIP NAMING
1 X
FIRMWARE UPDATE MD
5 X
MAILBOX
1 X
POWER LEVEL
1 X
APPLICATION STATUS
1 X X X
ZWAVEPLUS INFO
2 X X X
MANUFACTURER SPECIFIC
2 X
VERSION
2 X
ASSOCIATION *
2 X X X
ASSOCIATION GRP INFO *
3 X X X
INS14129-5 Z-Ware Library User Guide 2018-05-02
CC
Added
Added
* ASSOCIATION, ASSOCIATION_GRP_INFO, MULTI_CMD & DEVICE_RESET_LOCALLY CCs are added by Z-
Ware to the ZIPGW NIF
** INCLUSION_CONTROLLER & NW_MGMT_INCLUSION CCs are only present if the ZIPGW is an
inclusion controller.
2.5 Network Initialization
The following steps are carried out during network initialization:
1. Get ZIPGW’s Z-Wave Home ID, Node ID & Home Area Network (HAN) IP address.
2. Get ZIPGW attached controller’s cached node information.
3. Get CC versions present in the ZIPGW cached node information to create corresponding Z-Ware
interfaces.
4. Get ZIPGW’s hardware and firmware versions if VERSION CC is version 2 or higher.
5. Get ZIPGW’s manufacturer, product type and product id if MANUFACTURER_SPECIFIC CC presents.
6. Get node list of the HAN.
7. Turn on mailbox for ZIPGW SDK v2.1x and above. This will enable multi-client support and receive
wake up notification from device through mailbox ACK message.
8. Get ZIPGW dynamic DSK key for adding new node.
9. Set supported CCs in the ZIPGW attached controller’s NIF
10. For Portal version, set unsolicited destination address. For CE version, get unsolicited destination
address and if its IPv6 address is all zeroes, set it to the Z/IP client IPv6 address.
11. Resolve all the nodes in node list into corresponding HAN IPv6 addresses.
12. Perform Node Update (see 2.6) through HAN network for nodes that are not loaded with detailed
node information from persistent storage.
silabs.com | Building a more connected world.
Page 7 of 184
INS14129-5 Z-Ware Library User Guide 2018-05-02
2.6 Node Update
The following steps are carried out to acquire detailed node information based on the CCs present at
node and endpoint levels:
1. Get cached node information of the node of interest from the ZIPGW.
2. Assign the ZIPGW attached controller’s Z-Wave Return Route to the node.
3. Get CC versions of each CC listed in the node information.
4. Get library, protocol and application versions.
5. Get node’s hardware and firmware versions if Version CC version is 2 or higher.
6. Get MANUFACTURER_SPECIFIC CC Manufacturer ID, Product Type and Product ID. Based on these,
get device category from the device setting database. Get Device Serial Number if supported.
7. If the node has just been added into the network, set the WAKEUP CC notification receiving Node ID
to SIS with/without changing the wakeup interval. The wakeup interval will be changed if global
setting for wakeup interval is non-zero in device database.
8. For each endpoint in the node :a) Get security supported CCs at the endpoint if the node is included securely
b) Get version of CCs at the endpoint
c) If the node has just been added into the network, set device specific configuration parameters
based on Device Database
d) Get CONFIGURATION CC parameter number property if CC version is 3 or higher
e) Get ASSOCIATION CC’s maximum supported group. If the node has just been added into the
network, and group 1 is “Lifeline”, set SIS node id into group 1
f) Get Central Scene CC number of supported scenes. . If the node has just been added into the
network, and Central Scene CC version is 3 and greater, then set it to slow refresh.
g) Get Z-Wave Plus Information
h) Get Multilevel Sensor CC supported types, units and current value
i) Get ASSOCIATION GROUP INFORMATION CC details
j) Get Thermostat Fan Operating Mode CC supported modes, Thermostat Mode CC supported
and current mode, Thermostat Setpoint CC supported and current type and also temperature
range, Thermostat Operating State CC current state
k) Get Multilevel Switch CC supported types and current value
l) Get Simple AV CC supported controls
m) Get Alarm/Notification CC supported types & events
n) Get Protection CC supported states
o) Get User Code CC maximum supported codes
p) Get Meter CC capabilities & descriptor
q) Get Binary Sensor CC supported types & current value
r) Get Door Lock CC current state
s) Get Alarm Sensor CC supported types & current value
t) Get Barrier Operator CC current state
u) Get Color Switch CC supported components & current values
v) Get Binary Switch CC current state
w) Get Battery CC current level
x) Get Node Naming CC current name and location
silabs.com | Building a more connected world.
Page 8 of 184
CC
Ver
CC
Ver
VERSION
2
MANUFACTURER_SPECIFIC
2
WAKE_UP
2
CC
Ver
CC
Ver
ASSOCIATION
2
SENSOR_BINARY
2
ASSOCIATION_GRP_INFO
3
SENSOR_MULTILEVEL
11
BARRIER_OPERATOR
1
SIMPLE_AV_CONTROL
1
BATTERY
1
SWITCH_BINARY
1
CENTRAL_SCENE
3
SWITCH_COLOR
3
CLOCK
1
SWITCH_MULTILEVEL
3
CONFIGURATION
4
THERMOSTAT_FAN_MODE
1
DOOR_LOCK
1
THERMOSTAT_FAN_STATE
2
METER
3
THERMOSTAT_MODE
3
METER_TBL_MONITOR
1
THERMOSTAT_OPERATING_STATE
2
MULTI_CHANNEL_ASSOCIATION
3
THERMOSTAT_SETPOINT
3
NODE_NAMING
1
USER_CODE
1
NOTIFICATION/ALARM
7
VERSION
2
PROTECTION
2
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 7 – Node Update get/set CCs
Table 8 – Node Update endpoint get/set CCs
2.7 Network Update
The following steps are carried out to update the network:
1. Repeat steps 1 to 4 of Network Initialization (see 2.5 Network Initialization).
2. Request network update by using the command:
NETWORK_MANAGEMENT_BASIC CC-> NETWORK_UPDATE_REQUEST
3. Get node list of the HAN.
4. Resolve all the nodes in node list into corresponding HAN IPv6 addresses.
5. Request node neighbor update for each of the node in the node list. Repeat for up to 3
iterations if the request node neighbor update failed for some nodes that may be out-of-range.
6. Perform Node Update for each node in network (See 2.6 Node Update).
2.8 Background Polling
Z-Ware Library performs automatic background polling to cache device supported interface details (e.g.
supported sensor types and units) and device values (e.g. sensor readings for each supported type). For
always-on devices, polling is carried out for all relevant interfaces in a device followed by an interval of
10 seconds before the next device is polled. For FLIRS (Frequently Listening Routing Slave) devices,
polling is carried out only every 12 hours per device so as not to run the device’s batteries out. For
sleeping devices, polling is carried out whenever they wake up. As sleeping devices will go to sleep
mode when they don’t receive any Z-Wave messages, this type of polling has higher priority than the
silabs.com | Building a more connected world.
Page 9 of 184
INS14129-5 Z-Ware Library User Guide 2018-05-02
other two types of polling. The polling sequence of CCs are the same as those listed for each endpoint
in Section 2.6 Node Update.
2.9 Post-Set Polling
Some devices take time to reach their target settings especially mechanical devices. Z-Ware Library
performs post-set polling for door lock, multi-level switch motor and barrier operator interfaces. For
door locks, the polling intervals are 1, 2, 3 seconds; whereas for multi-level switch, the intervals are 1, 2,
3, 4 seconds before timeout occurs. For Barrier Operator CC, the intervals are 1 to 7 seconds
incrementally. If the endpoint supports the Supervision CC, then polling is not performed and
notification is expected from the device on completion. This allows the client to be informed if/when
the device has reached its target state.
2.10 Command Class Configuration
Some library clients may want to only implement control for selected CCs of those offered. However
this leads to Z-Wave certification form failures as the library performs background polling and
information caching for CCs not listed in the form. A CC configuration option file “cmd_class.cfg” list all
CCs offered allowing the client developer to comment out undesired CCs.
silabs.com | Building a more connected world.
Page 10 of 184
Action
API
Initiate network scanning for ZIPGW IP addresses. For each valid
zwnet_gw_discvr_start
To stop the network scanning and free the resources used in
zwnet_gw_discvr_stop
Action
API
Initialize API and get controller node ID, home ID, HAN address
and node list
zwnet_init
zwnet_notify_fn
INS14129-5 Z-Ware Library User Guide 2018-05-02
3 TYPICAL USAGE
3.1 Network Initialization
The first thing a client needs to do is to acquire the ZIPGW IP address either by means of reading from
configuration file or scanning the IP network using ZIPGW Discovery protocol. There are APIs to help
the client to do the network scanning for ZIPGW IP addresses.
Table 9 – Network scanning APIs
network interface IP address, a callback will report the result of
zwnet_gw_discvr_cb
each scanning.
scanning.
The client initializes itself by querying the ZIPGW attached controller node ID, home ID, HAN address
and the node list of all the nodes in the HAN.
After that it loads any persistent network information from any sessions before. This includes
information on the nodes, endpoints and interfaces along with their versions. Home ID is used as a
unique identifier into the persistent storage database. This is analogous to the node information that is
stored on non-volatile memory (NVM) of the controller.
Table 10 – Network initialization API
Sometimes a controller that was configured on a different host is introduced to ZIPGW. Here the
database on the host and the ZIPGW attached controller node information in NVM would not match.
This requires migration of the persistent database, a facility provided by the client. If this migration is
not performed, the information stored in the controller is used to request further meta-information
and can cause the load operation to be longer, depending on the number of nodes discovered and their
geometries and sleeping nodes may not be properly configured.
3.2 Network creation and tear down
Typically the user creates a network minimally with 2 devices, one of which is a controller, while the
other can be any type of node. The user initiates the node for inclusion and uses the controller to add
the device into its network and initiate.
Now the node can be controlled through the controller, which becomes the primary. Similarly more
nodes can be added. Removing is identical except that the API parameter is different. During adding,
silabs.com | Building a more connected world.
Page 11 of 184
Action
Controller
Node
Add node
zwnet_add(true)
zwnet_initiate
Remove node
zwnet_add(false)
zwnet_initiate
Action
API
Initialize portal API and listen for ZIPGW connections.
zwportal_init
zwportal_cb
Action
API
Close listening socket for ZIPGW connections.
zwportal_shutdown
Shut down existing TLS connections and free resources
zwportal_exit
INS14129-5 Z-Ware Library User Guide 2018-05-02
the node’s endpoints and interfaces are enumerated and populated as descriptors for control. Security
facilities are handled transparently with indication to the client.
The zwnet_notify_fn callback is used to notify the client of the operation’s progress while
zwnet_node_fn callback is called in between to provide a handle to the node.
Table 11 – Network creation and tear down APIs
zwnet_node_fn
zwnet_
zwnet_notify_fn(progress)
notify_fn(progress)
zwnet_node_fn
zwnet_
zwnet_notify_fn(progress)
notify_fn(progress)
3.3 Portal Usage
3.3.1 Portal Initialization
The first thing a portal application needs to do is to initialize the portal to listen for ZIPGW connections
at well known TCP port 44123. The connections from the ZIPGWs are secured using Transport Layer
Security protocol (TLS).
Table 12 – Portal initialization API
The callback function zwportal_cb will be invoked when a ZIPGW connection has successfully
completed the TLS handshake and the portal-gateway proprietary handshaking.
3.3.2 Portal Shutdown
To shut down the portal, there are two steps to follow. Firstly, the listening socket at the well know TCP
port 44123 needs to be closed to prevent any new gateway connections. Secondly, the existing TLS
connections need to be shut down gracefully. There are two APIs for these purposes as listed in the
table below.
Table 13 – Portal shut down APIs
silabs.com | Building a more connected world.
Page 12 of 184
Action
API
Add a client profile to the portal internal list
zwportal_clnt_add
Remove a client profile from the portal internal list
zwportal_clnt_rm
Find a client profile in the portal internal list based on gateway id
zwportal_clnt_find
Free client profiles list
zwportal_clnt_list_free
Get all the client profiles in the portal internal list
zwportal_clnt_list_get
Action
API
Get handle to node
zwnet_get_node, zwnode_get_next or through zwnet_node_fn
Get handle to endpoint
zwnode_get_ep, zwep_get_next
Get handle to interface
zwep_get_if, zwif_get_next
Set up report callback once
zwif_level_rpt_set (zwrep_level_fn)
Monitor the interface
zwif_level_get etc depending on type of interface
Control the interface
zwif_level_set etc depending on type of interface
zwnet_appl_fn
If (!zwnode_get_ep(node, &ep))
do
INS14129-5 Z-Ware Library User Guide 2018-05-02
3.3.3 Portal Client Profile Management
To help managing ZIPGW profiles, there are APIs for add, remove, find and list all client profiles as listed
in the table below.
Table 14 – Portal client profile management APIs
3.4 Interface monitor/control
Once a node is added, the client traverses its structure to arrive at the interface that it wants to monitor
or/and control.
As monitoring requires a callback, it is the client’s responsibility to set up the callback and implement a
timeout in case the callback never happens.
In order to reduce unnecessary callbacks to the client application, all live reports from nodes are
compared with the cached value (if available) and callback is executed only if they are different.
However, in all cases, the timestamps on the cached values are updated.
Table 15 – Interface Control APIs
zwnet_appl_fn
zwnet_appl_fn
zwrep_level_fn
Typically the client code would map the interface handle to the UI element that the user can
manipulate. So this enumeration happens mostly when a node is newly added and the UI elements
need to be populated.
{
silabs.com | Building a more connected world.
Page 13 of 184
{
Action
API
Get node/endpoint type
See Table 147 – zwnoded_t structure and Table 162 –
Set/get name/location
See Table 147 – zwnoded_t structure and 4.6.5
INS14129-5 Z-Ware Library User Guide 2018-05-02
if (!zwep_get_if(ep, &ifd))
{
do
{
switch (ifd->cls)
{
case COMMAND_CLASS_SWITCH_MULTILEVEL:
/* solicit current level */
zwif_level_get(ifd);
/* draw UI depending on capabilities */
if (ifd->ver == 3)
{
}
:
break;
:
}
}
while (!zwif_get_next(ifd, &ifd));
}
}
while (!zwep_get_next(ep, &ep));
}
3.5 Node identification
Nodes and endpoints contain information on their network and functional roles respectively i.e.
whether they are controllers or slaves; and whether they are binary switches etc. This allows
classification of nodes by the client. Further, all endpoints (including the controller’s endpoint) in a
node have name and location fields for easier identification by the user, rather than using the unique
Node ID.
Table 16 – Node identification APIs
zwepd_t structure
zwep_nameloc_set
silabs.com | Building a more connected world.
Page 14 of 184
Action
API
Get #groups in device
zwif_group_sup_get (if, zwif_group_sup_fn)
zwif_group_sup_fn
Get group information
zwif_group_get (if, group#)
Modify devices in group
zwif_group_add/del
Action
API
Disable command queuing
zwnode_cmd_q_ena_set(node, 0)
Perform configuration
eg. zwif_wakeup_set
Re-enable command queuing
zwnode_cmd_q_ena_set(node, 1)
Check command queue
zwnode_cmd_q_ena_get(node)
Get command queue items
zwnode_cmd_q_get(node)
Flush command queue
zwnode_cmd_q_cancel(node)
INS14129-5 Z-Ware Library User Guide 2018-05-02
3.6 Grouping
Devices can be grouped for device specific purposes e.g. a motion sensor could be made to turn on
multiple lights and an alarm. In this case, it could have 2 groups; 1 for the lights and dimmers and 1 for
the alarm. The user can add preferred lights to the light group and a chosen alarm to the alarm group.
The user may also be able to adjust the brightness to which a dimmer is set.
Grouping is achieved by the group interface.
Table 17 – Grouping APIs
zwnet_appl_fn
zwnet_appl_fn
zwif_group_fn
zwnet_appl_fn
3.7 Sleeping nodes
The API does automatic command queuing for nodes that are capable of sleeping. In this case the node
control/monitor functions return queued status. Commands can be removed from the queue as well.
It is important to configure the slave such that wake up notifications are sent to this controller, through
the wake up interface. Otherwise commands sent to this slave will cause the node specific command
queue to be stuck until user intervenes. Command queuing must be disabled after adding a slave that
is sleep capable. After completing the configuration of the slave, command queuing should be reenabled.
Table 18 – Command Queuing APIs
3.8 Firmware update
In order to bring the gateway up to date with the latest features or bug fixes, there are firmware update
APIs to facilitate the updating.
silabs.com | Building a more connected world.
Page 15 of 184
Action
API
Get firmwares information
zwif_fw_info_get
Requests firmware update operation to be carried
zwif_fw_updt_req
Action
API
The polling variant of APIs for getting report through
zwif_xxx_poll
Remove a polling request
zwnet_poll_rm
Remove multiple polling requests
zwnet_poll_rm_mul
Action
API
Load and store device specific configurations
zwdev_cfg_load
Free device specific configuration records
zwdev_cfg_free
Search for a match in device specific configuration records
zwdev_cfg_find
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 19 – Firmware update APIs
out
3.9 Polling facility
In order to help user application to poll the status of a device which does not support sending of
unsolicited report, there are polling APIs to help execute the polling that is conform to Z-Wave
recommendation.
Table 20 – Polling facility APIs
the polling facility
3.10 Device specific configuration and information database
To address earlier version of Z-Wave CCs which do not provide commands to retrieve supported device
types or properties, a database is used to fill in the necessary information based on manufacturers’
published datasheets. In addition, a device can be configured using the settings in the database once
the device is included/added to the Z-Wave network. In the recent releases, the facility has been
expanded to make devices that are not fully compliant with Z-Wave standard to work under the control
of Z-ware API. The database adopts the standard JSON format to enable easy editing by user. The
following APIs facilitate the loading and unloading (freeing) the database and searching for a specific
device configuration and information.
Table 21 – Device specific configuration and information database APIs
3.11 Network and client preference storage
To facilitate storing and retrieving of network and client specific preferences or configurations (which
are opaque to the Z-ware library), there are 4 APIs available. Each network is restricted to one storage
while there could be several client storages per network.
Table 22 – Network and client preference storage APIs
silabs.com | Building a more connected world.
Page 16 of 184
Action
API
Store network preference into persistent storage
zwnet_pref_set
Retrieve network preference from persistent storage
zwnet_pref_get
Store client preference into persistent storage
zwnet_client_pref_set
Retrieve client preference from persistent storage
zwnet_client_pref_get
Action
API
Accept or reject newly added node into security 2 mode
zwnet_add_sec2_accept
Grant keys to the newly added node in security 2 mode
zwnet_add_sec2_grant_key
Get ZIPGW Device Specific Key (DSK) in security 2 mode.
zwnet_sec2_get_dsk
INS14129-5 Z-Ware Library User Guide 2018-05-02
3.12 Security 2 (S2)
The library has been supporting legacy security internally without any user interactions. However, since
the introduction of Security 2 (S2) in Z-Wave specification, user has to be aware and to interact within
the S2 framework when adding and replacing failed nodes. There are a few APIs which have to be
called during the above-mentioned operations when adding or replacing an S2 device securely.
Table 23 – Security 2 APIs
This is useful when ZIPGW wants to join another S2
capable ZIPGW’s network.
The typical interactions between the user application and Z-ware library through API calls and callbacks
are shown in the following figure.
silabs.com | Building a more connected world.
Page 17 of 184
Action
API
Add a provisioning list entry
zwnet_pl_add
Get a provisioning list entry information through
zwnet_pl_get
Delete a provisioning list entry
zwnet_pl_del
Get all provisioning list entries through callback
zwnet_pl_list_get
Delete all provisioning list entries
zwnet_pl_list_del
User Application Z-ware Library
zwnet_add(net, add=1, sec2_param, incl_on_behalf=0)
zwnet_add_sec2_grant_key(net, granted_keys, grant_csa=0)
add_node_sec2_fn(usr_param, cb_param)
add_node_sec2_fn(usr_param, cb_param)
zwnet_add_sec2_accept(net, accept=1, dsk)
INS14129-5 Z-Ware Library User Guide 2018-05-02
where cb_param->cb_type == S2_CB_TYPE_REQ_KEY
where cb_param->cb_type == S2_CB_TYPE_DSK
3.13 SmartStart
As Z-Wave SmartStart inclusion doesn’t require user interaction, APIs are provided to help manage the
provisioning list stored at the ZIPGW.
Table 24 – Smart Start provisioning list management APIs
callback
3.14 Network Health Check
Network health status is provided via an API through the NW_MGMT_IMA CC which provides statistics
for packet error rate (PER), number of route changes (RC), number of neighbors (NB), maximum
reduction in transmit power where the last working route still works (LWRdb) and the difference
between last working route RSSI and background RSSI (LWR_RSSI) for determination of Network Health
silabs.com | Building a more connected world.
Page 18 of 184
Action
API
Start network health check on all but sleeping nodes
zwnet_health_chk
INS14129-5 Z-Ware Library User Guide 2018-05-02
Value (NHV) of each node. The NHV is then translated to Network Health Status (NHS) that is
presented to user by using a simple color code grading system. Users can identify devices with poor
network connectivity easily and subsequently take necessary action to remedy the situation such as
adding a repeater in between the devices with poor network connectivity.
Table 25 – Network health check API
silabs.com | Building a more connected world.
Page 19 of 184
Error code
Description
Value
ZW_ERR_CACHE_AVAIL *
The data is available in the cache (no live get from the
2
ZW_ERR_QUEUED *
The command is queued (no transmission status
1
ZW_ERR_NONE *
Operation succeeded
0
ZW_ERR_FAILED
Operation failed
-1
ZW_ERR_WRONG_IF
Wrong interface
-10
ZW_ERR_NO_RESP
No response from controller
-11
ZW_ERR_MEMORY
Out of memory
-12
ZW_ERR_NODE_NOT_FOUND
Node not found
-13
ZW_ERR_CLASS_NOT_FOUND
CC not found
-14
ZW_ERR_INTF_NOT_FOUND
Interface to a class not found
-15
ZW_ERR_INTF_NO_REP_HDLR
Interface report handler not found
-16
ZW_ERR_LAST_OP_NOT_DONE
Last operation uncompleted yet, try again
-17
ZW_ERR_NOT_IN_LIST
Node not in protocol layer failed node ID list
-18
ZW_ERR_OP_FAILED
The requested operation failed
-19
ZW_ERR_EP_NOT_FOUND
Endpoint not found
-20
ZW_ERR_RPT_NOT_FOUND
The report command of an interface not found
-21
ZW_ERR_NET_NOT_FOUND
Network not found
-22
ZW_ERR_CMD_VERSION
Incorrect CC version
-23
ZW_ERR_PENDING
Operation pending, it cannot be canceled now
-24
ZW_ERR_VALUE
The value is invalid
-25
ZW_ERR_QUEUE_FULL
The queue is full
-26
ZW_ERR_UNSUPPORTED
The requested function is unsupported for this node
-27
ZW_ERR_FILE_OPEN
Open file error
-28
ZW_ERR_FILE_WRITE
Write file error
-29
ZW_ERR_FILE_EOF
The end-of-file was reached
-30
ZW_ERR_FILE
File is corrupted
-31
ZW_ERR_FILE_HOME_ID
File home id doesn't match
-32
INS14129-5 Z-Ware Library User Guide 2018-05-02
4 API
The API is partitioned into the Portal, Network, Node, Endpoint, Interface and various specific Interface
APIs.
4.1 Error Codes
Error codes used in APIs, ZW_ERR_XXX are listed in the table below. They are defined in the header file
“zip_api.h”. They can also be found in Doxygen documentation under the “Modules->Network APIs”
Zw_error_codes section. Besides, occasionally the error code returned may be from low-level library
function call. These error codes are listed in the table “Low-level Library Error Codes”.
Table 26 – Error Codes, ZW_ERR_XXX
target device)
callback)
silabs.com | Building a more connected world.
Page 20 of 184
ZW_ERR_EXPIRED
Expired
-33
ZW_ERR_NO_RES
No resource for mutex, semaphore, timer, etc
-34
ZW_ERR_EVENT
Event is not processed
-35
ZW_ERR_TOO_LARGE
Data size is too large
-36
ZW_ERR_TOO_SMALL
Data size is too small
-37
ZW_ERR_TIMEOUT
Timeout
-38
ZW_ERR_TRANSMIT
Transmission failed
-39
ZW_ERR_NONCE_NOT_FOUND
Security nonce not found
-40
ZW_ERR_AUTH
Authentication error
-41
ZW_ERR_SEQ_NUMBER
Incorrect sequence number
-42
ZW_ERR_BUSY
Busy, try again later
-43
ZW_ERR_SEC_SCHEME
Security scheme unsupported
-44
ZW_ERR_TRANSPORT_INI
Initialization error on transport layer
-45
ZW_ERR_FRAME_INI
Initialization error on frame layer
-46
ZW_ERR_SESSION_INI
Initialization error on session layer
-47
ZW_ERR_APPL_INI
Initialization error on application layer
-48
ZW_ERR_UNEXPECTED
The error was unexpected under normal circumstances
-49
ZW_ERR_NETWORK_IF
Network interface not configured properly
-50
ZW_ERR_IP_ADDR
The IP address is invalid
-51
ZW_ERR_VERSION
Wrong version number
-52
ZW_ERR_INTF_NO_DATA
Interface data is missing
-53
ZW_ERR_FILE_READ
Read file error
-54
ZW_ERR_PARSE_FILE
Parsing file failed
-55
ZW_ERR_MISSING_ENTRY
Missing mandatory entry
-56
ZW_ERR_DEVCFG_NOT_FOUND
Device specific configuration record not found
-57
ZW_ERR_DISALLOWED
The operation is disallowed under certain
ZW_ERR_PSK_TOO_SHORT
DTLS pre-shared key length is too short
-59
ZW_ERR_NO_CACHE_AVAIL
The data is unavailable in the cache
-60
ZW_ERR_NOT_APPLICABLE
Not applicable and should be skipped or ignored
-61
ZW_ERR_SHUTDOWN
The system is shutting down
-62
ZW_ERR_POST_SET_POLL
Post-set polling error
-63
ZW_ERR_ORDER
Out of order
-64
ZW_ERR_CMD_UNSUPP_TGT
Command sent by the association group is unsupported
Error code
Description
Value
ZWHCI_ERROR_MEMORY
Out of memory
-100
ZWHCI_ERROR_RESOURCE
Out of resource
-101
TRANSPORT_ERROR_SIGNALING
Could not signal write thread to perform actual write
-102
INS14129-5 Z-Ware Library User Guide 2018-05-02
circumstances -58
at target node or endpoint -65
Note: Error code with (*) that has a value equal or greater than zero is not an error. In fact it is an
indication of success with more detailed description.
Table 27 – Low-level Library Error Codes
silabs.com | Building a more connected world.
Page 21 of 184
FRAME_ERROR_MULTIPLE_WRITE
Write while the previous write in progress is not
-103
FRAME_ERROR_SEND_TIMER
Send timer not functioning
-104
SESSION_ERROR_PREVIOUS_
COMMAND_UNCOMPLETED
Previous command uncompleted, retry later
-105
SESSION_ERROR_DEST_BUSY
The message has not timed out yet.The destination
-106
SESSION_ERROR_UNREACHABLE
Frame failed to reach destination host
-107
SESSION_ERROR_SND_FRM_TMOUT
Send frame timeout due to no ACK received
-108
SESSION_ERROR_SYSTEM
System error, the program should exit
-109
SESSION_ERROR_INVALID_RESP
The response command id doesn't match with the
sent command id
-110
SESSION_ERROR_SEND_BUSY
Send error at lower layer due to controller busy
-111
APPL_TX_STATUS_TIMEOUT
There is no transmit status callback from lower layer
-112
APPL_OPER_ALREADY_ACTIVE
The requested operation is already active
-113
APPL_OPER_NOT_STARTED
The requested operation fails to start
-114
APPL_ERROR_WAIT_CB
Waiting for transmit complete callback function, retry
-115
APPL_INVALID_ADDR
Invalid IPv6 address
-116
APPL_INVALID_NODE_ID
Invalid node id
-117
APPL_ERROR_RSLV_NODE_ID
Couldn't resolve node id to IP address
-118
ZWHCI_ERROR_TOO_LARGE
The value supplied is too large
-119
ZWHCI_ERROR_WRITE
Write failed
-120
ZWHCI_ERROR_READ
Read failed
-121
ZWHCI_ERROR_TIMEOUT
Time out
-122
ZWHCI_ERROR_VERIFY
Verification failed
-123
ZWHCI_ERROR_SHUTDOWN
System is shutting down
-124
Attribute
Type
I/O
Description
init_prm
zwportal_init_t
I
Portal initialization parameters
return
void *
O
Context on success, NULL on failure. Caller is required to call
if it is not null.
INS14129-5 Z-Ware Library User Guide 2018-05-02
allowed
host may have a long response time
later
4.2 Portal API
4.2.1 zwportal_init
This call initializes the portal to listen for ZIPGW connections at well know TCP port 44123. The callback
function zwportal_cb will be invoked when a ZIPGW connection has successfully completed the TLS
handshake and the portal-gateway proprietary handshaking. The portal application may use the
callback parameters to create an instance of Z/IP host controller using zwnet_init API.
Table 28 – zwportal_init Parameters
*
zwportal_shutdown() and zwportal_exit() with the returned context
silabs.com | Building a more connected world.
Page 22 of 184
Attribute
Type
I/O
Description
clnt_prof
clnt_prof_t*
I
An array of client profiles
prof_cnt
int I Number of client profiles in clnt_prof
zwportal_cb
zwportal_cb_t
I
Callback function when a new gateway has completed the TLS
usr_param
void *
I
User defined parameter used in callback function
ca_file
char *
I
File path to CA certificate that is used to sign ZIPGW public
ssl_file
char *
I
File path to SSL certificate (portal public certificate)
pvt_key_file
char *
I
File path to portal private key
svr_port
uint16_t
I
Portal listening port
Attribute
Type
I/O
Description
clnt_id
uint8_t[8]
I
Client's ID (currently using MAC address formatted as an
clnt_pin
uint8_t[8]
I
Client's PIN (password)
clnt_ipv6_addr
uint8_t[16]
I
Client's IPv6 address. May be all-zeroes IPv6 address
clnt_dflt_gw
uint8_t[16]
I
Client's default IPv6 gateway
clnt_pan_prefix
uint8_t[16]
I
Client's PAN interface prefix with /64 prefix length. May be
clnt_unsolicited_dst
uint8_t[16]
I
Client's forwarding destination address for unsolicited
svr_ipv6_addr
uint8_t[16]
I
Server's IPv6 address
clnt_unsolicited_port
uint16_t
I
Client's forwarding destination port for unsolicited
clnt_ipv6_prefix
uint8_t
I
Client's IPv6 address prefix length
svr_ipv6_prefix
uint8_t
I
Server's IPv6 address prefix length
Attribute
Type
I/O
Description
clnt_fd
int I Client socket file descriptor
clnt_ssl
void *
I
Client SSL object pointer
clnt_prof
clnt_prof_t*
I
Client profile used
usr_param
void *
I
User defined parameter passed when calling zwportal_init()
return
int O Non-zero if the new client connection is accepted; zero if it is
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 29 – zwportal_init_t structure
handshake and the portal-gateway proprietary handshaking
certificate
Table 30 – clnt_prof_t structure
IEEE EUI-64 identifier)
all-zeroes IPv6 address
message
message. Should be 4123
Table 31 – zwportal_cb_t Parameters
rejected.
silabs.com | Building a more connected world.
Page 23 of 184
Attribute
Type
I/O
Description
ctx
void *
I
The context returned from the call to zwportal_init()
return
int O Zero on success, non-zero on failure.
Attribute
Type
I/O
Description
ctx
void *
I
The context returned from the call to zwportal_init ()
return
int O Zero on success, non-zero on failure.
Attribute
Type
I/O
Description
sfd
int I Client socket file descriptor
ssl
void *
I
Client SSL object pointer
Attribute
Type
I/O
Description
ctx
void *
I
The context returned from the call to zwportal_init ()
clnt_prof
clnt_prof_t *
I
Client profile
return
int O Non-zero on success, zero on failure.
Attribute
Type
I/O
Description
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.2.2 zwportal_shutdown
This call closes listening socket at the well know TCP port 44123 to prevent any new gateway
connections. Take note that this function should not be called in the callback function which was passed
to the zwportal_init function.
Table 32 – zwportal_shutdown Parameters
4.2.3 zwportal_exit
This call shuts down existing TLS connections and free the resources used. Take note that this function
should not be called in the callback function which was passed to the zwportal_init function.
Table 33 – zwportal_exit Parameters
4.2.4 zwportal_clnt_conn_close
This call closes client's socket and SSL connection.
Table 34 – zwportal_clnt_conn_close Parameters
4.2.5 zwportal_clnt_add
Add a client profile to the portal internal list, overwriting old entry with the same gateway.
Table 35 – zwportal_clnt_add Parameters
4.2.6 zwportal_clnt_rm
Remove a client profile from the portal internal list.
Table 36 – zwportal_clnt_rm Parameters
silabs.com | Building a more connected world.
Page 24 of 184
ctx
void *
I
The context returned from the call to zwportal_init ()
gw_id
uint8_t*
I
Gateway id
return
int O Non-zero on success, zero on failure.
Attribute
Type
I/O
Description
ctx
void *
I
The context returned from the call to zwportal_init ()
clnt_prof
clnt_prof_t *
I/O
Client profile buffer with the gateway id set as input key to be
return
int O Non-zero on success, zero on failure.
Attribute
Type
I/O
Description
lst_hd
clnt_prof_lst *
I
List head of the client profiles list
Attribute
Type
I/O
Description
next
clnt_prof_lst *
I
Next portal client profile in the linked-list
clnt_prof
clnt_prof_t
I
Client profile
Attribute
Type
I/O
Description
ctx
void *
I
The context returned from the call to zwportal_init ()
lst_hd
clnt_prof_lst **
O
List head of the client profiles list
return
int O Number of client profiles in the list; negative value on failure.
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.2.7 zwportal_clnt_find
Find a client profile in the portal internal list based on gateway id.
Table 37 – zwportal_clnt_find Parameters
searched. On success, this buffer will be returned with found
entry.
4.2.8 zwportal_clnt_list_free
Free client profiles list.
Table 38 – zwportal_clnt_list_free Parameters
Table 39 – clnt_prof_lst structure
4.2.9 zwportal_clnt_list_get
Get all the client profiles in the portal internal list.
Table 40 – zwportal_clnt_list_get Parameters
Caller must call zwportal_clnt_list_free() to free the linked-list if
return value is greater than zero
silabs.com | Building a more connected world.
Page 25 of 184
Attribute
Type
I/O
Description
cfg_file
const char *
I
Device specific configurations file in JSON format
records
dev_rec_t **
O
Device specific configuration records sorted according to
record_cnt
uint16_t *
O
Number of device specific configuration records stored in
global_sett
dev_global_sett_t**
O
Device global settings
global_sett_cnt
uint16_t *
O
Number of entries in device global settings
err_loc
dev_cfg_error_t *
O
Parse error location for "device_records" in JSON file
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
vid
uint32_t
O
Vendor or Manufacturer ID
ptype
uint32_t
O
Product Type ID
pid
uint32_t
O
Product ID
category
uint8_t
O
Device category, DEV_XXX
ep_rec
ep_rec_t *
O
Endpoint records
Device Category
Description
#
DEV_CATEGORY_UNKNOWN
Unknown or un-categorized device
0
DEV_SENSOR_ALARM
Sensor alarm
1
DEV_ON_OFF_SWITCH
On/off switch
2
DEV_POWER_STRIP
Power strip
3
DEV_SIREN
Siren
4
DEV_VALVE
Valve
5
DEV_SIMPLE_DISPLAY
Simple display
6
DEV_DOORLOCK_KEYPAD
Door lock with keypad
7
DEV_SUB_ENERGY_METER
Sub energy meter
8
DEV_ADV_WHL_HOME_ENER_METER
Advanced whole home energy meter
9
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.3 Device Database API
These APIs load the device database.
4.3.1 zwdev_cfg_load
Load and store device specific configurations.
Table 41 – zwdev_cfg_load Parameters
manufacturer id, product type id and product id
"records"
Note: Caller must free the memory allocated to "records"
using zwdev_cfg_free() and memory allocated to
"global_sett" using zwdev_global_sett_free() if return value
is ZW_ERR_NONE
Table 42 – dev_rec_t structure
Table 43 – DEV_XXX meaning & values
silabs.com | Building a more connected world.
Page 26 of 184
DEV_SIM_WHL_HOME_ENER_METER
Simple whole home energy meter
10
DEV_SENSOR
Sensor
11
DEV_LIGHT_DIMMER
Light dimmer switch
12
DEV_WIN_COVERING_NO_POS
Window covering no position/endpoint
13
DEV_WIN_COVERING_EP
Window covering end point aware
14
DEV_WIN_COVERING_POS_EP
Window covering position/end point
15
DEV_FAN_SWITCH
Fan switch
16
DEV_RMT_CTL_MULTIPURPOSE
Remote control - multipurpose
17
DEV_RMT_CTL_AV
Remote control - AV
18
DEV_RMT_CTL_SIMPLE
Remote control - simple
19
DEV_UNRECOG_GATEWAY
Gateway (unrecognized by client)
20
DEV_CENTRAL_CTLR
Central controller
21
DEV_SET_TOP_BOX
Set top box
22
DEV_TV
TV
23
DEV_SUB_SYS_CTLR
Sub system controller
24
DEV_GATEWAY
Gateway
25
DEV_THERMOSTAT_HVAC
Thermostat - HVAC
26
DEV_THERMOSTAT_SETBACK
Thermostat - setback
27
DEV_WALL_CTLR
Wall controller
28
Attribute
Type
I/O
Description
next
ep_rec_t *
O
Point to next endpoint record
id
uint8_t
O
Endpoint id (starting from 0 for virtual endpoint, 1 and
new_if
uint16_t
O
New CC to be created/added to the endpoint, if any
new_if_ver
uint8_t
O
The "user defined version" for the new CC, if any
new_if_propty
uint8_t
O
New command class (interface) property (bit-mask)
redir_rec
redir_rec_t *
O
Command redirection records
if_rec
if_rec_t *
O
Interface records
Attribute
Type
I/O
Description
next
redir_rec_t *
O
Next redirection record
if_id
uint16_t
O
Interface id / CC id
cmd
int O Command value 0-255. -1 means don't care.
target_ep
uint8_t
O
Target endpoint id to redirect to
Attribute
Type
I/O
Description
next
if_rec_t *
O
Point to next interface record
INS14129-5 Z-Ware Library User Guide 2018-05-02
aware
Table 44 – ep_rec_t structure
onwards for real endpoints)
Table 45 – redir_rec_t structure
Table 46 – if_rec_t structure
silabs.com | Building a more connected world.
Page 27 of 184
type
uint8_t
O
Interface type, IF_REC_TYPE_XXX
usr_def_ver
uint8_t
O
User defined version
propty
uint8_t
O
Interface type specific property (bit-mask)
tmout
uint16_t
O
Interface type specific timeout value in seconds
rec
rec union
O
Union of interface records, the actual interface record
Interface Record Type
Description
#
IF_REC_TYPE_GROUP
Group
1
IF_REC_TYPE_CONFIG
Configuration
2
IF_REC_TYPE_BIN_SENSOR
Binary Sensor
3
IF_REC_TYPE_SENSOR
Sensor
4
IF_REC_TYPE_METER
Meter
5
IF_REC_TYPE_ALARM
Alarm/Notification
6
IF_REC_TYPE_BASIC
Basic
7
IF_REC_TYPE_ALRM_SNSR
Alarm Sensor
8
IF_REC_TYPE_THRMO_SETP
Thermostat setpoint
9
Attribute
Type
I/O
Description
grp
if_rec_grp_t *
O
Group interface record
config
if_rec_config_t *
O
Configuration interface
bsnsr
if_rec_bsnsr_t *
O
Binary Sensor interface
snsr
if_rec_snsr_t *
O
Sensor interface record
meter
if_rec_meter_t *
O
Meter interface record
alarm
if_rec_alarm_match_t*
O
Alarm//Notification interface
basic
if_rec_basic_match_t*
O
Basic interface record
alrm_snsr
if_rec_alrm_snsr_match_t*
O
Alarm sensor interface record
thrmo_setp
if_rec_thrmo_setp_t*
O
Thermostat setpoint
interface record
Attribute
Type
I/O
Description
grp_cnt
uint8_t
O
Number of group id in the grp_id array
grp_id
uint8_t[7]
O
Group IDs for the controller to set its node id into the
Attribute
Type
I/O
Description
INS14129-5 Z-Ware Library User Guide 2018-05-02
used is indicated by type attribute of this structure.
Table 47 – Interface Types: IF_REC_TYPE_XXX
Table 48 – rec union
record
record
record
Table 49 – if_rec_grp_t structure
groups
Table 50 – if_rec_config_t structure
silabs.com | Building a more connected world.
Page 28 of 184
next
if_rec_config_t *
O
Point to next configuration interface record
rec_type
uint16_t
O
Record type CONFIG_REC_TYPE_XXX
XXX
Description
SET
Configuration record type set
INFO
Configuration record type information
rec
union
O
Record as indicated by record type; union of
cfg_set
if_rec_cfg_set_t
O
For CONFIG_REC_TYPE_SET
cfg_info
if_rec_cfg_info_t
O
For CONFIG_REC_TYPE_INFO
Attribute
Type
I/O
Description
param_num
uint8_t
O
Parameter number
param_size
uint8_t
O
Data size: 1,2,or 4 bytes
param_val
int32_t
O
Configuration parameter value (signed integer)
Attribute
Type
I/O
Description
param_num
uint8_t
O
Parameter number
param_size
uint8_t
O
Data size: 1,2,or 4 bytes
param_min
int32_t
O
Minimum configuration parameter value
param_max
int32_t
O
Maximum configuration parameter value
param_deflt
int32_t
O
Default configuration parameter value (signed
param_name
char *
O
Parameter name
param_info
char *
O
Parameter information
Attribute
Type
I/O
Description
type
uint8_t
O
Supported binary sensor type
only)
rec_match
if_rec_bsnsr_match_t
O
Record matching condition
Attribute
Type
I/O
Description
pResult
void *
O
The result record that maps to. eg.
type
int O Binary sensor type ZW_BSENSOR_TYPE_XXX
state
int O Binary sensor state
INS14129-5 Z-Ware Library User Guide 2018-05-02
the following:
Table 51 – if_rec_cfg_set_t structure
Table 52 – if_rec_cfg_info_t structure
(signed integer)
(signed integer)
integer)
Table 53 – if_rec_bsnsr_t structure
ZW_BSENSOR_TYPE_XXX (for version 1
*
Table 54 – if_rec_bsnsr_match_t structure
if_rec_alarm_result_t*
silabs.com | Building a more connected world.
Page 29 of 184
resultType
int O Type of the resulted conversion.
Attribute
Type
I/O
Description
type_cnt
uint8_t
O
Number of thermostat setpoint supported
temp_range
zwsetp_temp_range_t
*
O
Temparature ranges
Attribute
Type
I/O
Description
min
zwsetp_t
O
Minimum setpoint temparature
max
zwsetp_t
O
Maximum setpoint temparature
Binary Sensor Type
Description
#
ZW_BSENSOR_TYPE_GP
General purpose sensor
1
ZW_BSENSOR_TYPE_SMOKE
Smoke sensor
2
ZW_BSENSOR_TYPE_CO
CO sensor
3
ZW_BSENSOR_TYPE_CO2
CO2 sensor
4
ZW_BSENSOR_TYPE_HEAT
Heat sensor
5
ZW_BSENSOR_TYPE_WATER
Water sensor
6
ZW_BSENSOR_TYPE_FREEZE
Freeze sensor
7
ZW_BSENSOR_TYPE_TAMPER
Tamper sensor
8
ZW_BSENSOR_TYPE_AUX
Aux sensor
9
ZW_BSENSOR_TYPE_DR_WIN
Door/Window sensor
10
ZW_BSENSOR_TYPE_TILT
Tilt sensor
11
ZW_BSENSOR_TYPE_MOTION
Motion sensor
12
ZW_BSENSOR_TYPE_GLASS_BRK
Glass break sensor
13
ZW_BSENSOR_TYPE_1ST_SUP
Return first sensor type on supported list
Multi-level Sensor Type
Description
#
ZW_SENSOR_TYPE_TEMP
Temperature sensor
1
ZW_SENSOR_TYPE_GP
General purpose sensor
2
ZW_SENSOR_TYPE_LUM
Luminance sensor
3
ZW_SENSOR_TYPE_POW
Power sensor
4
ZW_SENSOR_TYPE_HUMD
Relative humidity sensor
5
ZW_SENSOR_TYPE_VELO
Velocity sensor
6
ZW_SENSOR_TYPE_DIR
Direction sensor
7
ZW_SENSOR_TYPE_ATM
Atmospheric pressure sensor
8
ZW_SENSOR_TYPE_BARO
Barometric pressure sensor
9
INS14129-5 Z-Ware Library User Guide 2018-05-02
IF_REC_TYPE_XXX
Table 55 – if_rec_thrmo_setp_t structure
temparature range
Table 56 – zwsetp_temp_range_t structure
Table 57 – Binary Sensor Types: ZW_BSENSOR_TYPE_XXX
Table 58 – Multi-level Sensor Type: ZW_SENSOR_TYPE_XXX
silabs.com | Building a more connected world.
Page 30 of 184
ZW_SENSOR_TYPE_SLR
Solar radiation sensor
10
ZW_SENSOR_TYPE_DEW
Dew point sensor
11
ZW_SENSOR_TYPE_RAIN
Rain rate sensor
12
ZW_SENSOR_TYPE_TIDE
Tide level sensor
13
ZW_SENSOR_TYPE_WGT
Weight sensor
14
ZW_SENSOR_TYPE_VOLT
Voltage sensor
15
ZW_SENSOR_TYPE_CUR
Current sensor
16
ZW_SENSOR_TYPE_CO2
CO2-level sensor
17
ZW_SENSOR_TYPE_AIR
Air flow sensor
18
ZW_SENSOR_TYPE_TANK
Tank capacity sensor
19
ZW_SENSOR_TYPE_DIST
Distance sensor
20
ZW_SENSOR_TYPE_AGL
Angle Position sensor
21
ZW_SENSOR_TYPE_ROT
Rotation sensor
22
ZW_SENSOR_TYPE_WTR_TEMP
Water temperature sensor
23
ZW_SENSOR_TYPE_SOIL_TEMP
Soil temperature sensor
24
ZW_SENSOR_TYPE_SEIS_INT
Seismic intensity sensor
25
ZW_SENSOR_TYPE_SEIS_MAG
Seismic magnitude sensor
26
ZW_SENSOR_TYPE_UV
Ultraviolet sensor
27
ZW_SENSOR_TYPE_ELEC_RES
Electrical resistivity sensor
28
ZW_SENSOR_TYPE_ELEC_COND
Electrical conductivity sensor
29
ZW_SENSOR_TYPE_LOUDNESS
Loudness sensor
30
ZW_SENSOR_TYPE_MOIST
Moisture sensor
31
ZW_SENSOR_TYPE_FREQ
Frequency sensor
32
ZW_SENSOR_TYPE_TIME
Time sensor
33
ZW_SENSOR_TYPE_TGT_TEMP
Target temperature sensor
34
ZW_SENSOR_TYPE_PM_2_5
Particulate matter 2.5 sensor
35
ZW_SENSOR_TYPE_F_CH2O
Formaldehyde CH2O-level
36
ZW_SENSOR_TYPE_RAD_CONT
Radon Concentration sensor
37
ZW_SENSOR_TYPE_METH_DENS
Methane Density CH4 sensor
38
ZW_SENSOR_TYPE_VOC
Volatile Organic Compound
39
ZW_SENSOR_TYPE_CO_LVL
Carbon Monoxide CO-level
40
ZW_SENSOR_TYPE_SOIL_HUMD
Soil Humidity sensor
41
ZW_SENSOR_TYPE_SOIL_REAC
Soil Reactivity sensor
42
ZW_SENSOR_TYPE_SOIL_SAL
Soil Salinity sensor
43
ZW_SENSOR_TYPE_HEART_RT
Heart Rate sensor
44
ZW_SENSOR_TYPE_BLOOD_PRS
Blood Pressure sensor
45
ZW_SENSOR_TYPE_MUSCLE_MS
Muscle Mass sensor
46
ZW_SENSOR_TYPE_FAT_MS
Fat Mass sensor
47
ZW_SENSOR_TYPE_BONE_MS
Bone Mass sensor
48
ZW_SENSOR_TYPE_TBW
Total Body Water sensor
49
ZW_SENSOR_TYPE_BMR
Basic Metabolic Rate sensor
50
INS14129-5 Z-Ware Library User Guide 2018-05-02
sensor
sensor
sensor
silabs.com | Building a more connected world.
Page 31 of 184
ZW_SENSOR_TYPE_BMI
Body Mass Index sensor
51
ZW_SENSOR_TYPE_ACCEL_X
Acceleration, X-axis sensor
52
ZW_SENSOR_TYPE_ACCEL_Y
Acceleration, Y-axis sensor
53
ZW_SENSOR_TYPE_ACCEL_Z
Acceleration, Z-axis sensor
54
ZW_SENSOR_TYPE_SMOKE_DEN
Smoke Density sensor
55
ZW_SENSOR_TYPE_WATER_FLW
Water Flow sensor
56
ZW_SENSOR_TYPE_WATER_PRS
Water Pressure sensor
57
ZW_SENSOR_TYPE_RF_SGN
RF Signal Strength sensor
58
ZW_SENSOR_TYPE_PM_10
Particulate Matter 10 sensor
59
ZW_SENSOR_TYPE_RESPI_RATE
Respiratory rate sensor
60
ZW_SENSOR_TYPE_REL_MOD
Relative Modulation level
61
ZW_SENSOR_TYPE_BOILER_WTR_TEMP
Boiler water temperature
sensor
62
ZW_SENSOR_TYPE_DHW_TEMP
Domestic Hot Water (DHW)
63
ZW_SENSOR_TYPE_OUTSIDE_TEMP
Outside temperature sensor
64
ZW_SENSOR_TYPE_EXHAUST_TEMP
Exhaust temperature sensor
65
ZW_SENSOR_TYPE_WATER_CHLOR_LVL
Water Chlorine level sensor
66
ZW_SENSOR_TYPE_WATER_ACID
Water acidity sensor
67
ZW_SENSOR_TYPE_WATER_OXI_RED
Water Oxidation reduction
potential sensor
68
Multi-level Sensor Type
Unit
#
ZW_SENSOR_TYPE_TEMP
Celsius (C)
0
Fahrenheit (F)
1
ZW_SENSOR_TYPE_GP
Percentage value
0
Dimensionless value
1
ZW_SENSOR_TYPE_LUM
Percentage value
0
Lux
1
ZW_SENSOR_TYPE_POW
W 0 Btu/h
1
ZW_SENSOR_TYPE_HUMD
Percentage value
0
g/m3
1
ZW_SENSOR_TYPE_VELO
m/s 0 mph
1
ZW_SENSOR_TYPE_DIR
Direction unit: 0 to 360 degrees. 0 = no
0
ZW_SENSOR_TYPE_ATM
kPa 0 inches of Mercury
1
ZW_SENSOR_TYPE_BARO
kPa
0
inches of Mercury
1
INS14129-5 Z-Ware Library User Guide 2018-05-02
sensor
temperature sensor
Table 59 – Multi-level Sensor Unit
wind, 90 = east,180 = south, 270 = west,
and 360 = north
silabs.com | Building a more connected world.
Page 32 of 184
ZW_SENSOR_TYPE_SLR
W/m2
0
ZW_SENSOR_TYPE_DEW
Celsius (C)
0
Fahrenheit (F)
1
ZW_SENSOR_TYPE_RAIN
mm/h
0
in/h
1
ZW_SENSOR_TYPE_TIDE
m 0 feet
1
ZW_SENSOR_TYPE_WGT
kg 0 pounds
1
ZW_SENSOR_TYPE_VOLT
V 0 mV
1
ZW_SENSOR_TYPE_CUR
A 0 mA 1 ZW_SENSOR_TYPE_CO2
ppm
0
ZW_SENSOR_TYPE_AIR
m3/h
0
cfm (cubic feet per minute)
1
ZW_SENSOR_TYPE_TANK
l
0
cbm
1
US gallons
2
ZW_SENSOR_TYPE_DIST
m
0
cm 1 feet
2
ZW_SENSOR_TYPE_AGL
Percentage value
0
Degrees relative to north pole of standing
1
Degrees relative to south pole of standing
eye view
2
ZW_SENSOR_TYPE_ROT
rpm (revolutions per minute)
0
Hz (Hertz)
1
ZW_SENSOR_TYPE_WTR_TEMP
Celsius (C)
0
Fahrenheit (F)
1
ZW_SENSOR_TYPE_SOIL_TEMP
Celsius (C)
0
Fahrenheit (F)
1
ZW_SENSOR_TYPE_SEIS_INT
Mercalli
0
European Macroseismic
1
Liedu
2
Shindo
3
ZW_SENSOR_TYPE_SEIS_MAG
Local (ML)
0
Moment (MW)
1
Surface wave (MS)
2
Body wave (MB)
3
ZW_SENSOR_TYPE_UV
UV index
0
ZW_SENSOR_TYPE_ELEC_RES
ohm metre
0
ZW_SENSOR_TYPE_ELEC_COND
siemens per metre (S/m)
0
INS14129-5 Z-Ware Library User Guide 2018-05-02
eye view
silabs.com | Building a more connected world.
Page 33 of 184
ZW_SENSOR_TYPE_LOUDNESS
Absolute loudness (dB)
0
A-weighted decibels (dBA)
1
ZW_SENSOR_TYPE_MOIST
Percentage value
0
Volume water content (m3/m3)
1
Impedance (k ohm)
2
Water activity (aw)
3
ZW_SENSOR_TYPE_FREQ
Hz - Must be used until 4.294967295 GHz
0
kHz- Must be used after 4.294967295 GHz
1
ZW_SENSOR_TYPE_TIME
seconds
0
ZW_SENSOR_TYPE_TGT_TEMP
Celsius (C)
0
Fahrenheit (F)
1
ZW_SENSOR_TYPE_PM_2_5
mole per cubic meter (mol/m3)
0
Absolute microgram/cubic meter (ug/m3)
1
ZW_SENSOR_TYPE_F_CH2O
mole per cubic meter (mol/m3)
0
ZW_SENSOR_TYPE_RAD_CONT
Becquerel/cubic meter (bq/m3)
0
picocuries/liter (pCi/L)
1
ZW_SENSOR_TYPE_METH_DENS
mole per cubic meter (mol/m3)
0
ZW_SENSOR_TYPE_VOC
mole per cubic meter (mol/m3)
0
ZW_SENSOR_TYPE_CO_LVL
mole per cubic meter (mol/m3)
0
ZW_SENSOR_TYPE_SOIL_HUMD
Percentage value
0
ZW_SENSOR_TYPE_SOIL_REAC
acidity (pH)
0
ZW_SENSOR_TYPE_SOIL_SAL
mole per cubic meter (mol/m3)
0
ZW_SENSOR_TYPE_HEART_RT
beats/minute (Bpm)
0
ZW_SENSOR_TYPE_BLOOD_PRS
Systolic mmHg (upper number)
0
Diastolic mmHg (lower number)
1
ZW_SENSOR_TYPE_MUSCLE_MS
kilogram (kg)
0
ZW_SENSOR_TYPE_FAT_MS
kilogram (kg)
0
ZW_SENSOR_TYPE_BONE_MS
kilogram (kg)
0
ZW_SENSOR_TYPE_TBW
kilogram (kg)
0
ZW_SENSOR_TYPE_BMR
joule (J)
0
ZW_SENSOR_TYPE_BMI
BMI Index
0
ZW_SENSOR_TYPE_ACCEL_X
(m/s2)
0
ZW_SENSOR_TYPE_ACCEL_Y
(m/s2)
0
ZW_SENSOR_TYPE_ACCEL_Z
(m/s2)
0
ZW_SENSOR_TYPE_SMOKE_DEN
Percentage value
0
ZW_SENSOR_TYPE_WATER_FLW
liter/hour (l/h)
0
ZW_SENSOR_TYPE_WATER_PRS
kilopascal (kPa)
0
ZW_SENSOR_TYPE_RF_SGN
RSSI (Percentage value)
0
(dBm)
1
ZW_SENSOR_TYPE_PM_10
Mole per cubic meter (mol/m3)
0
Microgram per cubic meter (µg/m3)
1
ZW_SENSOR_TYPE_RESPI_RATE
Breaths per minute (bpm)
0
ZW_SENSOR_TYPE_REL_MOD
Percentage value (%)
0
ZW_SENSOR_TYPE_BOILER_WTR_TEMP
Celcius (C)
0
INS14129-5 Z-Ware Library User Guide 2018-05-02
silabs.com | Building a more connected world.
Page 34 of 184
ZW_SENSOR_TYPE_DHW_TEMP
Celcius (C)
0
ZW_SENSOR_TYPE_OUTSIDE_TEMP
Celcius (C)
0
ZW_SENSOR_TYPE_EXHAUST_TEMP
Celcius (C)
0
ZW_SENSOR_TYPE_WATER_CHLOR_LVL
Milligram per liter (mg/l)
0
ZW_SENSOR_TYPE_WATER_ACID
Acidity (pH)
0
ZW_SENSOR_TYPE_WATER_OXI_RED
MilliVolt (mV)
0
Meter Type
Description
#
ZW_METER_TYPE_ELEC
Electric meter
1
ZW_METER_TYPE_GAS
Gas meter
2
ZW_METER_TYPE_WATER
Water meter
3
Multi-level Sensor Type
Unit
Bit-mask
ZW_METER_TYPE_ELEC
kWh
0x01
kVAh
0x02
W
0x04
pulse count
0x08
V
0x10
A
0x20
power factor
0x40
ZW_METER_TYPE_GAS
cubic meters
0x01
cubic feet
0x02
pulse count
0x08
ZW_METER_TYPE_WATER
cubic meters
0x01
cubic feet
0x02
US gallons
0x04
pulse count
0x08
Z-Wave Alarm Type
Description
#
ZW_ALRM_SMOKE
Smoke alarm
1
ZW_ALRM_CO
Carbon monoxide alarm
2
ZW_ALRM_CO2
Carbon dioxide alarm
3
ZW_ALRM_HEAT
Heat alarm
4
ZW_ALRM_WATER
Water alarm
5
ZW_ALRM_LOCK
Lock access control alarm
6
ZW_ALRM_BURGLAR
Burglar alarm or home security
7
ZW_ALRM_POWER
Power management alarm
8
ZW_ALRM_SYSTEM
System alarm
9
ZW_ALRM_EMERGENCY
Emergency alarm
10
ZW_ALRM_CLOCK
Alarm clock
11
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 60 – Meter Type
Table 61 – Meter Supported Unit Bit-mask
Table 62 – Z-Wave Alarm//Notification Type
silabs.com | Building a more connected world.
Page 35 of 184
ZW_ALRM_APPLIANCE
Home appliance alarm
12
ZW_ALRM_HEALTH
Home health alarm
13
ZW_ALRM_SIREN
Siren alarm
14
ZW_ALRM_WATER_VLV
Water Valve alarm
15
ZW_ALRM_WEATHER
Weather alarm
16
ZW_ALRM_IRRIGATION
Irrigation alarm
17
ZW_ALRM_GAS
Gas alarm
18
ZW_ALRM_PEST_CTL
Pest control
19
ZW_ALRM_LIGHT_SNSR
Light sensor
20
Z-Wave
Z-Wave Alarm/Notification event
#
All
Unknown event.
254
Event inactive (push mode) / Previous Events cleared (pull mode)
0
Smoke alarm
Smoke detected with location
1
Smoke detected
2
Smoke alarm test
3
Replacement required
4
Carbon monoxide
Carbon monoxide detected with location
1
Carbon monoxide detected
2
Carbon monoxide test
3
Replacement required
4
Carbon dioxide
Carbon dioxide detected with location
1
Carbon dioxide detected
2
Carbon dioxide test
3
Replacement required
4
Heat alarm
Overheat detected with location info
1
Overheat detected
2
Rapid temperature rise detected with location
3
Rapid temperature rise detected
4
Underheat detected with location
5
Underheat detected
6
Water alarm
Water leak detected with location
1
Water leak detected
2
Water level dropped detected with location
3
Water level dropped detected
4
Replace Water Filter
5
Lock access
Manual lock operation
1
Manual unlock operation
2
RF lock operation
3
RF unlock operation
4
Keypad lock operation with user identifier
5
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 63 – Z-Wave Alarm/Notification Event
Alarm/Notificatio
n type
alarm
alarm
control alarm
silabs.com | Building a more connected world.
Page 36 of 184
Keypad unlock operation with user identifier
6
Manual not fully locked operation
7
RF not fully locked operation
8
Auto lock locked operation
9
Auto lock not fully operation
10
Lock jammed
11
All user codes deleted
12
Single user code deleted
13
New user code added
14
New user code not added due to duplicate code
15
Keypad temporary disabled
16
Keypad busy
17
New program code entered - unique code for lock configuration
18
Manually enter user access code exceeds code limit
19
Unlock by RF with invalid user code
20
Locked by RF with invalid user code
21
Window/door is open
22
Window/door is closed
23
Burglar alarm
Intrusion detected with location
1
Intrusion detected
2
Tampering, product covering removed
3
Tampering, Invalid Code
4
Glass breakage detected with location
5
Glass breakage detected
6
Motion detected with location info
7
Motion detected with unknown location info
8
Power
Power has been applied
1
AC mains disconnected
2
AC mains re-connected
3
Surge Detection
4
Voltage Drop/Drift detected
5
Over-current detected
6
Over-voltage detected
7
Over-load detected
8
Load error
9
Replace battery soon
10
Replace battery now
11
Battery is charging
12
Battery is fully charged
13
Charge battery soon
14
Charge battery now
15
System alarm
System hardware failure
1
System software failure
2
System hardware failure with OEM proprietary failure code
3
INS14129-5 Z-Ware Library User Guide 2018-05-02
management
alarm
silabs.com | Building a more connected world.
Page 37 of 184
System software failure with OEM proprietary failure code
4
Emergency alarm
Contact police
1
Contact fire service
2
Contact medical service
3
Alarm clock
Wake up
1
Timer ended
2
Time remaining
3
Barrier
Barrier performing Initialization process
64
Barrier operation (Open / Close) force has been exceeded.
65
Barrier motor has exceeded manufacturer’s operational time limit
66
Barrier operation has exceeded physical mechanical limits. (For
67
Barrier unable to perform requested operation due to UL
requirements.
68
Barrier Unattended operation has been disabled per UL requirements
69
Barrier failed to perform Requested operation, device malfunction
70
Barrier Vacation Mode
71
Barrier Safety Beam Obstacle
72
Barrier Sensor Not Detected / Supervisory Error
73
Barrier Sensor Low Battery Warning
74
Barrier detected short in Wall Station wires
75
Barrier associated with non-Z-Wave remote control
76
Appliance
Program started
1
Program in progress
2
Program completed
3
Replace main filter
4
Failure to set target temperature
5
Supplying water
6
Water supply failure
7
Boiling
8
Boiling failure
9
Washing
10
Washing failure
11
Rinsing
12
Rinsing failure
13
Draining
14
Draining failure
15
Spinning
16
Spinning failure
17
Drying
18
Drying failure
19
Fan failure
20
Compressor failure
21
Home Health
Leaving Bed
1
INS14129-5 Z-Ware Library User Guide 2018-05-02
example: barrier has opened past the open limit)
silabs.com | Building a more connected world.
Page 38 of 184
Sitting on bed
2
Lying on bed
3
Posture changed
4
Sitting on edge of bed
5
Volatile Organic Compound level
6
Siren
Siren Active
1
Water Valve
Valve Operation
1
Master Valve Operation
2
Valve Short Circuit
3
Master Valve Short Circuit
4
Valve Current Alarm
5
Master Valve Current Alarm
6
Weather
Rain
1
Moisture
2
Irrigation
Schedule Started
1
Schedule Finished
2
Valve Table Run Started
3
Valve Table Run Finished
4
Device is not Configured
5
Gas
Combustible Gas detected with location info
1
Combustible Gas detected with unknown location info
2
Toxic Gas detected with location info
3
Toxic Gas detected with unknown location info
4
Gas Alarm Test
5
Replacement Required
6
Z-Wave Alarm/Notification Event
Description
#
ZW_ALRM_PARAM_LOC
node location UTF-8 string (NULL terminated)
1
ZW_ALRM_PARAM_USRID
user id
2
ZW_ALRM_PARAM_OEM_ERR_CODE
OEM proprietary system failure code
3
ZW_ALRM_PARAM_PROPRIETARY
Proprietary event parameters
4
ZW_ALRM_PARAM_EVENT_ID
Event id which is no more active
5
ZW_ALRM_PARAM_UNKNOWN
Unknown alarm event parameters. It could
255
Alarm Sensor Type
Description
Assigned
Number
ZW_ALRM_SNSR_TYPE_GP
General Purpose Alarm
0
ZW_ALRM_SNSR_TYPE_SMOKE
Smoke Alarm
1
INS14129-5 Z-Ware Library User Guide 2018-05-02
Parameter Type
Table 64 – Z-Wave Alarm/Notification Event Parameter Type
be from a higher version of CC, or the device
violates the spec and send parameters when
Spec does not define
Table 65 – Alarm Sensor Type
silabs.com | Building a more connected world.
Page 39 of 184
ZW_ALRM_SNSR_TYPE_CO
CO Alarm
2
ZW_ALRM_SNSR_TYPE_CO2
CO2 Alarm
3
ZW_ALRM_SNSR_TYPE_HEAT
Heat Alarm
4
ZW_ALRM_SNSR_TYPE_WATER_LEAK
Water Leak Alarm
5
Attribute
Type
I/O
Description
type
uint8_t
O
Sensor type ZW_SENSOR_TYPE_XXX
unit
uint8_t
O
Sensor unit ZW_SENSOR_UNIT_XXX
Attribute
Type
I/O
Description
type
uint8_t
O
ZW_METER_TYPE_XXX
unit_supp
uint8_t
O
Supported unit bit-mask : ZW_METER_SUP_UNIT_XXX
Attribute
Type
I/O
Description
next
if_rec_alarm_match_t *
O
Point to next match record
pResult
if_rec_alarm_result_t *
O
The result alarm record that maps to
pRevMatch
if_rec_alarm_rev_match_t *
O
Device specific alarm reverse-matching record (It is the
match_valid
int O Flag to indicate whether the match entries below are
valid
type
int O Vendor proprietary alarm type
level_low
int O Vendor proprietary alarm level or lower limit of a
level_high
int O Vendor proprietary alarm level higher limit of a range
isRange
int O Flag to indicate vendor proprietary alarm level is a
range
ex_type
int O Z-Wave Alarm/Notification type (ZW_ALRM_XXX)
ex_event
int O Z-Wave Alarm/Notification event
ex_evt_len
int O Z-Wave Alarm/Notification event parameter length.
Zero if the event has no parameter
pEx_evt_prm
uint8_t *
O
pointer to Z-Wave Alarm/Notification event parameter
Attribute
Type
I/O
Description
type
int O Vendor proprietary alarm type
level
int O Vendor proprietary alarm level
ex_type
int O Z-Wave alarm/Notification type (ZW_ALRM_XXX)
type_name
char *
O
Device specific alarm type name
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 66 – if_rec_snsr_t structure
Table 67 – if_rec_meter_t structure
Table 68 – if_rec_alarm_match_t structure
OR result of match and result struct)
range
(ZW_ALRM_EVT_XXX)
Table 69 – if_rec_alarm_result_t structure
silabs.com | Building a more connected world.
Page 40 of 184
ex_event
int O Z-Wave alarm/Notification event
level_name
char *
O
Device specific alarm level name
ex_evt_len
int O Z-Wave alarm/Notification event parameter length.
Zero if the event has no parameter
ex_evt_type
int O Z-Wave alarm/Notification event parameter type
pEx_evt_prm
uint8_t *
O
pointer to Z-Wave alarm/Notification event parameter
Attribute
Type
I/O
Description
type
int O Vendor proprietary alarm type
ex_type
int O Z-Wave alarm/Notification type (ZW_ALRM_XXX)
ex_event
int O Z-Wave alarm/Notification event (ZW_ALRM_EVT_XXX)
Attribute
Type
I/O
Description
next
if_rec_basic_match_t *
O
Point to next match record
pResult
void *
O
The result record that maps to. eg.
command
int O Basic CC command. eg. BASIC_SET
value
int O Command value 0-255. -1 means don't care
resultType
Int O Type of the resulted conversion. IF_REC_TYPE_xxx
Attribute
Type
I/O
Description
next
if_rec_alrm_snsr_match_t *
O
Point to next match record
pResult
void *
O
The result record that maps to. eg.
type
int O Alarm sensor type. (ZW_ALRM_SNSR_TYPE_XXX)
state_low
int O Alarm sensor state or lower limit of a range. -1 means
don't care.
state_high
int O Alarm sensor state higher limit of a range
isRange
int O Flag to indicate Alarm sensor state is a range
resultType
int O Type of the resulted conversion. IF_REC_TYPE_xxx
Attribute
Type
I/O
Description
dev_ent
unsigned
O
Device entry number (starting from 1)
ep_ent
unsigned
O
Endpoint entry number (starting from 1)
if_ent
unsigned
O
Interface entry number (starting from 1)
INS14129-5 Z-Ware Library User Guide 2018-05-02
(ZW_ALRM_EVT_XXX)
(ZW_ALRM_PARAM_XXX)
Table 70 – if_rec_alarm_rev_match_t structure
Table 71 – if_rec_basic_match_t structure
if_rec_alarm_result_t*
Table 72 – if_rec_alrm_snsr_match_t structure
if_rec_alarm_result_t*
Table 73 – dev_cfg_error_t structure
silabs.com | Building a more connected world.
Page 41 of 184
Attribute
Type
I/O
Description
records
dev_rec_t *
I
Device specific configuration records
record_cnt
int I Number of records stored in "records" array
Attribute
Type
I/O
Description
global_sett
dev_global_sett_t *
I
Device setting records
global_sett_cnt
uint16_t
I
Number of records stored in " global_sett" array
Attribute
Type
I/O
Description
srch_key
dev_rec_srch_key_t *
I
Search key
records
dev_rec_t *
I
Device specific configuration records sorted according to
manufacturer id, product type id and product id
record_cnt
int I Number of records stored in "records" array
matched_rec
dev_rec_t *
O
The matched record; either exact match or partial match
where V="valid value"; X="don't care".
Return
int O Non-zero if a match is found; else returns zero
Attribute
Type
I/O
Description
vid
uint32_t
O
Vendor or Manufacturer ID
ptype
uint32_t
O
Product Type ID
pid
uint32_t
O
Product ID
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.3.2 zwdev_cfg_free
Free device specific configuration records.
Table 74 – zwdev_cfg_free Parameters
4.3.3 zwdev_global_sett_free
Free device global settings.
Table 75 – zwdev_global_sett_free Parameters
4.3.4 zwdev_cfg_find
Search for a match in device specific configuration records.
Table 76 – zwdev_cfg_find Parameters
as explained in the note below.
Note: This function supports "don't care" cases in device
specific configuration records.The search priority is as
follows (in the format (Manf id, Product Type, Product id))
: (V, V, V), (V, V, X), (V, X, X), (X, X, X)
Table 77 – dev_rec_srch_key_t structure
silabs.com | Building a more connected world.
Page 42 of 184
{
},
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.3.5 JSON File Format
The external file contains the records in JSON format. The following explains different record types
using c-style comments (/* and */). Please note that c-style comments are invalid in JSON standard and
hence should be removed in real use case.
"global_settings":
[
{
"wakeup_interval":480 /* Wakeup interval in seconds to set whenever a new sleep
capable device is added to the network. Value of zero or absent of this entry means do not
change the device default value*/
},
{
"wakeup_no_more_info_delay":60 /* Send "wakeup no more info" delay (in seconds)
whenever a new sleep capable device is added to the network. Value of zero means DO NOT send
"wakeup no more info". Absent of this entry means use default value of 60 seconds */
}
],
"device_records":
[
{
"_comment": "X company sensors",
"vid":1, /* vendor or manufacturer id */
"ptype": 4952, /* product type id */
"pid":3030, /* product id */
"category":1, /* device category as defined in DEV_XXX */
"ep": [ /*endpoints */
{
"epid":0, /* Endpoint id (starting from 0 for virtual endpoint which is node level,1
and onwards for real endpoints) */
"interface":[ /*interfaces*/
{
"if_type": 1, /*interface type as defined in IF_REC_TYPE_XXX */
"grp_id": [1, 3, 5] /*group id for the controller to set its node id into the
group(s)*/
},
{
"if_type": 2, /*interface type as defined in IF_REC_TYPE_XXX */
"config":[ /*Configuration set parameter*/
{
"param_num": 1, /* parameter number */
"param_size":2, /* data size: 1,2,or 4 bytes*/
"param_val":-10000 /* configuration parameter value (signed integer)*/
},
{
"param_num": 2, /* parameter number */
"param_size":1, /* data size: 1,2,or 4 bytes*/
"param_val":15 /* configuration parameter value (signed integer)*/
}
],
"config_info":[ /*Configuration parameter information*/
{
"param_num": 1, /* parameter number */
"param_name": "Sampling interval", /* parameter name */
"param_info": "Control the sampling interval in milliseconds (ms)", /*
parameter info */
"param_size": 1, /* data size: 1,2,or 4 bytes*/
"param_min": 10, /* minimum configuration parameter value (signed
integer)*/
"param_max": 100,/* maximum configuration parameter value (signed
integer)*/
"param_deflt":50 /* default configuration parameter value (signed
integer)*/
silabs.com | Building a more connected world.
Page 43 of 184
{
"zw_alarm_type": 7, /*Z-Wave alarm type (optional)*/
INS14129-5 Z-Ware Library User Guide 2018-05-02
"param_num": 2, /* parameter number */
"param_name": "Sensitivity", /* parameter name */
"param_info": "Sensitivity: 0=low, 1=normal, 2=high", /* parameter info */
"param_size": 1, /* data size: 1,2,or 4 bytes*/
"param_min": 0, /* minimum configuration parameter value (signed
integer)*/
"param_max": 2,/* maximum configuration parameter value (signed integer)*/
"param_deflt":1 /* default configuration parameter value (signed
integer)*/
}
]
}
]
},
{
"epid":1, /* Endpoint id (starting from 0 for virtual endpoint, 1 and onwards for
real endpoints) */
"create_interface":113, /* Create command class ID 113 (alarm command class) in
this endpoint. This interface must not already exist in the actual device and endpoint */
"create_interface_version":4, /* Version for the created command class */
"redirect":[ /* Command redirection*/
{
"interface": 156, /* CC ID for redirection*/
"command": -1, /* CC command 0-255 for redirection. -1 means don't care*/
"target_ep": 0 /* Target endpoint to redirect the command to. In this example,
redirect command from ep1 to ep0 */
}
],
"interface":[ /*interfaces*/
{
"if_type": 3, /*interface type as defined in IF_REC_TYPE_XXX */
"bin_sensor_type": 12, /*supported binary sensor type ZW_BSENSOR_TYPE_XXX.
This field is only valid for version 1 (optional) */
"no_event_clear": 1, /*indicate the interface is not capable to sent event
clear, i.e. binary sensor value of zero (optional); 1=not capable; 0 or absent of this
field=capable. */
"event_clear_timeout": 60, /*timeout in seconds (max: 3600 s), to generate
event_clear callback to user application. This field is only valid when "no_event_clear" = 1.
Default is 5 minutes.(optional)*/
"bin_sensor":[ /*Report conversion array*/
{/*Each element must contain "match" and "result" block, in the order of
"match" followed by "result"*/
"match":[/*The block that contains the original binary sensor report
data to compare against. Cannot be empty */
/*All the properties need to met for the conversion to happen.
If a property is missing, it will not be included for comparison*/
{
"type": 12, /*binary sensor type ZW_BSENSOR_TYPE_XXX (optional)*/
"state": 255, /*binary sensor state 0 or 255. -1 means don't care. */
"result_if_type": 6 /* Type of the resulted conversion as defined in
IF_REC_TYPE_XXX*/
}
],
"result":[ /*The block that contains the resultant report. Cannot be
empty */
/*If a property is missing, it will follow the same value from the original report*/
{
silabs.com | Building a more connected world.
Page 44 of 184
"ptype": 4950, /* product type id */
INS14129-5 Z-Ware Library User Guide 2018-05-02
"alarm_type_name": "Burglar", /*Alarm type name (optional)*/
"zw_alarm_event":8, /*Z-Wave alarm event (optional)*/
"alarm_level_name":"Motion detected" /*Alarm level name
(optional)*/
}
]
},
{
"match":[/*The block that contains the original binary sensor report
data to compare against. Cannot be empty */
/*All the properties need to met for the conversion to happen.
If a property is missing, it will not be included for comparison*/
{
"type": 12, /*binary sensor type ZW_BSENSOR_TYPE_XXX (optional)*/
"state": 0, /*binary sensor state 0 or 255. -1 means don't care. */
"result_if_type": 6 /* Type of the resulted conversion as defined in
IF_REC_TYPE_XXX*/
}
],
"result":[ /*The block that contains the resultant report. Cannot be
empty */
/*If a property is missing, it will follow the same value from the original report*/
{
"zw_alarm_type": 7, /*Z-Wave alarm type (optional)*/
"alarm_type_name": "Burglar", /*Alarm type name (optional)*/
"zw_alarm_event":0, /*Z-Wave alarm event (optional)*/
"alarm_level_name":"Event inactive", /*Alarm level name (optional)*/
"zw_alarm_param_type":5, /*Z-Wave alarm param type (optional)*/
"zw_alarm_param":[8] /*Z-Wave alarm parameters (optional)*/
}
]
}
]
},
{
"if_type": 4, /*interface type as defined in IF_REC_TYPE_XXX */
"sensor_type": 3, /* sensor type ZW_SENSOR_TYPE_XXX */
"sensor_unit": 0 /* supported sensor unit ZW_SENSOR_UNIT_XXX */
}
]
}
]
},
{
"_comment": "X company meter",
"vid":1, /* vendor or manufacturer id */
silabs.com | Building a more connected world.
Page 45 of 184
"pid":3030, /* product id */
{
INS14129-5 Z-Ware Library User Guide 2018-05-02
"category":10, /* device category as defined in DEV_XXX */
"ep": [ /*endpoints */
{
"epid":0, /* Endpoint id (starting from 0 for virtual endpoint, 1 and onwards for
real endpoints) */
"interface":[ /*interfaces*/
{
"if_type": 1, /*interface type as defined in IF_REC_TYPE_XXX */
"grp_id": [1] /*group id for the controller to set its node id into the group*/
},
{
"if_type": 2, /*interface type as defined in IF_REC_TYPE_XXX */
"config":[ /*Configuration parameter*/
{
"param_num": 1, /* parameter number */
"param_size":2, /* data size: 1,2,or 4 bytes*/
"param_val":-10000 /* configuration parameter value (signed integer)*/
}
]
},
{
"if_type": 5, /*interface type as defined in IF_REC_TYPE_XXX */
"meter_type": 1, /*meter type ZW_METER_TYPE_XXX */
"meter_supported_units":17 /*supported unit bit-mask; see Meter Supported Unit
Bit-mask table */
}
]
}
]
},
{
"_comment": "All alarms manufactured by Y company. pid= -1 means don't care; i.e. it
matches anything",
"vid":2, /* vendor or manufacturer id */
"ptype": 5, /* product type id */
"pid":-1, /* product id */
"category":1, /* device category as defined in DEV_XXX */
"ep": [ /*endpoints */
{
"epid":0, /* Endpoint id (starting from 0 for virtual endpoint, 1 and onwards for
real endpoints) */
"interface":[ /*interfaces*/
{
"if_type": 6, /*interface type as defined in IF_REC_TYPE_XXX */
"user_def_version": 7, /*user-defined interface version which will be reported
to user application (optional)*/
"no_event_clear": 1, /*indicate the interface is not capable to sent event clear
notification (optional); 1=not capable; 0 or absent of this field=capable. NOTE: This field
is valid only for notification CC version 4 and higher.*/
"alarm":[
{
"match":[ /*The block that contains the original alarm report data to
compare against. Cannot be empty */
/*All the properties need to met for the conversion to happen. If a property is missing, it
will not be included for comparison*/
{
"alarm_type": 21, /*Vendor specific alarm type (optional)*/
"alarm_level": 2 /*Vendor specific alarm level (optional)*/
}
],
"result":[ /*The block that contains the resultant report. Cannot be
empty*/
/*If a property is missing, it will follow the same value from the original
report*/
silabs.com | Building a more connected world.
Page 46 of 184
"zw_alarm_type": 6, /*Z-Wave alarm type mapped from vendor specific
}
INS14129-5 Z-Ware Library User Guide 2018-05-02
proprietary alarm type (optional)*/
"alarm_type_name": "Access Control", /*Alarm type name (optional)*/
"zw_alarm_event":5, /*Z-Wave alarm event mapped from vendor specific
alarm level (optional)*/
"alarm_level_name":"Keypad Lock", /*Alarm level name (optional)*/
"zw_alarm_param_type":4, /*Z-Wave alarm parameter type as defined in
ZW_ALRM_PARAM_XXX (Compulsory when zw_alarm_param is defined in either match/result block)*/
"zw_alarm_param":[0,1] /*Z-Wave alarm event parameters in an array
(optional)*/
}
]
},
"match":[ /*The block that contains the original alarm report data to
compare against. Cannot be empty */
/*All the properties need to met for the conversion to happen. If a property is missing, it
will not be included for comparison*/
{
"alarm_type": 9, /*Vendor specific alarm type (optional)*/
"alarm_level_range":[10,20] /*Vendor specific alarm level range, means
all values from 10, 20 (both number inclusive) will be used for translation. And they will be
translated into the same report. (optional)*/
"result":[ /*The block that contains the resultant report. Cannot be
empty*/
/*If a property is missing, it will follow the same value from the original report*/
{
"zw_alarm_type": 6, /*Z-Wave alarm type mapped from vendor specific
proprietary alarm type (optional)*/
"alarm_level_name":"Keypad Lock", /*Alarm level name (optional)*/
"zw_alarm_param_type":4, /*Z-Wave alarm parameter type as defined in
ZW_ALRM_PARAM_XXX (Compulsory when zw_alarm_param is defined in either match/result block)*/
"zw_alarm_param":[1] /*Z-Wave alarm event parameters in an array
(optional)*/
}
},
{
"match":[ /*The block that contains the original alarm report data to
compare against. Cannot be empty */
/*All the properties need to met for the conversion to happen. If a property is missing, it
will not be included for comparison*/
"alarm_type": 9, /*Vendor specific alarm level (optional)*/
"alarm_level": 2, /*Vendor specific alarm level (optional)*/
"zw_alarm_type": 6, /*Z-Wave alarm type (optional)*/
"zw_alarm_event": 5, /*Z-Wave alarm event(optional)*/
"zw_alarm_param":[0,1,2] /*Z-Wave alarm event parameters(optional)*/
],
"result":[ /*The block that contains the resultant report. Cannot be
empty */
/*If a property is missing, it will follow the same value from the original report*/
{
"zw_alarm_event": 7 /*Z-Wave alarm event(optional)*/
}
]
}
]
}
]
{
}
],
"alarm_type_name": "Access Control", /*Alarm type name (optional)*/
"zw_alarm_event":5, /*Z-Wave alarm event mapped from vendor specific
alarm level (optional)*/
]
{
}
silabs.com | Building a more connected world.
Page 47 of 184
]
{
INS14129-5 Z-Ware Library User Guide 2018-05-02
},
{
"_comment": "X company sensors",
"vid":271, /* vendor or manufacturer id */
"ptype": 1792, /* product type id */
"pid":4096, /* product id */
"category":1, /* device category as defined in DEV_XXX */
"ep": [ /*endpoints */
{
"epid":0, /* Endpoint id (starting from 0 for virtual endpoint, 1 and onwards for
real endpoints) */
"create_interface":113, /* Create CC ID 113 (alarm CC) in this endpoint. This
interface must not already exist in the actual device and endpoint */
"create_interface_version":4, /* Version for the created CC */
"interface":[ /*interfaces*/
{
"if_type": 7, /*interface type as defined in IF_REC_TYPE_XXX */
"basic":[
{
"match":[ /*The block that contains the original basic command data to
compare against. Cannot be empty */
/*All the properties need to met for the conversion to happen. If a property is missing, it
will not be included for comparison*/
{
"command": 1, /*Basic CC command. eg. BASIC_SET*/
"value":0,/* Command value 0-255. -1 means don't care. */
"result_if_type": 6 /* Type of the resulted conversion as defined in
IF_REC_TYPE_XXX*/
}
],
"result":[ /*The block that contains the resultant report. Cannot be
empty.*/
/*Content of this block will depends on the value of "result_if_type" in the match block. */
{
"zw_alarm_type": 6, /*Z-Wave alarm type (optional)*/
"alarm_type_name": "Access Control", /*Alarm type name (optional)*/
"zw_alarm_event":11, /*Z-Wave alarm event(optional)*/
"alarm_level_name":"Lock is Jammed" /*Alarm level name (optional)*/
}
]
},
{
"match":[
{
"command": 1, /*Basic CC command. eg. BASIC_SET*/
"value":255, /* Command value 0-255. -1 means don't care. */
"result_if_type": 6 /* Type of the resulted conversion as defined in
IF_REC_TYPE_XXX*/
}
],
"result":[
{
"zw_alarm_type": 6, /*Z-Wave alarm type (optional)*/
"alarm_type_name": "Access Control", /*Alarm type name (optional)*/
"zw_alarm_event":5, /*Z-Wave alarm event(optional)*/
"alarm_level_name":"Keypad Lock" /*Alarm level name (optional)*/
}
]
}
]
}
]
}
]
},
silabs.com | Building a more connected world.
Page 48 of 184
"_comment": "X company alarm sensors",
"zw_alarm_event":4, /*Z-Wave alarm event(optional)*/
INS14129-5 Z-Ware Library User Guide 2018-05-02
"vid":271, /* vendor or manufacturer id */
"ptype": 1792, /* product type id */
"pid":4096, /* product id */
"category":1, /* device category as defined in DEV_XXX */
"ep": [ /*endpoints */
{
"epid":0, /* Endpoint id (starting from 0 for virtual endpoint, 1 and onwards for
real endpoints) */
"create_interface":113, /* Create CC ID 113 (alarm CC) in this endpoint. This
interface must not already exist in the actual device and endpoint */
"create_interface_version":4, /* Version for the created CC */
"interface":[ /*interfaces*/
{
"if_type": 8, /*interface type as defined in IF_REC_TYPE_XXX */
"no_event_clear": 1, /*indicate the interface is not capable to sent event
clear, i.e. alarm sensor value of zero (optional); 1=not capable; 0 or absent of this
field=capable. */
"event_clear_timeout": 60, /*timeout in seconds (max: 3600 s), to generate
event_clear callback to user application. This field is only valid when "no_event_clear" = 1.
Default is 5 minutes.(optional)*/
"hidden":1, /*hide this interface from user application (optional)*/
"alrm_snsr":[
{
/*Each element must contain "match" and "result" block, in the order of
“match" followed by "result"*/
match":[ /*The block that contains the original alarm sensor command data
to compare against. Cannot be empty */
/*All the properties need to met for the conversion to happen. If a property is missing, it
will not be included for comparison*/
{
"type": 5, /*Alarm sensor type. eg. Water leak*/
"state":0, /* One Alarm sensor state value 0-255. -1 means don't
care. */
"result_if_type": 6 /* Type of the resulted conversion as defined in
IF_REC_TYPE_XXX*/
}
],
"result":[ /*The block that contains the resultant report. Cannot be
empty*/
/*Content of this block will depends on the value of "result_if_type" in the match block. */
{
"zw_alarm_type": 5, /*Z-Wave alarm type (optional)*/
"alarm_type_name": "Water Alarm", /*Alarm type name (optional)*/
"zw_alarm_event":0, /*Z-Wave alarm event(optional)*/
"alarm_level_name":"Event inactive", /*Alarm level name (optional)*/
"zw_alarm_param_type":5, /*Z-Wave alarm param type (optional)*/
"zw_alarm_param":[4] /*Z-Wave alarm parameters (optional)*/
}
]
},
{
"match":[
{
"type": 5, /*Alarm sensor type. eg. Water leak*/
"state_range":[1,255], /* All Alarm sensor state values within
the range. */
"result_if_type": 6 /* Type of the resulted conversion as defined in
IF_REC_TYPE_XXX*/
}
],
"result":[
{
"zw_alarm_type": 5, /*Z-Wave alarm type (optional)*/
"alarm_type_name": "Water Alarm", /*Alarm type name (optional)*/
silabs.com | Building a more connected world.
Page 49 of 184
"alarm_level_name":"Water level dropped" /*Alarm level name
}
INS14129-5 Z-Ware Library User Guide 2018-05-02
(optional)*/
}
]
}
]
}
]
}
]
},
{
"_comment": "X company thermostat setpoint",
"vid":271, /* vendor or manufacturer id */
"ptype":1882, /* product type id */
"pid":30, /* product id */
"category":27, /* device category as defined in DEV_XXX */
"ep": [ /*endpoints */
{
"epid":0, /* Endpoint id (starting from 0 for virtual endpoint, 1 and onwards
for real endpoints) */
"interface":[ /*interfaces*/
{
"if_type": 9, /*interface type as defined in IF_REC_TYPE_XXX */
"thrmo_setp":[
{
"type": 11, /* thermostat setpoint type, ZW_THRMO_SETP_TYP_XXX
*/
"min_unit": 0, /* Temparature unit, ZW_THRMO_SETP_UNIT_XXX*/
"min_value": "25.5", /* Minimum temparature value as string, may
contain decimal point */
"max_unit": 0, /* Temparature unit, ZW_THRMO_SETP_UNIT_XXX*/
"max_value": "30.5" /* Maximum temparature value as string, may
contain decimal point */
},
{
"type": 12, /* thermostat setpoint type, ZW_THRMO_SETP_TYP_XXX
*/
"min_unit": 0, /* Temparature unit, ZW_THRMO_SETP_UNIT_XXX*/
"min_value": "12.5", /* Minimum temparature value as string, may
contain decimal point */
"max_unit": 0, /* Temparature unit, ZW_THRMO_SETP_UNIT_XXX*/
"max_value": "28" /* Maximum temparature value as string, may
contain decimal point */
}
]
}
]
}
]
}
]
4.4 Network API
The network is seen through the eyes of a ZIPGW attached controller.
silabs.com | Building a more connected world.
Page 50 of 184
Attribute
Type
I/O
Description
cb
zwnet_gw_discvr_cb_t
I
Callback function when the scanning has completed
usr_param
void *
I
User defined parameter used in callback function
ipv4
int I Flag to indicate whether to use IPv4 as transport IP protocol.
use_mdns
int I Flag to indicate whether to use MDNS for gateway discovery.
return
void *
O
Context on success, NULL on failure. Caller is required to call
Attribute
Type
I/O
Description
gw_addr
uint8_t *
I
Gateway addresses. If ipv4 flag is set, each gateway address is 4-byte
long; else each gateway address is 16-byte long.
gw_cnt
uint8_t
I
Number of gateway addresses returned in gw_addr
ipv4
int I Flag to indicate the gw_addr parameter is IPv4 or IPv6.
usr_param
void *
I
User defined parameter passed when calling
zwnet_gw_discvr_start()
rpt_num
int I Report number that this callback is delivering the gateway addresses
total_rpt
int I Total reports that will be delivered by callbacks. Each callback
gw_name
char * *
I
Gateway names corresponding to the gw_addr. If NULL, it means
gateway name information is unavailable.
Attribute
Type
I/O
Description
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.4.1 zwnet_gw_discvr_start
This call starts a network scanning for ZIPGW IP addresses using ZIPGW Discovery protocol. Once the
scanning is done, the result will be available through a callback function. Take note that this function
can be called without calling the zwnet_init function first.
Table 78 – zwnet_gw_discvr_start Parameters
1= use IPv4; 0= use IPv6
Note: MDNS gateway discovery is only supported in ZIPGW
version 2.
zwnet_gw_discvr_stop() with the returned context if it is not
null.
Table 79 – zwnet_gw_discvr_cb_t Parameters
1=IPv4; 0=IPv6
report; start from 1
delivers one report. Zero is returned if there is no valid IP to facilitate
gateway discovery.
4.4.2 zwnet_gw_discvr_stop
This call stops the network scanning for ZIPGW IP addresses and free the resources used in network
scanning. Take note that this function should not be called in the callback function which was passed to
the zwnet_gw_discvr_start function as parameter cb.
Table 80 – zwnet_gw_discvr_stop Parameters
silabs.com | Building a more connected world.
Page 51 of 184
ctx
void *
I
The context returned from the call to zwnet_gw_discvr_start()
return
int O Zero on success, non-zero on failure.
Attribute
Type
I/O
Description
addr_str
char *
I
NULL terminated IPv4 / IPv6 address string
addr_buf
uint8_t *
O
Buffer that should be at least 16-byte long to store the result
ipv4
int *
O
Flag to indicate the converted numeric IP address is IPv4 or IPv6.
1=IPv4; 0=IPv6
return
int O Zero on success; non-zero on failure.
Attribute
Type
I/O
Description
addr
uint8_t *
I
IPv4 / IPv6 address in numerical form
addr_str
char *
O
Buffer to store the converted address string
addr_str_len
int I The size of the addr_str in bytes
ipv4
int I Flag to indicate the addr parameter is IPv4 or IPv6. 1=IPv4;
return
int O Zero on success, non-zero on failure.
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle from zwnet_init
dest_ip
uint8_t*
I
Destination host address either IPv4 or IPv6 according to
local_ip
uint8_t*
O
Buffer of 16-byte to store the local address (either IPv4 or IPv6
according to use_ipv4 flag)
use_ipv4
int I Flag to indicate IP address type. 1= IPv4; 0= IPv6
return
int O Zero on success, non-zero on failure.
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.4.3 zwnet_ip_aton
Utility to convert IPv4 / IPv6 address string to numeric equivalent.
Table 81 – zwnet_ip_aton Parameters
4.4.4 zwnet_ip_ntoa
Utility to convert IPv4 / IPv6 address in numerical form to string equivalent.
Table 82 – zwnet_ip_ntoa Parameters
0=IPv6
4.4.5 zwnet_local_addr_get
Utility to get local address that is reachable by destination host.
Table 83 – zwnet_local_addr_get Parameters
4.4.6 zwnet_listen_port_get
Utility to get local Z/IP listening port number.
use_ipv4 flag
silabs.com | Building a more connected world.
Page 52 of 184
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle from zwnet_init
return
uint16_t
O
The Z/IP client listening port number.
Attribute
Type
I/O
Description
init
zwnet_init_t *
I
user filled initialization information
net
zwnet_t **
O
handle to network for use in other zwnet_xxx API calls
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
user
void *
I
User context used in callbacks
host_port
uint16_t
I
Host listening and sending port
use_ipv4
Int I Flag to indicate whether to use IPv4 as transport IP
protocol. 1=use IPv4; 0=use IPv6
zip_router
uint8_t[16]
I
ZIPGW (gateway) IPv4/IPv6 address in numeric
notify
zwnet_notify_fn
I
Network operation notification
node
zwnet_node_fn
I
Node add/delete/status callback
appl_tx
zwnet_appl_fn
I
Application transmit data status callback
inif_cb
pl_info_fn
I
Unsolicited included node information frame (INIF)
unhandled_cmd
zwnet_unhandled_cmd_fn
I
Unhandled command callback
print_txt_fn
print_fn
I
Print text function pointer
portal_fd
#
int I Network file descriptor to connect to ZIPGW using
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 84 – zwnet_listen_port_get Parameters
4.4.7 zwnet_init
This call runs a state-machine to acquire the ZIPGW attached controller Home ID, controller’s Node ID,
HAN address and node list of the HAN. An internal network data structure is created and initialized
with each of the node id found in the acquired node list. User application could get access to the
controller Home ID and Node ID by calling zwnet_get_desc API only after the zwnet_notify_fn callback
function returns status is ZW_ERR_NONE.
To populate the internal network data structure with endpoints and interfaces, this API tries to retrieve
the node information from an internally maintained database. For those nodes found in the controller
routing table but do not have corresponding node information in the database, the node info statemachine is invoked to get the information (CCs supported, CC version, node name & location,
manufacturer id, product type id, product id and multi-instance/channel endpoints, etc) directly from
the node device.
Table 85 – zwnet_init Parameters
Table 86 – zwnet_init_t structure
format
callback when a Smart Start device (which has
joined a foreign network but it’s listed in the local
provisioning list) is powering up.
TLS
silabs.com | Building a more connected world.
Page 53 of 184
portal_ssl
#
void *
I
SSL object pointer to connect to ZIPGW using TLS
display_ctx
#
void *
I
Display context for the print_txt_fn
net_err
#
zwnet_net_err_fn
I
Unrecoverable network error callback, application
zwnet_exit()
portal_prof
#
clnt_prof_t
I
Profile of the ZIPGW that is connected to the portal
net_info_dir
const char *
I
Full path of directory for storing network and node
pref_dir
const char *
I
Full path of directory for storing network/user
preference files
dev_cfg_file
const char *
I
Device specific configurations file in JSON format. If
cmd_cls_cfg_file
const char *
I
Optional command classes configuration file.
dev_cfg_usr
dev_cfg_usr_t *
I
Device specific configurations (managed by user
internally. In this case
must be valid.
err_loc
dev_cfg_error_t
O
Error location while parsing device specific
sup_cmd_cls
sup_cmd_cls_t *
I
User application implemented CCs.NOTE: if the
sup_cmd_cls_cnt
uint8_t
I
User application implemented CCs count.
s2_unsolicited_cb
add_node_sec2_fn
I
Callback to report unsolicited joining device
dtls_psk*
uint8_t[32]
I
DTLS pre-shared key in binary format, MUST be at
dtls_psk_len*
uint8_t
I
DTLS pre-shared key length (bytes). If length is zero,
INS14129-5 Z-Ware Library User Guide 2018-05-02
should close this instance of Z-ware object, i.e. call
information file
it is NULL, device specific configurations will be
managed by user application. In this case
dev_cfg_usr must be valid.
Enable specific command classes probing after a
new node inclusion and during background polling.
If NULL, ALL supported command classes are
enabled.
application). If it is NULL, device specific
configurations will be managed by Z-ware library
dev_cfg_file
configuration file. Note: The error is not due to
JSON format parsing error.
controller has already implemented the CC, the
user's request for that CC will be ignored.
requested keys and/or status of Device Specific Key
(DSK)
least 16 bytes
Note: Attributes marked with (#) are only available for Portal version; whereas those marked with (*)
are only available for CE version.
Typical zwnet operations take in the network handle returned from this call and return the success
status of the operation as show in the table below. The parameters for such operations are not further
documented.
no DTLS will be used, i.e. communication will be
insecured
silabs.com | Building a more connected world.
Page 54 of 184
Attribute
Type
I/O
Description
dev_rec_find_fn
zwnet_dev_rec_find_fn
O
User supplied function to find device record
dev_cfg_ctx
void *
O
User specified device configuration context for use in
dev_glob_sett
dev_global_sett_t *
O
Optional device global settings
global_sett_cnt
uint16_t
O
Global settings count in dev_glob_sett
Attribute
Type
I/O
Description
dev_cfg_ctx
void *
I
User specified device configuration context
srch_key
dev_rec_srch_key_t *
I
Search key
matched_rec
dev_rec_t *
O
The matched record; either exact match or partial match
return
int O Non-zero if a match is found; else returns zero
Attribute
Type
I/O
Description
type
uint16_t
O
Setting type, GLOB_SET_TYPE_XXX:
XXX
Description
WKUP_INTV
Wakeup interval to set for a newly
WUNMI_DELAY
Send wakeup no more info delay for a
sett
union
O
Settings as indicated by setting type; union of the
wkup_intv
uint32_t
For GLOB_SET_TYPE_WKUP_INTV
wunmi_delay
uint16_t
For GLOB_SET_TYPE_WUNMI_DELAY
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle from zwnet_init
return
int O ZW_ERR_XXX
Attribute
Type
I/O
Description
user
void *
I
user context
src_node
uint8_t
I
source node id
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 87 – dev_cfg_usr_t structure
dev_rec_find_fn
Table 88 – zwnet_dev_rec_find_fn Parameters
as explained in the note below.
Note: This function supports "don't care" cases in device
specific configuration records.The search priority is as
follows (in the format (Manf id, Product Type, Product id))
: (V, V, V), (V, V, X), (V, X, X), (X, X, X)
where V="valid value"; X="don't care".
Table 89 – dev_global_sett_t structure
following:
added sleeping node
newly added sleeping node
Table 91 – zwnet_unhandled_cmd_fn Parameters
Table 90 – zwnet_xxx generic Parameters
silabs.com | Building a more connected world.
Page 55 of 184
src_ep
uint8_t
I
source endpoint id
cmd
uint8_t *
I
buffer that stores the unhandled command
cmd_len
Uint16_t
I
length of the unhandled command
Attribute
Type
I/O
Description
cls
uint16_t
O
CC
ver
uint8_t
O
Version of the CC
propty
uint8_t
O
Properties of the interface (bit-mask): BITMASK_CMD_CLS_XXX
BITMASK_CMD_CLS_INSECURE
CC is insecure
BITMASK_CMD_CLS_SECURE
CC is secure
Attribute
Type
I/O
Description
user
void *
I
from zwnet_init
op
uint8_t
I
operation ZWNET_OP_XXX
XXX
Description
NONE
Idle
INITIALIZE
Initializing local Z/IP controller
ADD_NODE
Adding a node
RM_NODE
Removing a node
RP_NODE
Replacing a failed node
RM_FAILED_ID
Removing a failed node
INITIATE
Initiating in response to or anticipation of some
operation
UPDATE
Updating network topology from SUC/SIS
RESET
Restoring ZIPGW attached controller to factory
NODE_UPDATE
Updating node information
MIGRATE
Migrating primary controller
SEND_NIF
Sending node information frame
NW_CHANGED
Network change detection
NODE_CACHE_UPT
Update node cached info (Internally used;
application won’t receive this notification)
SAVE_NW
Save network and node information to persistent
this notification)
SLEEP_NODE_UPT
Update sleeping node detailed information when
receive this notification)
FW_UPDT
Firmware update
HEALTH_CHK
Network health check
sts
uint16_t
I
status of current operation. When upper-byte is zero, the lower byte is the
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 92 – sup_cmd_cls_t structure
Table 93 – zwnet_notify_fn Parameters
default settings
storage. (Internally used; application won’t receive
it is awake. (Internally used; application won’t
current status of the operation (see table below). When upper-byte is non-
silabs.com | Building a more connected world.
Page 56 of 184
zero, it represents the total number of nodes to get detailed node
have completed getting detailed node information.
Operation:
Status
Description
All
DONE
Operation completed
FAILED
Operation failed
ADD_NODE
ADD_NODE_PROTOCOL_DONE
Protocol part done
ADD_NODE_GET_NODE_INFO
Getting node
detailed information
ADD_NODE_PROTOCOL_START
Smart Start add node
started
RP_NODE
RP_NODE_PROTOCOL_DONE
Protocol part done
RP_NODE_GET_NODE_INFO
Getting node
INITIATE
INI_PROTOCOL_DONE
Protocol part done
INI_GET_NODE_INFO
Getting node
detailed information
UPDATE
NU_TOPOLOGY
Network topology
NU_NEIGHBOR
Node neighbor
update started
NU_GET_NODE_INFO
Node information
FW_UPDT
FW_UPLOAD_STARTED
Uploading firmware
FW_UPLOADING
Uploading firmware
HEALTH_CHK
HEALTH_CHK_STARTED
Network health
HEALTH_CHK_PROGRESS
Network health
HEALTH_CHK_CMPLT
Network health
info
zwnet_sts_t
I
additional information for the specified op and sts; NULL if there is no
ret
int I ZW_ERR_XXX
Attribute
Type
I/O
Description
type
int
O
Type of info, ZWNET_STS_INFO_XXX
XXX
Description
INS14129-5 Z-Ware Library User Guide 2018-05-02
information; while the lower-byte represents the number of nodes that
ZWNET_OP_
OP_
Z-Wave protocol
detailed information
update started
*
update started
to device started
to device in progress
check started
check in progress
check completed
additional info
Table 94 – zwnet_sts_t structure
silabs.com | Building a more connected world.
Page 57 of 184
SS_START
Smart Start add node protocol started
OP_ADD_NODE_PROTOCOL_START)
FW_UPDT_PRG
Firmware update progress in
HEALTH_CHK_PRG
Network health check progress
HEALTH_CHK_RPT
Network health check completion
report
NODE_ID
Node id involved in the corresponding
info
union
O
Union of the following:
s2_dsk
char []
S2 DSK (for ZWNET_STS_INFO_SS_START)
progress_percent
uint8_t
Firmware update progress in % (for
ZWNET_STS_INFO_FW_UPDT_PRG)
health_chk_progress
zw_health_prg_t
Network health check progress (for
health_chk_rpt
zw_health_rpt_t
Network health check completion report (for
ZWNET_STS_INFO_HEALTH_CHK_RPT)
node_id
uint8_t
Node id (for ZWNET_STS_INFO_NODE_ID)
Attribute
Type
I/O
Description
node_cnt
uint8_t
O
Number of health check completed nodes
total
uint8_t
O
Total number of nodes scheduled for health check
Attribute
Type
I/O
Description
sts_cnt
uint8_t
O
Total number of node health status in the array
sts
zw_health_sts_t
O
Node health status array
Attribute
Type
I/O
Description
node_id
uint8_t
O
Node id
sts_cat
uint8_t
O
Status category which is derived from network health value:
NW_HEALTH_XXX
Description
GREEN
Network health is good
YELLOW
Network health is acceptable but latency can be
RED
Network health is insufficient because frames are
dropped
INS14129-5 Z-Ware Library User Guide 2018-05-02
(for ZWNET_OP_ADD_NODE and
percentage
network operation
[]
ZWNET_STS_INFO_HEALTH_CHK_PRG)
Table 95 – zw_health_prg_t structure
Table 96 – zw_health_rpt_t structure
Table 97 – zw_health_sts_t structure
observed occasionally
silabs.com | Building a more connected world.
Page 58 of 184
CRITICAL
Network health is critical because Z-Wave node is
value
uint8_t
O
Calculated network health value
Attribute
Type
I/O
Description
user
void *
I
from zwnet_init
node
zwnode_t *
I
node that was added, removed or updated
mode
uint8_t
I
0: added
Attribute
Type
I/O
Description
user
void *
I
from zwnet_init
tx_sts
uint8_t
I
transmission status ZWNET_TX_XXX
OK
Successful
NO_ACK
Send frame timeout due to no ACK received
SYS_ERR
System error, the program should exit or restart
DEST_BUSY
Message has not timed out yet. The destination host may
NOROUTE
Frame failed to reach destination host
Attribute
Type
I/O
Description
usr_ctx
void *
I
User context
lst_ent
struct pl_lst_ent *
I
Provisioning list entry
Attribute
Type
I/O
Description
user
void *
I
user context which was passed to zwnet_init
Attribute
Type
I/O
Description
msg
void *
I
Pointer to text messages
Attribute
Type
I/O
Description
INS14129-5 Z-Ware Library User Guide 2018-05-02
not responding at all
Table 98 – zwnet_node_fn Parameters
1: removed
2: updated
3: status alive
4: status down
5: status sleeping
Table 99 – zwnet_appl_fn Parameters
have a long response time (e.g. sleeping node)
Table 100 – pl_info_fn Parameters
Table 101 – zwnet_net_err_fn Parameters
Table 103 – zwnet_dev_rec_find_fn Parameter
Table 102 – print_fn Parameter
silabs.com | Building a more connected world.
Page 59 of 184
dev_cfg_ct
void *
I
User specified device configuration context
vid
uint16_t
I
Vendor or Manufacturer ID
ptype
uint16_t
I
Product Type ID
pid
uint16_t
I
Product ID
dev_rec
dev_rec_t *
O
Device record found
return
int O Non-zero on found; zero on not found
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle from zwnet_init
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle from zwnet_init
return
zwnetd_t *
O
network descriptor
Attribute
Type
I/O
Description
id
uint32_t
O
Z-Wave Home ID
ctl_id
uint8_t
O
Z/IP controller node id
ctl_role
uint8_t
O
Z/IP controller role. A bit-mask of ZWNET_CTLR_ROLE_XXX :
ZWNET_CTLR_ROLE_PROXY
Support Network Management
ZWNET_CTLR_ROLE_INCL
Support Network Management
ZWNET_CTLR_ROLE_PRI
Support Network Management
ctl_cap
uint8_t
O
Z/IP controller capabilities. A bit-mask of ZWNET_CTLR_CAP_XXX:
ZWNET_CTLR_CAP_S2
Support Security 2 protocol
ZWNET_CTLR_CAP_INC_ON_BEHALF
Support inclusion on-behalf
ZWNET_CTLR_CAP_SMART_START
Support Smart Start
ZWNET_CTLR_CAP_IMA
Support IMA (Z-Wave Network
ctl_zw_role
uint8_t
O
Z/IP controller Z-Wave role, ZW_ROLE_XXX:
ZW_ROLE_UNKNOWN
Unknown
INS14129-5 Z-Ware Library User Guide 2018-05-02
x
4.4.8 zwnet_exit
Clean up network and save detailed node information into file.
Table 104 – zwnet_exit Parameters
4.4.9 zwnet_get_desc
Get the read-only network descriptor for node enumeration and other purposes.
Table 105 – zwnet_get_desc Parameters
Table 106 – zwnetd_t structure
Proxy
Inclusion
Primary
Installation and maintenance)
silabs.com | Building a more connected world.
Page 60 of 184
ZW_ROLE_SIS
SIS
ZW_ROLE_INCLUSION
Inclusion controller
ZW_ROLE_PRIMARY
Primary controller
ZW_ROLE_SECONDARY
Secondary controller
user
void *
O
user context which was passed to zwnet_init
plt_ctx
void *
O
platform context for printing of output text messages
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle from zwnet_init
add
uint8_t
I
Operation
sec2_param
sec2_add_prm_t *
I
Parameters for adding node with security 2 protocol. This
incl_on_behalf
int I Flag to indicate enter into inclusion on-behalf (iob) mode;
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
usr_param
void *
O
User defined parameter used in callback
cb
add_node_sec2_fn
O
Callback to report joining device requested keys and/or status of
Device Specific Key (DSK)
dsk
char *
O
Optional Device Specific Key (DSK) of the joining node for
23669-20938-46346-33746-07431-56821-14553
Attribute
Type
I/O
Description
usr_param
void *
I
user supplied parameter when calling zwnet_add or zwnet_fail
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.4.10 zwnet_add
Called by inclusion controller to add/remove an initiating node to/from the network. On successful
addition, the new node is queried for its endpoints and interfaces, secure and otherwise. If the
interfaces are type sensor, the new node will be configured based on either the settings passed during
network initialization or the default values. It should result in callbacks to zwnet_node_fn followed by
zwnet_notify_fn.
Table 107 – zwnet_add Parameters
0 – remove
1 – add
parameter is ignored when non-security 2 ZIPGW is detected
or when removing node.
1=enter into iob mode, 0=normal add node. This parameter
is ignored when parameter add = 0 (i.e. remove node)
Table 108 – sec2_add_prm_t structure
Table 109 – add_node_sec2_fn Parameters
verification. Note that if this is not NULL, no DSK callback will be
executed.
The format of the DSK must be as shown in the example: 34028-
silabs.com | Building a more connected world.
Page 61 of 184
cb_param
sec2_add_cb_prm_t
I
DSK related callback parameters
Attribute
Type
I/O
Description
cb_type
uint8_t
O
Callback type as in S2_CB_TYPE_XXX :
XXX
Description
REQ_KEY
joining device requested keys
DSK
joining device DSK keys
req_key
sec2_keys_req_cb_prm_t
O
For cb_type=S2_CB_TYPE_REQ_KEY; the joining device
dsk
sec2_dsk_cb_prm_t
O
For cb_type=S2_CB_TYPE_DSK; the joining device DSK keys
Attribute
Type
I/O
Description
req_keys
uint8_t
O
Requested keys (bit mask) by the joining node
req_csa
uint8_t
O
Flag to indicate joining node is requesting Client-side
Authentication (CSA)
csa_pin
char [12]
O
CSA 10-digit PIN to be entered into the joining node if req_csa is
Attribute
Type
I/O
Description
pin_required
uint8_t
O
Indicate whether user is required to enter 5-digit pin.
1=required; 0=not required
dsk
char *
O
Device Specific Key (DSK) of the joining node for user to verify.
Attribute
Type
I/O
Description
net
zwnet_t *
I
Network handle
INS14129-5 Z-Ware Library User Guide 2018-05-02
*
Table 110 – sec2_add_cb_prm_t structure
requested keys and CSA request
Table 111 – sec2_keys_req_cb_prm_t structure
non-zero.
Example: 34028-23669 (Note: The hyphen is for display
purposes, it is not part of the PIN)
Table 112 – sec2_dsk_cb_prm_t structure
Note that the first 5 digits of DSK are missing if pin_required=1.
Example of complete DSK:
34028-23669-20938-46346-33746-07431-56821-14553
Example of DSK with first 5 digits missing:
-23669-20938-46346-33746-07431-56821-14553
4.4.11 zwnet_fail
Called by inclusion controller to replace/remove a failed node in the network. When replaced,
information on the node will be refreshed.
Table 113 – zwnet_fail Parameters
silabs.com | Building a more connected world.
Page 62 of 184
nodeid
uint8_t
I
Failed node id. This parameter is ignored when
replace
uint8_t
I
Operation
sec2_param
sec2_add_prm_t *
I
Optional parameters for replacing node with security 2
rplc_on_behalf
int I flag to indicate enter into "replace failed node" on-behalf
replace = 0.
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
Network handle
cb
get_dsk_fn
I
Callback to report ZIPGW DSK when joining another S2
usr_ctx
void *
I
user context used in callback
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
INS14129-5 Z-Ware Library User Guide 2018-05-02
rplc_on_behalf = 1.
0 – remove
1 – replace with an new initiating node
protocol. This parameter is ignored when removing failed
node (i.e. replace = 0).
(rob) mode; 1=enter into rob mode, 0=normal replace
failed node. This parameter is ignored when parameter
4.4.12 zwnet_migrate
This API is called by primary controller to transfer its primary controller role to another initiating
controller. The initiating controller must not be currently part of this network if it runs on older
firmware and a new node will be created with similar effect as with zwnet_add. With current firmware
the initiating controller can be a secondary controller in the network; in this case, no new node is
created. Upon completion, the controller invoking this function will become secondary controller. It
will then get node information from the new primary controller and resolve the primary controller node
id into IPv6 address.
4.4.13 zwnet_initiate
Indicates willingness to add/remove itself to/from the network or become the new primary. This action
is paired with a corresponding zwnet_add or zwnet_migrate from another controller. Upon
completion, it will rebuild its internal network structure if it has been added into a new network.
Table 114 – zwnet_initiate Parameters
capable Z-Wave network.
Note that the callback will not be invoked if the ZIPGW is not
S2 capable or this API is invoked to leave a Z-Wave network.
4.4.14 zwnet_initiate_classic
This API is provided mainly for backward compatibility to older Z-Wave controller which supports only
classic learn mode. For description and usage, please refer to the previous section zwnet_initiate.
silabs.com | Building a more connected world.
Page 63 of 184
Attribute
Type
I/O
Description
net
zwnet_t *
I
Network handle
cb
get_dsk_fn
I
Callback to report ZIPGW DSK when joining another S2
usr_ctx
void *
I
user context used in callback
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 115 – zwnet_initiate_classic Parameters
capable Z-Wave network.
Note that the callback will not be invoked if the ZIPGW is not
S2 capable or this API is invoked to leave a Z-Wave network.
4.4.15 zwnet_update
Updates network topology, routing table and internal network data structures. As it may take several
iterations to complete if there are nodes that are out of direct range, calling of this function should be
scheduled at a time of low network activity.
4.4.16 zwnet_abort
Abort current operation. User should be aware that aborting certain network operations such as add,
replace or joining/leaving a Z-wave network depends on the stage when the operation is aborted and
hence the operation may not be undone completely. For example, once the callback function
zwnet_notify_fn delivers the status of ADD_NODE_PROTOCOL_DONE, RP_NODE_PROTOCOL_DONE or
INI_PROTOCOL_DONE (for joining a network) the device has already been added to the Z-wave network
and aborting the operation at this moment still results in the node being added. To undone the
operation completely, the user needs to execute remove node operation manually. Similarly, for leaving
a Z-wave network, if the callback function zwnet_notify_fn delivers the status of INI_PROTOCOL_DONE,
the Z/IP gateway attached controller has already been removed from the Z-wave network and aborting
the operation at this moment is considered too late. User has to manually execute the API
zwnet_initiate to join in back the Z-wave network.
4.4.17 zwnet_reset
Reset the state of the ZIPGW attached controller, losing all network information. Upon completion, it
will get the controller’s node information.
4.4.18 zwnet_health_chk
Start network health check on all but sleeping nodes. This is part of the Installation and Maintenance
(IMA) utility function. It is recommended to run the network health check during the period when
there are few or no network activities running as the process may take a long time to complete.
4.4.19 zwnet_get_node
Get the first node (local controller) in the network.
silabs.com | Building a more connected world.
Page 64 of 184
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
noded
zwnoded_t *
O
node handle
return
Int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
nodeid
uint8_t
I
node id
noded
zwnoded_t *
O
node descriptor (Can be NULL, if the purpose is to verify the
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
nodeid
uint8_t
I
node id
epid
uint8_t
I
endpoint id
epd
zwepd_t *
O
endpoint descriptor (Can be NULL, if the purpose is to verify the
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
nodeid
uint8_t
I
node id
epid
uint8_t
I
endpoint id
cls
uint16_t
I
interface id (CC)
ifd
zwifd_t *
O
interface descriptor (Can be NULL, if the purpose is to verify the
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 116 – zwnet_get_node Parameters
4.4.20 zwnet_get_node_ by_id
Get node with specified node id in the network.
Table 117 – zwnet_get_node_by_id Parameters
existence of a node)
4.4.21 zwnet_get_ep_ by_id
Get endpoint with specified node and endpoint id in the network.
Table 118 – zwnet_get_ep_by_id Parameters
existence of an endpoint)
4.4.22 zwnet_get_if_ by_id
Get interface with specified node, endpoint and interface id in the network.
Table 119 – zwnet_get_if_by_id Parameters
existence of an interface)
silabs.com | Building a more connected world.
Page 65 of 184
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle from zwnet_init
return
void *
O
user context which was passed as parameter when calling zwnet_init
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
noded
zwnoded_t *
I
handle of the destination node that will receive the node
broadcast
uint8_t
I
broadcast flag. 1= broadcast; 0= single cast
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
node_sts_buf
uint8_t *
O
Buffer (min. size of 233 bytes) to store all the node status.
using the node id as index to the buffer.
ZWNET_NODE_STS_SLEEP
Node is sleeping
ZWNET_NODE_STS_DOWN
Node is down
ZWNET_NODE_STS_UP
Node is alive
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
node_id
uint8_t
I
Node id (ranging from 1 to 232)
return
uint8_t
O
node status (ZWNET_NODE_STS_XXX)
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.4.23 zwnet_get_user
Get the user context associated with the network handle.
Table 120 – zwnet_get_user Parameters
4.4.24 zwnet_send_nif
Send node information frame (NIF) to a node or broadcast to the network.
Table 121 – zwnet_send_nif Parameters
4.4.25 zwnet_all_node_sts_get
Get all node status.
Table 122 – zwnet_all_node_sts_get Parameters
4.4.26 zwnet_node_sts_get
Get node status.
information frame. NULL for broadcast of NIF.
Individual node status (ZWNET_NODE_STS_XXX) can be accessed
Table 123 – zwnet_node_sts_get Parameters
silabs.com | Building a more connected world.
Page 66 of 184
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
handle
uint16_t
I
handle of the polling request to remove
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
usr_token
uint32_t
I
user token of the polling request to remove
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
buf
void *
I
Buffer that contains the network preference
buf_size
uint16_t
I
Buffer size in bytes
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
buf
void **
O
Return buffer that contains the network preference
buf_size
uint16_t *
O
Buffer size in bytes
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.4.27 zwnet_poll_rm
Remove a polling request.
Table 124 – zwnet_poll_rm Parameters
4.4.28 zwnet_poll_rm_mul
Remove multiple polling requests.
Table 125 – zwnet_poll_rm_mul Parameters
4.4.29 zwnet_pref_set
Store network preference into persistent storage.
Table 126 – zwnet_pref_set Parameters
4.4.30 zwnet_pref_get
Retrieve network preference from persistent storage.
Table 127 – zwnet_pref_get Parameters
Note: Caller MUST free the return buffer "buf" if the call is
successful.
silabs.com | Building a more connected world.
Page 67 of 184
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
client_id
uint32_t
I
User-defined client id to identify the preference
buf
void *
I
Buffer that contains the client preference
buf_size
uint16_t
I
Buffer size in bytes
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
client_id
uint32_t
I
User-defined client id to identify the preference
buf
void **
O
Return buffer that contains the client preference
buf_size
uint16_t *
O
Buffer size in bytes
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
accept
int I 1=accept; 0=reject
dsk
char *
I
Complete Device Specific Key (DSK) of the added node if accept=1;
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.4.31 zwnet_client_pref_set
Store client preference into persistent storage.
Table 128 – zwnet_client_pref_set Parameters
4.4.32 zwnet_client_pref_get
Retrieve client preference from persistent storage.
Table 129 – zwnet_client_pref_get Parameters
Note: Caller MUST free the return buffer "buf" if the call is
successful.
4.4.33 zwnet_add_sec2_accept
Accept or reject newly added node into security 2 mode. This function should be called only after
receiving security 2 DSK callback during add or replace failed node operation.
Table 130 – zwnet_add_sec2_accept Parameters
else this can be NULL
4.4.34 zwnet_add_sec2_grant_key
Grant keys and CSA to the newly added node in security 2 mode. This function should be called only
after receiving security 2 requested keys callback during add or replace failed node operation.
Table 131 – zwnet_add_sec2_grant_key Parameters
silabs.com | Building a more connected world.
Page 68 of 184
net
zwnet_t *
I
network handle
granted_keys
uint8_t
I
security 2 granted keys (bit-mask) as in SEC_KEY_BITMSK_XXX
XXX
Description
S2_K0
S2: class key 0 (Unauthenticated devices)
S2_K1
S2: class key 1 (Authenticated devices)
S2_K2
S2: class key 2 (Access control devices)
S0
S0: legacy security network key
grant_csa
uint8_t
I
grant client-side authentication (CSA); 1=grant, 0=reject. If
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
cb
get_dsk_fn
I
callback to report ZIPGW DSK
usr_ctx
void *
I
user context used in callback
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
usr_ctx
void *
I
user context
dsk
char *
I
ZIPGW DSK string
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
dsk
char *
I
Device Specific Key (DSK). The format of the DSK must be 8
info
pl_info_t *
I
Buffer to store additional information of the device (optional).
info_cnt
uint8_t
I
Number of additional information stored in "info"
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
INS14129-5 Z-Ware Library User Guide 2018-05-02
joining node didn't request CSA, it is ignored.
4.4.35 zwnet_sec2_get_dsk
Get ZIPGW security 2 DSK.
4.4.36 zwnet_pl_add
Add a provisioning list entry.
Table 132 – zwnet_sec2_get_dsk Parameters
Table 133 – get_dsk_fn Parameters
Table 134 – zwnet_pl_add Parameters
Table 135 – pl_info_t structure
groups of 5 digits separated by '-' as shown in the example:
34028-23669-20938-46346-33746-07431-56821-14553
Info type PL_INFO_TYPE_NW_STS must not be used in this
function.
silabs.com | Building a more connected world.
Page 69 of 184
Attribute
Type
I/O
Description
type
uint8_t
O
Info type, PL_INFO_TYPE_XXX
XXX
Description
PROD_TYPE
Product type
PROD_ID
Product ID
INC_INTV
Smart Start inclusion request interval used by
UUID16
UUID assigned to the node
NAME
Device name
LOC
Device location
INCL_STS
Inclusion status of the provisioning list entry
S2_GRNT
S2 keys to be granted
BOOT_MODE
Bootstrapping mode
NW_STS
Network status of the provisioning list entry
info
union
O
Provisioning list entry information. The union of the following:
name
char [63]
O
For type PL_INFO_TYPE_NAME; device name in UTF-8 encoding.
terminated by NUL character
loc
char [63]
O
For type PL_INFO_TYPE_LOC; device location in UTF-8 encoding
prod_type
pl_prod_type_t
O
For type PL_INFO_TYPE_PROD_TYPE; product type
prod_id
pl_prod_id_t
O
For type PL_INFO_TYPE_PROD_ID; product id
interval
uint8_t
O
For type PL_INFO_TYPE_INC_INTV; Smart Start inclusion request
uuid
pl_uuid_t
O
For type PL_INFO_TYPE_UUID16; UUID assigned to the node as
defined by IETF RFC 4122
nw_sts
pl_nw_sts_t
O
For type PL_INFO_TYPE_NW_STS; network status of the
incl_sts
uint8_t
O
For type PL_INFO_TYPE_INCL_STS; inclusion status of the
XXX
Description
PENDING
The node will be included in the network when
PASSIVE
The node is in the Provisioning List but it has
INS14129-5 Z-Ware Library User Guide 2018-05-02
the node
It must not contains period character '.', underscore character '_'
and must not end with the dash character '-' and must be
with same restrictions as name field.
interval in unit of 128 seconds. This field must have value ranging
from 5 to 99.
provisioning list entry
provisioning list entry, PL_INCL_STS_XXX
it issues SmartStart inclusion requests
been decided by the supporting or controlling
node that the node is unlikely to issue
SmartStart inclusion requests in the near
future.
SmartStart Inclusion requests will be ignored
by the Z/IP Gateway. All entries with this status
MUST be updated to the “Pending” status
silabs.com | Building a more connected world.
Page 70 of 184
(PL_INCL_STS_PENDING) when a Provisioning
IGNORED
SmartStart inclusion requests sent by the node
Client or controlling node.
grnt_keys
uint8_t
O
For type PL_INFO_TYPE_S2_GRNT; S2 keys to be granted, see
boot_mode
uint8_t
O
For type PL_INFO_TYPE_BOOT_MODE; Bootstrapping mode, as
in PL_BOOT_MODE_XXX
XXX
Description
S2
The node MUST manually be set to Learn Mode
any).
SMART_STRT
The node will be included and S2 bootstrapped
functionality.
Attribute
Type
I/O
Description
generic_cls
uint8_t
O
Generic device class
specific_cls
uint8_t
O
Specific device class
icon_type
uint16_t
O
Installer icon type
Attribute
Type
I/O
Description
manf_id
uint16_t
O
Manufacturer ID
prod_type
uint16_t
O
Product type
prod_id
uint16_t
O
Product ID
app_ver
uint8_t
O
Application version
app_sub_ver
uint8_t
O
Application sub version
Attribute
Type
I/O
Description
pres_fmt
uint16_t
O
Presentation format, as in UUID_PRES_XXX
XXX
Description
32HEX
32 hex digits, no delimiters
16ASCII
16 ASCII chars, no delimiters
SN_32HEX
"sn:" followed by 32 hex digits, no delimiters
SN_16ASCII
"sn:" followed by 16 ASCII chars, no delimiters
UUID_32HEX
"UUID:" followed by 32 hex digits, no
delimiters
INS14129-5 Z-Ware Library User Guide 2018-05-02
List Iteration Get Command is received.
in the Provisioning List entry will be ignored
until the status is changed again by a Z/IP
SEC_KEY_BITMSK_XXX
and follow the S2 bootstrapping instructions (if
automatically using the Smart Start
Table 136 – pl_prod_type_t structure
Table 137 – pl_prod_id_t structure
Table 138 – pl_uuid_t structure
silabs.com | Building a more connected world.
Page 71 of 184
UUID_16ASCII
"UUID:" followed by 16 ASCII chars, no
RFC4122
RFC4122 compliant presentation (e.g.
“58D5E212-165B-4CA0-909B-C86B9CEE0111”)
uuid
uint8_t[16]
O
UUID assigned to the node as defined by IETF RFC 4122
Attribute
Type
I/O
Description
node_id
uint8_t
O
NodeID that has been assigned to the Provisioning List entry
status
uint8_t
O
network status of the Provisioning List entry, as in
XXX
Description
NOT_INCL
The node in the Provisioning List is not
ADDED
The node in the Provisioning List is included in
FAILED
The node in the Provisioning List has been
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
dsk
char *
I
Device Specific Key (DSK). The format of the DSK must be 8 groups
34028-23669-20938-46346-33746-07431-56821-14553
cb
pl_info_fn
I
callback to report provisioning entry information
usr_ctx
void *
I
user context used in callback
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
usr_ctx
void *
I
user context
lst_ent
pl_lst_ent_t *
I
provisioning list entry
Attribute
Type
I/O
Description
INS14129-5 Z-Ware Library User Guide 2018-05-02
delimiters
Table 139 – pl_nw_sts_t structure
during network inclusion. 0 indicates that the NodeID is not
assigned.
PL_NW_STS_XXX
4.4.37 zwnet_pl_get
Get a provisioning list entry information through callback.
Table 140 – zwnet_pl_get Parameters
of 5 digits separated by '-' as shown in the example:
currently included (added) in the network.
the network and is functional.
included in the Z-Wave network but is now
marked as failing.
Table 141 – pl_info_fn Parameters
Table 142 – pl_lst_ent_t structure
silabs.com | Building a more connected world.
Page 72 of 184
dsk
char [48]
O
Device Specific Key (DSK). The format of the DSK must be 8
34028-23669-20938-46346-33746-07431-56821-14553
info
pl_info_t[10]
O
Information of the device
info_cnt
uint8_t
O
Number of information stored in "info". If zero, the dsk is not
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
dsk
char *
I
Device Specific Key (DSK). The format of the DSK must be 8
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
cb
pl_list_fn
I
callback to report provisioning list entries
usr_ctx
void *
I
user context used in callback
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
usr_ctx
void *
I
user context
pl_list
pl_lst_ent_t
I
provisioning list
ent_cnt
uint8_t
I
number of entries in provisioning list 'pl_list'
lst_cmplt
int I Flag to indicate whether all the entries in 'pl_list' represent the whole list
INS14129-5 Z-Ware Library User Guide 2018-05-02
groups of 5 digits separated by '-' as shown in the example:
found in the provisioning list
4.4.38 zwnet_pl_del
Delete a provisioning list entry.
Table 143 – zwnet_pl_del Parameters
groups of 5 digits separated by '-' as shown in the example:
34028-23669-20938-46346-33746-07431-56821-14553
4.4.39 zwnet_pl_list_get
Get all provisioning entries through callback.
Table 144 – zwnet_pl_list_get Parameters
Table 145 – pl_list_fn Parameters
*
in ZIPGW. 1=all the entries have been retrieved from ZIPGW; 0=some of
the entries were not retrieved due to error.
4.4.40 zwnet_pl_list_del
Delete all provisioning list entries.
silabs.com | Building a more connected world.
Page 73 of 184
Attribute
Type
I/O
Description
net
zwnet_t *
I
network handle
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
nodeid
uint8_t
O
Z-Wave Node ID
propty
uint8_t
O
Properties of the node (bit-mask): NODE_PROPTY_XXX
vid
uint16_t
O
Z-Wave Vendor ID
type
uint16_t
O
Vendor type
pid
uint16_t
O
Z-Wave Product ID
net
zwnet_t *
O
Network handle
dev_id
dev_id_t
O
Device ID
proto_ver
uint16_t
O
Z-Wave Protocol Version
app_ver
uint16_t
O
Application Version
lib_type
uint8_t
O
Z-Wave Library Type
category
uint8_t
O
Device category, DEV_XXX
sensor
uint8_t
O
Flag to indicate whether the node is a sensor (FLIRS)
sleep_cap
uint8_t
O
Flag to indicate the node is capable to sleep (i.e. non-listening and
listen
uint8_t
O
Flag to indicate the node is always listening
wkup_intv
int32_t
O
Wake up interval in seconds. Negative value = invalid or unknown
s2_keys_valid
uint8_t
O
Flag to indicate whether s2_grnt_keys is valid
s2_grnt_keys
uint8_t
O
Security 2 granted keys (bit-mask), see SEC_KEY_BITMSK_XXX
NOTE: This is valid only s2_keys_valid = 1
s2_dsk
char[]
O
S2 DSK. If s2_dsk[0] == '\0', the DSK is unavailable for this node
Node property bit-mask
Description
NODE_PROPTY_SECURE_CAP_S0
Node capable to be included securely S0
NODE_PROPTY_SECURE_CAP_S2
Node capable to be included securely S2
NODE_PROPTY_ADD_SECURE
Node is included securely
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 146 – zwnet_pl_list_del Parameters
4.5 Node API
This corresponds to a Z-Wave device (node) and is coupled with Manufacturer Specific CC and Node
Naming and Location CC information. It also contains APIs for sleep command queuing and command
recording.
4.5.1 zwnoded_t
This is the descriptor used to access Z-Wave nodes. Only name and location fields are writeable.
Table 147 – zwnoded_t structure
support Wake up CC)
Table 148 – NODE_PROPTY_XXX
silabs.com | Building a more connected world.
Page 74 of 184
NODE_PROPTY_ADD_INSECURE
Node is included insecurely
Attribute
Type
I/O
Description
type
uint8_t
O
device id type: DEV_ID_TYPE_XXX, where
DEV_ID_TYPE_OEM
OEM factory default
DEV_ID_TYPE_SN
serial number
DEV_ID_TYPE_RANDOM
pseudo random number
format
uint8_t
O
device id data format: DEV_ID_FMT_XXX, where
DEV_ID_FMT_UTF
UTF-8
DEV_ID_FMT_BIN
binary and MUST be
len
uint8_t
O
device id length
dev_id
uint8_t[MAX_DEV_ID_LEN
O
device id
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
node handle
return
zwnet_t *
O
network handle
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
node handle
next
zwnoded_t *
O
next node handle
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
node handle
epd
zwepd_t *
O
endpoint handle
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 149 – dev_id_t structure
displayed as hexadecimal,
e.g. h’30313233A1
+ 1]
4.5.2 zwnode_get_net
Get handle to the network containing this node.
Table 150 – zwnode_get_net Parameters
4.5.3 zwnode_get_next
Get next node in network. The first i.e. local controller node may be obtained from zwnet_get_node.
Table 151 – zwnode_get_next Parameters
4.5.4 zwnode_get_ep
Get first endpoint in the node.
Table 152 – zwnode_get_ep Parameters
silabs.com | Building a more connected world.
Page 75 of 184
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
node handle
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
Node descriptor
enable
uint8_t
I
enable = 1 to enable command queuing; enable = 0 to disable
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
Node descriptor
enable
uint8_t *
O
enable = 1 indicates command queuing is enable; enable = 0
indicates command queuing is disable.
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
Node descriptor
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.5.5 zwnode_update
Updates node status and information.
Table 153 – zwnode_update Parameters
4.5.6 zwnode_cmd_q_ena_set
This call controls the command queuing facility for sleeping node.
Table 154 – zwnode_cmd_q_ena_set Parameters
command queuing.
4.5.7 zwnode_cmd_q_ena_get
Get the command queuing state for sleeping node.
Table 155 – zwnode_cmd_q_ena_get Parameters
4.5.8 zwnode_cmd_q_cancel
Cancel or remove all the commands in the queue for sleeping node.
Table 156 – zwnode_cmd_q_ena_cancel Parameters
4.5.9 zwnode_cmd_q_get
This call gets a copy of the command queue associated with the specified sleeping node.
silabs.com | Building a more connected world.
Page 76 of 184
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
Node descriptor
cmd_q
uint16_t **
O
A copy of the command queue is allocated and assigned to the
return
uint8_t
O
The number of entries in cmd_q. Each entry is 2-byte wide.
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
Node descriptor
on
uint8_t
I
1=turn on multi command encapsulation; 0=turn off and flush
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
Node descriptor
on
uint8_t *
O
state: 1=on; 0=off.
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
noded
zwnoded_t *
I
Node descriptor
return
ext_ver_t *
O
Extended version information if the node supports it; else return
Attribute
Type
I/O
Description
hw_ver
uint8_t
I
Hardware version
fw_cnt
uint8_t
I
Number of firmwares in the device, excluding the Z-Wave firmware
fw_ver
uint16_t[]
I
Firmware versions place holder as indicated in fw_cnt
INS14129-5 Z-Ware Library User Guide 2018-05-02
Table 157 – zwnode_cmd_q_get Parameters
cmd_q.
4.5.10 zwnode_mul_cmd_ctl_set
Turn on/off multi command encapsulation capability. By default, if a node support Multi-command CC,
the multi command encapsulation capability is turn on automatically.
Table 158 – zwnode_mul_cmd_ctl_set Parameters
(send) the commands in the buffer.
4.5.11 zwnode_mul_cmd_ctl_get
Get the current state of multi command encapsulation.
Table 159 – zwnode_mul_cmd_ctl_get Parameters
4.5.12 zwnode_get_ext_ver
Get extended version information.
Table 160 – zwnode_get_ext_ver Parameters
NULL.
Note: Caller has to free the returned extended version information
Table 161 – ext_ver_t structure
silabs.com | Building a more connected world.
Page 77 of 184
Attribute
Type
I/O
Description
generic
uint8_t
O
Z-Wave Generic device class
specific
uint8_t
O
Z-Wave Specific device class
epid
uint8_t
O
Endpoint number
nodeid
uint8_t
O
Node ID
aggr_ep_cnt
uint8_t
O
Total number of end point members that are represented by this
aggr_members
uint8_t[126]
O
Buffer to store the end point members that are represented by this
net
zwnet_t *
O
Network handle
name
char [33]
O
User configured name string of the endpoint
loc
char [33]
O
User configured location string of the endpoint
zwplus_info
zwplus_info_t
O
Z-Wave+ information
Attribute
Type
I/O
Description
zwplus_ver
uint8_t
O
Z-Wave+ version. Zero indicates this node is non-Z-Wave+
node_type
uint8_t
O
Z-Wave+ node type
role_type
uint8_t
O
Z-Wave+ role type
instr_icon
uint16_t
O
Installer icon type
usr_icon
uint16_t
O
User icon type
Attribute
Type
I/O
Description
epd
zwepd_t *
I
endpojnt handle
noded
zwnoded_t *
O
node handle
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.6 Endpoint API
This corresponds to Z-Wave channels or instances and is coupled with NodeInfo information. The APIs
here are mostly accessor functions.
4.6.1 zwepd_t
This is the read-only descriptor used to access endpoints.
Table 162 – zwepd_t structure
4.6.2 zwep_get_node
Get containing node handle.
aggregated end point. Zero means this endpoint is NOT an
aggregated end point
aggregated end point
Table 163 – zwplus_info_t structure
Table 164 – zwep_get_node Parameters
silabs.com | Building a more connected world.
Page 78 of 184
Attribute
Type
I/O
Description
epd
zwepd_t *
I
endpojnt handle
nxt_epd
zwepd_t *
O
next endpoint handle
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
epd
zwepd_t *
I
endpojnt handle
Ifd
zwifd_t *
O
interface handle
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
epd
zwepd_t *
I
endpojnt handle
nameloc
zw_nameloc_t *
I
NULL terminated name and location strings
return
int O ZW_ERR_NONE on success; else ZW_ERR_XXX
Attribute
Type
I/O
Description
name
char[33]
I
Node name
loc
char[33]
I
Node location
INS14129-5 Z-Ware Library User Guide 2018-05-02
4.6.3 zwep_get_next
Get next endpoint in node.
Table 165 – zwep_get_next Parameters
4.6.4 zwep_get_if
Get first interface in endpoint.
Table 166 – zwep_get_if Parameters
Note: Caller must free ifd->data if ifd->data_cnt is greater than zero.
4.6.5 zwep_nameloc_set
Set endpoint name and location string for device regardless whether the endpoint has Node Naming
And Location interface. If it does, the strings will be sent to the interface physically for storing in the
device.
Table 167 – zwep_nameloc_set Parameters
Table 168 – zw_nameloc_t structure
4.7 Interface API
This corresponds to Z-Wave CCes coupled with the corresponding Version CC information. Some of the
CCes, like security CC, multi-channel CC and multi-command CC are handled transparently. Basic CC is
added automatically to all endpoints even if it is not listed in the endpoint’s "multichannel capability
report".
Loading...