home-assistant-addon/esphome-beta/README.md

123 lines
5.5 KiB
Markdown
Raw Normal View History

2020-06-09 07:55:20 +02:00
# ESPHome Home Assistant Add-On
2019-02-13 22:05:11 +01:00
[![ESPHome logo](https://raw.githubusercontent.com/esphome/hassio/master/esphome-dev/logo.png)](https://esphome.io/)
[![GitHub stars](https://img.shields.io/github/stars/esphome/esphome.svg?style=social&label=Star&maxAge=2592000)](https://github.com/esphome/esphome)
[![GitHub Release][releases-shield]][releases]
[![Discord][discord-shield]][discord]
## About
This add-on allows you to manage and program your ESP8266 and ESP32 based microcontrollers
2020-06-09 07:55:20 +02:00
directly through Home Assistant **with no programming experience required**. All you need to do
2019-02-13 22:05:11 +01:00
is write YAML configuration files; the rest (over-the-air updates, compiling) is all
handled by ESPHome.
<p align="center">
<img title="ESPHome dashboard screenshot" src="https://raw.githubusercontent.com/esphome/hassio/master/esphome-dev/images/screenshot.png" width="700px"></img>
</p>
2020-06-09 07:55:20 +02:00
[View the ESPHome documentation](https://esphome.io/)
2019-02-13 22:05:11 +01:00
## Example
With ESPHome, you can go from a few lines of YAML straight to a custom-made
firmware. For example, to include a [DHT22][dht22].
temperature and humidity sensor, you just need to include 8 lines of YAML
in your configuration file:
<img title="ESPHome DHT configuration example" src="https://raw.githubusercontent.com/esphome/hassio/master/esphome-dev/images/dht-example.png" width="500px"></img>
Then just click UPLOAD and the sensor will magically appear in Home Assistant:
<img title="ESPHome Home Assistant MQTT discovery" src="https://raw.githubusercontent.com/esphome/hassio/master/esphome-dev/images/temperature-humidity.png" width="600px"></img>
## Installation
2020-06-09 07:55:20 +02:00
To install this Home Assistant add-on you need to add the ESPHome add-on repository
2019-02-13 22:05:11 +01:00
first:
2020-06-09 07:55:20 +02:00
1. Add the ESPHome add-ons repository to your Home Assistant instance. You can do this by navigating to the "Add-on store" tab in the Supervisor panel and then entering https://github.com/esphome/hassio in the "Add repository" field after selecting "Repositories" from the top-right menu.
2019-02-13 22:05:11 +01:00
2. Now scroll down and select the "ESPHome" add-on.
3. Press install to download the add-on and unpack it on your machine. This can take some time.
2020-06-09 07:55:20 +02:00
4. Optional: If you're using SSL/TLS certificates and want to encrypt your communication to this add-on, please enter `true` into the `ssl` field and set the `fullchain` and `certfile` options accordingly.
2019-02-13 22:05:11 +01:00
5. Start the add-on, check the logs of the add-on to see if everything went well.
2020-06-09 07:55:20 +02:00
6. Click "OPEN WEB UI" to open the ESPHome dashboard. You will be asked for your Home Assistant credentials - ESPHome uses Home Assistant's authentication system to log you in.
2019-02-13 22:05:11 +01:00
2020-06-09 07:55:20 +02:00
You can view the ESPHome documentation at https://esphome.io/
2019-02-13 22:05:11 +01:00
## Configuration
**Note**: _Remember to restart the add-on when the configuration is changed._
Example add-on configuration:
```json
{
"ssl": false,
"certfile": "fullchain.pem",
2019-06-03 14:18:46 +02:00
"keyfile": "privkey.pem"
2019-02-13 22:05:11 +01:00
}
```
### Option: `ssl`
2020-06-09 07:55:20 +02:00
Enables or disables encrypted SSL/TLS (HTTPS) connections to the web server of this add-on.
2019-02-13 22:05:11 +01:00
Set it to `true` to encrypt communications, `false` otherwise.
Please note that if you set this to `true` you must also generate the key and certificate
files for encryption. For example using [Let's Encrypt](https://www.home-assistant.io/addons/lets_encrypt/)
or [Self-signed certificates](https://www.home-assistant.io/docs/ecosystem/certificates/tls_self_signed_certificate/).
### Option: `certfile`
The certificate file to use for SSL. If this file doesn't exist, the add-on start will fail.
2020-06-09 07:55:20 +02:00
**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant
2019-02-13 22:05:11 +01:00
### Option: `keyfile`
The private key file to use for SSL. If this file doesn't exist, the add-on start will fail.
2020-06-09 07:55:20 +02:00
**Note**: The file MUST be stored in `/ssl/`, which is the default for Home Assistant
2019-02-13 22:05:11 +01:00
### Option: `leave_front_door_open`
Adding this option to the add-on configuration allows you to disable
authentication by setting it to `true`.
### Option: `esphome_version`
2020-06-09 07:55:20 +02:00
Manually override which ESPHome version to use in the add-on.
2019-02-13 22:05:11 +01:00
For example to install the latest development version, use `"esphome_version": "dev"`,
2020-06-09 07:55:20 +02:00
or for version 1.14.0: `"esphome_version": "v1.14.0""`.
2019-02-13 22:05:11 +01:00
Please note that this does not always work and is only meant for testing, usually the
ESPHome add-on and dashboard version must match to guarantee a working system.
2019-03-13 19:31:33 +01:00
### Option: `relative_url`
Host the ESPHome dashboard under a relative URL, so that it can be integrated
2020-06-09 07:55:20 +02:00
into existing web proxies like NGINX under a relative URL. Defaults to `/`.
2019-03-13 19:31:33 +01:00
### Option: `status_use_ping`
By default the dashboard uses mDNS to check if nodes are online. This does
not work across subnets unless your router supports mDNS forwarding or avahi.
Setting this to `true` will make ESPHome use ICMP ping requests to get the node status. Use this if all nodes always have offline status even when they're connected.
### Option: `streamer_mode`
If set to `true`, this will enable streamer mode, which makes ESPHome hide all
2019-03-13 19:31:33 +01:00
potentially private information. So for example WiFi (B)SSIDs (which could be
2020-06-09 07:55:20 +02:00
used to find your location), usernames, etc. Please note that you need to use
2019-03-13 19:31:33 +01:00
the `!secret` tag in your YAML file to also prevent these from showing up
while editing and validating.
2019-02-13 22:05:11 +01:00
[discord-shield]: https://img.shields.io/discord/429907082951524364.svg
[dht22]: https://esphome.io/components/sensor/dht.html
[discord]: https://discord.gg/KhAMKrd
2019-02-13 22:05:11 +01:00
[releases-shield]: https://img.shields.io/github/release/esphome/esphome.svg
[releases]: https://esphome.io/changelog/index.html
[repository]: https://github.com/esphome/esphome