Merge pull request #191 from fabaff/http

fabaff · fabaff · commit 2d47cd7c29ba · 2016-02-06T23:19:51.000+01:00
HTTP binary sensor and sensor docs
diff --git a/source/_components/binary_sensor.http.markdown b/source/_components/binary_sensor.http.markdown
@@ -0,0 +1,78 @@
+---
+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 URL for a binary sensor looks like the example below:
+
+```bash
+http://IP_ADDRESS:8123/api/states/binary_sensor.DEVICE_NAME
+```
+
+<p class='note'>
+You should choose a unique device name (DEVICE_NAME) to avoid clashes with other devices.
+</p>
+
+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"}'
+```
diff --git 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**.
diff --git a/source/_components/sensor.http.markdown 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
+```
+
+<p class='note'>
+You should choose a unique device name (DEVICE_NAME) to avoid clashes with other devices.
+</p>
+
+ 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.
diff --git 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/)
diff --git 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`:
 
