This repository contains ESPHome YAML configurations for Athom ESP32, ESP32-C3, and ESP32-C5 devices.

• Official website: https://www.athom.tech/
• AliExpress store: https://iotorero.aliexpress.com/
• Web firmware installer: https://athom-tech.github.io/esp32-configs/
• Releases: https://github.com/athom-tech/esp32-configs/releases
• ESPHome documentation: https://esphome.io/
• ESP Web Tools: https://esphome.github.io/esp-web-tools/
• Home Assistant: https://www.home-assistant.io/

Each file contains a dashboard_import URL in the form github://athom-tech/esp32-configs/<file>.yaml.

Use the GitHub Pages installer when you want the simplest first-time flash.

1. Open https://athom-tech.github.io/esp32-configs/ in a browser that supports Web Serial, such as Chrome or Edge.
2. Connect the device over USB.
3. Select the firmware version and device.
4. Click the install button and follow the browser prompts.
5. After flashing, provision Wi-Fi when prompted by the device or ESP Web Tools.

The installer reads firmware manifests and binaries published by the release workflow. If the installer says firmware is unavailable, wait for the firmware release and Pages workflow to complete.

Each YAML file includes a dashboard_import entry. In ESPHome Dashboard, import the device configuration with this pattern:

github://athom-tech/esp32-configs/<file>.yaml

For example:

github://athom-tech/esp32-configs/athom-smart-plug.yaml

After import, adjust substitutions such as the device name, friendly name, room, DNS domain, and restore behavior where the YAML exposes them.

Install ESPHome and build a selected configuration from the repository root:

esphome compile athom-smart-plug.yaml

Flash over USB for a first install:

esphome run athom-smart-plug.yaml

After the device is online, ESPHome can usually update it over the network:

esphome upload athom-smart-plug.yaml --device athom-smart-plug-v3.local

Use the actual YAML file and hostname for your device.

The YAML files enable ESPHome OTA updates. Once a device has been flashed and is reachable on Wi-Fi, future updates can be installed from ESPHome Dashboard or with the ESPHome CLI.

If OTA fails, confirm that:

• The device is powered and connected to the same network as ESPHome.
• The configured hostname resolves through mDNS or local DNS.
• The YAML still matches the hardware variant already installed on the device.
• The device has enough free memory and a stable Wi-Fi signal during upload.

• Most YAML files use substitutions for name, friendly_name, room metadata, project metadata, restore behavior, and optional DNS domain settings.
• Most Wi-Fi-based configurations include fallback access point and captive portal support so a device can expose a temporary setup network if it cannot join the configured network.
• ESPHome API is enabled for Home Assistant integration.
• OTA and web server support are enabled in the device configurations.
• Common diagnostic entities include status, uptime, Wi-Fi signal, and restart/factory-reset style buttons.
• Power-monitoring devices expose voltage, current, power, energy, total energy, and related calculated sensors where supported by the hardware.
• Presence and LD2450-based devices expose target, zone, presence, illuminance, and radar control entities.
• Devices are expected to be discovered by Home Assistant through the ESPHome integration after they are on the network.

Use Chrome or Edge for the web installer because Web Serial support is required. Use a data-capable USB cable, confirm that the device is in flashing mode if required, and close other serial monitors before installing.

Select the YAML or installer device entry that matches the exact Athom hardware variant. Similar devices may use different GPIO mappings, especially light and plug revisions.

Move the device closer to the access point, check credentials, and look for the fallback access point exposed by the device. If the YAML uses a custom DNS domain, confirm that the hostname you are using matches the configured name and domain.

Make sure the device and Home Assistant are on the same network segment, then add it manually from Home Assistant's ESPHome integration if automatic discovery does not appear.

Use the installed device's matching YAML, verify network reachability, and try a USB flash if the device is offline or running incompatible firmware.

Update ESPHome, check the error message for missing dependencies or component compatibility, and compare the failing YAML with nearby device configurations that build successfully. The CI workflow is the reference for the ESPHome versions expected to build.