ESPHome-Config

ESPHome configuration, templates, and projects.

Support

For ESPHome support visit Discord #general-support.
Only file an issue if you believe there is a bug in a template or one of my projects.

Templates

A collection of utility and device specific configuration templates.
Some templates are customized based on other people's work, see YML files for source references.

Device Templates

TuyaConvert

• Generic bootstrap template used when converting Tuya devices to ESPHome using TuyaConvert.
• See blog post for firmware conversion details.

Ayococr X5P WiFi Plug

• Template for the Ayococr X5P US 120V AC WiFi wall plug.
• See blog post for firmware conversion details.

EFUN SH331 WiFi Power Monitoring Plug

• Template for the EFUN SH331W US 120V AC WiFi power monitoring wall plug.
• See blog post for firmware conversion details.
• Note: No longer listed on Amazon.

Sonoff TH10/TH16 WiFi Relay

• Template for the Sonoff TH10 and Sonoff TH16 WiFi relay.
• Follow the Tasmota guide for flashing instructions.
• Note: Sonoff TH10 and TH16 have been replaced by the SONOFF TH Origin, see the Tasmota Templates for pin layouts.

Sonoff S31 WiFi Power Monitoring Plug

• Template for the Sonoff S31 US 120V AC WiFi power monitoring wall plug.
• Follow the Tasmota guide for flashing instructions.

Norvi NORVI-ENET-AE06-R DIN Controller

• Template for the Norvi NORVI-ENET-AE06-R or SensOper SC-EN-I6-RO4 ESP32 DIN form factor controllers.
• Flash over USB.
• Note:
  • Norvi devices are sold under the SensOper Controls brand in the US and available at the SensOper store.
  • Norvi branded devices can be shipped to the US from the Sri Lanka based Norvi store, or the Germany based CarTFT store.
  • Norvi addressed PSU interference and drifting ADC issues through a design change (May 2024 date code), see the notes section in YML for details.
  • There is an ongoing issue where enabling output on GPIO15 turns the status LED's on and could interfere with input sensors, see the notes section in YML for details.

RocketController ASTRA DIN Controller

• Template for the RocketController / RocketDyn ASTRA ESP32 DIN form factor controllers.
• Follow the RocketController guide for flashing instructions.

Kincony KC868-ASR DIN Controller

• Template for the Kincony KC868-ASR ESP32 DIN form factor controllers.
• Flash over USB.

GL-S10 POE Ethernet Bluetooth Proxy

• Template to use the GL-S10 IoT Gateway as a Bluetooth proxy.
• Follow the Blakadder guide for flashing instructions.
• Warning: Do not connect USB power and POE power at the same time.

Konnected blaQ Smart Garage Door Controller

• Template for the Konnected blaQ Smart Garage Door Controller.
• This is a Home Assistant friendly alternative to the Chamberlain myQ that cut off HA access.

Utility Templates

• RGB LED Status component. Useful for boards with only a RGB LED to use as Status LED component equivalent.
• ESP32-S3-DevKitC devkit template, and ESP32-S3-WROOM-2-N32R8V and ESP32-S3-WROOM-2-N16R8V board definitions for the ESP32-S3-DevKitC boards. The default esp32-s3-devkit-c-1 board only supports the ESP32-S3-WROOM-1-N8 with 8MB Quad Flash and no PSRAM, any other board requires some customization, especially for the Octal memory boards. Includes the on-chip temperature sensor and RGB LED as status LED.
• WEMOS LOLIN32 Lite devkit template for WEMOS LOLIN32 Lite and clone boards. Includes the LED as status LED.
• Adafruit ESP32-S3 Feather devkit template for the Adafruit ESP32-S3 Feather board. Includes the on-chip temperature sensor, RGB LED as status LED, and MAX17048 I2C battery charge monitor.

Projects

Garage Fan Thermostat

• Project garage-gate-fan.yaml and garage-door-fan.yaml configs are used to control Sonoff TH10's as thermostats for cool air ventilation in my garage.
• See blog post for project details.

Utility Gas and Water Meter Pulse Counter

• Project utility-pulse-counter.yaml config is used to measure water and gas consumption from my utility meter pulse counters.
• See blog post for project details.

Hot Water Recirculation Pump

• Project hot-water-recirc-pump.yaml config is used to control my whole home hot water recirculation pump using a Sonoff TH10 and several temperature probes.
• See blog post for project details.

TubesZB Ethernet Zigbee Coordinator

• Project zigbee-coordinator.yaml is used as my Zigbee Coordinator.
• Customized version of the TubesZB Ethernet Zigbee Coordinator.

Garage Fan Thermostat and Utility Gas and Water Meter Pulse Counter

• Project utility-counter-gate-fan.yaml is used as thermostat for cool air ventilation in my garage, and to measure water and gas consumption from my utility meter pulse counters.

Docker Deployment

