getcontrol

/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 #, a list reference #'s, or "all" to return control information for all devices)

{
	"ControlPairs": [
		{
			"Do_Update": true,
			"SingleRangeEntry": true,
			"ControlButtonType": 0,
			"ControlButtonCustom": "",
			"CCIndex": 0,
			"Range": null,
			"Ref": 2256,
			"Label": "On Last Level",
			"ControlType": 5,
			"ControlLocation": {
				"Row": 1,
				"Column": 3,
				"ColumnSpan": 0
			},
			"ControlLoc_Row": 1,
			"ControlLoc_Column": 3,
			"ControlLoc_ColumnSpan": 0,
			"ControlUse": 4,
			"ControlValue": 255,
			"ControlString": "",
			"ControlStringList": null,
			"ControlStringSelected": null,
			"ControlFlag": false
		},
		{
			"Do_Update": true,
			"SingleRangeEntry": true,
			"ControlButtonType": 0,
			"ControlButtonCustom": "",
			"CCIndex": 1,
			"Range": null,
			"Ref": 2256,
			"Label": "On",
			"ControlType": 5,
			"ControlLocation": {
				"Row": 1,
				"Column": 2,
				"ColumnSpan": 0
			},
			"ControlLoc_Row": 1,
			"ControlLoc_Column": 2,
			"ControlLoc_ColumnSpan": 0,
			"ControlUse": 1,
			"ControlValue": 99,
			"ControlString": "",
			"ControlStringList": null,
			"ControlStringSelected": null,
			"ControlFlag": false
		},
		{
			"Do_Update": true,
			"SingleRangeEntry": true,
			"ControlButtonType": 0,
			"ControlButtonCustom": "",
			"CCIndex": 2,
			"Range": null,
			"Ref": 2256,
			"Label": "Off",
			"ControlType": 5,
			"ControlLocation": {
				"Row": 1,
				"Column": 1,
				"ColumnSpan": 0
			},
			"ControlLoc_Row": 1,
			"ControlLoc_Column": 1,
			"ControlLoc_ColumnSpan": 0,
			"ControlUse": 2,
			"ControlValue": 0,
			"ControlString": "",
			"ControlStringList": null,
			"ControlStringSelected": null,
			"ControlFlag": false
		},
		{
			"Do_Update": true,
			"SingleRangeEntry": true,
			"ControlButtonType": 0,
			"ControlButtonCustom": "",
			"CCIndex": 3,
			"Range": {
				"RangeStart": 1,
				"RangeEnd": 98,
				"RangeStatusDecimals": 0,
				"RangeStatusValueOffset": 0,
				"RangeStatusDivisor": 0,
				"ScaleReplace": "",
				"HasScale": false,
				"RangeStatusPrefix": "Dim ",
				"RangeStatusSuffix": "%"
			},
			"Ref": 2256,
			"Label": "Dim (value)%",
			"ControlType": 7,
			"ControlLocation": {
				"Row": 2,
				"Column": 1,
				"ColumnSpan": 3
			},
			"ControlLoc_Row": 2,
			"ControlLoc_Column": 1,
			"ControlLoc_ColumnSpan": 3,
			"ControlUse": 3,
			"ControlValue": 1,
			"ControlString": "",
			"ControlStringList": null,
			"ControlStringSelected": null,
			"ControlFlag": false
		}
	],
	"ref": 2256,
	"name": "light",
	"location": "Office",
	"location2": "First Floor"
}

Fields:

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 ## %".