emonPi/Tx Configuration for Home Assistant

A Home Assistant integration that provides a web-based configuration interface for OpenEnergyMonitor emonPi/Tx devices connected via an ESP32 serial bridge running ESPHome.

Features

Device Configuration: Full configuration interface for CT calibration, voltage calibration, radio settings, and more
Friendly Channel Names: Add custom names to CT, Voltage, OPA, and Temperature channels for easier identification
- Names are stored per-device in Home Assistant
- Export/Import names as JSON for backup or migration
Multi-device Support: Switch between multiple emonPi/Tx devices from a dropdown selector
Batch Configuration: Edit multiple settings and apply them all at once with the floating Apply/Discard bar
Serial Terminal: Send commands and receive responses from your emonTx device
- Autoscroll toggle, copy to clipboard, download log, clear terminal
- Resizable terminal window
- Quick command buttons for common operations
Live Data Display: View real-time power and energy readings from all channels
- Data grouped by type (Voltage, Power, Energy, Temperature, Pulse)
- Inactive channels shown with strikethrough indicator
Accumulators Tab: View and reset individual energy and pulse counters
Zero Energy: Reset energy counters with confirmation countdown (matching firmware behavior)
Unsaved Changes Warning: Banner alerts you when device has unsaved changes
YAML Generator: Generate ESPHome sensor configuration for active channels
- Uses friendly names when configured
- Supports OPA pulse channels and temperature sensors
Multi-phase Support: Full support for emonPi3 with 3-phase voltage monitoring
Firmware Update & OTA Flash: Checks for emon32-fw firmware updates from GitHub and flashes them wirelessly
- Configurable check frequency (Never, Daily, Weekly, Monthly)
- Settings stored on the HA side (shared across all browsers)
- Blinking badge when update is available
- One-click OTA flash via emonWifi (emonTx6 / emonPi3, requires UART SAM-BA bootloader)
- Bootloader auto-detection: contextual notice shows setup steps or a green "ready" indicator based on the active bootloader
- Switch back to USB/UF2 bootloader: when the UART bootloader is active, a dedicated Bootloader card lets you revert to the UF2 bootloader from the UI (with inline confirmation), without needing a USB cable
No-response Detection: Shows a warning if the device doesn't respond within 10 seconds, with guidance for emonTx4/5 users (serial jumper must be removed)
RF Power Warning: Safety warning when setting RF power to high levels (7 dBm+)
Multi-language: Supports English, French, German, Italian, and Spanish

Requirements

Home Assistant 2023.1.0 or newer
ESPHome Integration installed in Home Assistant (Settings > Devices & Services > Add Integration > ESPHome)
An emonWifi (ESP32-C3 Mini) added to the ESPHome integration and showing as "Online"
ESPHome firmware on the emonWifi with the built-in emontx component and the emontx_ha_bridge external component configured
An emonTx/emonPi device connected to the emonWifi via UART

Note: If using a different ESP32 board, some settings (board type, GPIO pins) may need to be adjusted.

Important: This integration requires the emontx_ha_bridge component, which is not yet in mainline ESPHome. It must be loaded via external_components from the emontx-ha-bridge branch (see ESPHome Setup below).

Installation

With HACS (Recommended)

Install the integration through HACS using the button below or by adding https://github.com/FredM67/ha-emon-config to HACS as a custom repository.
Restart Home Assistant
Go to Settings > Devices & Services > Add Integration > Search for "emonPi/Tx Configuration"

Manual Installation

Download this repository
Copy the custom_components/emontx_config folder to your Home Assistant config/custom_components/ directory
Restart Home Assistant

Configuration

ESPHome Setup

Your ESP32 needs to be configured with the built-in emontx component (now standard in ESPHome) plus the emontx_ha_bridge external component from the emontx-ha-bridge branch. The bridge component fires esphome.emontx_raw / esphome.emontx_json events and registers the send_command service in Home Assistant.

Note: The emontx_ha_bridge companion component (which provides the HA-side bridge) is not yet in mainline ESPHome and must be loaded via external_components.

New to ESPHome? Start Here

If you haven't used ESPHome before, follow these steps:

