RESTful binary sensor
The rest
binary sensor platform is consuming a given endpoint which is exposed
by a
RESTful API
Tip: If you want to create multiple sensors
using the same endpoint, use the RESTful configuration instructions.
If the endpoint returns one of the values of these pairs: 0
/1
,
"0"
/"1"
, FALSE
/TRUE
, false
/true
, off
/on
or closed
/open
it can be used as-is. If the return value differs, use a
template.
If the endpoint returns XML with the text/xml
, application/xml
, or
application/xhtml+xml
content type, it will automatically be converted
to JSON according to this specification
{
"name": "Binary sensor",
"state": {
"open": "true",
"timestamp": "2016-06-20 15:42:52.926733"
}
}
Configuration
To enable this sensor,
add the following lines to your configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file for a GET request:
# Example configuration.yaml entry
binary_sensor:
- platform: rest
resource: http://IP_ADDRESS/ENDPOINT
or for a POST request:
# Example configuration.yaml entry
binary_sensor:
- platform: rest
resource: http://IP_ADDRESS/ENDPOINT
method: POST
or a template based request:
# Example configuration.yaml entry
binary_sensor:
- platform: rest
resource_template: "http://IP_ADDRESS/{{ now().strftime('%Y-%m-%d') }}"
Configuration Variables
The resource or endpoint that contains the value with template support.
Name of the REST binary sensor.
Defines a template for the icon of the entity.
Defines a template for the entity picture of the entity.
Defines a template if the entity state is available or not.
Sets the class of the device, changing the device state and icon that is displayed on the frontend.
An ID that uniquely identifies this entity. This allows changing the name
, icon
and entity_id
from the web interface.
The headers for the requests.
The query params for the requests.
Using templates
For incoming data, a value template translates incoming JSON or raw data to a valid payload.
Incoming payloads are rendered with possible JSON values, so when rendering, the value_json
can be used to access the attributes in a JSON based payload, otherwise the value
variable can be used for non-json based data.
Additional, the this
can be used as variables in the template. The this
attribute refers to the current entity state of the entity.
Further information about this
variable can be found in the template documentation
Example value template with json:
With given payload:
{ "state": "ON", "temperature": 21.902 }
Template {{ value_json.temperature | round(1) }}
renders to 21.9
.
Examples
In this section you find some real-life examples of how to use this sensor.
aREST sensor
Instead of using an aREST binary sensor, you could retrieve the value of a device supporting aREST directly with a REST binary sensor.
binary_sensor:
- platform: rest
resource: http://192.168.0.5/digital/9
method: GET
name: Light
device_class: light
value_template: '{{ value_json.return_value }}'
Accessing an HTTP authentication protected endpoint
The REST sensor supports HTTP authentication and template-enabled customized headers.
binary_sensor:
- platform: rest
resource: http://IP_ADDRESS:5000/binary_sensor
username: ha1
password: test1
authentication: basic
headers:
User-Agent: Home Assistant
Content-Type: application/json
X-Custom-Header: '{{ states("input_text.the_custom_header") }}'
The headers will contain all relevant details. This will also give you the ability to access endpoints that are protected by tokens.
Content-Length: 1024
Host: IP_ADDRESS1:5000
Authorization: Basic aGExOnRlc3Qx
Accept-Encoding: identity
Content-Type: application/json
User-Agent: Home Assistant