Silicon Labs Z-Ware Web Developer User guide

dotm

Instruction

Z-Ware Web Developer Guide

Document No.:

INS12902

Version:

13

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;BBR

Date:

2018-04-05

Reviewed By:

SOTHAYOTH;TNATARAJAN

Restrictions:

Public

Approved by:

Date CET Initials Name Justification

2018-04-05 13:05:10 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.

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page ii of vii

REVISION RECORD

Doc. Ver.

Date

By

Pages affected

Brief description of changes

7

20160830

SNA

ALL

Public version

8

20160908

20160927

AYY

SNA

8-10, 12-13,

17-19, 23,

35-36,

83-84

ALL

Marked Portal vs CE. Added CE version Z/IP gateway APIs.

Added S2 – CSA, IOB, initiate DSK. Added Multichannel V4 (in List EPs API)

Added Multilevel sensor V5, notes on existing

Updated supported CC and versions.

Updated intro to merge CE & Portal & distributed appendix

9

20170110

AYY

SNA

18, 22, 23-25, 28-

30, 67-69

Added command queue commands,

Added Barrier operator CC, Added prekit web APIs

Removed prekit info, Added Color CC for Jason

10

20170516

AYY

15-17, 60-61

Added controller ZWave role, ZWave node security property.

Modified node_alive_state values

Added thermostat setpoint V3 Range Get API

11

20170712

AYY

JHZ

20

80-81

Added Classic Set learn mode support

Modified firmware update CC

12

20170708

20170810

AYY

74-75

96

Updated Association Set command parameters

Updated Security Scene creation parameters

13

20180504

BBR

All

Added Silicon Labs template

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page iii of vii

Table of Contents

1 INTRODUCTION ................................................................................................................................... 1

1.1 Purpose .............................................................................................................................................. 1

1.2 Audience and prerequisites ................................................................................................................ 1

2 OVERVIEW ........................................................................................................................................... 2

2.1 Command Classes ............................................................................................................................. 2

2.2 Objects ............................................................................................................................................... 2

2.3 HTTP mechanism ............................................................................................................................... 4

2.4 Sample usage..................................................................................................................................... 4

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

5 NETWORK API ...................................................................................................................................15

5.1 Get information .................................................................................................................................15

5.2 List Nodes .........................................................................................................................................16

5.3 List Node/Endpoint Pairs ..................................................................................................................17

5.4 Inclusion/Exclusion ...........................................................................................................................18

5.4.1 Query device requested keys (S2 security only)....................................................................19

5.4.2 Set grant key(s) (S2 security only) .........................................................................................19

5.4.3 Query device DSK (S2 security only) .....................................................................................19

5.4.4 DSK accept (S2 security only) ...............................................................................................20

5.5 Initiate ...............................................................................................................................................20

5.5.1 Query local node DSK (S2 security only) ...............................................................................20

5.6 Send Node Information Frame (NIF) ................................................................................................20

5.7 Update Network ................................................................................................................................21

5.8 Reset Network ..................................................................................................................................21

5.9 Abort network operation ...................................................................................................................21

5.10 Get current network operation ..........................................................................................................21

5.11 Whitelist list get.................................................................................................................................24

5.12 Whitelist list report ............................................................................................................................24

5.13 Whitelist device info ..........................................................................................................................24

5.14 Whitelist Add .....................................................................................................................................24

5.15 Whitelist Remove..............................................................................................................................25

5.16 Whitelist Remove All ........................................................................................................................25

6 NODE/ENDPOINT API .......................................................................................................................26

6.1 List Endpoints ...................................................................................................................................26

6.2 List Interfaces in Endpoint ................................................................................................................27

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page iv of vii

6.3 Remove/Replace Failed Node .........................................................................................................27

6.4 Update Node ....................................................................................................................................28

6.5 Name/Location .................................................................................................................................28

6.5.1 Set ..........................................................................................................................................28

6.6 Command Queue .............................................................................................................................28

