ESPHome-Config

ESPHome configuration, templates, and home automation projects.

About

A collection of ESPHome hardware templates and projects I use in my home automation setup.

Templates

A collection of utility and device-specific configuration templates.

Note that for devices with native ESPHome factory firmware, I opt to strip out the generic project and Improv configuration in favor of a custom configuration specific to my environment. This also cuts down on resource utilization by removing unused features.

Device Templates

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.
• Imports Konnected's upstream firmware package and surgically strips stock provisioning, see the template for details.

Apollo PLT-1B Plant Sensor

• Template for the Apollo PLT-1B plant soil sensor.
• Imports Apollo's upstream firmware package and surgically strips the stock provisioning, see the template for details.

SmartHomeShop CeilSense Presence and Air Sensor

• Template for the SmartHomeShop CeilSense v1 Complete presence sensor.
• Imports SmartHomeShop's upstream firmware package and surgically strips the stock provisioning, see the template for details.

Utility Templates

Shared building-block includes, composed via packages: by the device templates and per-device configs:

• api.yaml - API with encryption and a configurable api_reboot_timeout.
• ota.yaml - ESPHome OTA with password.
• logger.yaml - logger configuration.
• time.yaml - Home Assistant time source.
• wifi.yaml - managed WiFi credentials from secrets.
• basic.yaml - restart button plus status, uptime, and version sensors.
• common.yaml - bundles the api / ota / logger / time / wifi / basic includes for a typical device.
• debug.yaml - debug component and debug text sensors.
• temperature.yaml - on-chip internal temperature sensor.
• ethernet-sensor.yaml - Ethernet IP / MAC info text sensors.
• secrets.yaml - re-exports the root secrets.yaml so templates can resolve secrets.

Board and component helpers:

• 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

Per-device configs live in the repository root. Each sets substitutions: (device name, friendly name, and any per-device overrides) and pulls in a template via packages:.

Plant Sensors (Apollo PLT-1B)

• music-room-plant-sensor.yaml, patio-plant-sensor.yaml, stairs-plant-sensor.yaml, and upstairs-hallway-plant-sensor.yaml use the Apollo PLT-1B template.

Garage Presence and Air Sensor (CeilSense)

• garage-presence-sensor.yaml uses the SmartHomeShop CeilSense template for presence, CO2, temperature, humidity, lux, and pressure in the garage.

Garage Door Controller (Konnected blaQ)

• garage-door-controller.yaml uses the Konnected blaQ template.
• Note: currently powered off pending an upstream investigation into self-opening incidents, see the status block in the config and issue #29.

Bluetooth Proxies (GL-S10)

• office-bluetooth-proxy.yaml and pantry-bluetooth-proxy.yaml use the GL-S10 Bluetooth Proxy template.

Garage Fan Thermostats

• garage-door-fan-controller.yaml (Sonoff TH10) and garage-gate-fan-controller.yaml (Norvi) control cool air ventilation fans in the garage based on temperature.
• See blog post for project details.

Hot Water Recirculation Pump

• recirculation-pump-controller.yaml (Sonoff TH10) controls the whole home hot water recirculation pump using temperature probes on an interval / duration schedule.
• See blog post for project details.

Usage

• The standard ESPHome container does not support running as non-root. Deploy the ESPHome-NonRoot container for non-root operation if desired.
• 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, or copy files.
  • cd /data/appdata/esphome/config
  • git clone -b develop https://github.com/ptr727/ESPHome-Config .
• Deploy secrets.yaml, use secrets._yaml as a template for required secrets.
• In VSCode open remote SSH workspace on the docker host, and open the workspace from config directory.

Notes

Issues

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

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.