Niviane, a REST/JSON interface for Z-Wave home automation

Posted June 19 2011, tagged z-wave,

Niviane is a windows service written in dot net that gives a REST/JSON interface to a Z-wave network.  It is uses Open Z-Wave to control devices, so all hardware compatible with that can be controlled through Niviane.

The service itself means that creating interfaces to control Z-wave is painless.  I've written a dot net client in 3 minutes, and mobile site in an evening.  The mobile site allows both Android and iPhone phones to control lights in my house.

The package comes with an installer that will install and configure the service to suit your network.  No need to have to go through the InstallUtil process.

I've build it to support the JSONP technique as well.  So if you want to write Javascript browser based interfaces JQuery, AJAX etc then thats possible.  If you don't have Visual studio, you can just run the installer and use whatever stack you prefer, even a webbrowser like lynx!

Getting Started

If you want to start playing with it, I've a few different files to download;

Most of the options can be ignored when installing.  The two of importance are the COM port, and the service address. 

For the COM port check with device manager to see what port has been assigned to your USB controller.  I've Aeon Labs Z-Stick II, and its always gone on to COM3 on my machines. 

The service address, is where commands need to be sent.  It defaults to http://localhost:9087/Niviane, which is fine for testing.  If you want to send commands from several computers then change it.  For exmple I've installed it on a web server that I can access from my laptop by going to http://masterserver/ so in the wizard I typed http://masterserver:9087/Niviane

Once you've the windows service up and running, its straight forward to start controlling the network.  Just make sure the Z-Wave controller is on the computer the service is running on, give it a few minutes to discover the network, then in a browser just go to;

http://localhost:9087/Niviane/nodes?callback=?

That should return all nodes as a JSON string.  The 'callback' parameter triggers the JOSNP format, just remove it to use JSON.

For dot net applications, just add a service reference to http://localhost:9087/Niviane.  The video linked aboves, shows all the steps to install and build a console client.

Service reference

The service reference is as follows, it can be seen at from this address http://localhost:9087/Niviane/help

To set the basic for node 2 its;

http://localhost:9087/Niviane/node/2/basic/100?callback=yes

Aside from Z-Wave there are a few options to run processes on the server.  I use it to control VLC to play music etc from my server.

UriDescriptionExample
alloff Turn everything off http://localhost:9087/Niviane/alloff
allon Turn everything on http://localhost:9087/Niviane/allon
isavailable Checks if the controller/network has completed startup http://localhost:9087/Niviane/isavailable
node/{NodeID} Gets details about a node http://localhost:9087/Niviane/node/{NODEID}
node/{NodeID}/basic/{Value} Sets tha basic property of a node http://localhost:9087/Niviane/node/{NODEID}/basic/{VALUE}
node/{NodeID}/location/{Value} Sets the location property of a node http://localhost:9087/Niviane/node/{NODEID}/location/{VALUE}
node/{NodeID}/name/{Value} Sets the name property of a node http://localhost:9087/Niviane/node/{NODEID}/name/{VALUE}
node/{NodeID}/pollingoff/{Value} Turns off polling for a particular node and value http://localhost:9087/Niviane/node/{NODEID}/pollingoff/{VALUE}
node/{NodeID}/pollingon/{Value} Turns on polling for a particular node and value http://localhost:9087/Niviane/node/{NODEID}/pollingon/{VALUE}
nodes Gets details of all nodes within the network http://localhost:9087/Niviane/nodes
processrunning Is there a process running which has been started previously http://localhost:9087/Niviane/processrunning
processstart/{Process} Start a process on the server http://localhost:9087/Niviane/processstart/{PROCESS}?arguments={ARGUMENTS}
processstop Stops the currently running process http://localhost:9087/Niviane/processstop
vlc Starts VLC with specified arguments http://localhost:9087/Niviane/vlc?arguments={ARGUMENTS}
comments powered by Disqus