Install the ESPHome Add-on (if using Home Assistant OS):
- Go to Settings > Add-ons > Add-on Store
- Search for "ESPHome" and install it
- Start the add-on and click "Open Web UI"
Create a New Device:
- In the ESPHome dashboard, click "+ New Device"
- Click "Continue" on the welcome screen
- Enter a name for your device (e.g., emonwifi)
- Select "ESP32-C3" as the device type
- Click "Skip" when asked to install (we'll edit the config first)
Edit the Configuration:
- Click "Edit" on your newly created device
- Replace or modify the generated YAML with the configuration below
- Adjust the GPIO pins for your specific board
- Click "Save" then "Install"
Install the Firmware:
- For first-time installation, use "Plug into this computer" or "Manual download"
- For subsequent updates, use "Wirelessly" (OTA)
Add to Home Assistant:
- Go to Settings > Devices & Services
- ESPHome devices are usually auto-discovered
- If not, click "Add Integration" > "ESPHome" and enter the device IP

Complete Example Configuration

Here's a complete ESPHome configuration file for the emonWifi:

esphome:
  name: emonwifi
  friendly_name: emonWifi

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf

# Enable logging
logger:

# Enable Home Assistant API with encryption
api:
  encryption:
    key: "your-32-byte-base64-key-here"  # See note below
  # Required for the HA bridge component
  homeassistant_services: true
  custom_services: true

# Enable Over-The-Air updates
ota:
  platform: esphome

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

# External component for the HA bridge
# (emontx itself is now built into ESPHome)
external_components:
  - source:
      type: git
      url: https://github.com/FredM67/esphome
      ref: emontx-ha-bridge
    components: [emontx, emontx_ha_bridge, emontx_updater]
    refresh: 0s

emontx_ha_bridge:

# UART connection to emonTx/emonPi
uart:
  id: emontx_uart
  rx_pin: GPIO20  # Adjust for your board
  tx_pin: GPIO21  # Adjust for your board
  baud_rate: 115200
  rx_buffer_size: 2048

# emonTx component — loaded from the fork branch (includes timing fixes)
emontx:

# HTTP client required by emontx_updater to download firmware binaries
http_request:
  buffer_size_rx: 4096

# OTA firmware updater — registers the flash_emontx6 service in Home Assistant
emontx_updater:

API Encryption Key

The api.encryption.key is required for secure communication between ESPHome and Home Assistant. You have two options:

Generate a new key: When you create a new ESPHome device through the Home Assistant ESPHome add-on, it automatically generates an encryption key for you. You can find it in your device's YAML configuration.
Use secrets: Store the key in your secrets.yaml file and reference it with !secret api_encryption_key:
```
api:
  encryption:
    key: !secret api_encryption_key
```

To generate a new key manually, you can use: openssl rand -base64 32

Minimal Addition to Existing Config

If you already have an ESPHome device configured, you only need to add these sections:

external_components:
  - source:
      type: git
      url: https://github.com/FredM67/esphome
      ref: emontx-ha-bridge
    components: [emontx, emontx_ha_bridge, emontx_updater]
    refresh: 0s

# Add homeassistant_services and custom_services to your existing api: section
api:
  # ... your existing config ...
  homeassistant_services: true
  custom_services: true

emontx_ha_bridge:

uart:
  id: emontx_uart
  rx_pin: GPIO20
  tx_pin: GPIO21
  baud_rate: 115200
  rx_buffer_size: 2048

emontx:

http_request:
  buffer_size_rx: 4096

emontx_updater:

Note: Both homeassistant_services: true and custom_services: true are required in the api: section. The emontx_ha_bridge component auto-registers the send_command service and fires esphome.emontx_raw and esphome.emontx_json events to Home Assistant. Commands sent via this service automatically have LF line endings appended as required by the emonTx firmware. Even though emontx is built into mainline ESPHome, the fork branch must be used as it adds a loop pause needed to keep the watchdog happy during the lengthy OTA firmware upload. emontx_updater requires http_request with buffer_size_rx: 4096 to download firmware binaries.

Home Assistant Setup

Prerequisites: Ensure the ESPHome integration is installed and your ESP32 device is added and showing as "Online" in Settings > Devices & Services > ESPHome.

Go to Settings > Devices & Services
Click "Add Integration"
Search for "emonPi/Tx Configuration"
Select your ESPHome device from the dropdown (only devices with the emontx_ha_bridge component will appear)
Click "Submit"

Usage

After installation, a new panel called "emonPi/Tx Config" will appear in the Home Assistant sidebar.

Device Config Tab

The main configuration interface with three sub-tabs:

Energy Sensors

CT Channels: Configure calibration (CT Type), phase lead, and friendly name for each current channel
Voltage Channels: Enable/disable, calibrate, and name voltage inputs (for 3-phase systems)
Bulk Configuration: Apply the same CT type and settings to multiple channels at once

Other Sensors

OPA Channels: Configure OneWire or Pulse input modes with optional pull-up and debounce period
Temperature Sensors: DS18B20 sensor management with 8-slot grid layout
- Scan for connected sensors on the OneWire bus
- Drag-and-drop sensors between slots to reassign
- Dropdown selector for slot reassignment
- Status indicators: matched (✓), pending (⏳), modified (✎), new (★), missing (⚠)
- Selectable/copyable sensor addresses
- Clear individual slots or all slots at once
- Restore saved sensor mappings from device memory
- Save mappings to device memory (with warning if pending changes exist)
- Slot changes use the "Apply/Discard" workflow
- Reliable list parsing using firmware [end] markers
Channel Names Backup: Export/Import friendly names as JSON for backup or migration

Other Settings

Radio Settings: Configure RF module (node ID, group, band, power, format)
- Warning displayed when setting RF power to high levels (7 dBm+)
Datalog Interval: Set the reporting interval
JSON Output: Enable/disable JSON serial format

Buttons:

Apply: Send pending configuration changes to the device
Discard: Revert to the last applied configuration
Save to Flash: Save configuration to EEPROM (sends s command)
Zero Energy: Reset all energy counters
Reset Defaults: Restore factory settings
Reload Config: Read current configuration from the device
Generate YAML: Generate ESPHome sensor configuration using friendly names

Pending Changes Bar: When you modify settings, a floating bar appears at the bottom showing the number of pending changes. Click "Apply" to send them to the device or "Discard" to revert.

Other features:

Device selector: Switch between multiple emonPi/Tx devices (dropdown in status bar)
Unsaved changes warning: Banner appears when configuration changes haven't been saved to flash

Serial Terminal Tab

A full serial terminal for direct communication:

Terminal Output: Shows all received data from the emonPi/Tx (resizable window)
Command Input: Type commands to send to the emonPi/Tx
Quick Commands: Buttons for common commands (l, v, s, ?)
Toolbar: Autoscroll toggle, copy to clipboard, download log, clear terminal

Firmware Update Tab

Manage emon32-fw firmware directly from the UI:

Check frequency: Configure automatic update checks (Never / Daily / Weekly / Monthly)
Check Now: Fetches the latest stable release from GitHub immediately
A blinking badge appears in the tab bar when a newer version is available
Bootloader detection (emonTx6 / emonPi3): the l command response is parsed to identify the active bootloader
- uart (SAM-BA): a green notice confirms the device is ready for OTA flashing
- usb (UF2) or unknown: a yellow notice explains the one-time USB setup needed to switch to the UART bootloader
Flash Firmware: Sends the .bin to the device over the air via emonWifi (~2 min, do not power off)
- A progress bar tracks the flash; the device reboots automatically on completion

Advanced Mode

Enable the Advanced Mode checkbox to access additional flashing options:

Custom GitHub repository: override the default openenergymonitor/emon32-fw source to fetch releases from a fork or alternative repo; a Check Now button re-fetches the release list from the new repo
Version selector: pick any specific release (newest first) instead of always flashing the latest; the latest version is labelled for convenience
Direct .bin URL: paste any URL to a firmware binary to bypass the release list entirely — useful for testing pre-release or custom builds; when set, it takes precedence over the version selector and an orange warning is shown

Bootloader card

When the UART SAM-BA bootloader is active, a separate Bootloader section appears below the Firmware Update card:

Switch back to USB bootloader: reverts the device to the UF2/USB bootloader without a USB cable
- An inline confirmation panel (red-tinted, no browser dialog) explains the consequences before proceeding
- After flashing, OTA firmware updates will no longer work until the UART bootloader is re-applied via USB
- The device reboots automatically and the green "ready" badge disappears

Live Data Tab

Real-time display of all sensor values received from the emonPi/Tx, grouped by type:

Voltage (V1-V3, depending on single/three phase)
Power (P1-P12, depending on device)
Energy (E1-E12, depending on device)
Other sensors: temperature, pulse, message counter (MSG)

Inactive channels are displayed with a strikethrough indicator.

Accumulators Tab

View and manage energy and pulse accumulators stored on the device:

Energy Accumulators: View current Wh values for each CT channel
Pulse Accumulators: View pulse counts for OPA channels configured as pulse inputs
Individual Reset: Zero individual accumulators with confirmation
Zero All: Reset all accumulators at once

Documentation

For detailed information about emonTx/emonPi devices, firmware configuration, and hardware specifications:

emonPi/Tx Documentation - Complete hardware and firmware guide
OpenEnergyMonitor Community - Community forum for support

Common emonPi/Tx Commands

Command	Description
`l`	List all configuration parameters
`v`	Show firmware version
`s`	Save configuration to EEPROM
`?`	Show help with available commands
`d`	Reset to default values
`z`	Zero energy counters (requires `y` confirmation)
`k<n> <ical> <ilead>`	Set CT channel calibration
`ol`	List found OneWire temperature sensors on bus
`on`	List saved temperature sensor addresses in NVM
`oh`	Save (hold) current temperature sensor slot mapping to NVM

Refer to the emonTx documentation for a complete list of commands.

Troubleshooting

No device found

First, ensure the ESPHome integration is installed in Home Assistant
Verify your ESP32 device is added to the ESPHome integration and shows as "Online"
Check that the API encryption key matches between ESPHome firmware and Home Assistant
Verify that the emontx_ha_bridge component is added to your ESPHome config via external_components
Verify that homeassistant_services: true and custom_services: true are set in your api: section
The device dropdown only shows ESPHome devices that have the _send_command service registered

No data received

Check the UART connections between ESP32 and emonTx
Verify the baud rate is correct (115200 by default)
Important: Make sure the emontx_ha_bridge component is configured in your ESPHome firmware
If you recently renamed your ESPHome device, hard refresh the browser (Ctrl+Shift+R) to reload the frontend
Check Developer Tools > Events and listen for esphome.emontx_raw events to verify data is being received
Look at the ESPHome logs for any errors

Config not loading / Commands not working

Verify the TX pin is connected and configured in ESPHome
Check that homeassistant_services: true and custom_services: true are set in your api: configuration
Monitor the serial output with an FTDI adapter to verify commands are being sent
emonTx4/5 users: The serial jumper must be removed (unsoldered or broken) for the emonWifi to communicate with the board. Without this, the device will not respond to commands. A red warning will appear on the Config tab after 10 seconds if no response is received

"action esphome.xxx_flash_emontx6 not found" error

The emontx_updater component is not loaded on your ESPHome device — the flash service is never registered in Home Assistant without it. To fix:

Add emontx_updater: and http_request: { buffer_size_rx: 4096 } to your ESPHome YAML (see ESPHome Setup)
Make sure emontx_updater is listed in the external_components block
Rebuild and flash the ESPHome firmware to the device via USB
After it reconnects, the Flash Firmware button will be enabled

A yellow warning is shown in the Firmware Update tab when the service is not detected.

OTA firmware flash fails or Flash button is missing

The Flash Firmware button only appears after a firmware check finds a .bin asset in the latest GitHub release
OTA flashing requires the UART SAM-BA bootloader (not the default UF2 bootloader shipped on new devices)
If the yellow "One-time USB setup required" notice is shown, you need to switch the bootloader once via USB:
1. Connect the device via USB
2. Copy change-bootloader-uart.uf2 from the emon32-fw release onto the EMONBOOT drive
3. Eject the drive — the device reboots with the UART bootloader active
4. Reload the Config tab; the notice should turn green
After switching, the bootloader change is permanent — the USB step does not need to be repeated

Switching back to the USB/UF2 bootloader

If you want to revert to the UF2 bootloader (e.g. to use drag-and-drop USB firmware updates again):

When the UART bootloader is active, use the Bootloader card in the Firmware Update tab — no USB cable needed
After confirming, the device flashes change-bootloader-usb.bin and reboots automatically
Once reverted, OTA firmware updates will not work until you re-apply the UART bootloader via USB

Phase values showing incorrect numbers

Make sure your ESPHome component is up to date (clean build and reinstall)
Hard refresh the browser (Ctrl+Shift+R) to clear cached panel files

Support

License

GPL-3.0 License - See LICENSE file for details.

Credits

OpenEnergyMonitor for the emonTx hardware and firmware
ESPHome for the amazing IoT framework

Name		Name	Last commit message	Last commit date
Latest commit History 364 Commits
.github		.github
custom_components/emontx_config		custom_components/emontx_config
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
pytest.ini		pytest.ini
release-notes.md		release-notes.md
requirements_test.txt		requirements_test.txt

Uh oh!

Folders and files

Latest commit

History

Repository files navigation