Turn an old Amazon Echo into a Home Assistant voice satellite that never talks to Amazon.

The Echo keeps what it is good at: Amazon's microphone processing and wake word engine, so it still hears you across the room and over its own music. Only Alexa goes. In its place runs hassmic, a small daemon that Home Assistant finds as an ESPHome device, with no YAML and no add-on.

Each model needs exactly the firmware its page names (donut: Fire OS 6574.1 only). A Dot 3 from 2019–2020 (C78MP8) or with a clock (36EBT3) is another model, and not supported. Every other Echo, and which are being worked on: all models; how to add one: devices/. ✅ works, tried on one Echo of that model · 🧪 untested: builds and installs on paper, never run on a device

The table is for the ESPHome mode (the default). The Echo can be a Wyoming satellite instead: voice, wake word, buttons and Music Assistant work, most of the rest does not (details).

The light ring speaks stock Alexa's language, unless you draw your own:

With several Echos, all of them hear you, but only one answers. They settle it among themselves, without Home Assistant and without a cloud; nothing to set up (how).

Everything else is set on the Echo's own settings page, http://<echo-ip>:28931/ ("Visit" on its device page in Home Assistant): every setting with what it does, the features to switch on and the entities each adds, your Echos side by side to copy settings and wake words between them, the log. A press of the action button lets your browser in. More.

• A supported Echo, and a USB way into it (its page says what: a cable, or wires).
• A Linux PC, running Linux on the machine itself (not macOS, not a VM or WSL: the unlock needs direct USB; a live USB stick works), with adb, fastboot, python3, make, unzip, debugfs (e2fsprogs), and free disk: about 7 GB for an Echo Show (a 16 GB stick), under 1 GB for the others, 5 GB more to build here instead of taking GitHub's build (8 for an Echo Input). On a live USB stick the session's own disk is RAM: keep the repository on a drive. The setup offers to install what is missing. An Echo that is unlocked already (by hand, as its XDA thread says) can also be set up from Windows: Git Bash (Git for Windows, with its unzip and curl), adb (platform-tools) and python3.
• Home Assistant with a working Assist pipeline (speech to text, conversation agent, text to speech). Try it in the app first. Optional: Music Assistant (tested with 2.10.4).
• Wi-Fi with a WPA2 password or none (no captive portal, no enterprise login) that reaches Home Assistant.

scripts/setup.sh

One guided run for every supported model. It does everything itself but the unlock, which you do by hand as the model's XDA thread says (it shows you the thread and checks the Echo afterwards), and stops only when you have to act: download a file (it picks it up from ~/Downloads), plug a cable or solder, unlock, type the Wi-Fi password. It wipes the Echo, so it asks for a typed yes first.

• Stopped? Ctrl-C any time; the next run continues where it left off. When a step fails it shows why and offers to try again (full output in build/<codename>/setup.log).
• Nothing to compile on a commit GitHub has built (every push to main and release): the setup takes that build, checked against the project's key, and skips the 1 GB Android NDK.
• Already rooted on the right firmware? It offers a shortcut: no unlock, no wipe.
• Windows: run scripts/setup.sh in Git Bash, with GitHub's build of a published commit. It takes an Echo unlocked already (on adb, in Fire OS or TWRP) and does everything after the unlock. New to command lines? An Echo from Windows, step by step, every command to paste and what each step asks of you.
• More Echos: --restart starts over for the next one, --preset hassmic-settings.conf gives it the settings exported from another.
• --dry-run shows every command without running one; --from <step> skips ahead.
• Back up secrets/update.key, made by the setup: it signs your updates and opens adb over Wi-Fi without Home Assistant.

The steps by hand, and what to solder: each model's page in Supported Echos.

Once the Echo is on your network, Home Assistant discovers it: add it, pick an Assist pipeline, say "Alexa". The Echo names itself after its model and MAC address ("Echo Dot 3 5695c4"); give it your name in Home Assistant.

• Online, installed from Home Assistant: pick a channel under "Online updates" on the Echo's settings page. release gets releases (the release branch), beta also every build of main that changes the Echo's software, off (the default) nothing. The Echo's firmware entity then shows new versions and installs them. ESPHome mode only. The Echo downloads them itself, so it needs internet access to GitHub; the page checks that before it takes a channel.
• From your PC: git pull, then scripts/ota-push.sh <echo-ip> (it remembers the address). It builds, or takes that commit's build from GitHub as the setup does, signs with your secrets/update.key and pushes over Wi-Fi (TCP 28929).

Either way a broken update cannot strand the Echo: until a new version has passed its self test, the Echo falls back to the last one that worked. What changed: CHANGELOG.md. What online updates trust: security.

The settings page's Log (System page) shows what the Echo did; over adb it is adb shell tail -30 /data/local/hassmic/boot.log. Lines start with UTC once the Echo has the time from Home Assistant (the page shows your time zone), boot+<seconds> before that: behind the firewall only Home Assistant sets the clock, on connecting and every 6 hours.

Open issues and measurements: PLAN.md.

• For now: adb shell rm /data/local/hassmic/hassmic.conf, reboot. A stock, unregistered Echo, which updates itself if it gets internet.
• For good: scripts/install-system.sh --uninstall. On the Echo Shows this also wipes the Echo's data, which Amazon's apps need to start again: it starts at Amazon's setup.
• All of it: reflash the stock firmware from TWRP, step 1 of the model's page.
• Start over but keep the install: factory reset (hold the action button 10 s).

No cloud: the firewall lets Amazon's programs reach only your local network, and firmware updates never get out. The link to Home Assistant is encrypted with a key Home Assistant sets; until you add the Echo, anyone on the network can connect. The settings page lets in only browsers you approved with the action button. adb is closed over Wi-Fi. Updates install only with a valid signature. The whole model, including what it does not protect against: docs/SECURITY.md.

• User guide: every feature and setting in detail.
• DEVELOPMENT.md: how it works, building, tests, contributing.
• docs/: what was found taking the Echo apart.

MIT, for everything written here. src/third_party/ keeps its own licences, stated in each file: monocypher (BSD-2-Clause OR CC0-1.0), dr_flac.h (public domain or MIT-0), minimp3.h (CC0-1.0), rnnoise/ (BSD-3-Clause, COPYING beside it), freeaptx.c/.h (LGPL-2.1-or-later; linked statically, and everything needed to rebuild and relink it is in this repository).

Nothing of Amazon's is in this repository or covered by this licence: firmware, libraries and wake word models come from your own device and stay Amazon's. Not affiliated with or endorsed by Amazon, Home Assistant or Music Assistant; "Alexa" and "Echo" are Amazon's trademarks.