Metadata-Version: 2.5
Name: firebreak
Version: 0.9.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: `--short`, 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 [8146][fireos-8146] on amonet v2.0.1, TWRP 3.7.0; also needs `boot-root.zip`. On an Echo (2nd Generation), rooted Fire OS 6 [6436][fireos-6436] on amonet-radar v1.0.0 | 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] | 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.
- [docs/rooting.md][rooting] 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.

## `--fastboot`

`stock [BUILD] --fastboot` leaves the device in fastboot at the end instead of
letting it start the Fire OS it now holds. The next run then needs no button
held, because a device already in fastboot is one firebreak can find by itself.
Only the `stock` target takes it, and not with `5.5.0.3`, which ends in the
Dot's bootrom over a serial port.

## `--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.

## `--short`

Use `--short` when the Dot shows no light and gives no fastboot. The run reaches
the Dot's bootrom by shorting its eMMC bus as it powers up, writes amonet
v1.1.0, and then goes on to the target. It takes any target; `--short` to
`unlock fireos6` has not been run on a Dot.

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 unlock fireos5 --short`.
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".

## 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 [6436][fireos-6436]
with amonet-radar v1.0.0, and `stock`, which returns one on amonet to that
build. Both have run on an Echo, and neither is proven: the first boot after
the root needed the Echo power-cycled by hand, which firebreak does not ask
for. Both are refused unless the run passes `--run-on-unproven-path`. 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, `write-test --short` reaches its bootrom as
[`--short`](#--short) does, 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-6436]: https://ftvdb.com/echo/firmware/com.amazon.radar.android.os/17af64ecc5b8f0303daf4e2a37c75b1a-12718777476-fire-os-6-5-7-2-ns6572-6436-2026-03-21/
[fireos-8146]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/8ca06ee4ef2806c974d2944b7fadd543-13222531716-fire-os-6574-1-ns65741-8146-2026-09-17/
[fireos-8149]: https://ftvdb.com/echo/firmware/com.amazon.biscuit.android.os/a01de630f6d943dddc9b751ae74bbb52-13222532484-fire-os-6574-1-ns65741-8149-2026-09-29/
[licence]: https://github.com/bboe/firebreak/blob/main/LICENSE.txt
[rooting]: https://github.com/bboe/firebreak/blob/main/docs/rooting.md
