EchoMuse README

The project's README from github.com/wilbowes/EchoMuse. As one markdown file: README.md.

EchoMuse

Turn an old Amazon Echo Dot (2nd gen) into a local voice assistant for Home Assistant.

CI Firmware emOS Controller License: MIT

Join the community — Discord · r/echomuse

EchoMuse makes a second-hand Echo Dot a voice satellite for Home Assistant: say the wake word, ask something, and hear the answer from the Dot. There is no Amazon account, no Alexa and no cloud service of ours. The Dot shows up in Home Assistant as an ordinary ESPHome voice satellite, so there is nothing extra to install there.

At a glance

What it is

What it isn't

What you need

An Echo Dot 2nd gen The hardware being repurposed.
Home Assistant With a working Assist pipeline.
An always-on computer Runs the controller. The Home Assistant machine itself is fine if it runs add-ons.
A Linux computer (a live USB works) and a micro-USB cable, once To unlock the Dot. The unlock does not run on macOS.
Chrome or Edge, once The setup wizard talks to the Dot over USB from the browser.

Getting started

  1. Unlock the Dot with R0rt1z2's amonet-biscuit. Either version works: v1.1.0 leaves it on FireOS 5, v2.0.0 moves it to FireOS 6. The rooting guide explains the choice. You do this at your own risk.

  2. Start the controller, as an add-on:

    Add the EchoMuse repository to Home Assistant

    or with Docker:

    mkdir echomuse && cd echomuse
    curl -O https://raw.githubusercontent.com/wilbowes/EchoMuse/main/controller/docker-compose.deploy.yml
    curl -o .env https://raw.githubusercontent.com/wilbowes/EchoMuse/main/controller/.env.example
    docker compose -f docker-compose.deploy.yml up -d
    
  3. Run the setup wizard from the dashboard with the Dot plugged in over USB. It installs everything and joins your WiFi. Approve the Dot in the dashboard and Home Assistant discovers it.

The quickstart walks through all three.

emOS or FireOS?

The wizard offers two ways to run EchoMuse on the Dot:

Features

Privacy

Status and known issues

EchoMuse is in active development and runs daily on a small fleet. emOS is newer than FireOS and has fewer device-hours behind it. Open issues worth knowing before you start:

Everything else is in the issue tracker.

Getting help

Documentation

Quickstart From nothing to talking to your Dot.
Rooting Unlocking the Dot, and which amonet version to use.
Configuration Every setting, in plain language.
FAQ Common problems and their fixes.
emOS How our own userspace on the Dot works.
How the voice pipeline works The path from wake word to answer.
Device ↔ controller protocol For porting EchoMuse to new hardware.
Contributing Building from source, tests, and how to send changes.
Engineering journal How each part was worked out, including the dead ends.

How it's built

EchoMuse is written largely with Claude, Anthropic's AI model, directed by the maintainer. More than half the commits carry a Co-Authored-By: Claude line, and replies on our issues are signed "Team EchoMuse (powered by Claude)". Nothing about that is hidden.

Credits

EchoMuse would not exist without:

Licence

EchoMuse is MIT licensed. It includes third-party components that keep their own licences, listed with their copyright notices in NOTICE.md. emOS releases also ship busybox (GPL-2.0), with its source and licence attached to each release, and wpa_supplicant (BSD).

Amazon, Echo, Echo Dot, Alexa and FireOS are trademarks of Amazon.com, Inc. or its affiliates. EchoMuse is an independent project, not affiliated with or endorsed by Amazon.

EchoMuse (wilbowes/EchoMuse)

homelab
Searching Database…

What is this?It turns a second-hand Amazon Echo Dot (2nd gen, 2016) into a local voice satellite for Home Assistant: say the wake word, ask, and hear the answer from the Dot. No Amazon account, no Alexa, no cloud - the microphones, speaker, LED ring and buttons keep working.
Is this software running on my computer, on the Dot itself, or both?Both. A controller runs on your own network as a Home Assistant add-on or Docker container, and the Dot itself gets replacement firmware - emOS by default, or rooted FireOS.
What does setup look like from zero to a working Dot?Three steps: unlock the Dot once over USB with R0rt1z2's amonet-biscuit tool, start the controller as a Home Assistant add-on or Docker container, then run the setup wizard from the dashboard with the Dot plugged in - it installs everything and joins your WiFi.
Do I need anything besides the Dot itself?Home Assistant with a working Assist pipeline and an always-on computer for the controller. The one-time unlock also needs a Linux machine (a live USB works), a micro-USB cable and Chrome or Edge - the unlock does not run on macOS.
What can go wrong, and is the Dot at risk?It is not ready out of the box: the unlock can soft-brick the Dot if a step goes wrong (the XDA thread covers recovery). Only the 2nd-gen Dot works today - Dot 3, Echo 2 and Echo Show 8 ports are in progress - and emOS on FireOS 6 cannot join WPA3 networks.
Does anything I say leave my network?Your speech stays on your LAN: the Dot listens for its wake word itself, then audio goes to the controller and on to Home Assistant, with no telemetry or analytics. With a fully local Assist pipeline (Whisper and Piper) nothing leaves your network.
Is the license plain MIT, or is there fine print?MIT for EchoMuse itself, but third-party components keep their own licences (NOTICE.md), and emOS releases bundle busybox (GPL-2.0) and wpasupplicant (BSD) with sources attached.
What can the revived Dot actually do?Voice turns through Home Assistant's Assist, wake word on the Dot or on the controller, barge-in, and multi-Dot homes where the first Dot to hear the wake word answers. Each Dot also works as a Home Assistant media player (media browser, Music Assistant, radio), plus timers, announcements, a Bluetooth proxy per Dot and an ambient light sensor.
emOS or rooted FireOS - which should I pick?emOS is the default: it replaces Amazon's Android with a small Linux userspace, runs on FireOS 5 and 6 devices, and the 3.5mm jack works properly on it; the wizard keeps your original boot image and restoring takes about ten seconds. Rooted FireOS keeps Android 5, works on FireOS 5 only, and is the older, more battle-tested path.
Can I train my own wake word?Yes - you train wake words with owwforge and install them from the dashboard. Detection can run on each Dot or on the controller, and the controller takes over automatically if a Dot cannot do it, so it never goes deaf.
Does the Dot's mute button really cut the microphones?Not at the hardware level. It is a software mute: it silences the microphones in the audio chip and EchoMuse refuses to listen while it is on, but the Dot 2 has no hardware switch that disconnects them.
Creator
wilbowes
Size
8.8 MB
Stars
1.3K
Age
5mo
Commits · 90 Days