esphome-docs/guides/getting_started_hassio.rst

162 lines
7.1 KiB
ReStructuredText
Raw Normal View History

Getting Started with ESPHome and Home Assistant
===============================================
2018-06-01 18:10:00 +02:00
2018-11-14 22:12:27 +01:00
.. seo::
:description: Getting Started guide for installing ESPHome Dashboard as a Home Assistant add-on and creating a basic configuration.
:image: home-assistant.svg
2018-11-14 22:12:27 +01:00
In this guide well go through how to install ESPHome on a device using the ESPHome Dashboard, installed as a Home Assistant add-on.
2018-06-01 18:10:00 +02:00
But first, here's a very quick introduction to how ESPHome works:
ESPHome is a *tool* which aims to make managing your ESP boards as simple as possible. It reads in a YAML configuration file and creates custom firmware which it installs on your ESP device. Devices or sensors added in ESPHome's configuration will automatically show up in Home Assistant's UI.
2018-06-01 18:10:00 +02:00
Installing ESPHome Dashboard
----------------------------
2019-01-16 11:30:50 +01:00
The ESPHome Dashboard can be installed as a Home Assistant add-on, which you can find in the add-on store in the Supervisor panel. Open it using the following button then click on INSTALL:
2018-06-01 18:10:00 +02:00
If you do not have the official ESPHome add-on repository added you can add with this button:
.. raw:: html
<a href="https://my.home-assistant.io/redirect/supervisor_addon/?addon=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon" target="_blank">
<img src="https://my.home-assistant.io/badges/supervisor_addon.svg" alt="Open your Home Assistant instance and show the dashboard of the ESPHome add-on." />
</a>
After that, wait a bit until it is installed (this can take a while). Click "Start" and then click "Open Web UI". If you see "502: Bad Gateway" it is currently starting, and you can refresh the page after a couple of seconds.
2018-06-01 18:10:00 +02:00
.. figure:: images/hassio_addon.png
:align: center
:width: 75.0%
You should now be greeted by a nice introduction wizard which will step you through
creating your first configuration.
.. figure:: images/dashboard_empty.png
2018-06-01 18:10:00 +02:00
:align: center
:width: 95.0%
The wizard will guide you through creating your first configuration and, depending on your browser, install it on your ESP device. You will need to name your configuration and enter your wireless network settings so that the ESP device can come online and can communicate with Home Assistant.
.. note::
The most difficult part of setting up a new ESPHome device is the initial installation. Installation requires that your ESP device is connected with a cable to a computer. Later updates can be installed wirelessly.
For guidance on making this first connection, see :doc:`physical_device_connection`
2018-06-01 18:10:00 +02:00
Dashboard Interface
2018-10-12 16:33:22 +02:00
-------------------
2018-06-01 18:10:00 +02:00
Assuming you created your first configuration file with the wizard, let's take a quick
tour of the ESPHome Dashboard interface.
2018-06-01 18:10:00 +02:00
.. figure:: images/dashboard_states.png
2018-06-01 18:10:00 +02:00
:align: center
:width: 95.0%
On the front page you will see all configurations for nodes you created. For each file,
there are a few basic actions you can perform:
- **UPDATE**: This button will show up if the device has not been installed with the same ESPHome version currently running.
- **EDIT**: This will open the configuration editor.
2018-06-01 18:10:00 +02:00
- **LOGS**: With this command you can view all the logs the node is outputting. If a USB device is
connected, you can choose to use the serial connection. Otherwise it will use the built-in OTA logs.
2018-06-01 18:10:00 +02:00
- **Overflow menu**: This is a dropdown menu which allows you to perform more actions.
2019-02-16 23:25:23 +01:00
- **Validate**: This will validate the configuration file.
- **Install**: Opens the Install dialog.
- **Clean Build Files**: This will delete all of the generated build files and is a safe operation to perform. Sometimes old files are not removed and can cause compile issues later on.
- **Delete**: This will delete the configuration file.
2018-11-05 22:03:08 +01:00
2019-02-16 23:25:23 +01:00
The configuration files for ESPHome can be found and edited under ``<HOME_ASSISTANT_CONFIG>/esphome/``.
For example the configuration for the ``garage-door`` node in the picture above can be found
in ``/config/esphome/garage-door.yaml``.
2018-06-01 18:10:00 +02:00
Now go ahead and use one of the :ref:`devices guides <devices>` to extend your configuration.
2018-06-01 18:10:00 +02:00
Adding some (basic) features
2018-10-12 16:33:22 +02:00
----------------------------
2018-06-01 18:10:00 +02:00
2019-02-16 23:25:23 +01:00
So now you should have a file called ``/config/esphome/livingroom.yaml`` (or similar).
Go open that file (in any text editor) and add a :doc:`simple GPIO switch </components/switch/gpio>`
2018-06-01 18:10:00 +02:00
to the configuration like this:
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
switch:
- platform: gpio
2018-10-20 15:10:26 +02:00
name: "Living Room Dehumidifier"
2018-06-01 18:10:00 +02:00
pin: 5
In above example, we're simply adding a switch that's called "Living Room Dehumidifier" (could control
2018-06-01 18:10:00 +02:00
anything really, for example lights) and is connected to the pin ``GPIO5``.
Connecting your device to Home Assistant
----------------------------------------
Once your configuration is installed on your ESP device and is online, it will be automatically discovered by Home Assistant and offered to set up on your integrations screen:
.. raw:: html
<a href="https://my.home-assistant.io/redirect/config_flow_start/?domain=esphome" target="_blank"><img src="https://my.home-assistant.io/badges/config_flow_start.svg" alt="Open your Home Assistant instance and start setting up a new integration." /></a>
Alternatively, you can manually add the device on the Home Assistant Integrations page. Click on the "Add Integration" button (bottom right), search for esphome, and enter the host name, eg: "<NODE_NAME>.local" as the host. Use the same process to add multiple esphome devices.
2018-06-01 18:10:00 +02:00
.. figure:: /components/switch/images/gpio-ui.png
2018-06-01 18:10:00 +02:00
:align: center
:width: 75.0%
After the first installation, you will probably never need to use the USB
2019-02-16 23:25:23 +01:00
cable again, as all features of ESPHome are enabled remotely as well.
2018-06-01 18:10:00 +02:00
Adding A Binary Sensor
2018-10-12 16:33:22 +02:00
----------------------
2018-06-01 18:10:00 +02:00
Next, were going to add a very simple binary sensor that periodically
checks a GPIO pin to see whether its pulled high or low - the :doc:`GPIO Binary
Sensor </components/binary_sensor/gpio>`.
2018-06-01 18:10:00 +02:00
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
binary_sensor:
- platform: gpio
name: "Living Room Window"
pin:
number: 16
inverted: true
mode:
input: true
pullup: true
2018-06-01 18:10:00 +02:00
This time when installing, you dont need to have the device plugged in
through USB again. The upload will happen wirelessly (:doc:`"over the air" </components/ota>`).
2018-06-01 18:10:00 +02:00
.. figure:: /components/binary_sensor/images/gpio-ui.png
2018-06-01 18:10:00 +02:00
:align: center
:width: 75.0%
Where To Go Next
2018-10-12 16:33:22 +02:00
----------------
2018-06-01 18:10:00 +02:00
2019-02-16 23:25:23 +01:00
Great 🎉! Youve now successfully setup your first ESPHome project
and installed your first ESPHome custom firmware to your node. Youve
2018-06-01 18:10:00 +02:00
also learned how to enable some basic components via the configuration
file.
2019-02-16 23:25:23 +01:00
So now is a great time to go take a look at the :doc:`Components Index </index>`.
Hopefully youll find all sensors/outputs/… youll need in there. If youre having any problems or
2018-06-01 18:10:00 +02:00
want new features, please either create a new issue on the `GitHub issue
2019-02-16 23:25:23 +01:00
tracker <https://github.com/esphome/issues/issues>`__ or find us on the
`Discord chat <https://discord.gg/KhAMKrd>`__ (also make sure to read the :doc:`FAQ <faq>`).
2018-06-01 18:10:00 +02:00
See Also
2018-10-12 16:33:22 +02:00
--------
2018-06-01 18:10:00 +02:00
- :doc:`ESPHome index </index>`
2018-06-01 18:10:00 +02:00
- :doc:`getting_started_command_line`
- :ghedit:`Edit`