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

Continuation of readme updating.

Browse Source
This commit is contained in:
Admin
2015-11-11 11:26:42 -06:00
parent d344b764da
commit 0ae66da085
1 changed files with 174 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
README.md
View File

@@ -45,9 +45,23 @@ This section will describe the REST api available for configuration. The REST bo
The body should be all in one string and not separated by returns, tabs or spaces. FYI, GET items do not require a body element. If you would like to see example return of json data for full Harmony Hub configuration if configured, which includes activities and devices, take a look at the resource file config.data. If you are interested in how the json data looks for the HA bridge configuration, after creating a device, look at the data directory for the device.db.
These calls can be accomplished with a REST tool using the following URLs and HTTP Verb types:
### Add a device
Add a new device to the HA Bridge configuration. This is the basic examples and the next 3 headinds describe alternate items to add.
Add a new device to the HA Bridge configuration. There is a basic examples and then three alternate examples for the add. Please note that dimming is supported as well as custom value based on the dimming number given from the echo. This is under the Dimming and Value example.
```
POST http://host:8080/api/devices
```
#### Body arguments
Name | Type | Description | Required
-----|-------|--------------|------------
name | string | A name for the device. This is also the utterance value that the Echo will use. | Required
deviceType | string | This identifies what type of device entry this is. It is used by the system and should be the values of "switch", "scene", "custom", "activity" or "button". | Required
onUrl | string | This is the URL that is executed for an "on" request and is used for the device types of "switch", "scene" and "custom". For "activity" or "button" it is the Json target generated by the Harmony Hub helpers. | Required
offUrl | string | This is the URL that is executed for an "off" request and is used for the device types of "switch", "scene" and "custom". For "activity" or "button" it is the Json target generated by the Harmony Hub helpers. | Required
httpVerb | string | This is used for "custom" calls that the user would like to execute. The values can only be "GET, "PUT", "POST". | Optional
contentType | string | This is an http type string such as "application/text" or "application/xml" or "application/json". | Optional
contentBody | string | This is the content body that you would like to send when executing an "on" request. | Optional
contentBodyOff | string | This is the content body that you would like to send when executing an "off" request. | Optional
#### Basic Example
```
{
"name" : "bedroom light",
"deviceType" : "switch",
@@ -55,11 +69,10 @@ POST http://host:8080/api/devices
"offUrl" : "http://192.168.1.201:3480/data_request?id=action&output_format=json&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue=0&DeviceNum=41"
}
```
### Dimming and value passing control
#### Dimming and value passing control Example
Dimming is also supported by using the expressions ${intensity.percent} for 0-100 or ${intensity.byte} for 0-255 or custom values using ${intensity.math(<your expression using "X" as the value to operate on>)} i.e. "${intensity.math(X/4)}".
e.g.
```
POST http://host:8080/api/devices
{
"name": "entry light",
"deviceType": "switch",
@@ -69,32 +82,23 @@ POST http://host:8080/api/devices
```
See the echo's documentation for the dimming phrase.
### POST/PUT support
added optional fields
* contentType (currently un-validated)
* httpVerb (POST/PUT/GET only supported)
* contentBody your post/put body for onUrl here
* contentBodyOff your post/put body for offUrl here
#### POST/PUT support Example
This will allow control of any other application that may need more then GET. You can also use the dimming and value control commands within the URLs as well.
e.g:
```
POST http://host:8080/api/devices
{
"name": "test device",
"deviceType": "switch",
"offUrl": "http://192.168.1.201:3480/data_request?id=action&output_format=json&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue=0&DeviceNum=31",
"onUrl": "http://192.168.1.201:3480/data_request?id=action&output_format=json&DeviceNum=31&serviceId=urn:upnp-org:serviceId:Dimming1&action=SetLoadLevelTarget&newLoadlevelTarget=${intensity.percent}",
"contentType" : "application/json",
"httpVerb":"POST",
"contentType" : "application/json",
"contentBody" : "{\"fooBar\":\"baz_on\"}"
"contentBodyOff" : "{\"fooBar\":\"baz_off\"}"
}
```
### Custom Usage URLs
#### Custom Usage URLs Example
Anything that takes an action as a result of an HTTP request will probably work and you can also use the dimming and value control commands within the URLs as well - like putting Vera in and out of night mode:
```
POST http://host:8080/api/devices
{
"name": "night mode",
"deviceType": "switch",
@@ -105,7 +109,21 @@ POST http://host:8080/api/devices
### Update a device
Update an existing device using it's ID that was given when the device was created and the update could contain any of the fields that are used and shown in the previous examples when adding a device.
```
POST http://host:8080/api/devices/`<id>`
POST http://host:8080/api/devices/<id>
```
#### Body arguments
Name | Type | Description | Required
-----|-------|--------------|------------
name | string | A name for the device. This is also the utterance value that the Echo will use. | Required
deviceType | string | This identifies what type of device entry this is. It is used by the system and should be the values of "switch", "scene", "custom", "activity" or "button". | Required
onUrl | string | This is the URL that is executed for an "on" request and is used for the device types of "switch", "scene" and "custom". For "activity" or "button" it is the Json target generated by the Harmony Hub helpers. | Required
offUrl | string | This is the URL that is executed for an "off" request and is used for the device types of "switch", "scene" and "custom". For "activity" or "button" it is the Json target generated by the Harmony Hub helpers. | Required
httpVerb | string | This is used for "custom" calls that the user would like to execute. The values can only be "GET, "PUT", "POST". | Optional
contentType | string | This is an http type string such as "application/text" or "application/xml" or "application/json". | Optional
contentBody | string | This is the content body that you would like to send when executing an "on" request. | Optional
contentBodyOff | string | This is the content body that you would like to send when executing an "off" request. | Optional
#### Basic Example
```
{
"name" : "bedroom light",
"deviceType" : "switch",
@@ -121,12 +139,12 @@ GET http://host:8080/api/devices
### Get a specific device
Get a device by ID assigned from creation and saved in the HA bridge configuration.
```
GET http://host:8080/api/devices/`<id>'
GET http://host:8080/api/devices/<id>
```
### Delete a specific device
Delete a device by ID assigned from creation and saved in the HA bridge configuration.
```
DELETE http://host:8080/api/devices/`<id>'
DELETE http://host:8080/api/devices/<id>
```
### Get HA Bridge Version
Get current version of the HA bridge software.
@@ -164,16 +182,14 @@ This section will describe the REST api available for controlling the bridge bas
{"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.
```
GET http://host:port/api/<username>/lights
```
#### Response
Returns a list of all lights in the system.
If there are no lights in the system then the bridge will return an empty object, {}.
#### Response example
```
{
"1": {
@@ -235,11 +251,10 @@ If there are no lights in the system then the bridge will return an empty object
}
```
### Get light attributes and state
GET http://host:port/api/<username>/lights/<id>
#### Description
Gets the attributes and state of a given light.
```
GET http://host:port/api/<username>/lights/<id>
```
#### Response
Name | Type | Description
-----|-------|-------------
@@ -267,7 +282,6 @@ alert | string | This will be set to "none".
effect | string | This will be set to "none".
colormode | string 2, 2 | This will be empty.
reachable | bool | Indicates if a light can be reached by the bridge and will be set to true.
#### Response example
```
{
"state": {
@@ -299,16 +313,15 @@ reachable | bool | Indicates if a light can be reached by the bridge and will be
}
```
### Set light state
Allows the user to turn the light on and off, modify the brightness.
```
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. <EFBFBD>brightness<EFBFBD>: 60 will set the light to a specific brightness. Optional
#### Body example
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. "brightness": 60 will set the light to a specific brightness. Optional
```
{
"on": true,
@@ -316,15 +329,140 @@ bri | uint8 | The brightness value to set the light to. Brightness is a scale fr
}
```
#### 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 `<60>Updated.<EFBFBD>` is returned.
#### Response example
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 "Updated." is returned.
```
[
{"success":{"/lights/1/state/bri":200}},
{"success":{"/lights/1/state/on":true}},
]
```
### Create user
Emulates creating a new user. The link button state on the HA Bridge is always on for the purpose of responding to this request. No actual user is saved as this is for compatibility.
```
POST http://host:port/api
```
#### Body arguments
Name | Type | Description | Required
-----|-------|--------------|-----------
devicetype | string 0..40 |
<application_name>#<devicename> application_name string 0..20, devicename string 0..19 (Example: my_hue_app#iphone peter ) | Required
username | string 10..40 | A username. If this is not provided, a random key will be generated and returned in the response. | Optional
```
{"devicetype": "my_hue_app#iphone peter"}
```
#### Response
Contains a list with a single item that details whether the user was added successfully along with the username parameter.
```
[{"success":{"username": "83b7780291a6ceffbe0bd049104df"}}]
```
### Get full state (datastore)
This command is used to fetch the entire datastore from the device, including settings and state information for lights, groups, schedules and configuration.
```
GET http://host:port/api/<username>
```
#### Response
Name | Type | Description
-----|-------|-------------
lights | object | A collection of all lights and their attributes.
groups | object | A collection of all groups and their attributes. This is empty.
config | object | All configuration settings.
schedules | object | A collection of all schedules and their attributes. This is not given.
scenes | object | A collection of all scenes and their attributes. This is empty.
sensors | object | A collection of all sensors and their attributes. This is not given.
rules | object | A collection of all rules and their attributes. This is not given.
```
{
"lights": {
"1": {
"state": {
"on": false,
"bri": 0,
"hue": 0,
"sat": 254,
"xy": [0.0000, 0.0000],
"ct": 0,
"alert": "none",
"effect": "none",
"colormode": "",
"reachable": true
},
"type": "Dimmable light",
"name": "Table Lamp 1",
"modelid": "LWB004",
"swversion": "65003148",
"pointsymbol": {
"1": "none",
"2": "none",
"3": "none",
"4": "none",
"5": "none",
"6": "none",
"7": "none",
"8": "none"
}
},
"2": {
"state": {
"on": true,
"bri": 254,
"hue": 0,
"sat": 254,
"xy": [0, 0],
"ct": 0,
"alert": "none",
"effect": "none",
"colormode": "",
"reachable": true
},
"type": "Dimmable light",
"name": "Table Lamp 2",
"modelid": "LWB004",
"swversion": "65003148",
"pointsymbol": {
"1": "none",
"2": "none",
"3": "none",
"4": "none",
"5": "none",
"6": "none",
"7": "none",
"8": "none"
}
}
},
"scenes":{
},
"groups":{
},
"config": {
"name": "Philips hue",
"mac": "00:00:88:00:bb:ee",
"dhcp": true,
"ipaddress": "192.168.1.74",
"netmask": "255.255.255.0",
"gateway": "192.168.1.254",
"proxyaddress": "",
"proxyport": 0,
"UTC": "2012-10-29T12:00:00",
"whitelist": {
"1028d66426293e821ecfd9ef1a0731df": {
"last use date": "2012-10-29T12:00:00",
"create date": "2012-10-29T12:00:00",
"name": "test user"
}
},
"swversion": "01003372",
"swupdate": {
"updatestate": 0,
"url": "",
"text": "",
"notify": false
},
"linkbutton": false,
"portalservices": false
},
}
```
## Ask Alexa
After this Tell Alexa: "Alexa, discover my devices"