mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-19 07:17:14 +00:00
🚜 Merges/Redirects HTTP component pages (#9165)
This commit is contained in:
Klaas Schoute
Fabian Affolter
parent
72c922bd66
commit
dc8a226b58
@ -1,86 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: "HTTP Binary Sensor"
|
||||
description: "Instructions on 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
|
||||
ha_release: pre 0.7
|
||||
ha_qa_scale: internal
|
||||
---
|
||||
|
||||
The HTTP binary sensor is dynamically created with the first request that is made to its URL. You don't have to define it in the configuration first.
|
||||
|
||||
The sensor will then exist as long as Home Assistant is running. After a restart of Home Assistant the sensor will be gone until it is triggered again.
|
||||
|
||||
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" \
|
||||
-H "Content-Type: application/json" \
|
||||
-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" \
|
||||
-H "Content-Type: application/json" \
|
||||
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'll find some real-life examples of how to use this sensor, besides `curl`, which was shown earlier.
|
||||
|
||||
### {% 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 content-type:application/json state=off \
|
||||
attributes:='{"friendly_name": "Radio"}'
|
||||
```
|
||||
@ -8,13 +8,24 @@ comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
logo: http.png
|
||||
ha_category: "Other"
|
||||
ha_category:
|
||||
- Other
|
||||
- Binary Sensor
|
||||
- Sensor
|
||||
ha_release: pre 0.7
|
||||
ha_iot_class: Local Push
|
||||
ha_qa_scale: internal
|
||||
redirect_from:
|
||||
- /components/binary_sensor.http/
|
||||
- /components/sensor.http/
|
||||
---
|
||||
|
||||
The `http` component serves all files and data required for the Home Assistant
|
||||
frontend. You only need to add this to your configuration file if you want to
|
||||
change any of the default settings.
|
||||
The `http` component serves all files and data required for the Home Assistant frontend. You only need to add this to your configuration file if you want to change any of the default settings.
|
||||
|
||||
There is currently support for the following device types within Home Assistant:
|
||||
|
||||
- [Binary Sensor](#binary-sensor)
|
||||
- [Sensor](#sensor)
|
||||
|
||||
<p class='note'>
|
||||
Don't use option `server_host` on a Hass.io installation!
|
||||
@ -114,51 +125,32 @@ http:
|
||||
login_attempts_threshold: 5
|
||||
```
|
||||
|
||||
The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/)
|
||||
blog post gives you details about the encryption of your traffic using free
|
||||
certificates from [Let's Encrypt](https://letsencrypt.org/).
|
||||
The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post gives you details about the encryption of your traffic using free certificates from [Let's Encrypt](https://letsencrypt.org/).
|
||||
|
||||
Or use a self signed certificate following the instructions here
|
||||
[Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/).
|
||||
Or use a self signed certificate following the instructions here [Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/).
|
||||
|
||||
## {% linkable_title APIs %}
|
||||
|
||||
On top of the `http` component is a [REST API](/developers/rest_api/),
|
||||
[Python API](/developers/python_api/) and
|
||||
[WebSocket API](/developers/websocket_api/) available. There is also support for
|
||||
[Server-sent events](/developers/server_sent_events/).
|
||||
On top of the `http` component is a [REST API](/developers/rest_api/), [Python API](/developers/python_api/) and [WebSocket API](/developers/websocket_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/).
|
||||
|
||||
The `http` platforms are not real platforms within the meaning of the
|
||||
terminology used around Home Assistant. Home Assistant's
|
||||
[REST API](/developers/rest_api/) sends and receives messages over HTTP.
|
||||
The `http` platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) sends and receives messages over HTTP.
|
||||
|
||||
## {% linkable_title HTTP sensors %}
|
||||
|
||||
To use those kind of [sensors](/components/sensor.http/) or
|
||||
[binary sensors](/components/binary_sensor.http/) 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.
|
||||
To use those kind of [sensors](#sensor) or [binary sensors](#binary-sensor) 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) need to be sent
|
||||
to the endpoint of the device and must be **POST**.
|
||||
All [requests](/developers/rest_api/#post-apistatesltentity_id) need to be sent to the endpoint of the device and must be **POST**.
|
||||
|
||||
## {% linkable_title IP filtering and banning %}
|
||||
|
||||
If you want to apply additional IP filtering, and automatically ban brute force
|
||||
attempts, set `ip_ban_enabled` to `true` and the maximum number of attempts.
|
||||
After the first ban, an `ip_bans.yaml` file will be created in the root
|
||||
configuration folder.
|
||||
It will have the banned IP address and time in UTC when it was added:
|
||||
If you want to apply additional IP filtering, and automatically ban brute force attempts, set `ip_ban_enabled` to `true` and the maximum number of attempts. After the first ban, an `ip_bans.yaml` file will be created in the root configuration folder. It will have the banned IP address and time in UTC when it was added:
|
||||
|
||||
```yaml
|
||||
127.0.0.1:
|
||||
banned_at: '2016-11-16T19:20:03'
|
||||
```
|
||||
|
||||
After a ban is added a Persistent Notification is populated to the Home
|
||||
Assistant frontend.
|
||||
After a ban is added a Persistent Notification is populated to the Home Assistant frontend.
|
||||
|
||||
<p class='note warning'>
|
||||
Please note, that sources from `trusted_networks` won't be banned automatically.
|
||||
@ -166,12 +158,133 @@ Please note, that sources from `trusted_networks` won't be banned automatically.
|
||||
|
||||
## {% linkable_title Hosting files %}
|
||||
|
||||
If you want to use Home Assistant to host or serve static files then create a
|
||||
directory called `www` under the configuration path (`/config` on Hass.io,
|
||||
`.homeassistant` elsewhere). The static files in `www/` can be accessed by the
|
||||
following URL `http://your.domain:8123/local/`, for example `audio.mp3` would
|
||||
be accessed as `http://your.domain:8123/local/audio.mp3`.
|
||||
If you want to use Home Assistant to host or serve static files then create a directory called `www` under the configuration path (`/config` on Hass.io, `.homeassistant` elsewhere). The static files in `www/` can be accessed by the following URL `http://your.domain:8123/local/`, for example `audio.mp3` would be accessed as `http://your.domain:8123/local/audio.mp3`.
|
||||
|
||||
<p class='note'>
|
||||
If you've had to create the `www/` folder for the first time, you'll need to restart Home Assistant.
|
||||
</p>
|
||||
|
||||
## {% linkable_title Binary Sensor %}
|
||||
|
||||
The HTTP binary sensor is dynamically created with the first request that is made to its URL. You don't have to define it in the configuration first.
|
||||
|
||||
The sensor will then exist as long as Home Assistant is running. After a restart of Home Assistant the sensor will be gone until it is triggered again.
|
||||
|
||||
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" \
|
||||
-H "Content-Type: application/json" \
|
||||
-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" \
|
||||
-H "Content-Type: application/json" \
|
||||
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'll find some real-life examples of how to use this sensor, besides `curl`, which was shown earlier.
|
||||
|
||||
#### {% 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 content-type:application/json state=off \
|
||||
attributes:='{"friendly_name": "Radio"}'
|
||||
```
|
||||
|
||||
## {% linkable_title Sensor %}
|
||||
|
||||
The HTTP sensor is dynamically created with the first request that is made to its URL. You don't have to define it in the configuration first.
|
||||
|
||||
The sensor will then exist as long as Home Assistant is running. After a restart of Home Assistant the sensor will be gone until it is triggered again.
|
||||
|
||||
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 -X POST -H "x-ha-access: YOUR_PASSWORD" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Bathroom Temp"}}' \
|
||||
http://localhost:8123/api/states/sensor.bathroom_temperature
|
||||
```
|
||||
|
||||
You can then use `curl` again to retrieve the [current sensor state](/developers/rest_api/#get-apistatesltentity_id) and verify the sensor is working.
|
||||
|
||||
```bash
|
||||
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
||||
-H "Content-Type: application/json" \
|
||||
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](#examples) page.
|
||||
@ -1,65 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: "HTTP Sensor"
|
||||
description: "Instructions on 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
|
||||
ha_release: pre 0.7
|
||||
ha_iot_class: Local Push
|
||||
ha_qa_scale: internal
|
||||
---
|
||||
|
||||
|
||||
The HTTP sensor is dynamically created with the first request that is made to its URL. You don't have to define it in the configuration first.
|
||||
|
||||
The sensor will then exist as long as Home Assistant is running. After a restart of Home Assistant the sensor will be gone until it is triggered again.
|
||||
|
||||
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 -X POST -H "x-ha-access: YOUR_PASSWORD" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Bathroom Temp"}}' \
|
||||
http://localhost:8123/api/states/sensor.bathroom_temperature
|
||||
```
|
||||
|
||||
You can then use `curl` again to retrieve the [current sensor state](/developers/rest_api/#get-apistatesltentity_id) and verify the sensor is working.
|
||||
|
||||
```bash
|
||||
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
|
||||
-H "Content-Type: application/json" \
|
||||
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.
|
||||
Loading…
x
Reference in New Issue
Block a user