6.6.1 Get State ................................................................................................................................31

6.6.2 Set State.................................................................................................................................31

6.6.3 Get ..........................................................................................................................................31

6.6.4 Cancel ....................................................................................................................................31

7 BASIC INTERFACE API .....................................................................................................................33

7.1 Select ................................................................................................................................................33

7.2 Get (Active) .......................................................................................................................................34

7.3 Get (Passive) ....................................................................................................................................34

7.4 Set ....................................................................................................................................................34

8 BINARY SWITCH INTERFACE API ...................................................................................................35

8.1 Select ................................................................................................................................................35

8.2 Get (Active) .......................................................................................................................................35

8.3 Get (Passive) ....................................................................................................................................35

8.4 Set ....................................................................................................................................................35

9 MULTILEVEL SWITCH INTERFACE API ..........................................................................................37

9.1 Select ................................................................................................................................................37

9.2 Get (Active) .......................................................................................................................................37

9.3 Get (Passive) ....................................................................................................................................38

9.4 Set ....................................................................................................................................................38

9.5 Get Level Change (Passive) ............................................................................................................38

9.6 Start Level Change ...........................................................................................................................38

9.7 Stop Level Change ...........................................................................................................................38

9.8 Get Capabilities (Active) ...................................................................................................................39

9.9 Get Capabilities (Passive) ................................................................................................................39

10 COLOR SWITCH INTERFACE API....................................................................................................40

10.1 Select ................................................................................................................................................40

10.2 Get (Active) .......................................................................................................................................40

10.3 Get (Passive) ....................................................................................................................................41

10.4 Set ....................................................................................................................................................41

10.5 Get Level Change (Passive) ............................................................................................................41

10.6 Start Level Change ...........................................................................................................................41

10.7 Stop Level Change ...........................................................................................................................42

10.8 Get Capabilities (Active) ...................................................................................................................42

10.9 Get Capabilities (Passive) ................................................................................................................42

11 BINARY SENSOR INTERFACE API ..................................................................................................43

11.1 Select ................................................................................................................................................43

11.2 Get (Active) .......................................................................................................................................43

11.3 Get (Passive) ....................................................................................................................................43

11.4 Get Support (Active) .........................................................................................................................44

11.5 Get Support (Passive) ......................................................................................................................44

12 MULTILEVEL SENSOR INTERFACE API .........................................................................................45

12.1 Select ................................................................................................................................................45

12.2 Get (Active) .......................................................................................................................................45

12.3 Get (Passive) ....................................................................................................................................46

12.4 Get Support (Active) .........................................................................................................................46

12.5 Get Support (Passive) ......................................................................................................................46

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page v of vii

12.6 Get Supported Scales (Active) .........................................................................................................46

12.7 Get Supported Scales (Passive) ......................................................................................................47

13 METER INTERFACE API ...................................................................................................................48

13.1 Select ................................................................................................................................................48

13.2 Get (Active) .......................................................................................................................................49

13.3 Get (Passive) ....................................................................................................................................49

13.4 Get Support (Active) .........................................................................................................................49

13.5 Get Support (Passive) ......................................................................................................................49

13.6 Reset ................................................................................................................................................49

14 DOOR LOCK INTERFACE API ..........................................................................................................50

14.1 Select ................................................................................................................................................50

14.2 Get (Active) .......................................................................................................................................50

14.3 Get (Passive) ....................................................................................................................................51

14.4 Set ....................................................................................................................................................51

14.5 Get Configuration (Active) ................................................................................................................51

14.6 Get Configuration (Passive) .............................................................................................................51

14.7 Set Configuration ..............................................................................................................................51

15 USER CODE INTERFACE API ..........................................................................................................52

15.1 Get (Active) .......................................................................................................................................52

15.2 Get (Passive) ....................................................................................................................................52

15.3 Set ....................................................................................................................................................52

15.4 Get Capabilities (Active) ...................................................................................................................53

