mhop/ha-bridge
1
0
Fork 0
mirror of https://github.com/bwssytems/ha-bridge.git synced 2025-12-16 18:24:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Adding supported HUE API calls descriptions.

Browse Source
This commit is contained in:
Admin
2015-11-10 13:57:01 -06:00
parent 4b98f799c2
commit a23d662444
1 changed files with 223 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

223
README.md
View File

@@ -158,6 +158,229 @@ Show the Harmony Hub's current activity.
```
GET http://host:8080/api/devices/harmony/show
```
## HUE REST API usage
This section will describe the REST api available for controlling the bridge based off of the HUE API. This Bridge does not support the full HUE API, only the calls that are supported with the HA Bridge are shown. The REST body examples are all formatted for easy reading, the actual body usage should be like this:
```
{"var1":"value1","var2":"value2","var3:"value3"}
```
### Get all lights
GET http://host:port/api/<username>/lights
#### Description
Gets a list of all lights that have been discovered by the bridge.
#### Response
Returns a list of all lights in the system. As of 1.3 the full light resource is returned from the bridge. As of 1.4 the uniqueid is returned and from 1.7 the manufacturername also.
Note: For bridge versions < 1.3 only the name and light identifier are returned. As from version 1.9 luminaireuniqueid is returned.
If there are no lights in the system then the bridge will return an empty object, {}.
#### Response example
```
{
"1": {
"state": {
"on": true,
"bri": 144,
"hue": 13088,
"sat": 212,
"xy": [0.5128,0.4147],
"ct": 467,
"alert": "none",
"effect": "none",
"colormode": "xy",
"reachable": true
},
"type": "Extended color light",
"name": "Hue Lamp 1",
"modelid": "LCT001",
"swversion": "66009461",
"pointsymbol": {
"1": "none",
"2": "none",
"3": "none",
"4": "none",
"5": "none",
"6": "none",
"7": "none",
"8": "none"
}
},
"2": {
"state": {
"on": false,
"bri": 0,
"hue": 0,
"sat": 0,
"xy": [0,0],
"ct": 0,
"alert": "none",
"effect": "none",
"colormode": "hs",
"reachable": true
},
"type": "Extended color light",
"name": "Hue Lamp 2",
"modelid": "LCT001",
"swversion": "66009461",
"pointsymbol": {
"1": "none",
"2": "none",
"3": "none",
"4": "none",
"5": "none",
"6": "none",
"7": "none",
"8": "none"
}
}
}
```
### Get light attributes and state
GET http://host:port/api/<username>/lights/<id>
#### Description
Gets the attributes and state of a given light.
#### Response
Name Type Description
state state object Details the state of the light, see the state table below for more details.
type string A fixed name describing the type of light e.g. <20>Extended color light<68>.
name string 0, 32 A unique, editable name given to the light.
modelid string 6, 6 The hardware model of the light.
uniqueid string 6, 32 As of 1.4. Unique id of the device. The MAC address of the device with a unique endpoint id in the form: AA:BB:CC:DD:EE:FF:00:11-XX
manufacturername string 6, 32 As of 1.7. The manufacturer name.
luminaireuniqueid string 6, 32 As of 1.9. Unique ID of the luminaire the light is a part of in the format: AA:BB:CC:DD-XX-YY. AA:BB:, ... represents the hex of the luminaireid, XX the lightsource position (incremental but may contain gaps) and YY the lightpoint position (index of light in luminaire group). A gap in the lightpoint position indicates an incomplete luminaire (light search required to discover missing light points in this case).
swversion string 8, 8 An identifier for the software version running on the light.
Pointsymbol object This parameter is reserved for future functionality.
The state object contains the following fields
Name Type Description
on bool On/Off state of the light. On=true, Off=false
bri uint8 Brightness of the light. This is a scale from the minimum brightness the light is capable of, 1, to the maximum capable brightness, 254.
hue uint16 Hue of the light. This is a wrapping value between 0 and 65535. Both 0 and 65535 are red, 25500 is green and 46920 is blue.
sat uint8 Saturation of the light. 254 is the most saturated (colored) and 0 is the least saturated (white).
xy list 2..2 of float 4 The x and y coordinates of a color in CIE color space.
The first entry is the x coordinate and the second entry is the y coordinate. Both x and y are between 0 and 1.
ct uint16 The Mired Color temperature of the light. 2012 connected lights are capable of 153 (6500K) to 500 (2000K).
alert string The alert effect, which is a temporary change to the bulb<6C>s state. This can take one of the following values:
<EFBFBD>none<EFBFBD> <20> The light is not performing an alert effect.
<EFBFBD>select<EFBFBD> <20> The light is performing one breathe cycle.
<EFBFBD>lselect<EFBFBD> <20> The light is performing breathe cycles for 15 seconds or until an "alert": "none" command is received.
Note that this contains the last alert sent to the light and not its current state. i.e. After the breathe cycle has finished the bridge does not reset the alert to "none".
effect string The dynamic effect of the light, can either be <20>none<6E> or <20>colorloop<6F>.
If set to colorloop, the light will cycle through all hues using the current brightness and saturation settings.
colormode string 2, 2 Indicates the color mode in which the light is working, this is the last command type it received. Values are <20>hs<68> for Hue and Saturation, <20>xy<78> for XY and <20>ct<63> for Color Temperature. This parameter is only present when the light supports at least one of the values.
reachable bool Indicates if a light can be reached by the bridge.
#### Response example
```
{
"state": {
"hue": 50000,
"on": true,
"effect": "none",
"alert": "none",
"bri": 200,
"sat": 200,
"ct": 500,
"xy": [0.5, 0.5],
"reachable": true,
"colormode": "hs"
},
"type": "Living Colors",
"name": "LC 1",
"modelid": "LC0015",
"swversion": "1.0.3",
"pointsymbol": {
"1": "none",
"2": "none",
"3": "none",
"4": "none",
"5": "none",
"6": "none",
"7": "none",
"8": "none"
}
}
```
### Set light state
PUT http://host:port/api/<username>/lights/<id>/state
#### Description
Allows the user to turn the light on and off, modify the hue and effects. Please see the FAQ for info on performance considerations.
#### Body arguments
Name Type Description
on bool On/Off state of the light. On=true, Off=false Optional
bri uint8 The brightness value to set the light to.
Brightness is a scale from 1 (the minimum the light is capable of) to 254 (the maximum). Note: a brightness of 1 is not off.
e.g. <20>brightness<73>: 60 will set the light to a specific brightness
Optional
hue uint16 The hue value to set light to.
The hue value is a wrapping value between 0 and 65535. Both 0 and 65535 are red, 25500 is green and 46920 is blue.
e.g. <20>hue<75>: 50000 will set the light to a specific hue.
Optional
sat uint8 Saturation of the light. 254 is the most saturated (colored) and 0 is the least saturated (white). Optional
xy list 2..2 of float 4 The x and y coordinates of a color in CIE color space.
The first entry is the x coordinate and the second entry is the y coordinate. Both x and y must be between 0 and 1.
If the specified coordinates are not in the CIE color space, the closest color to the coordinates will be chosen.
Optional
ct uint16 The Mired Color temperature of the light. 2012 connected lights are capable of 153 (6500K) to 500 (2000K). Optional
alert string
The alert effect, is a temporary change to the bulb<6C>s state, and has one of the following values:
<EFBFBD>none<EFBFBD> <20> The light is not performing an alert effect.
<EFBFBD>select<EFBFBD> <20> The light is performing one breathe cycle.
<EFBFBD>lselect<EFBFBD> <20> The light is performing breathe cycles for 15 seconds or until an "alert": "none" command is received.
Note that this contains the last alert sent to the light and not its current state. i.e. After the breathe cycle has finished the bridge does not reset the alert to "none".
Optional
effect string The dynamic effect of the light. Currently <20>none<6E> and <20>colorloop<6F> are supported. Other values will generate an error of type 7.
Setting the effect to colorloop will cycle through all hues using the current brightness and saturation settings.
Optional
transitiontime uint16 The duration of the transition from the light<68>s current state to the new state. This is given as a multiple of 100ms and defaults to 4 (400ms). For example, setting transistiontime:10 will make the transition last 1 second. Optional
bri_inc -254 to 254 As of 1.7. Increments or decrements the value of the brightness. bri_inc is ignored if the bri attribute is provided. Any ongoing bri transition is stopped. Setting a value of 0 also stops any ongoing transition. The bridge will return the bri value after the increment is performed. Optional
sat_inc -254 to 254 As of 1.7. Increments or decrements the value of the sat. sat_inc is ignored if the sat attribute is provided. Any ongoing sat transition is stopped. Setting a value of 0 also stops any ongoing transition. The bridge will return the sat value after the increment is performed. Optional
hue_inc -65534 to 65534 As of 1.7. Increments or decrements the value of the hue. hue_inc is ignored if the hue attribute is provided. Any ongoing color transition is stopped. Setting a value of 0 also stops any ongoing transition. The bridge will return the hue value after the increment is performed.
Note if the resulting values are < 0 or > 65535 the result is wrapped. For example:
{"hue_inc": 1}
on a hue value of 65535 results in a hue of 0.
{"hue_inc": -2}
on a hue value of 0 results in a hue of 65534.
Optional
ct_inc -65534 to 65534 As of 1.7. Increments or decrements the value of the ct. ct_inc is ignored if the ct attribute is provided. Any ongoing color transition is stopped. Setting a value of 0 also stops any ongoing transition. The bridge will return the ct value after the increment is performed. Optional
xy_inc -0.5 to 0.5 As of 1.7. Increments or decrements the value of the xy. xy_inc is ignored if the xy attribute is provided. Any ongoing color transition is stopped. Setting a value of 0 also stops any ongoing transition. Will stop at it's gamut boundaries. The bridge will return the xy value after the increment is performed. Optional
#### Body example
```
{
"hue": 50000,
"on": true,
"bri": 200
}
```
#### Response
A response to a successful PUT request contains confirmation of the arguments passed in. Note: If the new value is too large to return in the response due to internal memory constraints then a value of <20>Updated.<2E> is returned.
#### Response example
```
[
{"success":{"/lights/1/state/bri":200}},
{"success":{"/lights/1/state/on":true}},
{"success":{"/lights/1/state/hue":50000}}
]
```
## Ask Alexa
After this Tell Alexa: "Alexa, discover my devices"