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:
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
Version 1.1.0
Version 1.2.0
Usage:
To Invoke commands simply use the following URL structure:
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:
Returns:
------------------
List Events - Can list all events or only Events with the given type.
Parameters:
Param1 = all OR (Event Type Name)
URL Call:
Returns:
------------------
Execute Event - Starts an Event by Event Name
Parameters:
Param1 = (Event Name)
URL Call:
Returns:
------------------
Execute Event By ID - Starts an Event by Event ID
Parameters:
Param1 = (Event ID)
URL Call:
Returns:
------------------
List First Locations - Lists all Location 1 names
Parameters: (No Params)
URL Call:
Returns:
------------------
List Second Locations - Lists all Location 2 names
Parameters: (No Params)
URL Call:
Returns:
------------------
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)
URL Call:
Returns:
URL Call:
(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:
------------------
Get Devices For Location - Lists all devices in given locations
Parameters:
param1 = (Location 1 Name)
param2 = (Location 2 Name)
URL Call:
Returns:
------------------
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:
Returns:
------------------
Get Device Information By ID - Gets Information for a single Device by its ID
Parameters:
param1 = (Device ID)
URL Call:
Returns:
------------------
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:
Returns:
------------------
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:
Returns:
------------------
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:
Returns:
------------------
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:
Returns:
------------------
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:
Returns:
------------------
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:
Returns:
------------------
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:
Returns:
------------------
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:
Returns:
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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=(FUNC NAME)[¶m1=(PARAM 1 VALUE)¶m2=(PARAM 2 VALUE)]
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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=speak¶m1=Hello HomeSeer User
PHP Code:
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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listevents¶m1=all
PHP Code:
<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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=execevent¶m1=Event 1
PHP Code:
true OR false
Execute Event By ID - Starts an Event by Event ID
Parameters:
Param1 = (Event ID)
URL Call:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=execeventbyid¶m1=(EVENT ID)
PHP Code:
true OR false
List First Locations - Lists all Location 1 names
Parameters: (No Params)
URL Call:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listfirstlocations
PHP Code:
<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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listsecondlocations
PHP Code:
<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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listdevices¶m1=all
PHP Code:
<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>
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=listdevices¶m1=all¶m2=1
1 as the secondary location)
Returns:
PHP Code:
<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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdevicesforlocation¶m1=(Location 1 Name)¶m2=(Location 2 Name)
PHP Code:
<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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdeviceinfo¶m1=(Device 'Full' Name)
PHP Code:
<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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdeviceinfobyid¶m1=(Device ID)
PHP Code:
<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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=devicestatusbyname¶m1=(Device 'Full' Name)¶m2=(Status you want to check for)
PHP Code:
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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=devicestatusbyid¶m1=(Device Reference ID)¶m2=(Status you want to check for)
PHP Code:
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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdevicestatusvaluebyname¶m1=(Device 'Full' Name)¶m2=("value" or "label")
PHP Code:
"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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=getdevicestatusvaluebyid¶m1=(Device ID)¶m2=("value" or "label")
PHP Code:
"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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=setdevicebyname¶m1=(Device 'Full' Name)¶m2=(Status you want to set)
PHP Code:
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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=setdevicebyid¶m1=(Device Reference ID)¶m2=(Status you want to set)
PHP Code:
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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=setdevicevaluebyname¶m1=(Device 'Full' Name)¶m2=(Value you want to set)
PHP Code:
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:
Code:
http://(HS3 URL)/HomeSeer_REST_API.aspx?function=setdevicevaluebyid¶m1=(Device Reference ID)¶m2=(Value you want to set)
PHP Code:
All_Success
OR
All_Failed
Comment