====================================================================== DUNE HD STB -- Z-WAVE API ====================================================================== About this document ------------------- This document describes Z-Wave API provided by Dune HD set-top-boxes with Z-Wave support. Target audience is software developers implementing software which needs to use Z-Wave functionality of Dune HD STB. Readers are expected to be familiar with the following topics: - Z-Wave (overall concepts and details of particular Z-Wave command classes). - HTTP protocol. - JSON data format. Quick How To ------------ Here is quick start guide for experienced users: - Install the following plugin onto Dune HD STB: - http://files.dune-hd.com/partners/sdk/zwave/eval/dune_plugin_zwave_controller.2013_03_12.zip - Send the following HTTP requests to Dune HD STB: - http://{STB-IP-address}/cgi-bin/plugins/zwave_controller/do?cmd=start - http://{STB-IP-address}/cgi-bin/plugins/zwave_controller/do?cmd=enable_auto_start - Open Web UI in a web browser on PC using the following URL: - http://{STB-IP-address}:81 - Send Z-Wave API HTTP requests to Dune HD STB using the following URL: - http://{STB-IP-address}:81/ZWaveAPI/{command} More detailed information is available in the below sections. Overview -------- Z-Wave API is provided on top of HTTP protocol, using HTTP GET/POST requests and JSON syntax. Applications willing to use Z-Wave functionality of Dune HD STB can send HTTP requests to Dune HD STB in order to perform various actions, such as: - Add/remove Z-Wave devices to Z-Wave network managed by Z-Wave controller running inside Dune HD STB. - Get the list of currently configured Z-Wave devices. - Get the current status of Z-Wave devices. - Send commands to Z-Wave devices. - Wait for the events occurring with Z-Wave devices. The application willing to interact with Z-Wave API of a Dune HD STB can be: - Running outside of the STB. In this case, the application should know the IP address of the STB. - Running inside the STB. In this case, the application can interact with the API via localhost IP address. Prerequisites ------------- To use Z-Wave API on Dune HD STB, the following is needed: - Dune HD STB with a Z-Wave hardware module. - Z-Wave controller software installed and running on the Dune HD STB. Z-Wave Controller ----------------- Z-Wave controller is a software module running on the Dune HD STB, which implements Z-Wave controller functionality (i.e. allows managing Z-Wave devices on the Z-Wave network). Z-Wave controller is implemented as a background process which normally starts when the STB is powered on and never terminates. Z-Wave controller has the following responsibilities: - Implements Z-Wave controller functionality. - Provides Z-Wave API for applications. - Interacts with Z-Wave hardware module. - Manages the data stored in the flash memory of the STB. Applications willing to utilize Z-Wave functionality of Dune HD STB need to interact with Z-Wave controller via the provided Z-Wave API. Installing Z-Wave Controller Software ------------------------------------- Z-Wave controller software can be part of a particular Dune HD STB firmware, or installed separately. Checking if Z-Wave controller software is already available (installed and running) on a STB can be performed in the following ways: - Send any valid request to Z-Wave API. If the request fails with "Connection refused" error, it means that Z-Wave controller software is not installed or is not currently running on the STB. - Send "status" command to Z-Wave controller management API (see "Z-Wave Controller Management API" section). If you do not get HTTP OK response, it means that Z-Wave controller software is not installed. To install Z-Wave controller software onto a Dune HD STB, perform the following steps: - Download the following ZIP file (Dune HD STB plugin): - http://files.dune-hd.com/partners/sdk/zwave/eval/dune_plugin_zwave_controller.2013_03_12.zip - NOTE: This software is available for evaluation purposes and its production use would require an agreement with Dune HD. To download this software, you will need a login/password -- request them from your Dune HD contacts. - Put the ZIP file onto a USB flash drive, attach USB flash drive to the Dune HD STB. - Navigate in the menu of Dune HD STB to the USB flash drive, select the ZIP file, and press ENTER RC button. - You should see a message that the plugin has been installed successfully. After Z-Wave controller software is installed, you should start Z-Wave controller (and configure its automatic startup on STB boot, if you need it). This can be done using Z-Wave controller management API. Z-Wave Controller Management API -------------------------------- Z-Wave Controller can itself be managed (started/stopped) via a special HTTP URL: - http://{STB-IP-address}/cgi-bin/plugins/zwave_controller/do?cmd={CMD} Here, {STB-IP-address} is the IP address of the STB (can be localhost or 127.0.0.1 if the HTTP request is sent from the STB itself). {CMD} is a command that should be executed and can be one of the following strings: - status - Does nothing, just returns the current status of the Z-Wave controller. - start - Starts Z-Wave controller, if it is not running yet. Does nothing if Z-Wave controller is already running. This command is processed asynchronously and may return before Z-Wave controller is fully initialized and is ready to handle Z-Wave API requests; if it is needed to wait for Z-Wave API to be ready, Z-Wave API should be polled until it works. - stop - Stops Z-Wave controller, if it is running. Does nothing if Z-Wave controller is not running. After this command returns, Z-Wave controller is guaranteed to be not running, with all persistent data correctly flushed into the persistent storage. - restart - Restarts Z-Wave controller (is equivalent to "stop" command followed by "start" command). - flush - If Z-Wave controller is running, makes all persistent data managed by Z-Wave controller to be correctly flushed into the persistent storage (so that it is guaranteed that all recent changes are not lost in case of sudden STB power off). Does nothing if Z-Wave controller is not running. - enable_auto_start - Enables automatic startup of Z-Wave controller on STB boot. - disable_auto_start - Disables automatic startup of Z-Wave controller on STB boot. All of the above commands return plain-text HTTP response containing a few lines of text in the format "name = value": - In case of successful command completion, the response contains the following: - result = ok - running = {0|1} - auto_start = {0|1} - In case of an error (should never happen under normal circumstances): - result = error - error_message = {error description} Z-Wave API Transport -------------------- Z-Wave API requests are sent to Z-Wave controller using HTTP GET or HTTP POST requests (GET and POST requests are handled by Z-Wave controller the same way; it is recommended to use POST requests to avoid possible caching performed by the HTTP client or HTTP proxies). HTTP URL for Z-Wave API request is constructed in the following way: - http://{STB-IP-address}:81/ZWaveAPI/{command} Here are some examples of HTTP URLs representing Z-Wave API requests: - http://192.168.0.100:81/ZWaveAPI/Data/0 - http://192.168.0.100:81/ZWaveAPI/Run/controller.AddNodeToNetwork(1) HTTP response body for any Z-Wave API request is a data structure in JSON format. For the information about JSON format, please see http://en.wikipedia.org/wiki/JSON. Z-Wave API Concepts ------------------- Z-Wave API uses the following concepts: - Controller. - Represents Z-Wave controller itself. - Device. - Z-Wave device (also known as "node") in the Z-Wave network managed by Z-Wave controller. Each Z-Wave device has an ID (or "node ID") in the scope of the Z-Wave network. - Device instance. - A particular "instance" of Z-Wave device. In Z-Wave, each Z-Wave device contains one or several "instances", where each instance represents some aspect of the device. Each instance has an ID (instance ID) in the scope of Z-Wave device (ID can be 0, 1, etc). - Command class (CC): - Z-Wave command class. In Z-Wave, each Z-Wave device instance can support several interfaces, which are called "command classes". Each command class is identified has an ID. Command classes and their IDs are specified in Z-Wave standard. Z-Wave controller internally maintains the database with the information about all Z-Wave devices known to Z-Wave controller. This includes the information about the structure of each Z-Wave device (what instances it has, and what command classes are supported by each instance of each device), and information about the current (latest known) state of each Z-Wave device. When Z-Wave controller detects some changes in the state of Z-Wave devices, it updates its database. The database can be updated as the result of Z-Wave API command sent to Z-Wave controller by some client application, or asynchronously. Each database update has a timestamp, that allows to find the parts of the database which were changed since a particular time. Z-Wave controller exposes the following object model to Z-Wave API clients: - (object model root) - controller - devices[nodeId] - instances[instanceId] - commandClasses[ccId] Z-Wave API provides "Run" and "Data" commands which allow to run operations on any object in this object model and to retrieve the data set describing the properties of objects in this object model. Z-Wave API "Run" command ------------------------ "Run" command of Z-Wave API instructs Z-Wave controller to run the given operation on the given object. The object can be the controller itself, a particular device, a particular instance of a particular device, or a particular command class of a particular instance of a particular device. The general syntax is: - Run/{object-path}.{operation-name}({argument}, ..., {argument}) Supported object paths and operations: - controller.AddNodeToNetwork({0|1}) - Start (1) or stop (0) the process of adding a new Z-Wave device to Z-Wave network. - controller.RemoveNodeFromNetwork({0|1}) - Start (1) or stop (0) the process of removing Z-Wave device from Z-Wave network. - controller.SetLearnMode({0|1}) - Start (1) or stop (0) the learn mode process. - controller.SetDefault() - Performs full reset of Z-Wave controller. NOTE: this destroys all stored data about Z-Wave network. - devices[{nodeId}].instances[{instanceId}].commandClasses[{ccId}].Set({value}) - Sets Z-Wave device state corresponding to the given command class of the given device instance to the given value. - devices[{nodeId}].instances[{instanceId}].commandClasses[{ccId}].Get() - Invalidates Z-Wave device state corresponding to the given command class of the given device instance. This will force Z-Wave controller to reread this state when feasible (immediately if Z-Wave device supports it, or in future when Z-Wave device wakes up). Example of full HTTP URL representing a "Run" command: - http://192.168.0.100:81/ZWaveAPI/Run/devices[5].instances[0].commandClasses[38].set(99) - Sets the brightness of Z-Wave dimmer device ID "5" to the value "99" (which means 100% brightness). Z-Wave API "Data" command ------------------------- "Data" command of Z-Wave API allows the client to fetch a data set describing properties of objects from the Z-Wave controller database. The syntax is: - Data/{timestamp} Here, {timestamp} is the time in seconds since UNIX Epoch (1970-01-01 00:00:00 UTC) which limits the data set to be retrieved: the returned data set includes only those objects whose state has been updated since this time. If {timestamp} is 0, it effectively means "return all data". Example of full HTTP URL representing a "Data" command: - http://192.168.0.100:81/ZWaveAPI/Data/0 HTTP response body for "Data" command is the following JSON-formatted data structure: - { - "{path}": {subtree}, - "{path}": {subtree}, - ... - "{path}": {subtree}, - "updateTime": {current-timestamp} - } Here: - {path} is the path to the root element of an updated subtree in the hierarchy of objects from the database of Z-Wave controller, and {subtree} is the updated subtree itself. Each subtree contains the hierarchy of objects and their properties. - {current-timestamp} is the current time (seconds since UNIX Epoch) from the viewpoint of Z-Wave controller. The client of Z-Wave API can use this timestamp in the next "Data" command request to get updates since the previous request. The exact data structure (tree structure and available object properties) depends on particular types of Z-Wave devices and command classes supported by these devices. To get information about data structure that will be provided by Z-Wave controller for particular Z-Wave devices, connect these Z-Wave devices to Z-Wave controller and perform "Data" command (with timestamp = 0 to fetch the entire data set). Each object property is represented by a data structure with the following child properties: - value - The object property value itself. - updated - Boolean flag indicating if the value is currently up-to-date (i.e. was updated and not invalidated after that) or invalid (i.e. was invalidated and not yet updated after that). - updateTime - Timestamp (UNIX Epoch) when the value was lasted updated (i.e. Z-Wave controller received the information about this value from the Z-Wave device). - invalidateTime - Timestamp (UNIX Epoch) when the value was last invalidated (i.e. "Get" operation was executed on the object). Simple Web UI ------------- Z-Wave Controller software provides a simple built-in web UI (implemented in HTML+JavaScript), which can run on a PC (or any device with web browser and mouse or touchscreen). This web UI is accessible via the following URL: http://{STB-IP-address}:81 The web UI provides allows to perform various operation on Z-Wave controller, such as: - Adding/removing Z-Wave devices to/from Z-Wave network. - Viewing current state of Z-Wave devices. - Sending commands to Z-Wave devices. - Performing other operations on Z-Wave controller. The web UI also provides some debugging functions which can be useful for studying Z-Wave API and debugging its usage. Aditional Information --------------------- Z-Way controller software running on Dune HD STB is internally based on and is partially compatible with "Z-Way" software developed by Z-Wave.Me: - http://en.z-wave.me/content/what-z-way In particular, the provided Z-Wave API and the simple web UI are similar to and partially compatible to those provided by the Z-Way. The main differences between Z-Way controller software running on Dune HD STB and Z-Way are: - Z-Way is Python-based, Dune HD Z-Way controller is JavaScript-based. - Z-Way provides a Python-based automation engine, Dune HD Z-Way controller provides a JavaScript-based automation engine. - Other differences caused by specific tunings and optimizations implemented for Dune HD Z-Way controller. Thus, although it is not always applicable, the following documentation about Z-Way can be useful to get more information about Z-Wave controller, simple web UI and Z-Wave API provided by Dune HD STB: - http://en.z-wave.me/docs/zway_manual_en.pdf - http://en.z-wave.me/docs/ZWay_QSG_en.pdf - http://razberry.z-wave.me/docs/razberry.pdf General information about Z-Wave can be obtained here: - http://en.wikipedia.org/wiki/Z-Wave - http://www.z-wave.com/ - http://www.z-wavealliance.org/ - http://wiki.zwaveeurope.com/ - ftp://ftp.zwaveeurope.com/pub/doc/ZWHB_en_1.0.pdf