[C#.NET/ASP.NET] HS3 Z-Wave - XML HTTP RESTful API

[RedTechie]

About:
I spent hours trying to find something similar to a HTTP REST based API for HS3. After failing, I just decided to write my own via ASP C# .NET. This API will return XML based responses by just submitting a particular HTTP URL GET query.

One of the reasons I really wanted a REST based API for HomeSeer is I currently have an Adobe Air application that has a PHP backend. I am in the process of switching from Vera3 to HomeSeer v3 and I needed some way of interfacing HS3

with my PHP based Adobe Air application.

Please Note: I have only tested this script with HomeSeer 3 and the Z-Wave Plugin. I do not own HomeSeer 2.5 or earlier, so I make no guarantees if this script will work on it or not. I also currently only have a Light fixture based Z-Wave automation network.

Support and Discussion:
I can not post a reply in this thread. If you have any questions or issues with this API please post in my Discussion Thread located here: http://board.homeseer.com/showthread.php?p=1089133

Features:

• Invoke the HomeSeer Speaker Client and submit Text-To-Speech Phrases
• List all events or events with a certain Type
• Execute an Event by Name OR ID
• List all Location 1 names
• List all Location 2 names
• List all devices or devices that match a device type (Devices can also be listed in corelation with Locations)
• Get devices for the following Locations
• Get Device Information by Device Name OR ID
• Get Device Status/Value by Name OR ID
• Set Device Status/Value by Name OR ID

Installation:
Copy the extracted "HomeSeer_REST_API.aspx" file to your "[HS3 Root Install Path]\html" folder. For Example: C:\Program Files\HomeSeer HS3\html\HomeSeer_REST_API.aspx

Version Changes:
Version 1.0.0

• Initial Release

Version 1.1.0

• New Exec Event by ID call
• New Get Device Info by ID call
• New Get Device Status Value by Name call
• New Get Device Status Value by ID call

Version 1.2.0

• This version is a community based update with large contributions from the user 'Geer/Gear'
• New Set Device Value by Name (Recommended for non light fixtures)
• New Set Device Value by ID (Recommended for non light fixtures)
• "GetDeviceStatusValueByName" and "GetDeviceStatusValueByID" should now allow getting and setting of the status of a device which doesn't have defined controls
• Additional HS logging added to a few functions

Usage:
To Invoke commands simply use the following URL structure:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=(FUNC NAME)[&param1=(PARAM 1 VALUE)&param2=(PARAM 2 VALUE)]

The function value is required. Param1, 2, etc. are optional; not every function call will need parameters.

Usage Examples:

Speak - Invokes the HS3 Text-To-Speech Engine and sends out a message to all Speech Clients

Parameters:
Param1 = (Phrase you want HomeSeer to say)

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=speak&param1=Hello HomeSeer User

Returns:

Sent phrase to HomeSeer... 

------------------

List Events - Can list all events or only Events with the given type.

Parameters:
Param1 = all OR (Event Type Name)

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listevents&param1=all

Returns:

<eventList>
  <eventGroup name="Event Group 1" id="123">
    <event name="Event Name 1" id="8763" type="" enabled="True" includeInPowerfail="True" priorityEvent="False" security="False" />
  </eventGroup>
  <eventGroup name="Event Group 2" id="321">
    <event name="Event Name 2" id="427" type="" enabled="True" includeInPowerfail="True" priorityEvent="False" security="False" />
  </eventGroup>
</eventList> 

------------------

Execute Event - Starts an Event by Event Name

Parameters:
Param1 = (Event Name)

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=execevent&param1=Event 1

Returns:

true OR false 

------------------

Execute Event By ID - Starts an Event by Event ID

Parameters:
Param1 = (Event ID)

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=execeventbyid&param1=(EVENT ID)

Returns:

true OR false 

------------------

List First Locations - Lists all Location 1 names

Parameters: (No Params)

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listfirstlocations

Returns:

<firstLocationList>
  <location name="First Location Name 1" />
  <location name="First Location Name 2" />
</firstLocationList> 

------------------

List Second Locations - Lists all Location 2 names

Parameters: (No Params)

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listsecondlocations

Returns:

<secondLocationList>
  <location name="Second Location Name 1" />
  <location name="Second Location Name 2" />
</secondLocationList> 

------------------

List Devices - Lists Devices by type and or certain orders
There are a few ways you can request a list of devices. You can limit it to only certain device types like "Z-Wave Switch Binary" (On/Off Switch), you can also request the devices be organised in their respective locations.

Parameters:
param1 = "all" OR Device Type (Z-Wave Switch Binary, Z-Wave Temperature, etc.) You can specify multiple types by using a "*" For example: Z-Wave Switch Binary*Z-Wave Temperature
param2 = Order Logic (nothing (0), 1, 2)

• 0 or nothing = Display all devices regardless of location
• 1 = Display devices by Location1 then Location2
• 2 = Display devices by Location2 then Location1

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listdevices&param1=all

Returns:

<deviceList>
  <device name="Device Name 1" id="1433" type="Z-Wave Switch Binary" value="0" address="" code="" canDim="False" lastChange="1/1/0001 12:00:00 AM" firstLocation="Location1 Name" secondLocation="Location 2 Name" />
  <device name="Device Name 2" id="146" type="Z-Wave Temperature" value="100" address="" code="" canDim="False" lastChange="10/11/2013 10:25:41 PM" firstLocation="Location1 Name" secondLocation="Location 2 Name" />
</deviceList> 

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listdevices&param1=all&param2=1

(If param2 was set to the value of '2' it would have the same output but the logic would treat Location 2 as the primary location and Location

1 as the secondary location)

Returns:

<deviceList>
  <devicePrimaryLocation name="Location 1 Name">
    <deviceSecondaryLocation name="Location 2 Name">
      <device name="Device Name 1" id="1433" type="Z-Wave Static Controller" value="0" address="" code="" canDim="False" lastChange="1/1/0001 12:00:00 AM" firstLocation="Location 1 Name" secondLocation="Location 2 Name" />
    </deviceSecondaryLocation>
  </devicePrimaryLocation>
  <devicePrimaryLocation name="Location 1 Name">
    <deviceSecondaryLocation name="Location 2 Name">
      <device name="Device Name 2" id="146" type="Z-Wave Battery" value="100" address="" code="" canDim="False" lastChange="10/11/2013 10:25:41 PM" firstLocation="Location 1 Name" secondLocation="Location 2 Name" />
      <device name="Device Name 3" id="1647" type="Z-Wave Luminance" value="28" address="" code="" canDim="False" lastChange="11/24/2013 11:44:11 AM" firstLocation="Location 1 Name" secondLocation="Location 2 Name" />
    </deviceSecondaryLocation>
  </devicePrimaryLocation>
</deviceList> 

------------------

Get Devices For Location - Lists all devices in given locations

Parameters:
param1 = (Location 1 Name)
param2 = (Location 2 Name)

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdevicesforlocation&param1=(Location 1 Name)&param2=(Location 2 Name)

Returns:

<deviceListForLocation>
  <device name="Device 1 Name" id="1433" type="Z-Wave Static Controller" value="0" address="" code="" canDim="False" lastChange="1/1/0001 12:00:00 AM" firstLocation="Location 1 Name" secondLocation="Location 2 Name" />
  <device name="Device 2 Name" id="1433" type="Z-Wave Static Controller" value="0" address="" code="" canDim="False" lastChange="1/1/0001 12:00:00 AM" firstLocation="Location 1 Name" secondLocation="Location 2 Name" />
</deviceListForLocation> 

------------------

Get Device Information - Gets Information for a single Device

Parameters:
param1 = (Device 'Full' Name) Full Name means including Location 1, Location 2 and the Device's name. For example: 'Upstrairs Bedroom Lamp'. 'Upstairs' being Location 1, 'Bedroom' being Location 2 and 'Lamp' being the

device's name.

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdeviceinfo&param1=(Device 'Full' Name)

Returns:

<deviceInfo>
  <device name="Device Name" id="7162" type="Z-Wave Switch Binary" value="0" address="" code="" canDim="False" lastChange="11/24/2013 11:50:44 AM" firstLocation="Location 1 Name" secondLocation="Location 2 Name" />
</deviceInfo> 

------------------

Get Device Information By ID - Gets Information for a single Device by its ID

Parameters:
param1 = (Device ID)

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdeviceinfobyid&param1=(Device ID)

Returns:

<deviceInfo>
  <device name="Device Name" id="7162" type="Z-Wave Switch Binary" value="0" address="" code="" canDim="False" lastChange="11/24/2013 11:50:44 AM" firstLocation="Location 1 Name" secondLocation="Location 2 Name" />
</deviceInfo> 

------------------

Get Device Status By Name - Gets Status for Device by Name

Parameters:
param1 = (Device 'Full' Name) Full Name means including Location 1, Location 2 and the Device's name. For example: 'Upstrairs Bedroom Lamp'. 'Upstairs' being Location 1, 'Bedroom' being Location 2 and 'Lamp' being the

device's name.
param2 = (Status you want to check for) If you Want to see if a Lamp is on pass 'On'. If you Want to see if a Lamp is off pass 'Off'. If you want to check for a 20% Dim value pass 'Dim 20%'

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=devicestatusbyname&param1=(Device 'Full' Name)&param2=(Status you want to check for)

Returns:

true OR false 

------------------

Get Device Status By ID - Gets Status for Device by its Reference ID

Parameters:
param1 = (Device Reference ID) Can be retrieved from the 'ID' attribute from List Devices.
param2 = (Status you want to check for) If you Want to see if a Lamp is on pass 'On'. If you Want to see if a Lamp is off pass 'Off'. If you want to check for a 20% Dim value pass 'Dim 20%'

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=devicestatusbyid&param1=(Device Reference ID)&param2=(Status you want to check for)

Returns:

true OR false 

------------------

Get Device Status Value By Name - Gets Status Value for Device by Name

Parameters:
param1 = (Device 'Full' Name) Full Name means including Location 1, Location 2 and the Device's name. For example: 'Upstrairs Bedroom Lamp'. 'Upstairs' being Location 1, 'Bedroom' being Location 2 and 'Lamp' being the

device's name.
param2 = ("value" or "label") If you Want to see the value (0 - 255) of a device pass "value" for this param. If you want to see the label name (On - Off) associated with this value pass "label" for this param.

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdevicestatusvaluebyname&param1=(Device 'Full' Name)&param2=("value" or "label")

Returns:

"value" or "label" of device 

------------------

Get Device Status Value By ID - Gets Status Value for Device by ID

Parameters:
param1 = (Device ID)
param2 = ("value" or "label") If you Want to see the value (0 - 255) of a device pass "value" for this param. If you want to see the label name (On - Off) associated with this value pass "label" for this param.

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdevicestatusvaluebyid&param1=(Device ID)&param2=("value" or "label")

Returns:

"value" or "label" of device 

------------------

Set Device Status By Name - Sets Status for Device by Name *(Recommended for controlling Light fixtures)*

Parameters:
param1 = (Device 'Full' Name) Full Name means including Location 1, Location 2 and the Device's name. For example: 'Upstrairs Bedroom Lamp'. 'Upstairs' being Location 1, 'Bedroom' being Location 2 and 'Lamp' being the

device's name.
param2 = (Status you want to set) If you Want to set a Lamp to on pass 'On'. If you Want to set a Lamp to off pass 'Off'. If you want to set a 20% Dim value pass 'Dim 20%'

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=setdevicebyname&param1=(Device 'Full' Name)&param2=(Status you want to set)

Returns:

Indeterminate
OR
All_Success
OR
Some_Failed
OR
All_Failed 

------------------

Set Device Status By ID - Sets Status for Device by its Reference ID *(Recommended for controlling Light fixtures)*

Parameters:
param1 = (Device Reference ID) Can be retrieved from the 'ID' attribute from List Devices.
param2 = (Status you want to set) If you Want to set a Lamp to on pass 'On'. If you Want to set a Lamp to off pass 'Off'. If you want to set a 20% Dim value pass 'Dim 20%'

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=setdevicebyid&param1=(Device Reference ID)&param2=(Status you want to set)

Returns:

Indeterminate
OR
All_Success
OR
Some_Failed
OR
All_Failed 

------------------

Set Device Value By Name - Sets Value for Device by Name *(Recommended for controlling other types of z-wave devices)*

Parameters:
param1 = (Device 'Full' Name) Full Name means including Location 1, Location 2 and the Device's name. For example: 'Upstrairs Bedroom Lamp'. 'Upstairs' being Location 1, 'Bedroom' being Location 2 and 'Lamp' being the

device's name.
param2 = (Value you want to set) Example: 0-255

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=setdevicevaluebyname&param1=(Device 'Full' Name)&param2=(Value you want to set)

Returns:

All_Success
OR
All_Failed 

------------------

Set Device Value By ID - Sets Value for Device by its Reference ID *(Recommended for controlling other types of z-wave devices)*

Parameters:
param1 = (Device Reference ID) Can be retrieved from the 'ID' attribute from List Devices.
param2 = (Value you want to set) Example: 0-255

URL Call:

http://(HS3 URL)/HomeSeer_REST_API.aspx?function=setdevicevaluebyid&param1=(Device Reference ID)&param2=(Value you want to set)

Returns:

All_Success
OR
All_Failed 

[donstephens]

Ohh.... Cool!

[donstephens]

Stephen

First off, let me say this is really a slick idea.
I am running HS3 and HS2 on the same machine. HS2 is XXX.XXX.XXX.20 and
HS3 is XXX.XXX.XXX.20:81.

I don't know if this makes any difference.

Running the HTTP command

http://192.168.0.20/HomeSeer_REST_API.aspx?function=speak&param1=Hello%20HomeSeer%20User 

returns the error below.

Compiler Error Message: CS1502: The best overloaded method match for 'Scheduler.hsapplication.Speak(string, ref bool, string)' has some invalid arguments

Source Error:


Line 91:     void ICanTalk(string talkThis) 
Line 92:     {
Line 93:         hs.Speak(talkThis, false, "");
Line 94:         Response.Write("Sent phrase to HomeSeer...");
Line 95:     }

Source File: c:\Program Files\Homeseer HSPRO\html\HomeSeer_REST_API.aspx    Line: 93 

I am not sure if this is my problem or yours.

Thanks

[donstephens]

OK, my problem. Need the :81 in the URL field.

Having fun here.

[donstephens]

Very slick! Thanks again.


Appreciate the private note.

[rmasonjr]

Has anyone been successful at getting this running on the Zee?
The calls to the API just 'hang' and never respond. Nothing in the HomeSeer logs...

[Moskus]

Has anyone been successful at getting this running on the Zee?
The calls to the API just 'hang' and never respond. Nothing in the HomeSeer logs...

I have yet to test this, but sometimes when my scripts hang it's because passing (hs) as a reference fails. (Nothing) works for some reason.

[chewie]

Hey guys, just following up on this one, has anyone gotten this working with the Zee? Also can this be used to pass commands via HTTPS? I am considering using this to pass commands between instancse of Homeseer in different locations which would mean sending the commands over the Internet. I would set a different username/password on the remote site (Which will be a Zee) and then pass the commands via HTTPS so that the info is encrypted.

Any thoughts on whether or not this will work?

[jon00]

No, Rich has stated that ASP.NET pages are not supportable on the Zee due to very slow page rendering.

[DJF3]

Like

I like your script.. It allows me to have "single-line-URL's" that I can call from Python to get device information, run events, etc..

Because of this I can control my HS devices via Alfred on OSX (https://www.alfredapp.com/

Example: Command+Space "home lamp2"
(runs event that toggles Philips Hue Lamp 2)
Example: Command+Space "home tvoff"
(runs event that switches off TV + decoder)