Reading the repo
Opening the box…
Reading the repo
Opening the box…
Assembly instructions
Turn Amazon Echos (Echo Dot 3, Echo Dot 2, Echo 2) into local Home Assistant voice satellites. Keeps Amazon's mic processing and wake word engine, replaces Alexa with a small C daemon speaking ESPHome or Wyoming. Multiroom music via Music Assistant, Bluetooth speaker and proxy, no cloud.
Saved setup from 4 h ago
Will it work on macOS?
The maintainers included scripts/setup.sh. Run it from the cloned folder after reading it.
bash scripts/setup.sh
Also: scripts/install-boot.sh, scripts/install-system.sh
DEVELOPMENT.mdFor users: README.md. Progress, open issues and every measurement: PLAN.md. User-visible changes by date: CHANGELOG.md. Reverse-engineering notes: docs/.
Amazon's mixer daemon owns the audio hardware and runs the whole front end (libasp: AEC, beamforming, mic
calibration). hassmic takes the place of the Alexa client PuffinApp as the mixer's client through the reversed C API
of libmixerAPI.so, feeds the 16 kHz post-AEC stream to the stock libpryon.so wake word engine (or, picked on the
settings page, to microWakeWord: TFLite Micro's audio front end and an int8 TFLite interpreter of our own, mww_*.c),
and speaks the ESPHome native API (default) or Wyoming to Home Assistant.
Boot integration (scripts/system/): hassmic.rc (init) starts boot.sh (fixed, on /system), which picks the factory
copy or a verified push update and runs main.sh (updatable): main.sh firewall keeps the egress lock in place and is
the root side of push updates, main.sh satellite stops Alexa, updater and telemetry and keeps hassmic running.
No hassmic.conf = stock behaviour. sysinstall.sh writes the system partition from the running OS (otatool remount;
dm-verity is off): for install-system.sh, and for every update (pushed or online) once it passed its self test
(main.c: wake word engine loaded, ports bound, a second of mic audio; ota_healthy() leaves state/ota/healthy, root's
ota_watch promotes), which renews the factory copy and the bootstrap (boot.sh, otatool, hassmic.rc) over Wi-Fi.
Everything that differs between Echo models lives in devices/<codename>/: build settings, hardware constants linked
into the daemon (board.c), service names and install method for the scripts (device.conf), init rc and SELinux
rules. DEVICE picks one (default donut). The adb scripts check it against the connected Echo. Porting guide:
devices/README.md.
| Path | What |
|---|---|
| devices/ | one directory per Echo model (donut, biscuit, radar): device.mk, board.c, device.conf, hassmic.rc, sepolicy.rules, setup.sh, install instructions |
| src/hassmic/ | the daemon: core (capture, wake word, playback, LEDs, buttons), sound_pryon.c (optional sound detection, docs/re-aed.md), whisper_pryon.c (whisper detection with Amazon's model, docs/re-whisper.md), proto_esphome.c, proto_wyoming.c, arb.c (wake word arbitration between Echos), dropin.c (Drop In: calls between Echos of the arbitration network), call.c (a call's audio: gate, echo suppressor, jitter buffer, playout, and the call microphone where Amazon's mixer has one), duck.c (music ducked on the other Echos that heard the wake word), settings.c (settings by name, state/config), web.c (the settings page; its files in web/), artifacts.c (models copied between Echos by the page), davs.c (models downloaded from Amazon by the page, with dha.c for the device attestation its login needs, docs/re-davs-login.md), earsup.c (experimental: our own wake sound taken back out of the mic audio sent to the pipeline), micdenoise.c (RNNoise on the mic audio sent to the pipeline), micgain.c (gain of the mic audio sent to the pipeline), wakealign.c (where the wake word ends: its phones aligned with a cut-down Montreal Forced Aligner model, tools/wakealign/), wordtail.c (the same by the level, without a model), micend.c (experimental: the end of a request heard on the Echo, by the talker's level and Amazon's VAD), afemeta.c (the front end's record in the micAsr samples' lowest bits, docs/re-vad.md), sendspin.c (kept in sync by a rate of its own: resample.c), mass.c (Music Assistant's own API for the screen's music pages, json.c reads it), a2dp.c (Bluetooth speaker both ways), btout.c (playing on a Bluetooth speaker: the mixer's A2DP route, docs/re-a2dp-source.md), ble.c, push updates (ota.c), online updates (update.c), adbwifi.c (the debug access switch), improv.c (setup from a phone: Improv Wi-Fi over ble.c's peripheral role), netaddr.c (a new IP address: links over the old one closed, mDNS announced again until Home Assistant is back), wifimotion.c (experimental motion sensor from the Wi-Fi driver's receive level), wake.c (picks the wake word engine by the model: wake_pryon.c, or wake_mww.c = microWakeWord with mww_features.c (its audio front end), mww_model.c (its int8 .tflite models) and mww_store.c (its models in state/mww, managed by the page)) |
| src/ui/ | the Echo Show's screen UI, a process of its own (hassmic's screen.c starts it; ui.h lists the parts): scene.c (display list diffed per frame into one dirty rectangle, caches, touches, scrolling), widgets.c (icons, buttons, sliders, keyboard), face.c, drawer.c (pulled from the top edge: home, music, DND, apps), music.c (Music Assistant: playing, queue, library, search, speakers), words.c (what was said, the reply and the timers on a see-through layer of their own), gfx.c (anti-aliased drawing into the gralloc buffer), android.c (libhmui.so: JNI for the layers, text, images, apps, the screenshot; loaded by scripts/device/screen.dex, tools/mkscreen.py), touch.c (the touchscreen's evdev node, protocol B; tests/unit/touch_test.c); tools/uishot.c draws every view on the PC |
| src/kmod/ | kernel modules for Wi-Fi motion, hooking the Wi-Fi driver's receive path: hassmic_rcpi.c (biscuit, radar), hassmic_rcpi4m.c (donut; checkers, crown, cronos, athena, cannoli as 32-bit ARM; cupcake); built by make when the model's kernel sources and compiler are in toolchain/, see below |
| src/tools/ | mixcap, mixplay, pryon_test, aed_test (stock sound detector, docs/re-aed.md), whisper_test (whisper detector, docs/re-whisper.md), latency, otatool, runas (AIPC refuses uid 0, the image has no su), curlspy, hciscan (raw HCI on /dev/stpbt), a2dpprobe (stands in for the Bluetooth stack on the mixer's A2DP output) |
| src/include/ | C headers for the reversed libmixerAPI.so and libpryon.so |
| wakealign/ | the wake word aligners (src/hassmic/wakealign.c), cut out of the Montreal Forced Aligner's models: CC BY 4.0, credited in its README |
| geo/ | the countries' borders (src/hassmic/geo.c: Home Assistant's home location to a country, for the time zone's name), from Natural Earth (public domain): tools/geo/build.py |
| src/third_party/ | monocypher 4.0.2, dr_flac.h, minimp3.h, libfreeaptx 0.2.2, RNNoise 0.1.1 (own licences, see README) |
scripts/ | PC side: setup.sh (guided install), artifacts.sh (Amazon artifacts for an installed Echo: more wake words, the whisper detection model, the newest sound detection model; the old way through the Alexa app, a fallback to the settings page's "Download from Amazon"), deploy.sh, probe.sh, capture-test.sh, mic-compare.sh (micRaw against micAsr on a running Echo), wifi-join.sh, install-system.sh, ota-push.sh, bundle.sh (packs and signs an update; also CI's), otatool.py (bundles on the PC: keys, signing, checking, pushing; the Echo's own is src/tools/otatool.c), mkbootroot.py (a root boot.img from the model's stock one: checkers'), adb-wifi.sh (adb over Wi-Fi with the update key), kiosk-install.sh (Kiosk Satellite on an installed Show); lib/device.sh picks the model, lib/build.sh builds the Echo's binaries or takes the commit's release build, lib/setup.sh has the guided setup's helpers, lib/twrp.sh the Echo Shows' wipe in TWRP (setup's and install-boot.sh --uninstall's), lib/artifacts.sh the logic of artifacts.sh, lib/kiosk.sh and lib/apkcert.py fetch and check Kiosk Satellite |)
| scripts/device/, scripts/system/ | run on the Echo, reading the model's device.conf next to them; boot integration (boot.sh, main.sh) |
| tools/ | mkstubs.sh (stand-ins for the stock libraries, for building without the firmware), geo/ (build.py: Natural Earth's borders -> geo/borders.bin; geo.py its format and lookup in Python), wakealign/ (the wake word aligners from the Montreal Forced Aligner's models: build.sh -> wakealign/<word>-<locale>.wa and a <model>.was per acoustic model, needs MFA's env), speechcorpus/ (a speech corpus of designed voices: "Speech corpus" below), OTA payload dumper, Thumb disassembly helpers, qrun.sh (device binaries under qemu-arm; a toolchain/qemu-arm serves too), dexasm.py (a Dalvik assembler, writer, reader and type check, and a check against the firmware's own framework, for our hand-made dex files: no javac or d8 here), mkwifictl.py (assembles scripts/device/wifictl.dex, checkers' way into WifiService), mkringbar.py (scripts/device/ringbar.dex, checkers' light band on the screen), davs-fetch.py |
| docs/ | user guide (GUIDE.md), security model (SECURITY.md), reverse-engineering notes; img/src/*.typ are the README figures (Typst + CeTZ), tools/figures.sh renders them to img/*-light.svg / *-dark.svg |
| tests/ | protocol tests against the reference implementations |
| blueprints/ | Home Assistant blueprints for features that need an automation (automation/drop_in.yaml: Drop In by voice) |
| keys/ | release.pub: the key online updates are signed with; release.conf: that key and the repository whose releases they are (CI and releases, below) |
| .github/workflows/ | build.yml: builds, tests, betas and releases |
Device binaries need the NDK and the unpacked firmware in firmware/<codename>/ (the model's install page, steps 1–2, e.g. devices/donut/README.md), or
STUBS=1 instead of the firmware (below). Without the NDK only the host targets build. The test references:
uv sync (uv) makes .venv from uv.lock, every package pinned; to change one, edit
pyproject.toml, run uv lock and commit both.
make [DEVICE=donut] # ARM binaries into build/donut/
make DEVICE=donut STUBS=1 # the same, without the firmware: stand-ins for its libraries
make host # PC build (build/hassmic-host) + qemu build for the tests (needs libopus)
make unit # C unit tests; microWakeWord against pymicro-features and TFLite (mww_ref.py);
# the Drop In blueprint (blueprint_dropin.py); one target each (make
# unit-<name>, UNIT_TESTS), so make -j unit runs them at once
.venv/bin/python tests/run.py [-j N] [name ...] # every PC test below at once (CI), each in a network namespace of its own
# (unshare -rn); logs of those that fail, all in build/test-logs/;
# one that failed with the others runs again alone: passing then, it is
# flaky (a warning, <name>.first.log), not a failure; --strict: no reruns
.venv/bin/python tests/blueprint_dropin.py # the Drop In blueprint against stand-ins of Home Assistant's registries,
# states, actions and template engine (also in make unit)
.venv/bin/python tests/fake_ha_esphome.py # ESPHome native API, as Home Assistant (aioesphomeapi): entities,
# settings, voice assistant, replies, announcements (HTTP, HTTPS)
.venv/bin/python tests/fake_ha_esphome_timers.py # the same API: timers (ringing, and the next one running), encryption,
# clock and zone, noise reduction, LEDs, light sensor
.venv/bin/python tests/fake_ha_esphome_features.py # sound detection (3 s windows: HASSMIC_FAKE_SOUND_WINDOW), Wi-Fi motion
.venv/bin/python tests/fake_ha_esphome_buttons.py # runs cancelled while HA thinks or streams; the "Button" event entity
.venv/bin/python tests/fake_ha_esphome_address.py # a new address: links closed, mDNS announced again (netaddr.c)
# (the five share their setup: tests/esphome_common.py; one file was 90 s)
.venv/bin/python tests/fake_ha_arbitration.py # two Echos + Home Assistant + an unknown device: wake word arbitration: merge, forger,
# pairing; _join.py (tags, action, crash), _rounds.py, _kiosk.py, _window.py;
# shared tests/arbecho.py (the network's pace at 0.1: HASSMIC_ARB_SCALE)
.venv/bin/python tests/fake_ha_dropin.py # Drop In between two Echos: call, answer, hang-up paths, refusals, lost peer,
# the ringtone at the sounds volume (HASSMIC_EARCONS: stand-in stock sounds)
.venv/bin/python tests/ha_real_dropin.py --setup # once: build/ha-venv, Home Assistant (pinned) and what its integrations need
.venv/bin/python tests/ha_real_dropin.py # the Drop In blueprint in that real Home Assistant with four PC Echos (one
# the released build, from its git tag), in a network namespace with only
# loopback (unshare -rn); skips without build/ha-venv or user namespaces
.venv/bin/python tests/fake_web.py # the settings page: login by the action button, signed requests, export/import
.venv/bin/python tests/fake_web_artifacts.py # models copied from one Echo to another through the page, root's installer
.venv/bin/python tests/fake_web_wifi.py # Wi-Fi switch: the sealed password, its PSK, root's wifi.sh against a fake wpa_cli
.venv/bin/python tests/fake_wifi_join.py # checkers' setup join (wifi-join.sh) through a fake adb and WifiService
.venv/bin/python tests/fake_web_mww.py # microWakeWord: models from the page, the engine switch, real detections on the PC
.venv/bin/python tests/fake_web_davs.py # models downloaded from a fake Amazon on the Echo itself: the code pair
# login with the device attestation token, the download, staging, deregister
.venv/bin/python tests/fake_ha.py [--qemu] # Wyoming (wyoming)
.venv/bin/python tests/fake_ma_sendspin.py # Sendspin, as Music Assistant 2.10.8 (aiosendspin 10.2.1: Sendspin 1.0), the
# server strict: a deviation it would only log closes the connection
.venv/bin/python tests/fake_ma_sendspin.py --legacy # the same as Music Assistant up to 2.10.6 (aiosendspin 9.1.1, the draft before
# 1.0) from build/aiosendspin-9.1.1, which --setup makes (tests/run.py does)
.venv/bin/python tests/fake_ha_wakealign.py # the wake word's end by the aligner: file per language, too slow or busy
# by the level, speaker adaptation in use and saved
.venv/bin/python tests/fake_ha_stop_word.py # "<wake word>, stop" between two Echos: a dropped run cancelled, the setting
# stop_ends_listening off and on (the round, listening, thinking, 4 s)
.venv/bin/python tests/fake_ma_api.py # Music Assistant's API for the screen (mass.c) against a stand-in server
.venv/bin/python tests/fake_screen.py # the Echo Show's screen: what hassmic tells its UI (build/hassmic-host-screen,
# a stand-in UI), Sendspin's metadata and artwork, the band, restarts
tests/ota_push_test.sh # signed push-update path end to end
tests/otatool_test.sh # the PC's otatool (Python) against the Echo's (C)
.venv/bin/python tests/fake_ha_update.py # online updates: Home Assistant, GitHub and root's installer in one
.venv/bin/python tests/fake_ha_wakesound.py # wake sound removal off and on, against the PC's stand-in echo
.venv/bin/python tests/fake_ha_volumes.py # separate volumes: four of their own or following the music, media, keys,
# restart, Bluetooth speaker, page, exports, against the mixer's volumes as
# files (HASSMIC_FAKE_MIXER, HASSMIC_FAKE_SPEAKER)
.venv/bin/python tests/fake_ha_timer_sound.py # the timer's sound: stock's tone (a stand-in) by default, looped and cut
# off, the beep at its level, uploads as the page makes them, Play, delete,
# a restart (the page's loudness check: tests/unit/web_loudness_test.py)
.venv/bin/python tests/fake_ha_ring.py # the light ring: the animation set hassmic -G makes, Home Assistant's light,
# the Echo's own patterns first, the listening ring turned by the beam
.venv/bin/python tests/fake_ha_ring_acs.py # the same on the Echo Dot 5's binary animations: the set, its index files,
# the light drawn into its slots through a stand-in for libhmled.so
.venv/bin/python tests/fake_ha_ring_live_acs.py # "Light ring live" on the Echo Dot 5: frames into its slot through that
# stand-in, the Echo's own first, ledcontroller started again
.venv/bin/python tests/fake_improv.py # setup from a phone (Improv over BLE) on a fake Bluetooth controller,
# Wi-Fi through root's wifi.sh, adoption, factory reset
.venv/bin/python tests/fake_ha_bt_proxy.py # the Bluetooth proxy switched off and on (issue #152) on that controller
tools/qrun.sh [-t secs] <arm-binary> args runs a device binary on the PC under qemu-arm against
firmware/$DEVICE/rootfs, in a PID namespace of its own (bionic's mutexes hang with a pid over 65535). Where users may
not make namespaces (Ubuntu 24.04 and later) it stops and names the sysctl that allows them; --userns prints it.
The Wi-Fi motion kernel modules (src/kmod/) need the model's kernel sources and compiler in toolchain/; without
them make leaves the module out and says so, and that Echo gets no Wi-Fi motion (donut falls back to its driver's
RX_STAT, the last frame from anyone). make kernel-tools downloads them (scripts/kernel-tools.sh, about 115 MB,
770 MB unpacked; the guided setup does it in its downloads step, CI before every build); the kernel needs bc to
build:
make kernel-tools DEVICE=donut # kernel 4.4.22 (arm64), aarch64-linux-android-4.9
make kernel-tools DEVICE=radar # biscuit, radar: kernel 3.18.19 (ARM), arm-eabi-4.8
make kernel-tools DEVICE=cannoli # kernel 5.4.86 (ARM), arm-eabi-4.8
The pins are in device.mk (KSRC_URL, KSRC_SHA256, KCC_URL, KCC_DIGEST), or the Makefile's defaults for the
3.18 models: the sources by their checksum, the compiler by a digest over its files, since googlesource packs its
archive anew for every download.
The compilers are the ones Amazon built those kernels with (their version strings say so). The kernel config is in
the repository: biscuit's and radar's devices/<codename>/kconfig is their kernel's own (IKCONFIG, read out of the
firmware's boot.img with scripts/extract-ikconfig; device.mk KCONFIG); donut's kernel carries none, so its
devices/donut/kconfig is a fragment on top of the arm64 defconfig (KFRAG), with what donut's own modules show
(vermagic, no modversions, no signature). Where the kernel has CONFIG_MODVERSIONS (athena, cannoli),
devices/<codename>/Module.symvers has its CRCs of what the mod
Then run bash setup.sh. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: xcode-select --install
git clone https://github.com/Gamer92000/echo-dot-assist.git cd echo-dot-assist
Python >=3.13
brew install uv
uv sync
scripts/setup.sh
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/img/install-dark.svg">
<img alt="The setup's steps: on your PC (tools, downloads, USB access), into the Echo (USB cable, unlock, stock firmware, root; this wipes it and is skipped on a rooted Echo), build (or GitHub's build), onto your network (lock down and join Wi-Fi, install). Then add it in Home Assistant." src="docs/img/install-light.svg">
</picture>
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.
build/<codename>/setup.log).main and release): the setup takes that build,
checked against the project's key, and skips the 1 GB Android NDK.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.--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.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.
No reports for macOS yet.
GitManual AI Agent reads the 5 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.