[ Athom Smart Plug V3 — Dentra Energy Stats in ESPHome ]

The Athom Smart Plug V3 is an inexpensive
(~$10-12) ESP-based WiFi smart plug that ships with ESPHome
pre-flashed and the source available on GitHub. Out of the box you
get instantaneous power / voltage / current / power-factor sensors
and a cumulative total_energy_sensor — useful, but
not directly usable for the kind of dashboards most people actually
want ("how much did this fridge use yesterday / this week / this
month?").

The dentra/esphome-components
collection includes an energy_statistics component that
reads any cumulative energy sensor and breaks it into rolling Today /
Yesterday / Week / Month / Year buckets. Combined with the official
Athom base package via ESPHome's packages: include, the
whole thing is about 40 lines of YAML per plug and lights up the
Energy dashboard cards you actually want.

This guide is the full known-working config plus the reasoning for
each block. It's the file I drop onto every new V3 plug and flash
once — that's it.

After flashing, the device shows up in Home Assistant with the
standard Athom sensors plus five new ones:

  — Energy Today      — kWh since 00:00
                                  local time
  — Energy Yesterday  — the previous day's
                                  final total, frozen at midnight
                                  rollover
  — Energy Week       — running total since
                                  the start of the current week
  — Energy Month      — running total since
                                  the 1st of the current month
  — Energy Year       — running total since
                                  January 1st

All five reset automatically at their respective boundaries (midnight
in your configured timezone for Today / Yesterday, Monday 00:00 for
Week, etc.) and persist through reboots — the component stores
state in NVRAM so a power blip doesn't zero the running totals.

The cumulative total_energy_sensor the Athom base config
provides stays intact and continues exposing lifetime kWh, so you can
keep using it for whole-of-life consumption tracking.

  — Athom Smart Plug V3 — athom.tech
    has them direct, also widely available on AliExpress / Amazon.
    Make sure it's the V3 — older revisions use
    different ESP chips and different base configs
  — ESPHome dashboard — Home Assistant
    add-on, standalone Docker, or just pip install esphome
    and running locally
  — Wi-Fi credentials in secrets.yaml —
    wifi_ssid and wifi_password
  — The plug pre-adopted into your ESPHome dashboard — on a
    fresh V3 this happens automatically via the captive portal it
    spins up on first boot

No soldering, no UART tinkering, no JTAG, no replacement firmware.
The V3 ships with ESPHome already on it; everything below is an
OTA reflash of a config you author.

The complete working config for one plug. Paste this as
athom-smart-plug-1a2b3c.yaml in your ESPHome dashboard,
swap the per-device fields at the top, and click Install:

substitutions:
  name: "athom-smart-plug-1a2b3c"
  friendly_name: "Athom Plug V3 1a2b3c"
  current_limit: "16"                  # US (AU would be 10)
  timezone: "Pacific/Honolulu"         # Maui

packages:
  athom_plug:
    url: https://github.com/athom-tech/esp32-configs
    ref: main
    files: [athom-smart-plug.yaml]
    refresh: 1d

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

# --- Fancy energy breakdown: Today / Yesterday / Week / Month / Year ---
external_components:
  - source: github://dentra/esphome-components
    components: [energy_statistics]

sensor:
  - platform: energy_statistics
    total: total_energy_sensor         # provided by the Athom base config
    energy_today:
      name: "Energy Today"
      accuracy_decimals: 3
      icon: mdi:hours-24
    energy_yesterday:
      name: "Energy Yesterday"
      accuracy_decimals: 3
      icon: mdi:calendar-today
    energy_week:
      name: "Energy Week"
      accuracy_decimals: 3
      icon: mdi:calendar-week
    energy_month:
      name: "Energy Month"
      accuracy_decimals: 3
      icon: mdi:calendar-month
    energy_year:
      name: "Energy Year"
      accuracy_decimals: 3
      icon: mdi:calendar

The rest of this page is a walkthrough of why each block is the way
it is and what changes per plug.

substitutions:
  name: "athom-smart-plug-1a2b3c"
  friendly_name: "Athom Plug V3 1a2b3c"
  current_limit: "16"                  # US (AU would be 10)
  timezone: "Pacific/Honolulu"         # Maui

Four values that change per device or per install:

name — the ESPHome node hostname.
Must be unique on your network. The convention I follow is
athom-smart-plug-<last-3-bytes-of-MAC> — the MAC
is printed on the plug's label and on the captive-portal page it
serves on first boot. Anything works as long as it's unique;
predictable per-MAC names make fleet management easier than
arbitrary "kitchen_plug" / "lamp_plug" names that drift as you
relocate plugs.

friendly_name — what shows up in
the Home Assistant UI as the device name. Friendly version of the
hostname — you can change this later in HA without re-flashing
if you decide on a different scheme, so don't sweat it too much at
flash time.

current_limit — safety cutoff for
the on-board current sensor. The plug will trip and disconnect the
relay if it sees sustained draw above this many amps. Set to the
maximum continuous current rating for your local outlet standard:
16A for US/EU NEMA 5-15 / Schuko outlets,
10A for AU/UK lower-current outlets. Don't crank
this up — the plug's internal relay is only rated for the
nominal current and will eventually fail (or worse) if pushed past
it.

timezone — IANA timezone string
(Pacific/Honolulu, America/New_York,
Europe/London, etc.) — this is what
energy_statistics uses to figure out when "midnight"
happens for the Today / Yesterday rollover and when Monday starts
for Week. Get this wrong and your "Energy Today" will reset at a
weird time. Full IANA list at
en.wikipedia.org/wiki/List_of_tz_database_time_zones.

packages:
  athom_plug:
    url: https://github.com/athom-tech/esp32-configs
    ref: main
    files: [athom-smart-plug.yaml]
    refresh: 1d

This pulls in the official Athom base configuration from
athom-tech/esp32-configs
— the ESPHome packages: feature stitches a remote
YAML file into yours at build time. Everything in
athom-smart-plug.yaml upstream — the GPIO pin
assignments for the relay and button, the CSE7766 power monitor
driver setup, the WS2812 status LED, the OTA / API blocks, the
button-press behaviour, the relay-state-restore-after-reboot
config — lands in your config as if you'd typed it in.

Why use the package include instead of pasting it inline?

Two reasons:

  — Athom occasionally pushes fixes / improvements (better
    calibration constants for the CSE7766, status-LED behaviour
    tweaks). With refresh: 1d, the ESPHome dashboard
    re-downloads the package once per day, so the next time you
    re-flash a plug you get those improvements for free without
    chasing diffs.

  — Multi-plug fleets stay consistent. Every plug shares the
    same base config, with only the substitutions block changing
    per device. Bug fix upstream propagates everywhere on the next
    flash cycle.

If you'd rather pin to a specific known-good revision and never get
surprised, change ref: main to a specific commit SHA
(ref: a1b2c3d) or a tag. Then update only when you
choose.

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

Standard ESPHome pattern: pull credentials from
secrets.yaml rather than baking them into per-plug
configs that you might check into a public dotfiles repo or share
in a forum post. The Athom base package doesn't set Wi-Fi for you
— it expects the parent config to do that — so this block
is required.

If you don't have secrets.yaml set up yet: create
/config/esphome/secrets.yaml with two lines:

    wifi_ssid: "YourSSID"
    wifi_password: "YourPassword"

The ESPHome dashboard reads it from that fixed location across all
your projects; you only set it once.

external_components:
  - source: github://dentra/esphome-components
    components: [energy_statistics]

external_components: tells ESPHome to fetch additional
component code from outside its built-in library at compile time.
dentra/esphome-components
is a well-maintained collection of useful add-ons; we're pulling
just one component out of it (energy_statistics) to
keep the firmware image lean.

The github://dentra/esphome-components shorthand
expands to "clone the default branch of that repo." If you want to
pin to a release tag or a specific commit (recommended once you
have it working — same reasoning as the Athom package pin),
the long form is:

    source:
      type: git
      url: https://github.com/dentra/esphome-components
      ref: v1.2.3              # or a commit SHA

The components: [energy_statistics] filter is important
— the repo contains dozens of components and without the
filter ESPHome will try to compile all of them, blowing up your
firmware image size and possibly hitting flash limits on smaller
ESPs.

sensor:
  - platform: energy_statistics
    total: total_energy_sensor         # provided by the Athom base config
    energy_today:
      name: "Energy Today"
      accuracy_decimals: 3
      icon: mdi:hours-24
    energy_yesterday:
      name: "Energy Yesterday"
      accuracy_decimals: 3
      icon: mdi:calendar-today
    energy_week:
      name: "Energy Week"
      accuracy_decimals: 3
      icon: mdi:calendar-week
    energy_month:
      name: "Energy Month"
      accuracy_decimals: 3
      icon: mdi:calendar-month
    energy_year:
      name: "Energy Year"
      accuracy_decimals: 3
      icon: mdi:calendar

The actual work. One energy_statistics platform
declaration that reads from total: total_energy_sensor
— the cumulative-kWh sensor ID that the Athom base package
exposes — and produces five bucketed children.

total: — this is the source
sensor's ID, not its name. The Athom base config defines
the cumulative sensor with id: total_energy_sensor;
that's what we reference here. If you ever retarget this guide to
a different smart plug brand, check that brand's base config for
the equivalent cumulative-energy sensor ID and substitute it.

accuracy_decimals: 3 — three
decimal places (Wh-resolution on a kWh reading). Higher precision
than the source sensor produces is meaningless; lower throws away
information you might want. Three is the sweet spot for the CSE7766
chip the plug uses.

icon: — cosmetic. Material
Design Icons by name; HA picks them up automatically. The chosen
set distinguishes the five buckets at a glance on the device page
(mdi:hours-24 for today, mdi:calendar-week
for week, etc.). Drop the icon lines if you don't care; HA falls
back to a generic energy icon.

Each child also gets a name: field; that becomes the
HA entity friendly name (sensor.athom_plug_v3_1a2b3c_energy_today,
etc.). The entity_id auto-derives from the device's name
substitution + this name.

  1. ESPHome dashboard → New device (or edit an
     existing one). Paste the full config from
     step 0. Adjust the substitutions
     block.

  2. Save → Install. First flash should be over
     USB if the plug isn't on Wi-Fi yet; subsequent re-flashes are
     OTA. Compile takes 60-90 seconds; OTA upload another ~30s.

  3. Verify on the ESPHome side: the dashboard
     should now show the plug as Online with five new sensors in
     its preview — Energy Today / Yesterday / Week / Month /
     Year — alongside the stock Power / Voltage / Current /
     Power Factor / Total Energy.

  4. Verify in Home Assistant: HA should auto-pick
     up the new sensors via the ESPHome API integration. Look under
     Settings → Devices & Services → ESPHome →
     (your plug) — the five new entities appear there.

  5. Plug something in with a known steady draw
     (LED bulb, phone charger). Watch
     sensor.<plug_id>_energy_today tick up over a
     few minutes. If it does, you're done.

  6. Optional: add to Energy dashboard.
     Settings → Dashboards → Energy → Add consumption,
     pick sensor.<plug_id>_energy_today. The
     Energy dashboard expects a cumulative-kWh source, NOT a
     resetting one — so for the Energy card itself, use the
     stock total_energy_sensor (also exposed). The
     bucketed sensors from this guide are for your own dashboards,
     templates, and automations.

  Compile fails: "energy_statistics not found"
    Either the external_components: block is missing,
    or the components: [energy_statistics] filter is
    typo'd. Component names are case-sensitive.

  Compile fails: "total_energy_sensor not declared"
    The Athom base package didn't load — usually because the
    packages: block is wrong (typo in url / files /
    ref) or the dashboard is offline and can't fetch. Check the
    ESPHome compile log; the package-fetch failure is loud.

  Plug compiles and flashes but sensors stay at 0
    Make sure something is actually drawing power through the plug
    (>1W or so — some plugs have a small noise floor). If you
    see Power moving but Energy Today stays at 0, give it a few
    minutes — energy_statistics updates on a
    poll cycle, not every Power reading.

  Energy Today resets at the wrong time
    Timezone in substitutions: doesn't match where you
    live, or your ESPHome host isn't synced to NTP. Verify with
    esphome logs <config.yaml> — the log
    prints the resolved timezone on boot.

  Energy Today / Yesterday reset on every reboot
    NVRAM persistence requires the
    esp32: ... preferences: block in the base config
    (Athom's includes this, so this should "just work"). If you've
    overridden the base config or you're seeing this on a non-Athom
    plug, add an explicit:

        preferences:
          flash_write_interval: 1min

    so state survives across boots.

  Sensor names look weird in HA
    Entity IDs auto-derive from name in
    substitutions:. To rename without re-flashing, do
    it in HA itself — Settings → Devices &
    Services → ESPHome → (plug) → pencil icon.
    Don't try to override entity_id in the config
    block; the Athom base package controls the prefix.

For more than 2-3 plugs, copy this file once per plug and only
change the substitutions: block. A naming convention
based on the MAC suffix (printed on the plug, never changes,
unique by definition) saves a lot of "which one was this again?"
later:

    athom-smart-plug-1a2b3c.yaml    (substitution name: athom-smart-plug-1a2b3c)
    athom-smart-plug-4d5e6f.yaml    (substitution name: athom-smart-plug-4d5e6f)
    athom-smart-plug-7890ab.yaml    (substitution name: athom-smart-plug-7890ab)

The ESPHome dashboard sorts alphabetically, so a consistent prefix
keeps all your Athom plugs grouped. The friendly name in HA can be
whatever — you change that per-plug after flash via
Settings → Devices & Services → ESPHome →
(plug) → rename — the underlying hostname stays
predictable and stable.

Sharing the per-plug delta via YAML anchors.
If the only thing that differs between plugs is the substitutions
block, ESPHome doesn't have a great way to share the rest across
files — you can't !include a parent file that
references substitutions from the child. The pragmatic approach
is: keep one
athom-smart-plug-template.yaml as your gold-standard
master, and create new per-plug files via copy. When you change
something (e.g. pinning ref: to a new Athom commit),
sed across the lot:

    for f in athom-smart-plug-*.yaml; do
      sed -i 's|ref: main|ref: a1b2c3d|' "$f"
    done

Then Install → All from the ESPHome dashboard.
Cycle time per plug for an OTA reflash is ~90 seconds.