15.5 Get Capabilities (Passive) ................................................................................................................53

16 THERMOSTAT MODE INTERFACE API ...........................................................................................54

16.1 Select ................................................................................................................................................54

16.2 Get (Active) .......................................................................................................................................54

16.3 Get (Passive) ....................................................................................................................................54

16.4 Set ....................................................................................................................................................55

16.5 Get Capabilities (Active) ...................................................................................................................55

16.6 Get Capabilities (Passive) ................................................................................................................55

17 THERMOSTAT OPERATING STATE INTERFACE API ...................................................................56

17.1 Select ................................................................................................................................................56

17.2 Get (Active) .......................................................................................................................................56

17.3 Get (Passive) ....................................................................................................................................56

18 THERMOSTAT FAN MODE INTERFACE API ..................................................................................57

18.1 Select ................................................................................................................................................57

18.2 Get (Active) .......................................................................................................................................57

18.3 Get (Passive) ....................................................................................................................................57

18.4 Set ....................................................................................................................................................58

18.5 Get Capabilities (Active) ...................................................................................................................58

18.6 Get Capabilities (Passive) ................................................................................................................58

19 THERMOSTAT FAN STATE INTERFACE API .................................................................................59

19.1 Select ................................................................................................................................................59

19.2 Get (Active) .......................................................................................................................................59

19.3 Get (Passive) ....................................................................................................................................59

20 THERMOSTAT SETPOINT INTERFACE API ....................................................................................60

20.1 Select ................................................................................................................................................60

20.2 Get (Active) .......................................................................................................................................60

20.3 Get (Passive) ....................................................................................................................................61

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page vi of vii

20.4 Set ....................................................................................................................................................61

20.5 Get Capabilities (Active) ...................................................................................................................61

20.6 Get Capabilities (Passive) ................................................................................................................61

20.7 Range Get (Active) ...........................................................................................................................61

20.8 Range Get (Passive) ........................................................................................................................62

21 ALARM INTERFACE API ...................................................................................................................63

21.1 Select ................................................................................................................................................63

21.2 Get (Active) .......................................................................................................................................64

21.3 Get (Passive) ....................................................................................................................................64

21.4 Set ....................................................................................................................................................64

21.5 Get Capabilities (Active) ...................................................................................................................64

21.6 Get Capabilities (Passive) ................................................................................................................65

21.7 Get Supported Events (Active) .........................................................................................................65

21.8 Get Supported Events (Passive) ......................................................................................................65

22 WAKE UP INTERFACE API ...............................................................................................................66

22.1 Select ................................................................................................................................................66

22.2 Get (Active) .......................................................................................................................................66

22.3 Get (Passive) ....................................................................................................................................67

22.4 Set ....................................................................................................................................................67

23 BATTERY INTERFACE API ...............................................................................................................68

23.1 Select ................................................................................................................................................68

23.2 Get (Active) .......................................................................................................................................68

23.3 Get (Passive) ....................................................................................................................................68

24 CENTRAL SCENE INTERFACE API .................................................................................................69

24.1 Select ................................................................................................................................................69

24.2 Get (Passive) ....................................................................................................................................69

24.3 Get Capabilities (Active) ...................................................................................................................69

24.4 Get Capabilities (Passive) ................................................................................................................70

25 BARRIER OPERATOR INTERFACE API ..........................................................................................71

25.1 Select ................................................................................................................................................71

25.2 Get (Active) .......................................................................................................................................71

25.3 Get (Passive) ....................................................................................................................................72

25.4 Set ....................................................................................................................................................72

25.5 Get Subsystem Capabilities (Active) ................................................................................................72

25.6 Get Subsystem Capabilities (Passive) .............................................................................................72

25.7 Get Subsystem Config (Active) ........................................................................................................72

25.8 Get Subsystem Config (Passive) .....................................................................................................72

25.9 Set Subsystem Config ......................................................................................................................73

26 GROUP INTERFACE API ...................................................................................................................74

