Metadata-Version: 2.5
Name: firebreak
Version: 0.11.0
Summary: Root an Echo Dot (2nd Generation), move it between amonet targets, or return it to stock
Project-URL: Changelog, https://github.com/bboe/firebreak/blob/main/CHANGELOG.md
Project-URL: Source, https://github.com/bboe/firebreak
License-Expression: BSD-2-Clause
License-File: LICENSE.txt
Requires-Python: >=3.9
Requires-Dist: pyserial==3.5
Requires-Dist: update-checker==1.0.1
Description-Content-Type: text/markdown

# firebreak

firebreak unlocks an Echo Dot (2nd Generation) over USB, moves it between amonet
targets, or returns it to stock. Run it again with another target to move the
device. A stopped run picks up where it left off.

Unlocking a stock Dot needs `amonet-biscuit-v2.0.1.zip`, which amonet publishes
only on
[its XDA thread](https://xdaforums.com/t/unlock-root-twrp-unbrick-amazon-echo-dot-2nd-gen-2016-biscuit.4761416/).
A run downloads it unattended. If that fails, the run says so and opens your
browser for the thread instead, because the thread itself refuses an
unattended download. Either way the zip is checked against a pinned hash.
Moving an already-unlocked Dot between targets
needs that zip too, because the run checks the bootloader against the copy in
it, and so do the runs that go through the Dot's bootrom: `firebreak bootrom`, a
resume after `boot0` was erased, and `stock 5.5.0.3`.

| target | the device ends with | time |
| --- | --- | --- |
| `unlock fireos6` (default) | rooted Fire OS 6 [8149][fireos-8149] on amonet v2.0.1, TWRP 3.7.0; also needs `boot-root.zip`. On an Echo (2nd Generation), rooted Fire OS 6 [8149][fireos-radar-8149] on amonet-radar v1.0.1 | about 5 min from `unlock fireos5` |
| `unlock fireos5` | rooted Fire OS [5.5.5.4][fireos-5554] on amonet v1.1.0, TWRP 3.7.0_9-bboe2 | about 9 min from stock |
| `stock [BUILD]` | stock Fire OS at that build, with the device erased: Fire OS 6 [8149][fireos-8149] when left out, or Fire OS 5 from [5.5.0.3][fireos-5503] to [5.5.5.4][fireos-5554]. On an Echo (2nd Generation), Fire OS 6 [8149][fireos-radar-8149] when left out, any Fire OS 6 from [4305][fireos-radar-4305] to 8349, or Fire OS [5.5.5.4][fireos-radar-5554] | about 3 min from `unlock fireos5` |

`unlock` takes the newest amonet that firebreak supports for that Fire OS, so
a target no longer names an amonet version. `unlock` with no target takes
`fireos6`. The older names that carry an amonet version still work and say what
to use instead; those names go away in firebreak 1.0. Running firebreak with no
target at all warns which command replaced the old default, and that warning
goes away then too.

## Run it

It needs `adb` and `fastboot` from Android platform-tools, and
[uv](https://docs.astral.sh/uv/), which runs firebreak from PyPI and fetches a
Python for it when needed. Each
[release](https://github.com/bboe/firebreak/releases) also has `firebreak.pyz`,
which runs as `python3 firebreak.pyz` on Python 3.9 or later.

`uvx firebreak@latest` asks PyPI for the newest release on each run. Without a
network it fails, and `uvx firebreak` runs the copy uv already has.

### macOS

These commands use [Homebrew](https://brew.sh). Without it, download Google's
[platform-tools](https://developer.android.com/tools/releases/platform-tools).

```sh
brew install --cask android-platform-tools uv
uvx firebreak@latest unlock       # fireos6
uvx firebreak@latest stock        # 8149, or name 8344, 8338, 8146, 8142, 8138, 6302, 5041, 4405, 4315, 5.5.5.4, 5.5.5.0, 5.5.4.9, 5.5.4.6, 5.5.3.1, 5.5.0.3
```

### Linux

These commands are for Debian and Ubuntu. Run firebreak without `sudo`.

```sh
sudo apt install adb fastboot curl
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx firebreak@latest
```

### Windows

Install the drivers from an administrator PowerShell:

```powershell
cd $env:TEMP
curl.exe -fo fastboot.cab https://catalog.s.download.windowsupdate.com/d/msdownload/update/driver/drvs/2016/10/20940218_0ae8695c01fb84d1fdea5c9a04baf336ec5b1ba7.cab
curl.exe -fo mtk.cab https://catalog.s.download.windowsupdate.com/d/msdownload/update/driver/drvs/2016/07/20896845_fdc6bb5aa9a9bac99adf85d931d6c21d1130a96e.cab
mkdir -Force fastboot, mtk
expand -F:* fastboot.cab fastboot
expand -F:* mtk.cab mtk
pnputil /add-driver fastboot\tplink_winusb.inf /install
pnputil /add-driver mtk\cdc-acm.inf /install
Remove-Item -Recurse fastboot.cab, mtk.cab, fastboot, mtk
```

The drivers have x86 and x64 builds only, so on Windows on ARM the steps that
use fastboot or the bootrom cannot run.

Then open a new PowerShell, not as administrator, and run these:

```powershell
winget install Google.PlatformTools
winget install astral-sh.uv
uvx --managed-python firebreak@latest
```

`--managed-python` has uv use its own Python. A Python from the Microsoft
Store keeps firebreak's files where adb and fastboot cannot see them, and
firebreak stops on it.

## Notes

- From stock, firebreak asks for the fastboot gesture.
- A ring that stays solid blue at the fastboot gesture can mean a cable that
  carries power but no data, or a bad USB connection. Try another cable, then
  another port. On Windows it can also mean the [drivers](#windows) are
  missing.
- A ring that restarts instead of reaching TWRP, blue with about a second of
  turning cyan and little or no white, has been a USB port that cannot power
  it. To tell, hold the + button with the device on a USB wall charger: a ring
  that reaches white there means TWRP runs. Then use a port on the computer
  itself, with nothing else on it.
- A `/system` write that keeps failing with `failed to read copy response: EOF`
  can mean a poor USB connection. Unplug both ends of the cable, plug them back
  in firmly, and try another cable if it fails again.
- Do not connect a stock device to Wi-Fi before you unlock it. Amazon can
  update it to a build firebreak does not support.
- `amonet-biscuit-v2.0.1` and `amonet-radar-v1.0.1` root the Fire OS 6 build
  already installed, and keep the device's Wi-Fi and Alexa setup. Unlock it
  soon after setup, before it can update. `--factory-reset` erases the device and
  installs the target's build instead.
- [docs/unlocking.md][unlocking] says why each step is there.

## Bootloaders

From stock, only the LK decides whether firebreak can unlock a device.
`fastboot getvar lk_build_desc` reads it.

| `lk_build_desc` | ships in |
| --- | --- |
| `2c3569d-20260617_045829` | Fire OS 6 8338, 8344 |
| `63cb91b-20221007_072309` | Fire OS 6 [4405][fireos-4405] to [8149][fireos-8149] |
| `41fb3ce-20221007_151724` | Fire OS 6 [4310][fireos-4310], [4313][fireos-4313], [4315][fireos-4315] |
| `beb022a-20211202_231918` | Fire OS [5.5.5.4][fireos-5554] |
| `a828f29-20210822_210511` | Fire OS [5.5.4.9][fireos-5549], [5.5.5.0][fireos-5550] |
| `f379dba-20170906_000423` | Fire OS [5.5.3.1][fireos-5531] to [5.5.4.6][fireos-5546] |
| `0e1d0d9-20161018_220224` | Fire OS [5.5.0.3][fireos-5503] |

- [docs/devices.md][devices] has each build's preloader, TEE and
  anti-rollback versions.
- An LK older than 5.5.0.3 reports none of these, and so no `lk_build_desc`
  and no `pl_build_desc`. firebreak unlocks such a Dot with the default
  fastbrick image, which amonet v2.0.1's own map gives an LK it does not know.

## `--end-in-fireos`

`stock [BUILD]` leaves the device in fastboot at the end. The next run then
needs no button held, because a device already in fastboot is one firebreak can
find by itself. `--end-in-fireos` lets it start the Fire OS it now holds
instead. Only the `stock` target takes it. `5.5.0.3` cannot wait in fastboot,
so it waits in the Dot's bootrom, which the next run picks up with no button
held; power the Dot off and it starts Fire OS 5 instead.

## `--no-wait`

`stock [BUILD] --no-wait` starts the writes at once. Without it the run counts
down 10 seconds first, which is the last point Ctrl-C leaves the device as it
is. Only the `stock` target takes it.

## One command per entry point

A target run starts wherever the device is, so testing one stage means
reaching its state first. Three commands do only that, and stop there.

| command | where it leaves the device | writes |
| --- | --- | --- |
| `firebreak fastboot` | the fastboot its bootloader gives | nothing |
| `firebreak twrp` | its TWRP | nothing, where the bootloader is unlocked and its recovery holds a TWRP; `--force` writes one |
| `firebreak bootrom` | its bootrom, with amonet's payload holding it | boot0's header from a recovery, all of boot0 from fastboot |
| `firebreak short` | the same, with the test point shorted | nothing |

Each asks before a write and says what the write does. `--force` answers in
advance, and a run with no terminal to ask at stops and names it.

## `short`

Use `firebreak short` when the Dot shows no light and gives no fastboot. It
reaches the Dot's bootrom by shorting its eMMC bus as it powers up, and holds
it there. The run after it joins that payload with no second
short, so this is how a target run starts on a Dot that cannot reach fastboot.
Only this command asks for a short.

1. Open the Dot with a Torx T8 screwdriver. Lift the shield's lid off the eMMC
   by its corners; its metal frame stays on the board.
2. Find the passive marked in [this
   photo](https://xdaforums.com/attachments/short2-jpg.6273804/), in the row
   between R60 and C52 beside the eMMC ([where that is on the
   board](https://andygoetz.org/blog/2022/05/echo-dot-v2-dumping-emmc/)). Do not
   use C52, which is a capacitor.
3. With the Dot unplugged, run
   `uvx firebreak@latest short --device biscuit`.
4. When firebreak prints "Short … test point and plug it in", hold a wire from
   that passive to the shield frame beside it, which is ground, and plug the Dot
   in. A Dot plugged in before that message can go unseen. On "Short … missed",
   unplug it and try again.
5. Take the wire off when firebreak prints "The short may come off now".
6. Leave the Dot plugged in, and run the target you want, such as
   `uvx firebreak@latest unlock`. A power cycle loses the hold.

## Reporting a problem

When a run fails, run firebreak again with the `report` command, as in
`uvx firebreak@latest report`, then please stop by `#support-device-unlocking`
in the [EchoMuse Discord](https://discord.gg/vAPHMDvREG) and paste what it
prints. It starts the device's recovery, prints what the device, its eMMC and
this computer are, and the device's partition table, and writes no partition. A
device already in a recovery stays there, and it is left in its recovery
afterwards.

`report` also names the device and lists its USB devices. An Echo (2nd
Generation) takes `unlock fireos6`, which roots Fire OS 6
[8149][fireos-radar-8149] with amonet-radar v1.0.1, and `stock [BUILD]`, which
returns one on amonet to
any of sixteen stock builds, from Fire OS [5.5.5.4][fireos-radar-5554] to
Fire OS 6 8349, which amonet-radar v1.0.1 is the first release to
unlock. Both have run on an Echo. The first boot after
the root has sometimes shown nothing on USB; the run waits, and after a minute
it asks for the Echo's power to be unplugged and plugged back in. Every other
target is for the Echo Dot (2nd Generation). The report is the same on other
Echo devices and helps add them.

`write-test` then tells a failing eMMC from a failing cable. It pushes a
pattern into the Dot's RAM, then has the Dot write it over its own `cache`
partition and read it back, so nothing crosses USB. It erases `cache`, which
holds nothing the Dot needs, and leaves an empty filesystem there, or says
it could not.

For a Dot that shows no light, run [`short`](#short)
first; `write-test` then goes through the payload waiting there, writes a
pattern over the end of `cache` from this computer, and reads it back. It says
whether the eMMC refused a write or the bytes did not arrive, and puts back
what was there when the Dot still answers.

## Credits

firebreak automates work that other people did first.

- [xyz](https://github.com/xyzz/amonet) wrote amonet, a MediaTek bootrom
  exploit. firebreak's bootrom and payload clients follow its protocol.
- [k4y0z](https://github.com/chaosmaster) made the first port of amonet to the
  Echo Dot (2nd Generation).
- [Rortiz2](https://github.com/R0rt1z2) continued
  [that port](https://github.com/R0rt1z2/amonet/tree/mt8163-biscuit), released
  it with TWRP, and keeps
  [the XDA thread](https://xdaforums.com/t/unlock-root-twrp-unbrick-amazon-echo-dot-2nd-gen-2016-biscuit.4761416/).
  The `bboe` TWRP is a fork of
  [their TWRP tree](https://github.com/R0rt1z2/twrp_device_amazon_echo-mt8163).
- AntiEngineer helped find the pins and bring up UART on a Dot.
- [topjohnwu](https://github.com/topjohnwu/Magisk) wrote Magisk, which roots
  Fire OS 5.
- [Andy Goetz](https://andygoetz.org/blog/2022/05/echo-dot-v2-dumping-emmc/)
  described how to short the eMMC bus at the passives beside R60.
- [mtkclient](https://github.com/bkerler/mtkclient), by bkerler, agrees with
  two of firebreak's bootrom addresses.
- [ftvdb](https://ftvdb.com/) keeps the Fire OS builds that the tables link to.

## Licence

firebreak uses the BSD 2-Clause licence, in [LICENSE.txt][licence]. This
repository contains no Amazon code, and firebreak is not affiliated with,
endorsed by, or supported by Amazon.

[devices]: https://github.com/bboe/firebreak/blob/main/docs/devices.md#biscuit
[fireos-4310]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/2c4db2f5fa2ddb390faf5ccf9a879b01-8087721594-fire-os-6-5-5-5-ns6555-4310-2022-11-23/
[fireos-4313]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/0c90e6241451777048da197542c82b87-8087722362-fire-os-6-5-5-5-ns6555-4313-2023-01-10/
[fireos-4315]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/03c7c4dc338a93635dda0f5e1cd4e451-8087722874-fire-os-6-5-5-5-ns6555-4315-2023-11-20/
[fireos-4405]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/570f3f6b28f94323e01e95561c87887f-8289072516-fire-os-6-5-5-6-ns6556-4405-2023-01-21/
[fireos-5503]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/6049e04dd518483ed6e5b0d72ffe9eac-564196920-fire-os-5-5-0-3-564196920-2018-09-20/
[fireos-5531]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/789c6b80b00b90a35c3016d42a7c4455-641575220-fire-os-5-5-3-1-641575220-2019-07-22/
[fireos-5546]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/547fad91b469b9d6a3a1fcdb85b43671-666694320-fire-os-5-5-4-6-666694320-2021-06-23/
[fireos-5549]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/538f9374ad45f3f1ea18948609d7446f-672720020-fire-os-5-5-4-9-672720020-2021-10-27/
[fireos-5550]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/1be9f19c0c16337c34d55390a146c990-673726720-fire-os-5-5-5-0-673726720-2021-12-14/
[fireos-5554]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/805e721e1bed461d8a81015a1f703fc1-680767620-fire-os-5-5-5-4-680767620-2022-11-18/
[fireos-8149]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/a01de630f6d943dddc9b751ae74bbb52-13222532484-fire-os-6574-1-ns65741-8149-2026-09-29/
[fireos-radar-4305]: https://ftvdb.com/echo/firmware/com.amazon.radar.android.os/3341ac1839e3ce5b4770ecfdebce828b-8087720314-fire-os-6-5-5-5-ns6555-4305-2022-11-30/
[fireos-radar-5554]: https://ftvdb.com/echo/firmware/com.amazon.radar.android.os/e7338ac28c64f1846389c8a7bf871c94-680767620-fire-os-5-5-5-4-680767620-2022-11-18/
[fireos-radar-8149]: https://ftvdb.com/echo/firmware/com.amazon.radar.android.os/43c054c90359193ce6c1d0b65fbfeb0e-13222532484-fire-os-6574-1-ns65741-8149-2026-09-29/
[licence]: https://github.com/bboe/firebreak/blob/main/LICENSE.txt
[unlocking]: https://github.com/bboe/firebreak/blob/main/docs/unlocking.md
