Skip to main content

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.

Click 🔥 Firmware (Auto-updated) to browse the community device database in place of the partition list — every device/build the tool has learned about (CUREF/MODEL, Version, Date, Size, Mode, SW ver). Double-click a row to load that device. The list grows on its own (see below).

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

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.
tcl-fw templates [--all] List validated firmware templates with a NEW tag on recent builds (--all shows full release history).
tcl-fw sync Pull newly-recorded devices from the community server into your device list.
tcl-fw sharing [--on|--off] Show or change community device-ID sharing (opt-out, nothing personal).

Community device database (opt-out)

tcl-fw can only auto-fill a device it knows about, so it grows its own list. When a lookup succeeds, the tool reports the device identifiers it used to a small community registry; other installs pull those in, so a device one person discovers becomes auto-detectable for everyone.

  • Shared: curef, firmware version (fv), mode, resolved tv/fw_id, package size, TCL software version (SVN), and the tool version.

  • Never shared: no IMEI (the FOTA protocol uses a fixed placeholder), no IP, no account — nothing that identifies you or your specific handset.

  • Opt-out, disclosed on first run. Turn it off any time:

    tcl-fw sharing --off      # stop sharing;  --on to resume
    tcl-fw sharing            # status + exactly what's recorded
    

    The desktop app shows the same notice once and a checkbox at the bottom of the window. Submissions are fire-and-forget: if the server is unreachable the tool proceeds normally and simply skips the record.

The device list refreshes automatically (once a day, in the background, gated on the same opt-out); tcl-fw sync pulls it on demand. The registry is public — browse what's recorded at the server's /about and /api/curefs. Server code and privacy details live in curef-server/.

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.

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.

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.

Metadata

Release files for tcl-fw 3.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tcl-fw 3.5.0
File Size Uploaded Provenance Actions
tcl_fw-3.5.0.tar.gz 60.8 kB With provenance Details for tcl_fw-3.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tcl-fw 3.5.0
File Interpreter ABI Platform Actions
tcl_fw-3.5.0-py3-none-any.whl Python 3 none any Details for tcl_fw-3.5.0-py3-none-any.whl

Total release size: 119.4 kB

Release files / tcl_fw-3.5.0.tar.gz

Download URL tcl_fw-3.5.0.tar.gz
Size 60.8 kB
Tags Source
SHA-256 checksum
How to use checksums
219a08029d2702547dd0bbf15ca0e7fed47918d8594a1d07319295736ed31c2d
BLAKE2b-256 checksum
How to use checksums
d7c60316178d22ae376fed295a2d7d2e55f3fe5e10c3e08074d7677ae17dba14
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 20, 2026.

Transparency log

Release files / tcl_fw-3.5.0-py3-none-any.whl

Download URL tcl_fw-3.5.0-py3-none-any.whl
Size 58.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3becbb9e08c42eda68325d0053f1373cdfcfb0af75dce70446927a10bb41869b
BLAKE2b-256 checksum
How to use checksums
b0f764812200b748d604c4b9ba028f741c170d1c63a7acac936f392a728c42fb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 20, 2026.

Transparency log

Security for tcl-fw 3.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tcl_fw-3.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page