ESPHome (https://esphome.io/) is a fantastic project for writing code for Epressif’s ESP8266 and ESP32 system-on-a-chip boards. It is not a general-purpose tool, since it targets those two platforms, and the firmware you create with it, while can have some general application, is geared towards connecting your ESP device with the Home Assistant home automation platform (https://www.home-assistant.io/)
For a more general-use tool (but without the connection to Home Assistant), look for Platform.IO (http://platform.io/). Since my goal is connecting devices to Home Assistant, I’ll focus on ESPHome on this series of short posts.
There are two official ways to get ESPHome installed. If you’re running Home Assistant via the hass.io RaspberryPI installer, then it may be more convenient to install ESPHome as an add-on. In that case, follow this guide: getting_started_hassio
My personal preference is to run EPSHome as tool on my main development computer, and not on HA, and as a result the steps below follow this other guide: getting_started_command_line
- Python: ESPHome (and platform.io) is built on top of python; as of version 1.14.0 (current release), ESPHome supports both python 2.x and 3.x, but support for 2.x will be dropped soon, so go ahead and install Python 3.x (3.8.0 is current)
- Pip: you also need to have python’s package manager, pip;
$ pip install esphome
That’s all there is to it; after all dependencies have been fetched, you should be all set.
Testing the install and creating a simple device config file
To ensure that the installation succeeded, check the version of the tool:
$ esphome . version Version: 1.14.0
ESPHome creates the firmware for your devices using configuration files in YAML format which describe the device, what peripherals are connected and what functionality we want to enable. To create a very simple first config file we can use the wizard feature:
$ esphome my_first_device.yaml wizard
The wizard will ask a few questions; for this experiment, respond as follow:
- Step 1 : name
- Step 2 : ESP device
- Step 2: Board
- Step 3: Wifi ssid
Answer: the name of your WiFi network (case-sensitive, watch-out!)
- Step 3: Wifi ssid
Answer: the password to your WiFi network
- Step 4: OTA
Answer: a password for over-the-air (OTA) firmware updates
If all goes well, a named my_first_device.yaml should’ve been created, with contents similar to the following:
esphome: name: my_first_device platform: ESP8266 board: nodemcuv2 wifi: ssid: "dummy" password: "dummy" # Enable logging logger: # Enable Home Assistant API api: password: "dummy" ota: password: "dummy"
Don’t worry if the file looks slightly different; some options vary on different versions.
Future posts will cover some other topics, including:
- How to validate and build this configuration
- Uploading the resulting firmware to an actual device via a serial connection
- Over-the-air updates
- Removing secrets (such as the WiFi password) from the config file
- Adding sensors and other capabilities