26.1 Get (Active) .......................................................................................................................................74

26.2 Get (Passive) ....................................................................................................................................75

26.3 Set ....................................................................................................................................................75

26.4 Get Supported Groupings (Active) ...................................................................................................75

26.5 Get Supported Groupings (Passive) ................................................................................................75

26.6 Get Specific Group – Current Active Group (Active) ........................................................................76

26.7 Get Specific Group – Current Active Group (Passive) .....................................................................76

27 GROUP INFO INTERFACE API .........................................................................................................77

27.1 Get ....................................................................................................................................................77

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page vii of vii

28 CONFIGURATION INTERFACE API .................................................................................................78

28.1 Select ................................................................................................................................................78

28.2 Get (Active) .......................................................................................................................................78

28.3 Get (Passive) ....................................................................................................................................78

28.4 Set ....................................................................................................................................................79

29 FIRMWARE UPDATE INTERFACE API ............................................................................................80

29.1 Get Info (Active)................................................................................................................................81

29.2 Get Info (Passive) .............................................................................................................................81

29.3 Get Update Request (Active) ...........................................................................................................81

29.4 Get Update Request (Passive) .........................................................................................................81

30 Z/IP GATEWAY INTERFACE API ......................................................................................................83

30.1 Get Mode (Active) ............................................................................................................................83

30.2 Get Mode (Passive) ..........................................................................................................................84

30.3 Set Mode ..........................................................................................................................................84

30.4 Set Lock ............................................................................................................................................84

30.5 Get Unsolicited Destination (Active/Passive) ...................................................................................84

30.6 Set Unsolicited Destination ..............................................................................................................85

31 SCENES API .......................................................................................................................................86

31.1 Get Capabilities ................................................................................................................................87

31.2 List Scenes .......................................................................................................................................88

31.3 Get Scene Details ............................................................................................................................88

31.4 Save Scene ......................................................................................................................................89

31.5 Delete Scene ....................................................................................................................................90

31.6 Execute Scene .................................................................................................................................90

31.7 Update Scene Status .......................................................................................................................90

31.8 Scene Get Statelog ..........................................................................................................................91

32 SECURITY SCENES API ...................................................................................................................93

32.1 Get Capabilities ................................................................................................................................93

32.2 List Security Scenes .........................................................................................................................94

32.3 Get Security Scene Details ..............................................................................................................94

32.4 Save Security Scene ........................................................................................................................96

32.5 Delete Security Scene ......................................................................................................................97

32.6 Security Scene Set State .................................................................................................................98

32.7 Security Scene Get Statelog ............................................................................................................98

33 INTERFACE APIS USED IN SCENE/SECURITY SCENE ..............................................................100

33.1 Basic Set Event ..............................................................................................................................100

33.2 Binary Switch Set Action ................................................................................................................101

33.3 Multilevel Switch Set Action ...........................................................................................................101

33.4 Door Lock Set Action ......................................................................................................................101

33.5 Thermostat Setpoint Set Action ......................................................................................................101

33.6 Binary Sensor Report Event ...........................................................................................................102

33.7 Multilevel Sensor Report Event ......................................................................................................102

33.8 Alarm Report Event ........................................................................................................................102

33.9 Central Scene Command Event .....................................................................................................102

REFERENCES .........................................................................................................................................103

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 1 of 103

1 INTRODUCTION

1.1 Purpose

Z-Ware is a Z-Wave Web Gateway which runs over Z-Wave over 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 & monitoring of

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 prerequisites

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

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 2 of 103

2 OVERVIEW

2.1 Command Classes

Command Class

Versions

Description

BASIC

1

Basic

SWITCH_BINARY

1

Binary Switch

SWITCH_MULTILEVEL

1-3

Multilevel Switch

SENSOR_BINARY

1-2

Binary Sensor

SENSOR_MULTILEVEL

1-9

Multilevel Sensor

METER

1-3

Meter

DOOR_LOCK

