52cdd35344
* fixing typo in rest switch template example * adding example with template to docs * adding generic info about response JSON * making requested changes * changing file mode, removing response parsing information * updating docs with generic info and link to specific topic * fixing file permissions
2.7 KiB
2.7 KiB
| layout | title | description | date | sidebar | comments | sharing | footer | logo | ha_category | ha_release |
|---|---|---|---|---|---|---|---|---|---|---|
| page | RESTful Switch | Instructions how to integrate REST switches into Home Assistant. | 2015-09-14 19:10 | true | false | true | true | restful.png | Switch | 0.7.6 |
The rest switch platform allows you to control a given endpoint that supports a RESTful API. The switch can get the state via GET and set the state via POST on a given REST resource.
To enable this switch, add the following lines to your configuration.yaml file:
# Example configuration.yaml entry
switch:
- platform: rest
resource: http://IP_ADDRESS/ENDPOINT
Configuration variables:
- resource (Required): The resource or endpoint that contains the value.
- name (Optional): Name of the REST switch.
- body_on (Optional): The body of the POST request that commands the switch to become enabled. Default is "ON". This value can be a template, which is useful if the POST request needs to depend on the state of the system. For example, to enable remote-temperature-sensor tracking on a radio thermostat, one has to send the current value of the remote temperature sensor. On can achieve this using the template
'{"rem_temp":{{states.sensor.bedroom_temp.state}}}'. - body_off (Optional): The body of the POST request that commands the switch to become disabled. Default is "OFF". This value can also be a template.
- is_on_template (Optional): A template that determines the state of the switch from the value returned by the GET request on the resource url. This template should compute to a boolean (True or False). If the value is valid JSON, it will be available in the template as the variable value_json. See this example in the template docs. Default is equivalent to
'{% raw %}{{ value_json == body_on }}{% endraw %}'. This means that by default, the state of the switch is on if and only if the response to the GET request matchesbody_on.
Make sure that the URL matches exactly your endpoint or resource.
{% linkable_title Example %}
{% linkable_title Switch with templated value %}
This example shows a switch that uses a template to allow Home Assistant to determine its state. In this example the REST endpoint returns this JSON response with true indicating the switch is on.
{"is_active": "true"}
switch:
- platform: rest
resource: http://<address>/led_endpoint
body_on: '{"active": "true"}'
body_off: '{"active": "false"}'
is_on_template: '{% raw %}{{value_json.is_active}}{% endraw %}'