echo-dot-assist README

项目的 README,来自 github.com/Gamer92000/echo-dot-assist。合并为一个 markdown 文件:README.md。

echo-dot-assist

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.

Inside the Echo, Amazon's microphones, audio front end and wake word engine stay. hassmic replaces the Alexa client and talks to Home Assistant, Music Assistant and Bluetooth devices. A firewall keeps the Amazon cloud out.

[!CAUTION] Vibecoded, unaudited, your risk. Code, notes and docs were written by an AI (Claude) in conversation with the author, and tried on one Echo of each model. The install unlocks the bootloader and writes the system partition: it can brick the Echo. A mistake in the firewall or the updates could leave it online or open on your network. Read what you run. No warranty, no support.

Supported Echos

Echo Model Codename Way in
✅ Echo Dot 3rd gen (2018) D9N29T donut open the case, wires on test pads
✅ Echo Dot 2nd gen (2016) RS03QR biscuit micro-USB, no soldering
✅ Echo 2nd gen (2017) XC56PY radar open the case, solder USB to the amplifier board
✅ Echo Show 5 1st gen (2019) H23K37 checkers micro-USB, no soldering; the ring as a band on screen
✅ Echo Show 8 1st gen (2019) C7H6N3 crown micro-USB, no soldering; as checkers
✅ Echo Show 5 2nd gen (2021) C76N8S cronos micro-USB, no soldering; as checkers
✅ Echo Show 8 2nd gen (2021) A8H3N2 athena micro-USB, no soldering (a serial-port unlock); the ring as a band on screen
✅ Echo Input (2018) C1125P cupcake micro-USB, no soldering; no speaker (jack or Bluetooth), one LED

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

[!IMPORTANT] Getting into the Echo is R0rt1z2's work, not this project's. Every model above unlocks with their exploits for MediaTek's chips (amonet, kamakiri, saiyaku), their bootloader payload kaeru and TWRP as they ported it to each model, and their XDA threads walk through the unlock and root. Without them none of this would run on an Echo. The unlock and boot-root you do by hand, as the model's thread says: R0rt1z2 asks that they are never run from an installer or a script, so the setup sends you to the thread, waits, and checks the Echo before it goes on.

What you get

Stock Alexa With hassmic
Voice assistant Alexa, in Amazon's cloud Home Assistant Assist
Hears you across the room, over music ✅ ✅ the same front end
Wake words Alexa, Echo, Computer, … the same, or any microWakeWord or openWakeWord model
Only the nearest Echo answers ✅ decided in the cloud ✅ decided on your network
Timers, announcements, follow-ups ✅ ✅
Drop In between Echos ✅ through Amazon ✅ on your network
Multiroom music Amazon speaker groups Music Assistant (Sendspin)
Bluetooth speaker for your phone SBC SBC, AAC, aptX, aptX HD
Plays on a Bluetooth speaker ✅ ✅
Bluetooth proxy for Home Assistant – ✅
Do not disturb, equalizer, ring brightness Alexa app entities in Home Assistant
Buttons and light ring in automations – an event and a light in Home Assistant
Light ring animations of your own – drawn on the settings page, for each of the Echo's
Echo Show: your words, the reply and timers on screen Alexa's screens large letters over the screen, experimental
Louder speaker (Echo Dot 2, Echo 2, Echo Dot 3) – up to +12 dB on the settings page (Echo Dot 3: +2 dB)
Sound detection (smoke alarm, glass, …) Alexa Guard, checked in the cloud on the Echo, less reliable
Whisper detection answers in a whisper a sensor for your conversation agent
Motion sensor – from the Wi-Fi signal, experimental
Wi-Fi setup from a phone Alexa app Home Assistant app
Talks to Amazon always never (firewalled)
Updates from Amazon, automatic signed: from your PC, or from Home Assistant

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).

On the Echo

The buttons: action (talk, pause, stop an alarm, cancel; approve a login; hold 10 s for a factory reset), volume up and down (10 % steps; both held 2 s pairs Echos), microphone off (hardware mute), and your voice.

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

Light ring: blue with cyan when listening, blue and cyan spinning when thinking, cyan when speaking, red when muted, orange spinning when not set up, purple for do not disturb, a blue chaser while phones can pair, a rainbow to identify the Echo.

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).

Three Echos in kitchen, living room and hall. Someone in the living room says Alexa; that Echo heard it clearest and answers, the other two stay quiet. They compare over the network in a split second.

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.

Requirements

Install

scripts/setup.sh
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.

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.

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.

Updating

An update comes from your PC (signed with your key) or from Home Assistant (a GitHub release, signed with the release key). Root checks the signature: a bad one is refused. The new version starts and tests itself within 30 seconds; if it passes it is kept for good, if it fails the Echo falls back to the last copy that worked.

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.