1-2

Door Lock

USER_CODE

1

User Code

THERMOSTAT_MODE

1-2

Thermostat Mode

THERMOSTAT_OPERATING_STATE

1

Thermostat Operating State

THERMOSTAT_FAN_MODE

1-4

Thermostat Fan Mode

THERMOSTAT_FAN_STATE

1-2

Thermostat Fan State

THERMOSTAT_SETPOINT

1-2

Thermostat Setpoint

ALARM

1-8

Alarm

WAKE_UP

1-2

Wake Up

BATTERY

1

Battery

CENTRAL_SCENE

1-2

Central Scene

ASSOCIATION

1-2

Association

ASSOCIATION_GRP_INFO

1

Association Group Info (AGI)

MULTI_CHANNEL_ASSOCIATION

2

Multi Channel Association

NODE_NAMING

1

Node Naming

CONFIGURATION

1

Configuration

FIRMWARE_UPDATE_MD

1-3

Firmware Meta Data

ZIP_GATEWAY

1

Z/IP Gateway

ZIP_PORTAL

1

Z/IP Portal

ZWAVEPLUS_INFO

1

Z-Wave+ Info

VERSION

2

Version

The following command classes are handled automatically internally and not exposed to the user

 Security

 CRC-16 Encapsulation

 Multi Channel

 Multi Command

 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.

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 3 of 103

 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 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 & 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

email

timezone

Figure 2: Z-Ware Web API Objects

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 4 of 103

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, all other APIs need to be prefixed with “/cgi/zcgi/networks/”. Eg. 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>

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

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 5 of 103

<body>

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>”);

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 6 of 103

zwif_level_setup($(this).attr(‘desc’));

zwif_level_set($(this).attr(‘desc’), “50”);

}

});

},

});

}

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 */

