From 85bae8d3864dd83876130a7d8bc00cdd37de8137 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 6 Feb 2016 00:19:40 +0100 Subject: [PATCH 1/7] Add http binary sensor docs --- .../_components/binary_sensor.http.markdown | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 source/_components/binary_sensor.http.markdown diff --git a/source/_components/binary_sensor.http.markdown b/source/_components/binary_sensor.http.markdown new file mode 100644 index 000000000000..e24de0615586 --- /dev/null +++ b/source/_components/binary_sensor.http.markdown @@ -0,0 +1,79 @@ +--- +layout: component +title: "HTTP Binary Sensor" +description: "Instructions how to integrate HTTP binary sensors within Home Assistant." +date: 2016-02-05 12:15 +sidebar: true +comments: false +sharing: true +footer: true +logo: http.png +ha_category: Binary Sensor +--- + + +The `http` binary sensor platform is not a real platform within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) is consuming and proceeding messages recieved over HTTP. + +To use those kind of sensors in your installation no configuration in Home Assistant is needed. All configuration is done on the devices themself. This means that you must be able to edit the target URL or endpoint and the payload. The entity will be created after the first message has arrived. + +All [requests](/developers/rest_api/#post-apistatesltentity_id) needs to be sent to the endpoint of the device and must be **POST**. The URL looks like the example below: + +```bash +http://IP_ADDRESS:8123/api/states/binary_sensor.DEVICE_NAME +``` + +It's suggested that you choose an unique device name to avoid clashes with other devices. The JSON payload must contain the new state and can have a friendly name. The friendly name is used in the frontend to name the sensor. + +```json +{"state": "on", "attributes": {"friendly_name": "Radio"}} +``` + +For a quick test `curl` can be useful to "simulate" a device. + +```bash +$ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \ + -d '{"state": "off", "attributes": {"friendly_name": "Radio"}}' \ + http://localhost:8123/api/states/binary_sensor.radio +``` + +To check if the sensor is working, use again `curl` to retrieve the [current state](/developers/rest_api/#get-apistatesltentity_id). + +```bash +$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ + http://localhost:8123/api/states/binary_sensor.radio +{ + "attributes": { + "friendly_name": "Radio" + }, + "entity_id": "binary_sensor.radio", + "last_changed": "16:45:51 05-02-2016", + "last_updated": "16:45:51 05-02-2016", + "state": "off" +} +``` + +## {% linkable_title Examples %} + +In this section you find some real life examples of how to use this sensor. Beside `curl`. + +### {% linkable_title Using Python request module %} + +As already shown on the [API](/developers/rest_api/) page, it's very simple to use Python and the [Requests](http://docs.python-requests.org/en/latest/) module for the interaction with Home Assistant. + +```python +response = requests.post( + 'http://localhost:8123/api/states/binary_sensor.radio', + headers={'x-ha-access': 'YOUR_PASSWORD', 'content-type': 'application/json'}, + data=json.dumps({'state': 'on', 'attributes': {'friendly_name': 'Radio'}})) +print(response.text) +``` + +### {% linkable_title Using `httpie` %} + +[`httpie`](https://github.com/jkbrzt/httpie) is a user-friendly CLI HTTP client. + +```bash +$ http -v POST http://localhost:8123/api/states/binary_sensor.radio \ + x-ha-access:YOUR_PASSWORD state=off \ + attributes:='{"friendly_name": "Radio"}' +``` From 117a4137f5eef7d2dab3a4b4a7bb0d131079e1bb Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 6 Feb 2016 11:07:48 +0100 Subject: [PATCH 2/7] Add http sensor docs --- source/_components/sensor.http.markdown | 55 +++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 source/_components/sensor.http.markdown diff --git a/source/_components/sensor.http.markdown b/source/_components/sensor.http.markdown new file mode 100644 index 000000000000..21faf7405f22 --- /dev/null +++ b/source/_components/sensor.http.markdown @@ -0,0 +1,55 @@ +--- +layout: component +title: "HTTP Sensor" +description: "Instructions how to integrate HTTP sensors within Home Assistant." +date: 2016-02-05 12:15 +sidebar: true +comments: false +sharing: true +footer: true +logo: http.png +ha_category: Sensor +--- + +The URL for a sensor looks like the example below: + +```bash +http://IP_ADDRESS:8123/api/states/sensor.DEVICE_NAME +``` + +

+It's suggested that you choose an unique device name (DEVICE_NAME) to avoid clashes with other devices. +

+ + The JSON payload must contain the new state and should include the unit of measurement and a friendly name. The friendly name is used in the frontend to name the sensor. + +```json +{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Bathroom Temperature"}} +``` + +For a quick test `curl` can be useful to "simulate" a device. + +```bash +$ curl -XPOST -H "x-ha-access: YOUR_PASSWORD" \ + -d '{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Bathroom Temp"}}' \ + http://localhost:8123/api/states/sensor.bathroom_temperature +``` + +Use again `curl` to retrieve the [current state](/developers/rest_api/#get-apistatesltentity_id) to check if the sensor is working. + +```bash +$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ + http://localhost:8123/api/states/sensor.bathroom_temperature +{ + "attributes": { + "friendly_name": "Bathroom Temp", + "unit_of_measurement": "\u00b0C" + }, + "entity_id": "sensor.bathroom_temperature", + "last_changed": "09:46:17 06-02-2016", + "last_updated": "09:48:46 06-02-2016", + "state": "20" +} +``` + +For more examples please visit the [HTTP Binary Sensor](/components/binary_sensor.http/#examples) page. From 8efd0e7d17e7aec504a1afc01730f42a99e3b1b0 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 6 Feb 2016 11:08:07 +0100 Subject: [PATCH 3/7] Move some parts to http component docs --- source/_components/binary_sensor.http.markdown | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/source/_components/binary_sensor.http.markdown b/source/_components/binary_sensor.http.markdown index e24de0615586..72ac7dedfaa5 100644 --- a/source/_components/binary_sensor.http.markdown +++ b/source/_components/binary_sensor.http.markdown @@ -11,18 +11,17 @@ logo: http.png ha_category: Binary Sensor --- - -The `http` binary sensor platform is not a real platform within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) is consuming and proceeding messages recieved over HTTP. - -To use those kind of sensors in your installation no configuration in Home Assistant is needed. All configuration is done on the devices themself. This means that you must be able to edit the target URL or endpoint and the payload. The entity will be created after the first message has arrived. - -All [requests](/developers/rest_api/#post-apistatesltentity_id) needs to be sent to the endpoint of the device and must be **POST**. The URL looks like the example below: +The URL for a binary sensor looks like the example below: ```bash http://IP_ADDRESS:8123/api/states/binary_sensor.DEVICE_NAME ``` -It's suggested that you choose an unique device name to avoid clashes with other devices. The JSON payload must contain the new state and can have a friendly name. The friendly name is used in the frontend to name the sensor. +

+It's suggested that you choose an unique device name (DEVICE_NAME) to avoid clashes with other devices. +

+ +The JSON payload must contain the new state and can have a friendly name. The friendly name is used in the frontend to name the sensor. ```json {"state": "on", "attributes": {"friendly_name": "Radio"}} From f85ff0a8f320d3498b7e0e3a1f33c3cef8daed2f Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 6 Feb 2016 11:08:28 +0100 Subject: [PATCH 4/7] Add details about sensors --- source/_components/http.markdown | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/source/_components/http.markdown b/source/_components/http.markdown index f0876ff711d1..f0a7f0d6e49a 100644 --- a/source/_components/http.markdown +++ b/source/_components/http.markdown @@ -25,9 +25,16 @@ http: Configuration variables: -- **api_password** (*Optional*): Protect Home Assistant with a password +- **api_password** (*Optional*): Protect Home Assistant with a password. - **server_port** (*Optional*): Let you set a port to use. Defaults to 8123. - **development** (*Optional*): Disable caching and load unvulcanized assets. Useful for Frontend development. - **ssl_certificate** (*Optional*): Path to your TLS/SSL certificate to serve Home Assistant over a secure connection. - **ssl_key** (*Optional*): Path to your TLS/SSL key to serve Home Assistant over a secure connection. +On top of the `http` component is a [REST API](/developers/rest_api/) and a [Python API](/developers/python_api/) available. + +The `http` platforms are not a real platform within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) is consuming and proceeding messages received over HTTP. + +To use those kind of sensors in your installation no configuration in Home Assistant is needed. All configuration is done on the devices themselves. This means that you must be able to edit the target URL or endpoint and the payload. The entity will be created after the first message has arrived. + +All [requests](/developers/rest_api/#post-apistatesltentity_id) needs to be sent to the endpoint of the device and must be **POST**. From 1a4159ec5511b90719b174f96623579373efdacd Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 6 Feb 2016 11:08:51 +0100 Subject: [PATCH 5/7] Update title --- source/developers/api.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/developers/api.markdown b/source/developers/api.markdown index e2a3fb24705c..2b69960b015d 100644 --- a/source/developers/api.markdown +++ b/source/developers/api.markdown @@ -12,5 +12,5 @@ footer: true Home Assistant is offering a RESTful API and a Python API for convenient access to a Home Assistant instance over HTTP. -- [Rest API](/developers/rest_api/) +- [RESTful API](/developers/rest_api/) - [Python API](/developers/python_api/) From 856a23aa9d7b5e9e20cbd06a4530b4dfa910ec9f Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 6 Feb 2016 11:09:04 +0100 Subject: [PATCH 6/7] Update title --- source/developers/rest_api.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/developers/rest_api.markdown b/source/developers/rest_api.markdown index 3537acc98264..373eeba3bfd5 100644 --- a/source/developers/rest_api.markdown +++ b/source/developers/rest_api.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "Rest API" -description: "Home Assistant Rest API documentation" +title: "RESTful API" +description: "Home Assistant RESTful API documentation" date: 2014-12-21 13:27 sidebar: false comments: false @@ -14,7 +14,7 @@ Home Assistant runs a web server accessible on port 8123. * http://IP_ADDRESS:8123/ is an interface to control Home Assistant. * http://IP_ADDRESS:8123/api/ is a Rest API. -The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml` file). +The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml` file in the [`http:` section](/components/http/)). There are multiple ways to consume the Home Assistant Rest API. One is with `curl`: From c5aaa22792be0cb46bc30e1abb02cea11c4e7daf Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sat, 6 Feb 2016 23:18:05 +0100 Subject: [PATCH 7/7] Update note --- source/_components/binary_sensor.http.markdown | 2 +- source/_components/sensor.http.markdown | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_components/binary_sensor.http.markdown b/source/_components/binary_sensor.http.markdown index 72ac7dedfaa5..8b7d19b096f8 100644 --- a/source/_components/binary_sensor.http.markdown +++ b/source/_components/binary_sensor.http.markdown @@ -18,7 +18,7 @@ http://IP_ADDRESS:8123/api/states/binary_sensor.DEVICE_NAME ```

-It's suggested that you choose an unique device name (DEVICE_NAME) to avoid clashes with other devices. +You should choose a unique device name (DEVICE_NAME) to avoid clashes with other devices.

The JSON payload must contain the new state and can have a friendly name. The friendly name is used in the frontend to name the sensor. diff --git a/source/_components/sensor.http.markdown b/source/_components/sensor.http.markdown index 21faf7405f22..8681aca6d238 100644 --- a/source/_components/sensor.http.markdown +++ b/source/_components/sensor.http.markdown @@ -18,7 +18,7 @@ http://IP_ADDRESS:8123/api/states/sensor.DEVICE_NAME ```

-It's suggested that you choose an unique device name (DEVICE_NAME) to avoid clashes with other devices. +You should choose a unique device name (DEVICE_NAME) to avoid clashes with other devices.

The JSON payload must contain the new state and should include the unit of measurement and a friendly name. The friendly name is used in the frontend to name the sensor.