Mstar-bin-tool (Cross-Platform)

mstar-bin-tool (often found on GitHub under luckyzhu/mstar-bin-tool or similar forks) is a Python script designed to handle firmware images for TVs, set-top boxes, monitors, and other devices using MStar/MediaTek embedded controllers.

It specifically works with:

The tool allows you to:

pip install -r requirements.txt

Note: Some forks may have different dependencies. If requirements.txt is missing, manually install cryptography, pycryptodome, python-magic, click.

Use dd or a hex editor to modify raw binary partitions.

mstar-bin-tool is a specialized suite of Python scripts designed to manipulate MStar firmware binaries, commonly found in smart TVs (like Letv) and other embedded systems. It is primarily used by developers and hobbyists for firmware modding, recovery, and security analysis. Core Functionality

The toolset provides the necessary logic to bypass proprietary packaging and access the underlying filesystem of MStar-based devices. Its primary capabilities include: Unpacking ( Deconstructs monolithic firmware files (e.g., MstarUpgrade.bin LetvUpgrade.bin ) into individual partition images.

Reassembles modified partition images back into a valid, flashable Key Extraction ( extract_keys.py

Scans MBOOT binaries to retrieve AES encryption keys and RSA public keys used for secure boot and partition signing. Secure Partitioning ( secure_partition.py mstar-bin-tool

Encrypts raw images and generates the required signature files to satisfy device security checks during the boot process. Technical Architecture Target Hardware: MStar (now MediaTek) SoC-based devices. Primary Source: Originally popularized through the dipcore/mstar-bin-tool repository on GitHub, with various forks like qdvbp/mstar-tools adding support for modern secure boot requirements. Common Use Cases Custom Rom Development:

Users unpack stock firmware to remove bloatware, add root access, or change system configurations before repacking. Unbricking:

Extracting specific partitions (like the bootloader or recovery) to flash via hardware programmers or serial consoles. Security Research:

Investigating how the MStar bootloader handles signature verification and encryption. Usage Requirements

To use the tool effectively, a Linux environment (or WSL) is typically recommended along with: Python 3.x PyCryptodome:

Required for handling the AES/RSA cryptographic functions found in secure_partition.py Header Configuration: Most versions require a configuration file (often

) that defines the memory offsets and partition layout specific to the target device model.

🛠️ How to Unpack and Repack MStar TV Firmware Using mstar-bin-tool

If you are trying to modify Android Smart TV firmware running on MStar processors (like Letv, TCL, or generic boards), the open-source python command-line set mstar-bin-tool on GitHub is the absolute best utility to use. The tool allows you to:

Here is a quick, straightforward guide on how to utilize it to modify your TV software. 📋 Prerequisites Install Python 3.4 or higher on your machine.

Download or clone the scripts from the official mstar-bin-tool GitHub Repository.

Grab the target .bin firmware file you want to edit (e.g., CtvUpgrade.bin or MstarUpgrade.bin). 🔓 Step 1: Unpacking the Firmware

To pull apart the packed .bin file and access the internal image partitions (like system.img or boot.img), use unpack.py: python unpack.py Use code with caution. Copied to clipboard

💡 Example: python unpack.py C:/Firmware/MstarUpgrade.bin C:/Firmware/Unpacked/

This will dump all active headers and partition image files into your designated output folder. 🔑 Step 2: Handling Secure Boot Keys (If Needed)

Newer MStar builds utilize SECURE_BOOT where boot.img and recovery.img are AES encrypted.

Use extract_keys.py to target the MBOOT.img partition and grab the keys: python extract_keys.py ./unpacked/MBOOT.img Use code with caution. Copied to clipboard

Decrypt or encrypt your partitions directly using the vendor-pushed aescrypt2 tool located in the repository's /bin directory. 🔒 Step 3: Repacking the Firmware pip install -r requirements

Once you have modified your target files (like pulling out specific system apps or replacing splash screens), you can combine them back into a flashable .bin asset using pack.py: python pack.py Use code with caution. Copied to clipboard 💡 Example: python pack.py configs/letv-x355pro-full.ini

Make sure you reference or create an appropriate .ini configuration script. You can review reference templates already provided in the repository's configs/ folder. dipcore/mstar-bin-tool - GitHub

The utility operates via a command-line interface (CLI). Below are the primary modes of operation.

To understand why you need mstar-bin-tool, you must understand MStar's "All-In-One" design.

Most embedded devices store the bootloader, kernel, and root filesystem as separate partitions on an SPI NAND or NOR flash. MStar, however, often concatenates these parts into a single monolithic binary (firmware.bin), then adds:

mstar-bin-tool automates the process of stripping that header, decrypting the payload, and splitting the result into discrete files (e.g., boot.bin, kernel.bin, rootfs.bin).

Cause: The offset calculator failed. Use --force-offset <hex> manually by inspecting the header structure.

To understand the tool's function, one must understand the structure of the firmware it manipulates.