ESPHome-Config

ESPHome configuration, templates, and 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.
  • I am experiencing issues with PSU and ADC stability on several devices, see the notes section in YML for details.
  • Norvi addressed the issues through a design change (May 2024 date code) and sent me replacement devices, that I still need to test and verify.

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.

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.

RatGDO LiftMaster Garage Door Controller

• Project garage-door-controller.yaml is used as to control my LiftMaster garage door opener.
• Customized version of the RatGDO Garage Door Controller.

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 ugo=rwx /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.

Renaming a Device in Home Assistant

• Rename HA entities:
  • Stop HA container using docker stop home-assistant.
  • Reset config permissions:
    • sudo chown -R nobody:users /data/appdata/home-assistant/config
    • sudo chmod -R ugo=rwx /data/appdata/home-assistant/config
  • Edit core.config_entries and rename title and host.
  • Edit core.device_registry and rename name.
  • Edit core.entity_registry and rename unique_id and original_name.
• Set new ESPHome device name:
  • Set use_address in wifi config, see notes.
  • Update firmware.
  • Delete or uncomment use_address.
  • Update firmware.
• Restart HA container using docker start home-assistant.
• Troubleshooting:
  • Look at ESPHome integration entities, fix incorrect entries.
  • E.g. search for entities named foo_2, delete foo, and rename foo_2 to foo.
  • E.g. replace short entity names with fully qualified names.
• Note: ESPHome + HA v2024+ made improvements in device and entity naming changes and conflicts, and the listed steps may no longer be required.

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.