home-assistant.github.io/source/_components/binary_sensor.http.markdown

layout	title	description	date	sidebar	comments	sharing	footer	logo	ha_category
component	HTTP Binary Sensor	Instructions how to integrate HTTP binary sensors within Home Assistant.	2016-02-05 12:15	true	false	true	true	http.png	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 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 needs to be sent to the endpoint of the device and must be POST. The URL looks like the example below:

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.

{"state": "on", "attributes": {"friendly_name": "Radio"}}

For a quick test curl can be useful to "simulate" a device.

$ 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.

$ 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 page, it's very simple to use Python and the Requests module for the interaction with Home Assistant.

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 is a user-friendly CLI HTTP client.

$ http -v POST http://localhost:8123/api/states/binary_sensor.radio \
      x-ha-access:YOUR_PASSWORD state=off \
      attributes:='{"friendly_name": "Radio"}'