Controlling with JSON
| URL | Description |
| /JSON?request=getstatus&ref=##&location1=LOC1&location2=LOC2 | Returns the status of a device in the system or all the devices in the following format. The following parameters are supported in order to filter the response: location1=loc1 (only return the devices that are in the specific location1, omit or set to "all" for all devices at this location) location2=loc2 (only return the devices that are in the specific location2, omit or set to "all" for all devices at this location) ref=## (only return the device that matches the specific reference #, this may be a list of reference #'s like 3467,2342,869, omit or set to "all" to return all devices) All GET requests are terminated with a CRLF. If no JSON data is expected from the request, the return may be either "ok", or "error". This response is for 2 devices, the first is a thermostat temperature, the second is a light switch:
Where: ref = unique device reference number, used for any subsequent requests such as device control, leave blank or set to "ALL" to get the status for all devices name = the name of the device location = the location of the device such as "kitchen" location2 = the second location of the device such as "first floor" value = the current value of the device, a double status = the current string that represents the status of the device such as "on" or "off" last_change = the date/time the device last changed status relationship = 2:root device (other devices may be part of this physical device),3:standalone=this is the only device that represents this physical device,4:child=this device is part of a group of devices that represent this physical device hide_from_view = true/false if true, this device has been set to not be visible in any user interface device_type_string = The string the describes this device, set by plugin authors on their devices. associated_devices = a list of device reference #'s that are associated with this device. If the device is a ROOT device, then the list is child devices, if the device is a child device, then the list will contain one device that is the root device. device_type = Detailed information about the capabilities of the device, used mainly to determine if the device adheres to other API's such as thermostat, energy, etc. See the Devices section in the Scripting section in the HomeSeer HS3 user documentation for information about the properties in this section. |
| /JSON?request=getcontrol&ref=## | Returns control information for a device in the system, or all devices. Devices contain "control pairs", one pair for each possible control value. For example, a light that can be turned on and off would contain 2 control pairs, one for ON and one for OFF. The control pair describes how to control the device. The most important information is the "Label" and the "ControlValue", as those will be needed when the device is to be controlled. The information from this call can be used to build a user interface that will control the device. Parameters: ref=### (where ### is the device reference #, or "all" to return control information for all devices) {
Where: Label = The label to display on this control, if its a button, it would be the button label like "On" or "Off" ControlType = Specifies the control type for this control, possible values are: Not_Specified = 1 Values = 2 'This is the default to use if one of the others is not specified. Single_Text_from_List = 3 List_Text_from_List = 4 Button = 5 ValuesRange = 6 'Rendered as a drop-list by default. ValuesRangeSlider = 7 TextList = 8 TextBox_Number = 9 TextBox_String = 10 Radio_Option = 11 Button_Script = 12 ' Rendered as a button, executes a script when activated. Color_Picker = 13 ControlLocation = Specifies the desired location of the control using row/column ControlUse = If the pair is to control a specifc function, such as On/Off/Dim, this specifies this function. This makes it easier to control basic devices without knowing the label. For example, some devices may use "On" for On, and others may use "Bright Full" for on. By checking this property it is easy to find the control element for common controls. The possible values are: Not_Specified = 0 _On = 1 _Off = 2 _Dim = 3 _On_Alternate = 4 _Play = 5 ' media control devices _Pause = 6 _Stop = 7 _Forward = 8 _Rewind = 9 _Repeat = 10 _Shuffle = 11 ControlValue = The value for this pair, use when controlling the device. Range = Specifies the range of this pair. This is used for pairs that represent multiple values, such as the dim level of a light. A light may specifiy a range of 1-99 for the dim levels. The range also specifies the label using RangeStatusPrefix (such as "Dim"), and RangeStatusSuffix (such as "%"). The formatted status of the device will then be formatted as "Dim ## %". |
| /JSON?request=controldevicebyvalue&ref=###&value=# | Control a device given the device's reference number "ref", and value "value". For example, if a light has a value of 0 for off, the following would turn off the device with reference # 3570: /JSON?request=controldevicebyvalue&ref=3570&value=0 The return is the current JSON formatted status of the device (same return as "getstatus"), or the string "error". |
| /JSON?request=controldevicebylabel&ref=###&label=label | Control a device by label, this is the label as returned by the "getcontrol" parameter. For example, if the device has a label "On" to turn a device on, the following URL would turn it on: /JSON?request=controldevicebylabel&ref=3570&label=On The return is the current JSON formatted status of the device (same return as "getstatus"), or the string "error". |
| /JSON?request=getevents | Returns the names of all events in the system. An event is an action to be performed such as controlling a light, a sequence of lights, a thermostat, etc. Events have two properties, a group name and an event name. This command returns the group name and event name for all events. These two pieces of information are used to control an event. Example: {
|
| /JSON?request=runevent&group=GROUPNAME&name=EVENTNAME | This command will execute the actions of an event. Pass the group name and event name. The group and name are not case sensitive. Note: Only available if A2Z-Link is enabled for automation. |
| /JSON?request=speak&phrase=text&host=HOST:NAME | Speaks the given phrase using text-to-speech. phrase = the phrase to speak host = the speaker host to speak out of. HomeSeer supports multiple hosts, like PC's and mobile devices. Each device is assgined a unique host:name ID. For example, a host on the PC named "hometroller" with the name "Android" would have the host name: HomeTroller:Android. If this is added to the host parameter, then the phrase will be spoken out that host only. Many hosts can be added and are separated by a comma, IE: host=HomeTroller:Android,iPhone:bill Note: Only available if A2Z-Link is enabled for automation. |
| /JSON?request=getlocations | Returns all the location names for location 1 and location 2 |
| /JSON?request=getcounter&counter=NAME | Returns the value for the given named counter |
| /JSON?request=getsetting&setting=SETTING_NAME | Returns the value for a specific settting. For example, the setting for
the name of location 1 is called "gLocLabel". To get the name of this
label use: /JSON?request=getsetting&setting=gLocLabel The return might be: {
|