automatous-io/shelly-gen4-esphome

⚠️ Disclaimer. Installing third-party firmware voids your Shelly warranty, and Shelly cannot provide technical support for a device running third-party code. Incorrect flashing can brick your device. Always back up your original firmware before proceeding. You assume all responsibility for any damage, data loss, or device failure. This project is not affiliated with Shelly, Allterco Robotics, ESPHome, CSA, or Espressif Systems.

ESPHome firmware and install path for Shelly Gen4 devices, built on the ESP-Shelly-C68F module (ESP32-C6, 8MB flash), deployed through the stock Shelly web UI or over UART. Upload one zip on the device's firmware update page and it reboots into ESPHome, with the native Home Assistant API and a local web page.

Every supported model is verified on real hardware, and the metering models are calibrated against a reference meter.

A Shelly Plug US Gen4 after conversion, adopted in Home Assistant through the native API. Max Power is set to 130W under a 140W lamp: the meter reads 141.0W and Overpower reports a problem, caught just as the protection trips. The protections are on every relay model from 1.5.0.

• Supported devices
• In Home Assistant
• Quick start
• Features
• Roadmap
• Documentation
• Repository layout
• Credits
• Other projects from Automatous
• License

Pin assignments for every model, and the hardware findings behind them, are in the GPIO Map.

Stock device pages, no custom cards.

The 2PM doubles the controls: two relays, each with its own linking, mode, and pulse length.

And it meters each output separately, with Overpower and Overcurrent faults per channel. Energy is a primary sensor on every metering model, so it feeds the Energy Dashboard.

Voltage and mains frequency are diagnostic on every metering model, with both temperatures where the board has an NTC.

The non-metering models and the rest of the entities are in First Boot and Adoption.

Prebuilt firmware, and the stock web UI needs no UART adapter. Nothing to compile and no shell, so a Home Assistant OS install is enough.

1. Download automatous-io-<model>-esphome-vX.Y.Z-ota.zip from the latest release.
2. Install it through the stock Shelly web UI, after checking the running slot.
3. Join it to Wi-Fi and adopt it in Home Assistant or ESPHome Builder.

Building it yourself produces the same zip, plus a UART binary for esptool.

Adoption points a small stub at this repository, so later improvements arrive on your next rebuild with nothing to edit. From 1.0.0 the stable ids, substitution names, and package URLs only change with a major version, so adopted devices can track main.

• Stock web UI install, no UART adapter required. UART is there if you want a backup of stock firmware first.
• Native Home Assistant API, plus a local web page on the device.
• ESPHome Builder adoption, with this repository as the update channel.
• Relay linking, latch or momentary mode, and pulse length, as Home Assistant selects and as build-time defaults.
• Switch input and onboard button, with configurable debounce and power-on restore behavior.
• Live metering on the PM models, the Plug US, and the EM Mini through its CT clamp: current, power, energy, voltage, and frequency, calibrated against a reference meter. Energy is a primary sensor so it feeds the Energy Dashboard.
• The ESP32-C6's internal temperature on every model, plus the board NTC as Temperature where there is one.
• Overpower, overcurrent, overvoltage, and overheating protection on the relay models, with the limits adjustable from Home Assistant. See Customizing.
• On the Plug US: the RGB LED ring as a Home Assistant light with stock's power and relay state modes, and illuminance with a dark / twilight / bright reading.
• A Bluetooth proxy on every model, so Home Assistant reaches Bluetooth devices through the ESP32-C6's radio. A Bluetooth Proxy switch turns it off at runtime.
• Factory reset by a 5 second button hold, from Home Assistant, or from the device page.
• Shelly's stock partition layout preserved, which is what lets the stock installer accept the build.

• Thread — the native Home Assistant API over Thread instead of Wi-Fi, through ESPHome's openthread component on the C6's 802.15.4 radio. Possible today, unproven on this hardware. Not Matter.

The detail, the dependencies, and what is actually in the way is in the Roadmap.

Everything is in docs/, with build scripts/ and the changelog at the repo root. The usual path is Installing, then First Boot and Adoption; Building is for compiling it yourself instead of downloading.

• Installing — the web UI path, the slot rule, UART, and backing up stock
• First Boot and Adoption — Wi-Fi setup, what lands in Home Assistant, and the adoption stub
• Customizing — every substitution, the stable ids, and package merging
• Calibrating the Power Meter — measuring the metering constants on your own unit
• Building — the dev container, a host venv, and what a build produces
• GPIO Map — pin assignments per model and the hardware findings behind them
• The Partition System — why stock ESPHome does not boot here, and how these builds do
• Roadmap — what a Thread build would need
• Changelog — release history by model

shelly-gen4-esphome/
├── README.md          This file.
├── LICENSE            Apache 2.0.
├── docs/              Documentation and the images it references.
├── scripts/           Build script and the stock web UI zip packager.
├── components/
│   └── shelly_gen4_partition/   External component that ships Shelly's stock partition tables.
└── configs/
    ├── shelly-gen4-base.yaml    Shared base: ESP32-C6, partitions, API, web server, OTA, Bluetooth proxy.
    ├── shelly-1-gen4.yaml       Relay, switch input, button, status LED.
    ├── shelly-1pm-gen4.yaml     Adds a BL0942 power meter and an NTC.
    ├── shelly-1-mini-gen4.yaml  Mini form factor, with an NTC.
    ├── shelly-1pm-mini-gen4.yaml  Mini form factor, BL0942 meter and NTC.
    ├── shelly-2pm-gen4.yaml     Two relays, two switch inputs, per-channel ADE7953 metering.
    ├── shelly-plug-us-gen4.yaml  Plug: relay, button, BL0942 meter, LED ring, light sensor.
    └── shelly-em-mini-gen4.yaml  Energy meter: BL0942 on a CT clamp, button, status LED, NTC, RTC.

Each model config is a package your adoption stub references. See Customizing for what a stub can change.

The Shelly 1PM Gen4 config started from the community Shelly 1PM Gen 4 page on ESPHome Devices. The shape of the bl0942 block, the 9600 baud rate, and the NTC divider chain with its 10k/3350 starting values all come from there. The 2PM Gen4 pin map started from the Shelly Plus 2PM Gen 4 page there and the Tasmota template on blakadder, decoded against Tasmota's source, then corrected on hardware. The software-scaling approach for its ADE7953 follows the Power Strip 4 Gen4 calibration fix. The 1PM Mini Gen4 has no public source; its starting guess was the 1 Mini Gen4 map in shelly-1-gen4-matter-thread's GPIO reference, which held for everything but the meter. The 1 Mini Gen4 config uses that same map directly. The Plug US Gen4 has no public source either; every pin was found on the device. The EM Mini Gen4's pins were also found on the device; its LED, button, meter, and RTC match the earlier UART-flashed configs in barrenechea/esphome-config-files and dext0r/hotaru.

Most of the device-specific knowledge here comes from shelly-1-gen4-matter-thread, the Matter over Thread firmware for Shelly Gen4 devices: the stock partition offsets, the GPIO maps, the behavior of the stock installer, and the reversibility testing that established the full chip backup and restore path. Its Flashing Guide and Reversibility pages cover the UART wiring, flash mode, backup procedure, and test evidence in depth, and apply to this project unchanged.

Everything in this repository (scripts, configs, docs) is licensed under Apache 2.0. See LICENSE.

The prebuilt firmware on the releases page is not. Those images are compiled from ESPHome, whose C++ runtime is GPLv3; the images themselves are distributed under the GPLv3. Every release names the ESPHome and ESP-IDF versions it was built with and links this repository at that tag; together those are the corresponding source for the binaries attached to it.