These instructions are summarised from the online instructions. See: https://esphome.io/guides/installing_esphome.html
Quickstart
Installation
The following installs ESPhome on a Windows computer so that it can be run from the ‘cmd’ window (text input).
Install Python (and Pip)
See instructions here: https://www.python.org/downloads/
Ensure that option “Add Python to PATH” is selected before installing the package.
Check that Python is installed
In a Windows ‘cmd’ window (command prompt).
python --version
=> Should return something like: Python 3.10.1
Install dependencies
pip3 install wheel
Install ESPHome
pip install esphome
Check installation
esphome version
=> Should return something like: Version: 2023.12.0
ESPHome is now installed, and can be run from the Windows CMD
Using ESPHome
Create/Edit YAML files
ESPHome is driven via YAML configuration files in the working directory. YAML (Yet Another Markup Language) files are text files which are formatted in a specific way. They can be edited with any tool which can edit text files. (MS Notepad is good, MS Word may cause problems. MS Visual Studio (Code) is a good place to start.)
Once installed, view available ESPhome options
esphome -h
A simple YAML file that works with the Heltec Wifi LoRa 32 V3, which can be extended, looks like the following. (Copy and save this file as ‘esphome-device.yaml’) To understand the parts of this fle and the YAML configuration options, see: https://esphome.io/
esphome:
name: "lora-sx126x"
esp32:
board: esp32-s3-devkitc-1
framework:
type: arduino
logger:
wifi:
networks:
- ssid: WIFI_SSID_GOES_HERE
password: WIFI_PASSWORD_GOES_HERE
ota:
password: OTA_PASSWORD_GOES_HERE
# Enable Home Assistant API
api:
encryption:
key: API_KEY_GOES_HERE
web_server:
port: 80
With an ESP32 board, new firmware can be built and installed using a YAML configuration file with:
esphome run esphome-device.yaml
These commands can be run individually as the following.
esphome compile configuration-file.yaml
esphome upload configuration-file.yaml
esphome logs configuration-file.yaml
When the program is running, it can be interupted by pressing the key combination: Ctrl-C
Over the Air (OTA) Updates
If enabled in the YAML file, ESPHome also supports “Over the Air” updates. This means that if the ESP board is currently connected to a Wifi network then using this connection, it can be directly upgraded with new firmware.
This option can be selected during the ‘upload’ step. If the board is not connected with USB and only connected to Wifi, this will happen automatically.
Additional notes – For Linux Users
Using a Virtual Environment – venv
The above process is very similar when installing on Linux or MacOS. On Linux, it is possible to setup a ‘virtual environment’ (venv) for development by installing and using the ‘venv’ command. This will allow the local Python libraries to be installed and run separately to the system libraries. This is useful to allow the development environment to use more recent library versions and/or allow the development environment to use more stable version. This helps when debugging and tracking down issues that may be caused by libraries.
Ensire that you are working in the required local project directory (eg. with the ‘cd’ command)
With Python and Pip installed as installed, create the venv development environment in the current working directory.
pip3 install venv python -m venv venv . venv/bin/activate
Install and run ESPHome as before.
To restart editing session in an existing venv enabled directory
Setup the venv environment again by using:
. venv/bin/activate
At this stage, it is also possible to install ESPHome directly from the GitHub
development repository. This is useful for debugging, bug fixing and testing.
Install development version from the Github ESPHome repository
This requires that the ‘git’ lool has been installed. (Use ‘apt git install’ on Ubuntu.)
git clone https://github.com/esphome/esphome.git cd esphome python -m venv venv . venv/bin/activate ./scripts/setup
As required, update the local copy of the code with the following.
git pull
./scripts/setup