Repository navigation
Lineage
amble-home is a port, not a discovery. The knowledge of how amaran lights talk came from other people's work, and this page says whose.
wesbos/amaran-BLE-control (MIT) is where it starts. Wes Bos reverse-engineered the amaran app's Bluetooth: that the lights form a Telink SigMesh network, that the app's desktop version keeps the mesh keys and the fixture table in an SQLite database on disk, and that with those keys a computer can speak to the lights directly. His DIRECT-BLE-CONTROL.md is the research record and remains the best explanation of the protocol. The opcodes amble-home sends, the scaling of intensity, the exclusivity of color and color temperature, the layout of a status reply: all of it is his.
The author's own fork of that repository, on a branch called bridge-local, turned the research into an ESP-IDF firmware that ran his studio's seven lights from Home Assistant over MQTT for months. It was a working product with no users but one, and it taught the lessons that shaped amble-home:
- How to inject the imported keys into Espressif's mesh stack through its internal calls, so the box is a node on the app's mesh without the app knowing.
- That the lights answer to the app's address, so a box must overhear replies rather than receive them; the bridge did that with a patch to ESP-IDF, amble-home does it with a link-time wrap and no patch.
- A race in ESP-IDF's mesh advertising buffer pool that leaked a buffer every so often and killed the radio after about a week, found by watching the counters. Espressif fixed it upstream; the pinned ESP-IDF now contains the fix.
- That everything else in the bridge (Wi-Fi, MQTT, HTTP, discovery, logging, and the absence of over-the-air updates) was work ESPHome already does better.
Its findings are carried in docs/origin.md.
abrockmann/amaran-BLE-control-streamdeck is Arne Brockmann's fork of the same research, aimed at driving the lights from a Stream Deck. The advertising-pool race was found and fixed between the two projects, and the fix was contributed there. amble-home is the Home Assistant branch of that family tree, not a competitor to it: a Stream Deck plugin lives on a computer beside its control software, a Home Assistant device lives on a shelf; they share the protocol and little else.
By October 2026 the bridge needed a successor and the question was where to put the work. Contributing to the Stream Deck fork meant putting Home Assistant code where it had no home. Keeping the fork meant maintaining Wi-Fi, MQTT and HTTP code by hand forever. ESPHome already had every piece but the mesh, with a browser flasher, over-the-air updates and native Home Assistant discovery thrown in. So the mesh layer was ported onto ESPHome as one external component, and amble-home is the result: the mesh knowledge is the only thing it has to own.
The whole of v1 was designed, built and put into production in ten days, from 2026-10-24, in a private repository that remains the author's development record. The public history starts at 1.0.0.
The repository is owned and directed by Chris Williams. The software is written and maintained by Claude (Anthropic), working as the project's engineer under his direction, with Codex (OpenAI) reviewing the slices that touch keys, the mesh, the import page or the release pipeline. Chris reads the designs, decisions and issues, decides scope, and owns the merge button; he does not read the code. The Developers page describes the working method, and AGENTS.md in the repository is the standing agreement under which the work is done.
- ESPHome: the framework the box runs on, and the reason most of the product did not have to be written.
- ESP Web Tools: the browser flasher, with Improv Wi-Fi setup over the same cable.
- ESP-IDF and its ESP-BLE-MESH stack: the mesh node itself. amble-home builds against whatever version ESPHome pins, unmodified.
- sql.js: SQLite compiled to WebAssembly, which lets the Edit page read the desktop app's database inside the browser.
- Home Assistant: where the lights end up.
The lights, the app and the mesh are Aputure's and Sidus Link's. amble-home uses their app's data with the user's own account and never touches the mesh's membership; the app remains in charge. The project is not affiliated with, endorsed by or supported by Aputure, amaran or Sidus Link, and the author told Sidus Link about it as soon as the repository went public.
Other people have put amaran lights into Home Assistant by other routes, for example ha-amaran-ble, a custom integration that speaks the mesh from the Home Assistant host's own Bluetooth. amble-home has not examined it and takes nothing from it; it is listed so you know it exists.
Using amble-home
Working on it