HuskerMinion/techo5-dot

What changed · Stock vs TECHO5 Dot · Install · Credits · TECHO5 for the Echo Show 5

TECHO5 Dot replaces Fire OS on the Amazon Echo Dot 2nd generation (codename biscuit) with a small Alpine Linux image and one daemon. The Dot becomes a Home Assistant voice satellite: it hears the wake word on the device, talks to Home Assistant over its encrypted native API, and sends nothing to Amazon. It still uses the internet for what you'd expect: checking this repo for signed updates and setting its clock.

Built on EchoLocal by Yuri Gelfand (MIT), which first made the Echo Dot 2 an ESPHome-native Home Assistant satellite with one Go daemon on Fire OS. TECHO5 Dot's daemon is that daemon, by way of TECHO5's echod (EchoLocal's code vendored and developed further), and much of it is still EchoLocal's. What this project adds is Linux in place of Fire OS: the boot image and slots, Wi-Fi without Android, the seven-microphone work, rebuilt Bluetooth, signed updates and the installer. See NOTICE.

It's a sibling of TECHO5, which did the same for the Echo Show 5. Both run the same daemon source, built per device.

Status: in daily use on three units. Everything marked ✅ below was verified on a bench Dot that came from Fire OS 6574.1, and the installer and updates on two more. Expect rough edges, and keep your backups.

• Fire OS is gone at runtime. Linux boots from the recovery partition. No Android process runs, not even for Wi-Fi: cmd/wmtup talks to MediaTek's combo chip directly, where Amazon's loader used to.
• All seven microphones work together. The daemon averages all seven microphones and cancels the speaker's own echo from that average. Measured against the center mic alone, the average heard speech 1–2.5 dB better, and 2–4 dB better between 1.5 and 4.7 kHz. Steering a delay-and-sum beam added nothing on this 72 mm ring, so it isn't the default. The numbers and method are in docs/microphones.md.
• Bluetooth came back, rebuilt. Stock Bluetooth belonged to Fire OS. Here the Dot runs:
  • a kernel built from Amazon's GPL source with Bluetooth turned on and 48 upstream security fixes backported (BlueBorne and later);
  • a bridge from the chip's raw HCI channel to BlueZ;
  • bluez-alsa, rebuilt with an upstream crash fix Alpine's package lacks.
• Updates can't be forged, and a bad one rolls itself back. Releases are signed (ed25519). An update installs into the spare of two root filesystem slots and boots on trial. If it doesn't come up healthy, the Dot returns to the previous slot by itself.

Numbers from the bench unit:

• Memory: about 445 MB of 481 MB free with everything running, Bluetooth included.
• Wake word: about 30% of one core.
• Root filesystem: 49 MB.

Timed from a reboot command until Home Assistant's API answers from another machine, on the same Dot:

About the same, not faster. By Linux's own clock the Dot is on Wi-Fi at 21 s and listening for the wake word at 26 s. The other ~19 s come before that clock starts: shutting down, the bootloader, and loading the kernel. An earlier build waited for Bluetooth before starting the daemon and took 128 s; now Bluetooth comes up in the background and a paired speaker reconnects when it's ready.

• An Echo Dot 2nd gen, already unlocked with amonet, with Fire OS 6574.1 in its system slots, and sitting in TWRP or running Fire OS with root adb (for example with EchoLocal installed). Unlocking isn't part of this project; Getting started has every command.
• The Dot joined to Wi-Fi once in Fire OS. If it hasn't been, the installer asks for a network.
• A Windows, Linux or macOS computer with Python 3, adb and git (setup for each), plus Home Assistant. Nothing is compiled.

Starting from a stock Dot? Getting started walks through it in order: updating Fire OS, the amonet unlock (linked), this installer, and Home Assistant.

git clone https://github.com/HuskerMinion/techo5-dot
cd techo5-dot
python3 tools/install-dot.py --dry-run   # checks, backups, download, boot image; writes nothing
python3 tools/install-dot.py

It finds the Dot on its own (asking which, if several are plugged in) and asks what to call it in Home Assistant when it has no name yet. From a script, pass --serial <adb serial> --name "Kitchen" and it asks nothing.

The installer:

1. Backs up every boot-critical partition to backups/<serial>/ and checks each copy against the device. On TWRP it reads the real bootloader partitions, not amonet's decoys.
2. Downloads the latest signed release (the root filesystem, the Bluetooth kernel and the rescue environment's packages). The manifest is only believed once the release key's signature over it checks out — the same key the device itself trusts — and every file is checked against the checksums it carries. --release dot-v0.6.0 picks a version instead of the newest — releases here are tagged dot-vX.Y.Z, so the tag is what goes in, not the bare version; --rootfs and --kernel take your own builds (docs/building.md).
3. Builds this unit's boot image from its own recovery backup, with the Bluetooth kernel (--no-bluetooth-kernel keeps the unit's own, without Bluetooth). No Amazon binary is ever downloaded or published.
4. Writes the image to recovery, and the root filesystem into slot a.
5. Keeps an existing Home Assistant name and key, or asks for a name and makes a key.
6. Reboots, then waits on the Dot's USB console until the boot reports healthy.

Home Assistant then finds the Dot as an ESPHome device.

Updates after that come from this repo's releases, through Home Assistant's update card. They carry the root filesystem only; a Dot installed before the Bluetooth kernel gets it with python3 tools/update-boot.py --serial <serial> --address <address> (SSH switched on in Home Assistant). On Windows, type python for python3.

• docs/porting-plan.md: how it was built, milestone by milestone, and what each step proved.
• docs/hardware.md: the board, partitions, kernels, and the Bluetooth kernel's security backports.
• docs/microphones.md: the array measurements, echo cancellation, and the LED whine that turned out to be Fire OS's.
• tools/: the installer, the Wi-Fi tool, the boot image updater, and tools/linux/ (initramfs, root filesystem overlay, slot tool, firewall, kernel and bluez-alsa build scripts and patches).
• cmd/wmtup: Wi-Fi chip bring-up without Android.
• docs/building.md: building the kernel, bluez-alsa, the daemon and the root filesystem yourself.
• The daemon's source: TECHO5, branch main, built with -tags dot.

See NOTICE for the full list.

• EchoLocal (MIT, Yuri Gelfand): the Echo Dot 2 daemon this project is built on (see above).
• EchoMuse / emOS (MIT, Wil Bowes): the first Linux userspace on this hardware. Its notes on the USB gadget, Wi-Fi patch download and the mic array saved days.
• amonet and kaeru (R0rt1z2): the unlock.
• @proffalken: the step-by-step install from Linux (the exact Fire OS build, trusting the adb key, byte-safe backups, the Linux serial console lookup) that the getting started guide and the cross-platform installer are based on.
• jxlarrea: echo cancellation measurements on the Echo Show family.
• bluez-alsa (arkq): the upstream fix for the fdk-aac capability crash (6ccf455).
• The Linux kernel's Bluetooth developers: every backported fix is listed with its commit.
• TECHO5: the daemon, the Linux image tooling and the root filesystem slot design this project shares.
• Amazon's GPL kernel source release for the Echo Dot (2nd generation): the kernel the Dot's Bluetooth build starts from.
• Alpine Linux, BlueZ and BusyBox: the system underneath.
• microWakeWord (Kevin Ahrendt) and the ESPHome wake word models: the wake word on the device.
• Home Assistant, ESPHome and go-esphome-device: the voice pipeline and the API the Dot speaks; Music Assistant for Sendspin.

MIT for this project. See LICENSE and NOTICE. The kernel patches in tools/linux/kernel-patches and the bluez-alsa patch keep their upstream licenses (GPL-2.0 and MIT).

TECHO5 Dot isn't affiliated with Amazon. Echo and Alexa are trademarks of Amazon.com, Inc.