Install and configure ESPHome

Note

If you want to add ESPHome in Home Assistant, then you need to go through this section to install and configure it.

If you don’t use it, you can skip this section and go directly to the next one: Log In.

ESPHome is the perfect solution for creating custom firmware for your ESP8266/ESP32 boards.

../../_images/esphome_logo.png

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 (just like Home Assistant) 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.

Installation

  1. Installation dependencies.

sudo pip3 install cryptography==2.8

  1. Install ESPHome, you need to install Python and install the console script through pip3.

Note

Python 3.7 or above is required to install ESPHome 1.18.0 or above.

sudo pip3 install esphome

Alternatively, there’s also a Docker image available for easy installation (the Docker hub image is available for AMD64, ARM and ARM64(AARCH64) right now; if you have another architecture, please install ESPHome through pip or use the Home Assistant add-on:

docker pull esphome/esphome

  1. Open the ESPHome Dashboard.

Note

You need to keep this command running while you are operating in the ESPHome dashboard.

esphome dashboard config/

Configure ESPHome

  1. Open a browser and enter ESPHome Dashboard through http://localhost:6052 or http://X.X.X.X:6052 (replace X.X.X.X with your Raspberry Pi’s IP address).

  2. Create configuration.

Click on the "+" to start adding configurations.

../../_images/image44.png

Enter a name and the WiFi and password that you need to have your device connect to and then click NEXT.

../../_images/image48.png

Select the device type (ESP32 for example).

../../_images/image46.png

Enter

Once added, you will see them in the Dashboard of ESPHome.

Note

When it is not the first time to add a device, click "+" on the main page, follow the prompts to enter the device name, WIFI and password, select the device type.

../../_images/image53.png

  1. Edit the .yaml file.

Click EDIT in the bottom right corner to go inside the .yaml file, you will see the following default components.

../../_images/desphome_yaml0.png

  • esphome: Contains the name, platform, and board type that you set up.

  • logger: The logger component automatically logs all log messages through the serial port and through MQTT topics.

  • api: The ESPHome native API is used to communicate with clients directly, with a highly-optimized network protocol. Currently, only the ESPHome tool and Home Assistant use this native API.

  • ota: With the OTA (Over The Air) update component you can upload your firmware binaries to your node without having to use a USB cable for uploads.

  • wifi: This core ESPHome component sets up WiFi connections to access points for you. It needs to be in your configuration or otherwise ESPHome will fail in the config validation stage.

  • captive_portal: The captive portal component in ESPHome is a fallback mechanism for when connecting to the configured WiFi fails. After 1 minute of unsuccessful WiFi connection attempts, the ESP will start a WiFi hotspot (with the credentials from your configuration).

Now start to add other components. There are a lot of components in the ESPHome official website, including Sensor Components, Output Components, Light Components, etc., Here we take Binary Light in Light Components as an example.

../../_images/image52.png

Add the following code to the end of the .yaml file.

# Example configuration entry
light:
  - platform: binary
    name: "Desk Lamp"
    output: light_output

output:
  - id: light_output
    platform: gpio
    pin: GPIO16
../../_images/desphome_yaml.png

  1. Install the .yaml file to ESP32 board.

After editing, click INSTALL in the lower right corner to compile and install. There are 2 methods for you to choose: Wirelessly and USB Port. But for the first installation you need to connect the ESP32 board to the Raspberry Pi using USB and then choose the second installation method. At a later time you can install and compile via Wirelessly.

It takes about 10 minutes to download the dependencies during the first compilation, so please be patient.

../../_images/install_esp32.png

After successful installation, if you connect an LED to GPIO16 in ESP32 board, you will see the LED is lit. Also please record this IP, you will need to fill in this IP when you add ESPHome to Home Assistant.

../../_images/install_suc.png

Note

If there is no response when clicking INSTALL, please clear the browser cache and INSTALL again.

sudo rm -rf ~/.cache/chromium

ESPHome configuration is complete and you can now add it to Home Assistant.