Announcement

Collapse
No announcement yet.

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

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

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

    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:
    Code:
    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:
    Code:
    http://(HS3 URL)/HomeSeer_REST_API.aspx?function=speak&param1=Hello HomeSeer User
    Returns:
    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&param1=all
    Returns:
    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&param1=Event 1
    Returns:
    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&param1=(EVENT ID)
    Returns:
    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
    Returns:
    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
    Returns:
    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&param1=all
    Returns:
    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
    URL Call:
    Code:
    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:
    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&param1=(Location 1 Name)&param2=(Location 2 Name)
    Returns:
    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&param1=(Device 'Full' Name)
    Returns:
    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&param1=(Device ID)
    Returns:
    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&param1=(Device 'Full' Name)&param2=(Status you want to check for)
    Returns:
    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&param1=(Device Reference ID)&param2=(Status you want to check for)
    Returns:
    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&param1=(Device 'Full' Name)&param2=("value" or "label")
    Returns:
    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&param1=(Device ID)&param2=("value" or "label")
    Returns:
    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&param1=(Device 'Full' Name)&param2=(Status you want to set)
    Returns:
    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&param1=(Device Reference ID)&param2=(Status you want to set)
    Returns:
    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&param1=(Device 'Full' Name)&param2=(Value you want to set)
    Returns:
    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&param1=(Device Reference ID)&param2=(Value you want to set)
    Returns:
    PHP Code:
    All_Success
    OR
    All_Failed 
    Attached Files
    Last edited by RedTechie; August 10th, 2014, 09:27 AM. Reason: New Version - v1.2.0 Released!

  • #2
    Ohh.... Cool!
    Don

    Comment


    • #3
      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
      PHP Code:
      http://192.168.0.20/HomeSeer_REST_API.aspx?function=speak&param1=Hello%20HomeSeer%20User 
      returns the error below.


      PHP Code:
      Compiler Error MessageCS1502The 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(talkThisfalse"");
      Line 94:         Response.Write("Sent phrase to HomeSeer...");
      Line 95:     }

      Source Filec:\Program Files\Homeseer HSPRO\html\HomeSeer_REST_API.aspx    Line93 
      I am not sure if this is my problem or yours.

      Thanks
      Don

      Comment


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

        Having fun here.
        Don

        Comment


        • #5
          Very slick! Thanks again.


          Appreciate the private note.
          Don

          Comment


          • #6
            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...
            HS3Pro Running on a Raspberry Pi3
            64 Z-Wave Nodes, 168 Events, 280 Devices
            UPB modules via OMNI plugin/panel
            Plugins: Z-Wave, BLRF, OMNI, HSTouch, weatherXML, EasyTrigger
            HSTouch Clients: 3 Android, 1 Joggler

            Comment


            • #7
              Originally posted by rmasonjr View Post
              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.
              HSPro 3.0.0.458, Z-NET with Z-wave plugin 3.0.1.190, RFXCOM + 2x RFXtrx433E, HSTouch, Squeezebox plugin, iTach IP/WF2IR & GC-100-6 with UltraGCIR, BLDenon, NetcamStudio, Jon00s Webpage builder, Harmony Hub plugin, SCSIP (with FreePBX), Arduino plugin, IFTTT, Pushalot plugin, Device History plugin.
              Running on Windows 10 (64) virtualized
              on ESXi (Fujitsu Primergy TX150 S8).
              WinSeer (for Win10) - TextSeer - FitbitSeer - HSPI_MoskusSample

              Are you Norwegian (or Scandinavian) and getting started with HomeSeer? Read the "HomeSeer School"!

              Comment


              • #8
                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?

                Comment


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

                  Comment


                  • #10
                    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)

                    Comment

                    Working...
                    X