When something is wrong

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.

The wake word and the button do nothing

Most likely no connection to Home Assistant; the Echo does not show that yet. In the log, wake: ALEXA type=2 means it heard you, client connected / voice assistant: subscribed means Home Assistant is there. Nothing after the last client disconnected: check the Echo's address (adb shell ifconfig wlan0), that Home Assistant reaches it (TCP 26053) and the Echo reaches Home Assistant (8123). Keep exactly one Wi-Fi profile on the Echo.

No sound from replies or music

The Echo fetches every reply, announcement and play_media from the URL Home Assistant or Music Assistant gives it. Home Assistant builds it from its internal URL (Settings › System › Network), or its LAN IP. The Echo must resolve that name (DNS from DHCP; .local works) and reach the address: on a network without internet, a URL inside it. The log says what failed (net: cannot ...). No button sounds either? Check the volume.

"Invalid encryption key" in Home Assistant

After a reset of the Echo, or when something else set a key first:

scripts/adb-wifi.sh <echo-ip>, then adb shell rm /data/local/hassmic/state/api_key, reboot the Echo, delete the device in Home Assistant and add it again.

Open issues and measurements: PLAN.md.

Undo it

Security

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.

More

Licence

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.

echo-dot-assist (Gamer92000/echo-dot-assist)

正在搜索数据库…

这是什么?echo-dot-assist 可以把旧款亚马逊 Echo(Dot 2、Dot 3、Echo 2 以及多款 Echo Show)改造成本地的 Home Assistant 语音卫星。它保留 Echo 的麦克风阵列和唤醒词引擎,但用一个小型守护进程(hassmic)取代 Alexa。该守护进程通过 ESPHome 或 Wyoming 与 Home Assistant 通信,不连接亚马逊云端。
这是固件改装还是 Home Assistant 插件?这是一款自定义固件,需要刷写到 Echo 的硬件上。之后 Home Assistant 会把 Echo 当作普通的 ESPHome 设备,Home Assistant 一侧无需 YAML 或插件。
我该怎么在我的 Echo 上安装?运行引导式安装程序(scripts/setup.sh,或在 Windows 上通过 Git Bash 运行),适用于你所支持的 Echo 型号。它会逐步指导你下载文件、插上数据线或焊接导线、解锁引导程序,并输入你的 Wi-Fi 密码。
除了 Echo 本身,我还需要什么?一台 Linux 电脑(不能是 macOS、虚拟机或 WSL),并安装 adb、fastboot、python3、make、unzip 和 debugfs;解锁时还需要 USB 数据线或焊接,并且要有可正常工作的 Home Assistant Assist 流程。部分型号也可以在 Windows 上通过 Git Bash 和 adb 完成设置。
这会把我的 Echo 刷成砖吗?会的。安装过程会解锁引导程序并改写系统分区。项目方也提醒,该项目属于随意式编程(vibe coding)产物,未经安全审计,且每个支持的型号只在一台设备上测试过。因此一旦出错,设备可能变砖,或在你的网络中暴露风险。
解锁也能在 Windows 上完成吗?主要设置需要原生 Linux 电脑来完成 USB 解锁。不过,Echo Dot 2(或任何已解锁的 Echo)可以在 Windows 上通过 Git Bash,配合 adb、fastboot 和 python3 来刷写。
Echo 还会连接亚马逊的服务器吗?不会。项目的防火墙只允许 Echo 上亚马逊自带的程序访问你的本地网络。hassmic 的固件更新只会发送到你的电脑或 Home Assistant,从不发往亚马逊。
几台改装后的 Echo 能一起播放音乐吗?可以。多房间音频通过 Music Assistant,借助 Sendspin 协议实现,取代了亚马逊的音箱组功能。
我能用 Wyoming 卫星代替 ESPHome 吗?可以。Echo 可以运行在 Wyoming 模式下:语音、唤醒词、按钮和 Music Assistant 仍然可用,但大部分额外功能(比如灯环动画和详细实体)只在 ESPHome 模式下提供。
如果更新导致 Echo 出故障怎么办?更新经过签名并带有自检功能。如果新版本自检失败,Echo 会自动回退到上一个能正常工作的版本,因此有问题的更新不会让设备永久失效。
我能撤销改装,恢复原版 Alexa 吗?可以。你可以删除 hassmic 配置,临时恢复为原厂状态、未注册的 Echo;也可以运行 scripts/install-system.sh --uninstall 完全卸载;或者从 TWRP 重新刷写原版固件。
大小
9.6 MB
星标
1.3K
时长
1个月
提交 · 90 天