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. Mode 4 (full-image decryption) exists entirely because of that work. Thank you.

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

Install

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 — no Python needed.

Desktop app

Prefer clicking to typing? Launch the GUI:

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

# 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:

adb shell getprop ro.tct.curef

Commands

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.

Make it flashable (pack)

A service pack names every file only by a numeric ID, but it ships the device's MTK scatter. tcl-fw reads that scatter to rename the images to their real partition names and write a ready-to-load SP Flash Tool scatter:

tcl-fw pull T702Z-EARXUS12-V --pack     # pull, then auto-pack
tcl-fw pack pkg_T702Z-EARXUS12-V        # or pack a folder you already pulled
tcl-fw pack pkg_… --dry-run             # preview the mapping, rename nothing

In the GUI, click ⚡ Make flashable after a pull. Result:

pkg_<curef>/
  boot.img  init_boot.img  vendor_boot.img  dtbo.img  vbmeta*.img
  system.img  vendor.img  product.img  system_ext.img  preloader_*.bin  …
  MT6835_Android_scatter.txt      # load this in SP Flash Tool / mtkclient

Partitions are matched by content (MTK-GFH name, AVB descriptors, dtbo/boot magic, ext4/erofs label) and, for the big filesystem images, by size-fit against the scatter. Anything it can't place confidently is left untouched and listed for you to name by hand — it never guesses a partition into a wrong name.

Related — Image Anarchy

Pulled a package and want to flash, repack, or explore it? Check out 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 — cracked the AES-128-ECB header-decryption scheme and the universal key; the reference implementation lives in mode4/tcl-fw.py. Mode 4 is theirs.
• vehoelite — the original tcl-fota-tool FOTA protocol client (check/download signing, fileset parsing), preserved in legacy/, and the companion Image Anarchy firmware toolkit.
• Predecessor protocol research: mbirth/tcl_ota_check, thurask/bbarchivist.

License

MIT — see LICENSE.