ESPHome examples for the Heltec Wifi LoRa 32 V3 Board

Contents

• Introduction
  • Secrets
  • Issues
• Installation Process
  • Install ESPHome and Configure the Environment
  • Checkout this repository
  • Create a Configuration File (yaml)
  • Compile Image
  • Install Image
  • View Logs
  • Everything together
• Useful Links
• Examples
  • simple-esphome-esp32s3.yaml
  • heltec.yaml
  • custom.yaml
  • custom_lora.yaml
  • lora_sender.yaml / lora_receiver.yaml
  • custom_lorawan.yaml

Introduction

The Heltec Wifi LoRa 32 V3 is based on the esp32s3 chip, with an additional LoRa radio chip.

The notes here refer to a ESPHome programming system installed on a Ubuntu laptop (Version 22.04). It is also possible to use the ESPHome system installed as a plugin in a Home Assistant installation on RasberryPi (compilation is just little slower).

Note: With an base ESPHome image installed on the board, which has wifi enabled, it is possible to do further upgrades using Over-the-Air (OTA) updates using the esphome tool.

Secrets

Passwords and Secrets (wifi, api access etc.) are stored in a separate file (secrets.yaml) which only has a template stored in this repository.

This file is not required if the “wifi”, “api” and “ota” components are not used.

Template for “secrets/”

# Your Wi-Fi SSID and password
wifi_ssid: ""
wifi_password: ""

# Fallback Access Point Configuration Password
wifi_ap_password: ""

# API Key, used for accessing Home Assistant
api_encryption_key: ""

# Over-the-air update key
ota_password: ""

There is a separate file in use for LoRaWAN credentials (secrets-lorawan.h) which is being treated in a similar way.

Issues

[ONGOING] Unable to drive FastLED lights

See: esphome/issues#4079

Works on a different Esp32 board (Heltec Wifi Lora 32 (V2)). More testing required.

[MISSING] Support in ‘esphome wizard’

This is for all of the Heltec V3 boards.

[ONGOING] Deep sleep for Heltec Board with LoRa V3

• Issue: Heltec-Aaron-Lee/WiFi_Kit_series#6
• Code: Heltec-Aaron-Lee/WiFi_Kit_series#6 (comment)

Installation Process

The following the installation process for linux (Ubuntu).

Install ESPHome and Configure the Environment

Note: None of the following should be done with elevated privileges (eg, sudo)

See: https://esphome.io/guides/installing_esphome.html#linux

Check that correct version of python3 is available. Works with 3.10.7.

python3 --version

Setup the python environment

python3 -m venv venv
source venv/bin/activate

Run the ‘source venv/bin/activate’ command to re-enter the environment.

Install esphome with

pip3 install esphome

NOTE: Over time, additional python dependencies will need to be installed. This may happen automatically, but can also be done manually with ‘pip install’. With the virtual Python environment configured as above (look for the “(venv)” in the command line prompt) additional python libraries will be installed in the ‘venv/lib/python’ subdirectory.

Once the installation is completed, check that esphome has been installed correctly with the following.

esphome version

Checkout this repository

This can be done by cloning this Github repository, forking and cloning that, or downloading and extracting the code as a zip file from Github.

To clone the Github repository on Linux, use:

git clone https://github.com/PaulSchulz/esphome-esp32s3.git

Create a Configuration File (yaml)

ESPHome is (mostly) driven through YAML (Yet Another Markup Language) configuration files, which make use of ‘components’ (both internal and supported by the project, and external, previously called custom components) to provide the desired functionality.

At the end of the process, ESPHome will have compiled a binary image (program) based on your YAML file, installed (uploaded it) onto your ESP32 board, rebooted it, and begun to monitor and display the output (logs) over USB or Wifi.

Configuration Wizard

To get started, there is a configuration wizard which will create a simple yaml configuration file.

To run it, use:

esphome wizard basic.yaml

ISSUE: It appears as though the ‘heltec-wifi-lora-32-v3’ and ‘esp32-s3-devkitc-1’ arn’t yet supported in the wizard.

Manually Create Configuration

YAML files are just text files, formatted in a particular structured way to represent hierarchies of lists (or arrays), maps (or dictionary, key and value pairs), multiline strings together with some additional application specific extensions (eg. !include and !secret)

You can use your favorite text editor (you have one of those right?) to make changes and edits to your YAML files.

Compile Image

esphome compile heltec-wifi-lora-32-v3.yaml

Install Image

If you have several ways of communicating with your ESP32 device, you will need to choose which method to use during the install process.

Initial install via USB

esphome upload --device /dev/ttyUSB0 heltec-wifi-lora-32-v3.yaml

View Logs

The logging from the device can be viewed over the USB serial connection when connected with the following command:

esphome logs --device /dev/ttyUSB0

Everything together

ESPHome provide a quick way of doing everything for you (run), only stopping if there is an error.

esphome run heltec-wifi-lora-32-v3.yaml

Useful Links

ESPHome Customised Components

https://esphome.io/custom/custom_component.html

Custome Component Examples

https://github.com/thegroove/esphome-custom-component-examples

Examples

simple-esphome-esp32s3.yaml

Simple example

heltec.yaml

Example using more hardware specific options.

• Screen drawing enabled

custom.yaml

This is a minimal custom build which responds in the logs with a 10s tick.

Files:

• custom.yaml
• my_custom_component.h

To build and install over a serial connection.

esphome run --device /def/ttyUSB0 custom.yaml

custom_lora.yaml

This components sets up a ping/pong message exchange between two Heltec WiFo LoRa 32 (V3) devices.

Files:

• custom_lora.yaml
• my_lora_component.h

To build and install over a serial connection.

esphome run --device /def/ttyUSB0 custom_lora.yaml

lora_sender.yaml / lora_receiver.yaml

This pair of configurations can be used to create a pair of boards which use the LoRa radio to send a signal from the sender to the receiver.

Files:

• lora-sender.yaml
• lora-receiver.yaml
• component/lora/sender.h
• component/lora/receiver.h

To build and install over a serial connection.

# Install sender
esphome run --device /def/ttyUSB0 lora-sender.yaml
# Install receiver
esphome run --device /def/ttyUSB0 lora-sender.yaml

custom_lorawan.yaml

This components sets up a Heltec Wifi LoRa 32(V3) board as a device on a LoRaWAN network. Credentials for the device are set in ‘lorawan_secrets.h’.

Files:

• custom_lorawan.yaml
• my_lorawan_component.h
• lorawan_secrets.h

To build and install over a serial connection, edit ‘lorawan_secrets.h’ and add the device’s LoRaWAN credentials. Run the following to compile and install.

esphome run --device /def/ttyUSB0 custom_lorawan.yaml