Silicon Labs Z-Ware SDK 7.13.0 Web Developer Reference guide

Silicon Labs
Brand
Silicon Labs
Model
Z-Ware SDK 7.13.0 Web Developer
Type
Reference guide
`
Instruction
Z-Ware SDK 7.13.0 Web Developer Guide
Document No.:
INS 14430
Version:
1
Description:
The Web API exported by Z-Ware Web Server, a Z/IP client that acts as a Z-Wave
Web Gateway
Written By:
SAMBAT;YANYAN;KSUNDARAM
Date:
2019-11-18
Reviewed By:
SOTHAYOTH;TNATARAJAN
Restrictions:
Public
Approved by:
Date CET Initials Name Justification
2019-11-18 02:01:53 NTJ Niels 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.
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page ii of ix
Doc. Ver.
Date
By
Pages affected
Brief description of changes
1
20180806
AYY
2, 11-12, 15-16,
18, 36, 40, 43, 54,
56-59, 62, 66, 70,
82-83, 84-92, 97-
99, 123
Cloned for SDK 7.00.00 from INS14167
Update supported CC list and versions.
Update network information API with timestamp.
Updated Library version info.
Updated Command queue list.
Added 3-part-versioning.
Added CCs Version v3, Multilevel Switch v3, Meter v4-5. Configuration v3-4,
Sound Switch v1,Doorlock v4, Indicator v1-3,Time v1-2.
Updated Alarm Report Event for Scene/Security Scene event.
Added State number for Binary Switch, Mutilevel Switch, Doorlock,
Thermostat Fan mode, Thermostat Mode, Thermostat Setpoint, Indicator and
Barrier Operator CCs.
2
20181011
AYY
7, 8, 19-20, 22 -
25, 31, 33, 39,
61-62
Updated registration API error code.
Removed v1 Web API response for S2 inclusion Web APIs.
Updated current network operation response to include affected Node ID info.
Corrected parameter info for remove/replace failed node.
Clarified error response format for all the CCs in CMD_BASIC_SETUP.
Added NODE_RESET network operation and info notes.
Added Firmware update network operation.
Made user code param to be optional for deleting a user code.
Added parameter information for network health check get info API.
Update Web API error response format.
3
20190305
AYY
16-17, 19-20, 23-
25, 39-40, 42-43,
46-48, 63-68, 86-
88, 95-97, 108-
109, 129-130,
132
Added State number for Basic, Color Switch and Sound Switch CCs.
Added Window Covering CC API.
Added Firmware backup function Web API.
Added Firmware backup operation and completed bytes in Get Current
Network Operation API.
Remove ‘wkup_intv’ attribute in List Nodes API.
Added Multilevel Switch Level Change Set as Scene Action.
Updated Color Switch Set Action with optional color_dur parameter.
Update Central Scene Command Event with additional key attribute (Value 1
to 6).
Added User Code CC v2 API.
Added Binary Switch CC v2 Duration support.
Added S2 inclusion set grant key API with ‘accept’ support.
4
20190531
AYY
111
103
102
120-121, 123
137
51, 52
118-119
112
Added new completion code for Firmware update command.
Added comment for Node association in Asoociation/Multichannel
association.
Added missing param_id in Window Covering CC stop level change API.
Added ‘stateless’ scene status and scene action status.
Added Sound Switch Tone play set for Scene action.
Added functionality for Binary Sensor CC Get command to yield all cached
sensor reports from different types in server.
Added documentation for Z/IP Portal Interface.
Added Firmware Update CC v6 API.
5
20190912
SNA
AYY
15, 89, 97, 120
132,
150,
151,152,
147
49
v1.39 for SDK v7.11.2
APIs: zw_feature, Battery v2, Sound Switch v2, Firmware Update v7
Scene: ‘active + stateless’ status.
Scene: Scene Sound Switch Tone Play Set Action volume description
Scene: Window Covering action. Notification clear event trigger
Scene: feature web api version
Added missing Color Switch CC command numbering
6
20191113
AYY
2
89-90
65-67,
37
18
41
109-112
V1.41 for SDK v7.12.0
Update Table for supported Command Classes.
Added ‘size’ param in Battery CC Health Get API.
Added Door Lock Logging CC v1 API.
Remove Command Queue feature.
Added new node property in Node List API.
Added ‘Node Identify’ API.
Added Protection CC v1-2 API.
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page iii of ix
Table of Contents
1 INTRODUCTION ..................................................................................................................................1
1.1 Purpose .............................................................................................................................................1
1.2 Audience and Requirements .............................................................................................................1
2 OVERVIEW ..........................................................................................................................................2
2.1 Command Classes ............................................................................................................................2
2.2 Objects ..............................................................................................................................................3
2.3 HTTP Mechanism..............................................................................................................................4
2.4 Sample Usage ...................................................................................................................................4
2.5 API Error Response...........................................................................................................................7
3 REGISTRATION API ...........................................................................................................................8
3.1 Register (Portal Only) ........................................................................................................................8
3.2 Login..................................................................................................................................................9
3.3 Logout................................................................................................................................................9
3.4 Change Password .............................................................................................................................9
3.5 Reset Password ..............................................................................................................................10
3.6 Unregister Account (Portal Only).....................................................................................................10
4 SYSTEM API......................................................................................................................................11
4.1 Platform and Version Numbers .......................................................................................................11
4.2 Connection Status (Portal Only) ......................................................................................................11
4.3 Information.......................................................................................................................................12
4.4 Z/IP Gateway (CE only)...................................................................................................................13
4.4.1 Initialize Z/IP Gateway...........................................................................................................13
4.4.2 Get Currently Used Z/IP Gateway.........................................................................................13
4.4.3 List Available Z/IP Gateways.................................................................................................14
4.5 Feature ............................................................................................................................................15
5 NETWORK API ..................................................................................................................................17
5.1 Get Information................................................................................................................................17
5.2 List Nodes........................................................................................................................................18
5.3 List Node/Endpoint Pairs .................................................................................................................20
5.4 Inclusion/Exclusion ..........................................................................................................................20
5.4.1 Query Device Requested Keys (S2 Security Only) ...............................................................21
5.4.2 Set Grant Key(s) (S2 Security Only) .....................................................................................21
5.4.3 Query Device DSK (S2 Security Only) ..................................................................................22
5.4.4 DSK Accept (S2 Security Only).............................................................................................22
5.4.5 Query Smart Start Device DSK (S2 Security Only)...............................................................22
5.5 Initiate ..............................................................................................................................................23
5.5.1 Query Local Node DSK (S2 Security Only)...........................................................................23
5.6 Send Node Information Frame (NIF) ...............................................................................................23
5.7 Update Network...............................................................................................................................24
5.8 Reset Network .................................................................................................................................24
5.9 Abort Network Operation .................................................................................................................24
5.10 Get Current Network Operation.......................................................................................................24
5.10.1 S2 Inclusion Flow Diagram....................................................................................................28
5.11 Provisioning List get ........................................................................................................................29
5.12 Provisioning List Device Info ...........................................................................................................31
5.13 Provisioning List Add .......................................................................................................................32
5.14 Provisioning List Remove ................................................................................................................32
5.15 Provisioning List Remove All ...........................................................................................................32
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page iv of ix
5.16 Provisioning List Inif Get..................................................................................................................32
5.17 Provisioning List Inif Acknowledge ..................................................................................................33
5.18 Network Health Check.....................................................................................................................33
5.19 Network Health Check Get Information ...........................................................................................34
6 NODE/ENDPOINT API.......................................................................................................................35
6.1 List Endpoints ..................................................................................................................................35
6.2 List Interfaces in Endpoint ...............................................................................................................36
6.3 Remove/Replace Failed Node.........................................................................................................36
6.4 Update Node ...................................................................................................................................37
6.5 Name/Location ................................................................................................................................37
6.5.1 Set .........................................................................................................................................37
6.6 Command Queue (Not supported) ..................................................................................................37
6.6.1 Get State ...............................................................................................................................40
6.6.2 Set State................................................................................................................................41
6.6.3 Get.........................................................................................................................................41
6.6.4 Cancel ...................................................................................................................................41
6.7 Node Identify ...................................................................................................................................41
7 BASIC INTERFACE API....................................................................................................................42
7.1 Select...............................................................................................................................................42
7.2 Get (Active)......................................................................................................................................43
7.3 Get (Passive)...................................................................................................................................43
7.4 Set ...................................................................................................................................................43
8 BINARY SWITCH INTERFACE API ..................................................................................................44
8.1 Select...............................................................................................................................................44
8.2 Get (Active)......................................................................................................................................44
8.3 Get (Passive)...................................................................................................................................45
8.4 Set ...................................................................................................................................................45
9 MULTILEVEL SWITCH INTERFACE API .........................................................................................46
9.1 Select...............................................................................................................................................46
9.2 Get (Active)......................................................................................................................................47
9.3 Get (Passive)...................................................................................................................................47
9.4 Set ...................................................................................................................................................47
9.5 Get Level Change (Passive)............................................................................................................47
9.6 Start Level Change..........................................................................................................................48
9.7 Stop Level Change ..........................................................................................................................48
9.8 Get Capabilities (Active) ..................................................................................................................48
9.9 Get Capabilities (Passive) ...............................................................................................................48
10 COLOR SWITCH INTERFACE API...................................................................................................49
10.1 Select...............................................................................................................................................49
10.2 Get (Active)......................................................................................................................................50
10.3 Get (Passive)...................................................................................................................................50
10.4 Set ...................................................................................................................................................51
10.5 Get Level Change (Passive)............................................................................................................51
10.6 Start Level Change..........................................................................................................................51
10.7 Stop Level Change ..........................................................................................................................52
10.8 Get Capabilities (Active) ..................................................................................................................52
10.9 Get Capabilities (Passive) ...............................................................................................................52
11 BINARY SENSOR INTERFACE API .................................................................................................53
11.1 Select...............................................................................................................................................53
11.2 Get (Active)......................................................................................................................................53
11.3 Get (Passive)...................................................................................................................................54
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page v of ix
11.4 Get Support (Active) ........................................................................................................................54
11.5 Get Support (Passive) .....................................................................................................................54
12 MULTILEVEL SENSOR INTERFACE API ........................................................................................55
12.1 Select...............................................................................................................................................55
12.2 Get (Active)......................................................................................................................................55
12.3 Get (Passive)...................................................................................................................................56
12.4 Get Support (Active) ........................................................................................................................56
12.5 Get Support (Passive) .....................................................................................................................56
12.6 Get Supported Scales (Active) ........................................................................................................56
12.7 Get Supported Scales (Passive) .....................................................................................................56
13 METER INTERFACE API ..................................................................................................................58
13.1 Select...............................................................................................................................................58
13.2 Get (Active)......................................................................................................................................59
13.3 Get (Passive)...................................................................................................................................59
13.4 Get Support (Active) ........................................................................................................................59
13.5 Get Support (Passive) .....................................................................................................................59
13.6 Reset ...............................................................................................................................................60
14 DOOR LOCK INTERFACE API .........................................................................................................61
14.1 Select...............................................................................................................................................62
14.2 Get (Active)......................................................................................................................................62
14.3 Get (Passive)...................................................................................................................................62
14.4 Set ...................................................................................................................................................62
14.5 Get Configuration (Active) ...............................................................................................................63
14.6 Get Configuration (Passive) ............................................................................................................63
14.7 Set Configuration.............................................................................................................................63
14.8 Get Capability (Active).....................................................................................................................63
14.9 Get Capability (Passive) ..................................................................................................................64
15 DOOR LOCK LOGGING INTERFACE API ....................................................................................................65
15.1 Select...............................................................................................................................................65
15.2 Get (Active)......................................................................................................................................66
15.3 Get (Passive)...................................................................................................................................66
15.4 Get Capabilities (Active) ..................................................................................................................66
15.5 Get Capabilities (Passive) ...............................................................................................................67
16 USER CODE INTERFACE API..........................................................................................................68
16.1 Get (Active)......................................................................................................................................69
16.2 Get (Passive)...................................................................................................................................70
16.3 Set ...................................................................................................................................................70
16.4 Get Number of Users (Active) .........................................................................................................71
16.5 Get Number of Users (Passive).......................................................................................................71
16.6 Get Capabilities (Active) ..................................................................................................................71
16.7 Get Capabilities (Passive) ...............................................................................................................71
16.8 Get Keypad Mode (Active) ..............................................................................................................72
16.9 Get Keypad Mode (Passive)............................................................................................................72
16.10 Set Keypad Mode ............................................................................................................................72
16.11 Get Master Code (Active) ................................................................................................................72
16.12 Get Master Code (Passive) .............................................................................................................72
16.13 Set Master Code..............................................................................................................................72
16.14 Get Checksum (Active)....................................................................................................................73
16.15 Get Checksum (Passive).................................................................................................................73
17 THERMOSTAT MODE INTERFACE API ..........................................................................................74
17.1 Select...............................................................................................................................................74
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page vi of ix
17.2 Get (Active)......................................................................................................................................74
17.3 Get (Passive)...................................................................................................................................75
17.4 Set ...................................................................................................................................................75
17.5 Get Capabilities (Active) ..................................................................................................................75
17.6 Get Capabilities (Passive) ...............................................................................................................75
18 THERMOSTAT OPERATING STATE INTERFACE API...................................................................76
18.1 Select...............................................................................................................................................76
18.2 Get (Active)......................................................................................................................................76
18.3 Get (Passive)...................................................................................................................................77
18.4 Logging Get (Active)........................................................................................................................77
18.5 Logging Get (Passive) .....................................................................................................................77
18.6 Logging Supported Get (Active) ......................................................................................................77
18.7 Logging Supported Get (Passive) ...................................................................................................77
19 THERMOSTAT FAN MODE INTERFACE API..................................................................................78
19.1 Select...............................................................................................................................................78
19.2 Get (Active)......................................................................................................................................78
19.3 Get (Passive)...................................................................................................................................79
19.4 Set ...................................................................................................................................................79
19.5 Get Capabilities (Active) ..................................................................................................................79
19.6 Get Capabilities (Passive) ...............................................................................................................79
20 THERMOSTAT FAN STATE INTERFACE API.................................................................................80
20.1 Select...............................................................................................................................................80
20.2 Get (Active)......................................................................................................................................80
20.3 Get (Passive)...................................................................................................................................80
21 THERMOSTAT SETPOINT INTERFACE API ...................................................................................81
21.1 Select...............................................................................................................................................81
21.2 Get (Active)......................................................................................................................................81
21.3 Get (Passive)...................................................................................................................................82
21.4 Set ...................................................................................................................................................82
21.5 Get Capabilities (Active) ..................................................................................................................82
21.6 Get Capabilities (Passive) ...............................................................................................................82
21.7 Range Get (Active) ..........................................................................................................................82
21.8 Range Get (Passive) .......................................................................................................................83
22 ALARM INTERFACE API ..................................................................................................................84
22.1 Select...............................................................................................................................................84
22.2 Get (Active)......................................................................................................................................85
22.3 Get (Passive)...................................................................................................................................85
22.4 Set ...................................................................................................................................................85
22.5 Get Capabilities (Active) ..................................................................................................................85
22.6 Get Capabilities (Passive) ...............................................................................................................86
22.7 Get Supported Events (Active) ........................................................................................................86
22.8 Get Supported Events (Passive) .....................................................................................................86
23 WAKE UP INTERFACE API ..............................................................................................................87
23.1 Select...............................................................................................................................................87
23.2 Get (Active)......................................................................................................................................87
23.3 Get (Passive)...................................................................................................................................88
23.4 Set ...................................................................................................................................................88
24 BATTERY INTERFACE API ..............................................................................................................89
24.1 Select...............................................................................................................................................89
24.2 Get (Active)......................................................................................................................................90
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page vii of ix
24.3 Get (Passive)...................................................................................................................................90
24.4 Health Get (Active) ..........................................................................................................................90
24.5 Health Get (Passive) .......................................................................................................................90
25 CENTRAL SCENE INTERFACE API ................................................................................................91
25.1 Select...............................................................................................................................................91
25.2 Get (Passive)...................................................................................................................................91
25.3 Get Capabilities (Active) ..................................................................................................................92
25.4 Get Capabilities (Passive) ...............................................................................................................92
25.5 Get Configuration (Active) ...............................................................................................................93
25.6 Get Configuration (Passive) ............................................................................................................93
25.7 Set Configuration.............................................................................................................................93
26 BARRIER OPERATOR INTERFACE API .........................................................................................94
26.1 Select...............................................................................................................................................94
26.2 Get (Active)......................................................................................................................................94
26.3 Get (Passive)...................................................................................................................................95
26.4 Set ...................................................................................................................................................95
26.5 Get Subsystem Capabilities (Active) ...............................................................................................95
26.6 Get Subsystem Capabilities (Passive) ............................................................................................95
26.7 Get Subsystem Configuration (Active) ............................................................................................95
26.8 Get Subsystem Configuration (Passive)..........................................................................................96
26.9 Set Subsystem Configuration ..........................................................................................................96
27 SOUND SWITCH INTERFACE API...................................................................................................97
27.1 Select...............................................................................................................................................97
27.2 Tone Play Get (Active) ....................................................................................................................98
27.3 Tone Play Get (Passive)..................................................................................................................98
27.4 Tone Play Set ..................................................................................................................................98
27.5 Tone Info Get (Active) .....................................................................................................................98
27.6 Tone Info Get (Passive)...................................................................................................................99
27.7 Tone Configuration Get (Active) ......................................................................................................99
27.8 Tone Configuration Get (Passive) ...................................................................................................99
27.9 Tone Configuration Set....................................................................................................................99
28 INDICATOR INTERFACE API .........................................................................................................100
28.1 Select.............................................................................................................................................100
28.2 Get (Active)....................................................................................................................................100
28.3 Get (Passive).................................................................................................................................101
28.4 Set .................................................................................................................................................101
28.5 Get Capabilities (Active) ................................................................................................................102
28.6 Get Capabilities (Passive) .............................................................................................................102
29 TIME INTERFACE API ....................................................................................................................103
29.1 Select.............................................................................................................................................103
29.2 Time Get (Active)...........................................................................................................................103
29.3 Time Get (Passive)........................................................................................................................104
29.4 Date Get (Active) ...........................................................................................................................104
29.5 Date Get (Passive) ........................................................................................................................104
29.6 Time Zone & Daylight Savings Time Get (Active) .........................................................................104
29.7 Time Zone & Daylight Savings Time Get (Passive) ......................................................................105
30 WINDOW COVERING INTERFACE API .........................................................................................106
30.1 Select.............................................................................................................................................106
30.2 Get (Active)....................................................................................................................................107
30.3 Get (Passive).................................................................................................................................107
30.4 Set .................................................................................................................................................107
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page viii of ix
30.5 Start Level Change........................................................................................................................107
30.6 Stop Level Change ........................................................................................................................108
30.7 Get Capabilities (Active) ................................................................................................................108
30.8 Get Capabilities (Passive) .............................................................................................................108
31 PROTECTION INTERFACE API .....................................................................................................109
31.1 Select.............................................................................................................................................110
31.2 Get (Active)....................................................................................................................................110
31.3 Get (Passive).................................................................................................................................110
31.4 Set .................................................................................................................................................110
31.5 Exclusive Control Get (Active).......................................................................................................110
31.6 Exclusive Control Get (Passive) ....................................................................................................111
31.7 Exclusive Control Set ....................................................................................................................111
31.8 Timeout Get (Active)......................................................................................................................111
31.9 Timeout Get (Passive)...................................................................................................................111
31.10 Timeout Set ...................................................................................................................................111
31.11 Get Capabilities (Active) ................................................................................................................111
31.12 Get Capabilities (Passive) .............................................................................................................112
32 GROUP INTERFACE API................................................................................................................113
32.1 Get (Active)....................................................................................................................................113
32.2 Get (Passive).................................................................................................................................114
32.3 Set .................................................................................................................................................114
32.4 Get Supported Groupings (Active) ................................................................................................114
32.5 Get Supported Groupings (Passive)..............................................................................................115
32.6 Get Specific Group – Current Active Group (Active) .....................................................................115
32.7 Get Specific Group – Current Active Group (Passive) ..................................................................115
33 GROUP INFO INTERFACE API ......................................................................................................116
33.1 Get.................................................................................................................................................116
34 CONFIGURATION INTERFACE API...............................................................................................117
34.1 Select.............................................................................................................................................117
34.2 Get (Active)....................................................................................................................................118
34.3 Get (Passive).................................................................................................................................118
34.4 Set .................................................................................................................................................118
34.5 Info Get (Active).............................................................................................................................118
34.6 Info Get (Passive)..........................................................................................................................119
35 FIRMWARE UPDATE INTERFACE API .........................................................................................120
35.1 Get Info (Active).............................................................................................................................123
35.2 Get Info (Passive)..........................................................................................................................123
35.3 Get Update Request (Active).........................................................................................................123
35.4 Get Update Request (Passive)......................................................................................................124
35.5 Get Backup Request (Active) ........................................................................................................124
35.6 Get Backup Request (Passive) .....................................................................................................125
35.7 Get Activation Request (Active).....................................................................................................125
35.8 Get Activation Request (Passive)..................................................................................................125
36 Z/IP GATEWAY INTERFACE API ...................................................................................................127
36.1 Get Mode (Active)..........................................................................................................................127
36.2 Get Mode (Passive).......................................................................................................................128
36.3 Set Mode .......................................................................................................................................128
36.4 Set Lock.........................................................................................................................................128
36.5 Get Unsolicited Destination (Active/Passive) ................................................................................128
36.6 Set Unsolicited Destination............................................................................................................129
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page ix of ix
37 Z/IP PORTAL INTERFACE API.......................................................................................................130
37.1 Gateway Config Get (Active) .........................................................................................................130
37.2 Gateway Config Get (Passive) ......................................................................................................131
37.3 Gateway Config Set.......................................................................................................................131
37.4 Gateway Config Status (Passive)..................................................................................................131
38 SCENES API....................................................................................................................................132
38.1 Scene Action Status and Scene Status.........................................................................................134
38.2 Get Capabilities .............................................................................................................................134
38.3 List Scenes ....................................................................................................................................135
38.4 Get Scene Details..........................................................................................................................135
38.5 Save Scene ...................................................................................................................................136
38.6 Delete Scene .................................................................................................................................137
38.7 Execute Scene ..............................................................................................................................137
38.8 Update Scene Status.....................................................................................................................138
38.9 Scene Get Statelog .......................................................................................................................138
39 SECURITY SCENES API.................................................................................................................140
39.1 Get Capabilities .............................................................................................................................140
39.2 List Security Scenes ......................................................................................................................141
39.3 Get Security Scene Details............................................................................................................141
39.4 Save Security Scene .....................................................................................................................143
39.5 Delete Security Scene ...................................................................................................................144
39.6 Security Scene Set State...............................................................................................................145
39.7 Security Scene Get Statelog .........................................................................................................145
40 INTERFACE APIS USED IN SCENE/SECURITY SCENE ..............................................................147
40.1 Basic Set Event .............................................................................................................................148
40.2 Binary Switch Set Action ...............................................................................................................148
40.3 Multilevel Switch Set Action...........................................................................................................148
40.4 Multilevel Switch Level Change Set Action ...................................................................................148
40.5 Color Switch Set Action .................................................................................................................149
40.6 Door Lock Set Action.....................................................................................................................149
40.7 Barrier Operator Set Action ...........................................................................................................149
40.8 Thermostat Mode Set Action .........................................................................................................150
40.9 Thermostat Setpoint Set Action.....................................................................................................150
40.10 Sound Switch Tone Play Set Action ..............................................................................................150
40.11 Window Covering Set Action .........................................................................................................151
40.12 Window Covering Level Change Set Action..................................................................................151
40.13 Binary Sensor Report Event ..........................................................................................................151
40.14 Multilevel Sensor Report Event .....................................................................................................151
40.15 Alarm Report Event .......................................................................................................................152
40.16 Central Scene Command Event ....................................................................................................152
REFERENCES ........................................................................................................................................154
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 1 of 154
1 INTRODUCTION
1.1 Purpose
Z-Ware is a Z-Wave Web Gateway which runs over Z-Wave for IP (Z/IP) Application Programming
Interface (API) and exports an abstracted object-based Web API to applications. For more information
on Z-Ware, see [1]. This document covers the Web API.
The API provides a well-defined interface to command classes, which allow the control and monitoring
various attributes of various devices in a Z-Wave network. The API also provides support for Scenes,
which are a macro-control element that allow a set of actions to be executed based on user action, Z-
Wave events, or schedule.
Some of the APIs are applicable only to the Portal version, and some to the Consumer Electronic (CE)
version and are marked accordingly in their respective section headers, while most are applicable to
both.
1.2 Audience and Requirements
Web developers
Figure 1: Z-Ware Architecture
Z-Ware Apps
Z-Ware Web API
Z/IP Gateway
Z-Ware Web Server
Z-Ware C API
Z-Ware Library
Z/IP API
Z/IP Gateway
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 2 of 154
2 OVERVIEW
2.1 Command Classes
Command Class
Versions
ALARM
8
ASSOCIATION
2
ASSOCIATION_GRP_INFO
3
BARRIER_OPERATOR
1
BASIC
2
BATTERY
1
CENTRAL_SCENE
3
CONFIGURATION
4
DOOR_LOCK
4
DOOR_LOCK_LOGGING
1
FIRMWARE_UPDATE_MD
5
INDICATOR
3
METER
5
MULTI_CHANNEL_ASSOCIATION
3
NODE_NAMING
1
PROTECTION
2
SENSOR_BINARY
2
SENSOR_MULTILEVEL
11
SOUND_SWITCH
1
SWITCH_BINARY
2
SWITCH_COLOR
3
SWITCH_MULTILEVEL
4
THERMOSTAT_FAN_MODE
4
THERMOSTAT_FAN_STATE
2
THERMOSTAT_MODE
3
THERMOSTAT_OPERATING_STATE
2
THERMOSTAT_SETPOINT
3
TIME
2
USER_CODE
2
VERSION
3
WAKE_UP
2
WINDOW_COVERING
1
ZIP_GATEWAY
1
ZIP_PORTAL
1
ZWAVEPLUS_INFO
2
The following command classes are handled automatically internally and not exposed to the user
Security
CRC-16 Encapsulation
Multi-Channel
Multi-Command
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 3 of 154
Manufacturer-Specific
Device Reset Locally
Some Z/IP-related
2.2 Objects
The API abstracts Z-Wave through objects for networks, nodes, endpoints, and interfaces.
A Z-Wave Home Area Network (HAN), uniquely identified by a Home ID, is encapsulated in a zwnet
object.
A device in this HAN, uniquely identified by a Node ID, is encapsulated in a zwnode object.
Channels in a multichannel device are encapsulated in a zwep object, and the node level virtual
channel is given an endpoint ID of 0.
Command classes (CCs) are either handled internally or encapsulated within specific interface
objects (zwif_xxx). Interface descriptors are subclassed according to their specific capabilities. CC
and their corresponding versions supported are listed in Appendix A.
The System module (zw) provides access to the Web server and connectivity to the local controller.
The Scenes module (zwscene) allows the execution of a set of actions triggered by a user action,
schedule, or a Z-Wave event.
The diagram below shows the relationship between and the attributes and methods within these objects.
zwnet
home_id
local_node_id
suc_node_id
net_role
operation
add
initiate
migrate
send_nif
update
reset
abort
zwnode
desc, id
vid,pid,type
category
alive
sec/_incl_failed
lib_type
proto_ver
app_ver/sub
hw_ver
fw_ver/sub/tgt
FLiRs_cap
sleep_cap
wakeup_interv
mul_cmd_state
cmdq
s2_keys_valid
s2_grant_keys
fail
update
cmdq_xxx
zwep
desc, id
gen/spc dc
name/loc
zwplus_ver
role/node_type
inst/usr_icon
aggr_ep_list
zwif_xxx
desc, id
name
ver, real_ver
sec,unsec
report
zw
lang
version
info
zipr_status
register
unregister
login
logout
changepswd
resetpswd
setup
get
set
…
node_list
ep_list
if_list
registration
username
pswd
access code
pin
email
timezone
Figure 2: Z-Ware Web API Objects
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 4 of 154
2.3 HTTP Mechanism
The Z-Ware API generally uses HTTP POST to the base URL of the Web server. The HTTP Connection
timeout is 15s while maximum number of simultaneous connections is 40. The Common Gateway
Interface (CGI) is used to communicate between the Web server and the Z-Wave-specific middleware,
the timeout for which is 11s. Unless specified otherwise, for all API functions:
Request Type is POST
All numeric values sent/received in Request/Reponse are decimal values and their valid ranges
are as defined by their corresponding fields in Z-Wave command class (CC) specification.
Order of Request parameters must be followed.
All list values received in Response are delimited by commas and terminate with a comma.
All references to application constants in Request/Response (defined in Appendix B & C), must
be replaced with their corresponding values.
In Response, if {updt_time} is 0, it indicates that no Z-Wave reports were received since the
server started up. So, the rest of the values in the response are undefined.
Except for registration APIs, prefix all other APIs with “/cgi/zcgi/networks/”, for example the level interface
API would be “/cgi/zcgi/networks//zwif_level”. The double slash indicates the default network for the
client.
2.4 Sample Usage
The following is a jQuery example of enumerating the network up to setting a dimmer’s level to 50%.
<html>
<script src=”http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js”
type=”text/javascript”></script>
max_scenes
max_actions
max_schedules
max_events
timezone
statelog
zwscenes
list
update
save
delete
exec
save
delete
set_state
id, name
active
armed
alarmed
time
sms
email
zwsecscn
zwscene
id, name
stat,time
lk:stat,time
le:trig,time
max_scenes
max_arm
max_disarm
max_alarm
timezone
statelog
zwsecscenes
list
update
actions
schedules
events
action
type
stat,time
lk:stat,time
uri, cmd
ifd, parm
event
type
stat,time
uri, cmd
ifd, parm
schedule
type
dd:hh:mm
arm
disarm
alarm
secevent
scene
lt:event, time
events
Figure 3: Z-Ware Scene API Objects
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 5 of 154
<body>
<script>
var _local;
function zwif_level_setup(ifd) {
$.ajax({
type: “POST”,
url: “cgi/zcgi/networks//zwif_level”,
data:”cmd=1&ifd=” + ifd
});
}
function zwif_level_set(ifd, level) {
$.ajax({
type: “POST”,
url: “zwif_level”,
data:”cmd=4&ifd=” + ifd + “&value=” + level,
});
}
function zwep_get_if_list(ep) {
$.ajax({
type: “POST”,
url: “cgi/zcgi/networks//zwep_get_if_list”,
data:”epd=” + ep,
dataType: “xml”,
async: false,
success: function(xml) {
$(xml).find(‘zwif’).each(function(){
document.write(“zwif: (desc, id, name, ver, sec, unsec) = (“);
document.write($(this).attr(‘desc’) + “, “);
document.write($(this).attr(‘id’) + “, “);
document.write($(this).attr(‘name’) + “, “);
document.write($(this).attr(‘ver’) + “, “);
document.write($(this).attr(‘sec’) + “, “);
document.write($(this).attr(‘unsec’) + “)<br>”);
/* set mlv switch to 50% */
if ($(this).attr(‘id’) == “38”)
{
document.write(“sending ...<br>”);
zwif_level_setup($(this).attr(‘desc’));
zwif_level_set($(this).attr(‘desc’), “50”);
}
});
},
});
}
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 6 of 154
function zwnode_get_ep_list(node) {
$.ajax({
type: “POST”,
url: “cgi/zcgi/networks//zwnode_get_ep_list”,
data:”noded=” + node,
dataType: “xml”,
async: false,
success: function(xml) {
$(xml).find(‘zwep’).each(function(){
document.write(“zwep: (desc, id, gen, spc, pid, name, loc) = (“);
document.write($(this).attr(‘desc’) + “, “);
document.write($(this).attr(‘id’) + “, “);
document.write($(this).attr(‘generic’) + “, “);
document.write($(this).attr(‘specific’) + “, “);
document.write($(this).attr(‘name’) + “, “);
document.write($(this).attr(‘loc’) + “)<br>”);
zwep_get_if_list($(this).attr(‘desc’) );
});
},
});
}
function zwnet_get_node_list() {
$.ajax({
type: ”POST”,
url: ” cgi/zcgi/networks//zwnet_get_node_list”,
dataType: ”xml”,
async: false,
success: function(xml) {
$(xml).find(‘zwnode’).each(function(){
id = $(this).attr(‘id’);
if (_local != id)
/* do not list our controller */
{
desc = $(this).attr(‘desc’);
document.write(“<br>zwnode: (desc, id, vid, pid) = (“);
document.write(desc + “, “);
document.write(id + “, “);
document.write($(this).attr(‘vid’) + “, “);
document.write($(this).attr(‘pid’) + “)<br>”);
zwnode_get_ep_list(desc);
}
});
},
});
}
function zwnet_get_desc() {
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 7 of 154
$.ajax({
type: “POST”,
url: “cgi/zcgi/networks//zwnet_get_desc”,
dataType: “xml”,
async: false,
success: function(xml) {
a = $(xml).find(‘zwnet’);
document.write(“zwnet: (home, local, suc, role) = (“);
document.write(a.attr(‘home’) + “, “);
_local = a.attr(‘local’);
document.write(_local + “, “);
document.write(a.attr(‘suc’) + “, “);
document.write(a.attr(‘role’) + “)<br>”);
zwnet_get_node_list();
},
});
}
zwnet_get_desc();
</script></body></html>
2.5 API Error Response
The response of the Web APIs on success return will be specified under the respective API sections in
the rest of the document. On fail return, the response will contain an <error> tag and be in the following
format unless specified otherwise in the respective API sections.
If parameter format is incorrect,
e.g., Certain part of the key/value pair is missing: key1=value1&key2
<?xml version=“1.0”?><zwave><error> </error></zwave>
if one or more parameters are missing/invalid/other failure:
<?xml version=“1.0”?><zwave><error>
CommandNameFailed
</error></zwave>
CommandName is the name of the command/Web API. For example,
/zwnet_provisioning_list_list_get API failure response will be:
<zwave><error>tServWhitelistListGetFailed</error></zwave>
/zwnet_provisioning_list_info API failure response will be:
<zwave><error>tServWhitelistDeviceInfoFailed</error></zwave>
/zwnet_provisioning_list_add API failure response will be:
<zwave><error>tServWhitelistAddFailed</error></zwave>
Response
Empty, if network uninitialized
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 8 of 154
3 REGISTRATION API
3.1 Register (Portal Only)
URI
/register/register
Request
firstname={first_name}&lastname={last_name}&usrname={username}
&passwd={password}&cpasswd={confirm_password}
&rac={remote_accesscode}&pin={pin}&email={email}&timezone={timezone}
{first_name} is the first name of user to be registered.
{last_name} is the last name of user to be registered.
{username} is the username of the user to be registered.
{password} is the password of the user account to be registered.
{confirm_password} is same as {password}.
{remote_accesscode} is the remote access code of Z/IP Gateway.
{pin} is pin of the Z/IP Gateway.
{email} is the email address of the user to be registered.
{timezone} is time zone information of the user to be registered in Olson format
On success
<?xml version=”1.0”?><zwave><register>status</register></zwave>
Where status is
0 – Successful, registration mail sent
1 – Successful but sending mail failed
Response
On failure,
<?xml version=”1.0”?><zwave><error>status</error></zwave>
where status is:
2 – firstname parameter has error
3 – lastname parameter has error
4 – username parameter has error
5 – password parameter has error
6 – rac_pin parameter has error
7 – passwords did not match error
8 – email parameter has error
9 – timezone parameter has error
10 – server connection error
11 – internal bind error
12 – username exists error
13 – gateway already exists error
14 – internal hash generation failed error
15 – user registration error
16 – gateway registration error
17 – internal certification generation tool setup error
Note
If successful, the user should receive an email on his registered email ID with all the
registered information (except password) and an unregister link, if the user wants to re-
register with different information.
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 9 of 154
3.2 Login
URI
/register/login
Request
usrname={username}&passwd={curr_password}
{username} is the registered username for the application.
{curr_password} is the current password for the application.
On success,
<?xml version=”1.0”?><zwave><login>status</login></zwave>
where status is:
0 – successful
Response
On failure,
<?xml version=”1.0”?><zwave><error>status</error></zwave>
where status is:
1 – username blank error
2 – password blank error
3 – invalid username or password error
4 – internal error
Note
Cookies are used to maintain sessions.
3.3 Logout
URI
/register/logout
Response
<?xml version=”1.0”?><zwave><logout>status</logout></zwave>
where status is:
0 – successful
3.4 Change Password
URI
/register/changepasswd
Request
curr={curr_passwd}&next={next_ passwd}
{curr_passwd} is the current password for the application.
{next_ passwd} is the next intended password for the application
On success:
<?xml version=“1.0”?><zwave><msg>tServPasswdChgSucessful</msg></zwave>
if current or next password hash is not passed as input:
<?xml version=“1.0”?><zwave><error>
tServPasswdChgFailed<!—Parameter missing/invalid-->
</error></zwave>
Response
On other failure:
<?xml version=“1.0”?><zwave><error>
tServPasswdChgFailed<!—Internal error-->
</error></zwave>
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 10 of 154
3.5 Reset Password
URI
/register/resetpasswd
Request
usrname={username}
{username} is the username of the account to be password reset.
<?xml version=”1.0”?><zwave><resetpasswd>status</resetpasswd></zwave>
where status is:
0 – successful, mail sent
1 – successful, mail send failed
Response
On failure,
<?xml version=”1.0”?><zwave><error>status</error></zwave>
where status is:
2 – invalid input error
3 – LDAP connection error
4 – LDAP bind error
5 – username not unique error
6 – invalid email or hash error
Note
If successful, the user also receives an email on his registered email ID with a link to
complete the reset password process.
3.6 Unregister Account (Portal Only)
URI
/register/unregister
Request
usrname={user_name}&hash={hash_code}[&isResetPasswd=true]
user_name: username of account that needs to be unregistered.
Hash_code: 512 bit hash code generated by the server, which is part of the link sent by
server.
isResetPasswd: indicates whether this is part of the reset password process
On success,
<?xml version=”1.0”?><zwave><unregister>status</unregister></zwave>
where status is
0 – successful
1 – successful, completed reset password procedure
Response
On failure,
<?xml version=”1.0”?><zwave><error>status</error></zwave>
2 – invalid user name or hash
3 – LDAP connection error
4 – LDAP bind error
5 – unique entry find error
6 – user hash error
7 – LDAP delete error
Note
If this is called from the link in the reset password email, it unregisters the user but without
disconnecting the user’s Z/IP Gateway. This enables the user to re-register with the new
information quickly.
INS14430-6 Z-Ware SDK 7.13.0 Web Developer Guide 2019-11-18
silabs.com | Building a more connected world.
Page 11 of 154
4 SYSTEM API
4.1 Platform and Version Numbers
URI
/zw_version
Response
<?xml version=“1.0”?><zwave>
<version platform=”{platform}” app_major=”{app_major}” app_minor=”{app_minor}”
app_patch=”{app_patch}” ctl_major=”{ctl_major}” ctl_minor=”{ctl_minor}”
ctl_patch=”{ctl_patch}” />
</zwave>
Values
Description
platform
Server platform e.g., Windows
®
OS, Linux
®
OS, and osx
respectively for Microsoft Windows, GNU/Linux and OS X.
app_major/minor/patch
Application Major/minor/patch version
ctl_major/minor/patch
Internal API major/minor/patch version
4.2 Connection Status (Portal Only)
URI
/zwportal_zipr_status
Response
On success:
<?xml version=“1.0”?><zwave><zwportal_zipr status=“{connection_status}” /></zwave>
where {connection_status} is 0 if Zipr is not connected to portal server or network is not
initialized. 1 otherwise
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40
  • Page 41 41
  • Page 42 42
  • Page 43 43
  • Page 44 44
  • Page 45 45
  • Page 46 46
  • Page 47 47
  • Page 48 48
  • Page 49 49
  • Page 50 50
  • Page 51 51
  • Page 52 52
  • Page 53 53
  • Page 54 54
  • Page 55 55
  • Page 56 56
  • Page 57 57
  • Page 58 58
  • Page 59 59
  • Page 60 60
  • Page 61 61
  • Page 62 62
  • Page 63 63
  • Page 64 64
  • Page 65 65
  • Page 66 66
  • Page 67 67
  • Page 68 68
  • Page 69 69
  • Page 70 70
  • Page 71 71
  • Page 72 72
  • Page 73 73
  • Page 74 74
  • Page 75 75
  • Page 76 76
  • Page 77 77
  • Page 78 78
  • Page 79 79
  • Page 80 80
  • Page 81 81
  • Page 82 82
  • Page 83 83
  • Page 84 84
  • Page 85 85
  • Page 86 86
  • Page 87 87
  • Page 88 88
  • Page 89 89
  • Page 90 90
  • Page 91 91
  • Page 92 92
  • Page 93 93
  • Page 94 94
  • Page 95 95
  • Page 96 96
  • Page 97 97
  • Page 98 98
  • Page 99 99
  • Page 100 100
  • Page 101 101
  • Page 102 102
  • Page 103 103
  • Page 104 104
  • Page 105 105
  • Page 106 106
  • Page 107 107
  • Page 108 108
  • Page 109 109
  • Page 110 110
  • Page 111 111
  • Page 112 112
  • Page 113 113
  • Page 114 114
  • Page 115 115
  • Page 116 116
  • Page 117 117
  • Page 118 118
  • Page 119 119
  • Page 120 120
  • Page 121 121
  • Page 122 122
  • Page 123 123
  • Page 124 124
  • Page 125 125
  • Page 126 126
  • Page 127 127
  • Page 128 128
  • Page 129 129
  • Page 130 130
  • Page 131 131
  • Page 132 132
  • Page 133 133
  • Page 134 134
  • Page 135 135
  • Page 136 136
  • Page 137 137
  • Page 138 138
  • Page 139 139
  • Page 140 140
  • Page 141 141
  • Page 142 142
  • Page 143 143
  • Page 144 144
  • Page 145 145
  • Page 146 146
  • Page 147 147
  • Page 148 148
  • Page 149 149
  • Page 150 150
  • Page 151 151
  • Page 152 152
  • Page 153 153
  • Page 154 154
  • Page 155 155
  • Page 156 156
  • Page 157 157
  • Page 158 158
  • Page 159 159
  • Page 160 160
  • Page 161 161
  • Page 162 162
  • Page 163 163
  • Page 164 164

Silicon Labs Z-Ware SDK 7.13.0 Web Developer Reference guide

Silicon Labs
Brand
Silicon Labs
Model
Z-Ware SDK 7.13.0 Web Developer
Type
Reference guide
Download PDF
report

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI

Related papers

Other documents