{

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 7 of 103

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() {

$.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>

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 8 of 103

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

Response

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

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

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, in case the user wants to re-

register with different information.

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 9 of 103

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.

Response

On success,

<?xml version=”1.0”?><zwave><login>status</login></zwave>

where status is:

0 – successful

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

Response

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>

On other failure:

<?xml version=“1.0”?><zwave><error>

tServPasswdChgFailed<!—Internal error-->

</error></zwave>

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 10 of 103

3.5 Reset Password

URI

/register/resetpasswd

Request

usrname={username}

{username} is the username of the account to be password reset.

Response

<?xml version=”1.0”?><zwave><resetpasswd>status</resetpasswd></zwave>

where status is:

0 – successful, mail sent

1 – successful, mail send failed

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 server, which is part of the link sent by server.

isResetPasswd: whether this is part of the reset password process

Response

On success,

<?xml version=”1.0”?><zwave><unregister>status</unregister></zwave>

where status is

0 – successful

1 – successful, completed reset password procedure

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 him to re-register with new information

quickly.

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 11 of 103

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}”

ctl_major=”{ctl_major}” ctl_minor=”{ctl_minor}” />

</zwave>

Values

Description

platform

Server platform eg. windows, linux and osx respectively for Microsoft

Windows, GNU/Linux and OS X

app_major/minor

Application Major/minor version

ctl_major/minor

Internal API major/minor 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, and 1 otherwise

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 12 of 103

4.3 Information

URI

/zw_info

Response

<?xml version=”1.0”?><zwave>

<zw_info vname=“{vendor_name}” pname=“{product_name}”

spltform=“{server_platform}” uname=“{username}” init=“{is_hcweb_init_done}”

home_id=“{zwave_home_id}” ctlr_id=“{zwave_controller_id}”

zipgw =”{zip_gateway}” portalcid=”{portal_client}”

server_ip=“{server_ip}” client_ip=“{client_ip}” >

[ <version …> …]

</zw_info></zwave>

Parameter

Description

{vendor_name}

Vendor Name

{product_name}

Product Name

{server_platform}

OS platform of the server e.g. Windows or Linux

{is_hcweb_init_done}

indicates whether the server is initialized or uninitialized.

{username}

username for the current connection to the server.

{zwave_home_id}

Home ID of the Z-Wave network

{zwave_controller_id}

Z-Wave controller’s Node ID

{zip_gateway}

The hostname or IP address of the current Z/IP Gateway, only

for Z/IP version

{portal_client}

The name or ID of the current portal client, only for Portal version

{server_ip}

The Z-Ware’s IP address

{client_ip}

The client’s IP address

zw_info_version_name

Description

zw_ctl

Internal Z-Wave Controller Library

zw_appl

Z-Ware

zw_webapi

Z-Ware web API

zw_ui_engineering

Engineering Z-App

zw_ui_stb

TV UI Z-App

zw_ui_pc

PC/Tablet UI Z-App

zw_ui_phone

Phone UI Z-App

Example:

<?xml version=”1.0”?><zwave>

<zw_info vname=”Silicon Labs” pname=”Z-Ware and Z-Ware Apps”

spltform=”linux” uname=”kml” init=”1” home_id=”EE3B8842” ctlr_id=”1”

portalcid=”00-1E-32-FF-FF-20-02-59”

server_ip=”172.31.37.210” client_ip=”119.73.233.67” >

</zw_info></zwave>

INS12902-13 Z-Ware Web Developer Guide 2018-04-05

silabs.com | Building a more connected world.

Page 13 of 103

4.4 Z/IP Gateway (CE only)

These requests serve to connect to any Z/IP Gateway for Z-Wave communication. They use the

following parameters:

Parameter

Description

{zip_gw_name}

name or address of the Z/IP gateway, UTF-8 encoded and then URL encoded.

If “::” (IPv6 address with all zeros) during Initialize, previous Z/IP gateway is used.

{unsol_rpt_port}

port number for receiving unsolicited reports.

If 0, system will assign a random port to receive unsolicited reports.

{zip_gw_status}

0: no Z/IP gateway is initialized;

1: a Z/IP gateway is currently initialized.

{zip_gw_addr}

address of the Z/IP gateway after name resolution

{zip_gw_discvr_flag}

1: default. enable Z/IP gateway discovery before listing them

0: list cached Z/IP gateways

{zip_gw_flag}

decimal representation of the following 8-bit mask.

Bit

7

6

5

4

3

2

1

0

Use

R

V

C

D

B

B – 1 if the Z/IP gateway is already initialized using another instance of Host

Controller Web Server Application in the same machine; 0 if otherwise

D – 1 if the Z/IP gateway is in the discovery list; 0 if otherwise

C – 1 if the Z/IP gateway is in the cached list; 0 if otherwise

V – 1 if the Z/IP gateway is version 2 gateway; 0 if otherwise

R – Reserved

4.4.1 Initialize Z/IP Gateway

URI

/zw_gw_set

Request

For version 1 gateway:

zip_gw_name={zip_gw_name}&unsol_rpt_port={unsol_rpt_port}

For version 2 gateway:

zip_gw_name={zip_gw_name}&unsol_rpt_port={unsol_rpt_port}&key={preshared_key}

{preshared_key}: Z/IP gateway preshared key.

Response

Empty on success

if Z/IP gateway name or address is not passed as input:

<?xml version=“1.0”?><zwave><error>

tServNoAddrNum

</error></zwave>

On other failure:

<?xml version=“1.0”?><zwave><error>tServNwInit</error></zwave>

4.4.2 Get Currently Used Z/IP Gateway

URI

/zw_gw_get

Response

<?xml version=“1.0”?><zwave>

<gw_status status=“{zip_gw_status}” name=“{zip_gw_name}”

addr=”{zip_gw_addr}” unsol_rpt_port=”{unsol_rpt_port}” />

</zwave>

Page is loading ...

Silicon Labs Z-Ware Web Developer User guide

Silicon Labs Z-Ware Web Developer User guide

Related papers

Other documents