Metadata-Version: 2.4
Name: tcl-fw
Version: 3.1.1
Summary: Pull and decrypt official TCL (MediaTek) FOTA firmware — flashable service packages, fully offline.
Author: vehoelite, Littlenine Ennea
License: MIT
Project-URL: Homepage, https://github.com/vehoelite/tcl-fota-tool
Project-URL: Credit, https://github.com/LittlenineEnnea
Keywords: tcl,fota,firmware,mediatek,android,mbn,decrypt,scatter
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: pycryptodome>=3.20
Provides-Extra: gui
Requires-Dist: PySide6>=6.6; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pyinstaller>=6.0; extra == "dev"
Requires-Dist: PySide6>=6.6; extra == "dev"
Dynamic: license-file

# tcl-fw

**Pull and decrypt official TCL (MediaTek) firmware — flashable service packages, fully offline.**

`tcl-fw` talks to TCL's own FOTA download servers the way the on-device updater
does (no Google, no account, no dongle), lists a device's complete factory
"service" fileset, streams the plaintext partitions, and **AES-decrypts** the
small partitions that ship inside an encrypted 4 MiB header — producing clean,
flashable images (`lk.img`, `boot.img`, `vbmeta.img`, `preloader_*.bin`, the
scatter, …).

> ### Credit
> The header-decryption scheme that makes this tool possible — **AES-128-ECB
> with a universal key recovered from `sugar_otu_r.dll`** — was cracked by
> **[Littlenine Ennea](https://github.com/LittlenineEnnea)**. Mode 4 (full-image
> decryption) exists entirely because of that work. Thank you.

Works on TCL-made Android devices (TCL, REVVL, Alcatel).

---

## Install

```bash
pip install tcl-fw          # CLI only
pip install "tcl-fw[gui]"   # CLI + desktop app (PySide6)
```

Or grab the standalone `tcl-fw` / `tcl-fw.exe` (CLI) or `tcl-fw-gui.exe`
(desktop app) from
[Releases](https://github.com/vehoelite/tcl-fota-tool/releases) — no Python needed.

## Desktop app

Prefer clicking to typing? Launch the GUI:

```bash
tcl-fw-gui        # or:  python -m tcl_fw_gui
```

Pick (or **Detect**) a device → **Load** to see every partition with real sizes
→ tick what you want → **Pull**. Per-partition progress, live decrypt log, and
SHA-1 verification, all over the exact same backend as the CLI. On Windows the
GUI uses the native `adb`, so **Detect phone** works without any usbipd/WSL
plumbing.

## Quickstart

```bash
# Plug in a phone with USB debugging on — tcl-fw reads the curef itself:
tcl-fw pull

# …or name the device explicitly:
tcl-fw list  T704SP-EAUHUS12-V          # see every partition, size, name
tcl-fw pull  T704SP-EAUHUS12-V          # download + decrypt the whole package
tcl-fw pull  T704SP-EAUHUS12-V --small  # just the small parts (lk/preloader/… fast)
tcl-fw pull  T704SP-EAUHUS12-V --only lk,boot,vbmeta
tcl-fw decrypt some_header.bin          # decrypt one local header blob
```

Find your curef on a handset:

```bash
adb shell getprop ro.tct.curef
```

## Commands

| Command | What it does |
|---|---|
| `tcl-fw pull [curef]` | Download + decrypt a device's service package into flashable images. Auto-detects the curef from a plugged-in phone if omitted. `--small`, `--only p1,p2`, `--out DIR`, `--no-verify`. |
| `tcl-fw list [curef]` | Resolve a device and list every partition: name, real size, and whether it comes from the body or the encrypted header. |
| `tcl-fw decrypt <blob>` | Decrypt a single local encrypted-header blob and name it by content. |
| `tcl-fw devices [--detect]` | List known devices, or probe for a connected phone. |

## How it works

TCL's FOTA server delivers each partition in one of two ways, and `tcl-fw`
handles both automatically:

- **Large partitions** (`super`, `system`, `vendor`, `boot`, `md1img`, …) — the
  plaintext **body** *is* the image; it's streamed straight to disk (with resume
  and SHA-1 verification against the server's `checksum.php`).
- **Small partitions** (`lk`, `preloader`, `tee`/`atf`, `vbmeta`, `spmfw`,
  `scatter`, …) — the body is empty; the real image lives inside an encrypted
  ~4 MiB header fetched from `encrypt_header.php`. That blob is **AES-128-ECB**
  with the single universal key

  ```
  KEY = ascii( md5("TeleExtTest" + "t0523" + "jP7GHdmuBz").hexdigest()[:16] )
      = e26baba108b08a28
  ```

  The header is padded with a constant filler block, which `tcl-fw` detects and
  trims to recover the exact image.

Partitions are named **authoritatively** from the server: the `check_new.php`
manifest is joined to the `.sca` scatter's `rename_prefix → file_name` map, so
you get real names, not guesses. When the scatter is unavailable, images are
identified by content (MTK GFH partition name, ext4 volume label, AVB/boot/dtbo
magic).

## Output

```
pkg_<curef>/
  lk.img  boot.img  vbmeta.img  super.img  preloader_*.bin  …
  <device>.sca            # the flash-tool scatter
  manifest.json           # what was pulled, sizes, checksum results
```

Feed these to SP Flash Tool, `fastboot`, or `mtkclient`.

## Related — Image Anarchy

Pulled a package and want to flash, repack, or explore it? Check out
**[Image Anarchy](https://github.com/vehoelite/image-anarchy)** — a companion
toolkit for working with Android firmware images. `tcl-fw` gets you the clean,
named partitions; Image Anarchy helps you do something with them.

## Legal / ethical use

This tool downloads firmware that TCL's own servers serve publicly, for the
purpose of repairing, restoring, or inspecting **a device you own**. It uses no
exploit against the device and asks the servers only for what the on-device
updater already requests. Respect your local laws and TCL's terms.

## Credits

- **[Littlenine Ennea](https://github.com/LittlenineEnnea)** — cracked the
  AES-128-ECB header-decryption scheme and the universal key; the reference
  implementation lives in [`mode4/tcl-fw.py`](mode4/tcl-fw.py). Mode 4 is theirs.
- **[vehoelite](https://github.com/vehoelite)** — the original `tcl-fota-tool`
  FOTA protocol client (check/download signing, fileset parsing), preserved in
  [`legacy/`](legacy/), and the companion
  [Image Anarchy](https://github.com/vehoelite/image-anarchy) firmware toolkit.
- Predecessor protocol research: `mbirth/tcl_ota_check`, `thurask/bbarchivist`.

## License

MIT — see [LICENSE](LICENSE).