• The standard ESPHome container does not support running as non-root.
• Deploy the ESPHome-NonRoot container for non-root operation.
• Set directory permissions:
  • sudo chown -R nonroot:users /data/appdata/esphome
  • sudo chmod -R ug=rwx,o=rx /data/appdata/esphome
• Clone Git repository in ESPHome config folder.
  • cd /data/appdata/esphome/config
  • git clone -b develop https://github.com/ptr727/ESPHome-Config .
• Deploy secrets.yaml, use secrets._yaml as template.
• In VSCode open remote SSH workspace on docker host, and open workspace from config directory.

Notes

General

• Not all templates are documented here.
• I deployed Zigbee in my home using Z2M and TubesZB Zigbee Ethernet coordinator, and no longer use ESPHome flashed smart plugs. For US smart plugs I highly recommend the Sengled Zigbee power monitoring smart plugs.

Espressif32 and Framework Versions

• PlatformIO version is determined by the ESPHome release, it cannot be updated independently.
• framework: type: can be arduino or esp-idf, use esp-idf for ESP32 devices.
• platform_version specifies the platformio/espressif32 version.
  • Using latest is not supported, use an exact version number.
• version specifies the platformio/framework-espidf version.
  • Using latest will use the version supported by platformio/espressif32 at release time, not the current latest version.

Debugging

VSCode Setup

• Install VSCode.
• Clone ptr727/ESPHome-Config repo and open workspace.
• Upload secrets.yaml.
• Open ESPHome-Config workspace.
• Install recommended extensions (from workspace).
• Associate YAML files with ESPHome (from the ESPHome extension).
• Select default Python interpreter and create virtual environment (Ctrl-Shift-P Python...).
• Install ESPHome (in venv terminal): pip install --upgrade [--pre] setuptools wheel platformio esphome.
• Make sure ESPHome is installed: esphome version.
• Compile ESPHome project: esphome compile esp32-s3-test.yaml.
• Launch Dashboard: esphome dashboard ., open http://localhost:6052/.

Debugging in DevContainer

• Setup VSCode.
• Open workspace and clone in devcontainer volume.
• TODO: Serial port forwarding config.

Debugging on Windows

• Install Python from the Microsoft Store.
• Setup VSCode.
• Compile ESPHome project: esphome compile esp32-s3-feather-test.yaml.
• Plugin device, hold Boot and press Reset if required.
• List COM ports from PowerShell:
  • Serial ports: [System.IO.Ports.SerialPort]::getportnames()
  • Msft drivers: Get-CimInstance -Class Win32_SerialPort | Select-Object Name, Description, DeviceID.
  • Custom drivers: Get-CimInstance -ClassName Win32_PnPEntity | Where-Object { $_.Name -match '.*\(COM(\d)\)' } Select-Object Caption.
• Upload firmware: esphome run --device COM4 esp32-s3-feather-test.yaml.
• Log output: esphome logs [--device COM5] esp32-s3-feather-test.yaml.

Debugging on Windows WSL

• Install Ubuntu or Debian from the Microsoft Store.
• Install USBIPD-WIN from GitHub Releases.
• Bind serial port.
  • Open PowerShell as Admin in Terminal, referred to as Windows.
  • Open Ubuntu in Terminal, referred to as WSL.
  • Windows: usbipd list, e.g. 7-1 303a:1001 USB Serial Device (COM4), USB JTAG/serial debug unit Not shared
  • Windows: usbipd bind --busid 7-1
  • Windows: usbipd attach --wsl --busid 7-1
  • WSL: sudo apt update && sudo apt upgrade -y && sudo apt autoremove -y
  • WSL: sudo apt install python3 python3-venv usbutils -y
  • WSL: lsusb, e.g. Bus 001 Device 002: ID 303a:1001 Espressif USB JTAG/serial debug unit
  • WSL: dmesg | grep tty, e.g. cdc_acm 1-1:1.0: ttyACM0: USB ACM device
  • WSL: ls /dev/tty*, e.g. /dev/ttyACM0, /dev/ttyUSB0
• Install VSCode and the Remote Explorer extension.
• Open VSCode Remote WSL Ubuntu session.
  • Setup VSCode in remote WSL session.
  • List COM ports: ls /dev/tty*.
  • Upload firmware: esphome run --device /dev/ttyUSB0 esp32-s3-test.yaml
• Unbind serial port.
  • Windows: usbipd detach --busid 7-1
  • Windows: usbipd unbind --all

Debugging in PlatformIO

• Setup VSCode and install the PlatformIO extension.
• Compile the project using esphome compile [project].
• Launch the PlatformIO extension and open the project folder, e.g. ./.esphome/build/esp32-s3-test
• PlatformIO will open a new instance of VSCode for that project.
• Select default Python interpreter and create virtual environment (Ctrl-Shift-P Python...).
• PlatformIO Core will be installed in the virtual environment and use the environment Python.