Dune HD STB - Z-WAVE API

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.

Here is quick start guide for experienced users:

   - Install the following plugin onto Dune HD STB:
      - http://files.dune-hd.com/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.

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.

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

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

"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).

"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).

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.

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