Mstar-bin-tool <2024>

mstar-bin-tool is a popular open-source command-line utility used to unpack and repack firmware for devices using MStar chipsets

, such as Android Smart TVs (e.g., Letv, XGIMI) and set-top boxes.

If you are looking for a "paper" (technical guide or documentation) for this tool, here is a breakdown of its primary functions and usage: Core Capabilities Firmware Unpacking (

: Extracts individual partitions and components from a consolidated firmware file (like CtvUpgrade.bin MstarUpgrade.bin Firmware Packing ( : Recompiles modified partitions back into a flashable file using a configuration file ( Key Extraction ( extract_keys.py : Retrieves public keys from the

binary, which are necessary to decrypt secured partitions like recovery.img Secure Partitioning ( secure_partition.py

: Encrypts images and generates digital signatures for devices with Secure Boot Typical Firmware Structure A standard MStar upgrade binary consists of: Header Script (16KB)

: A set of plain-text U-Boot commands executed by the TV to set up the environment and flash partitions. : The actual binary data for partitions like

: Contains a magic number and CRC32 checksums for integrity verification. Recommended Resources & Documentation GitHub Repository

: The official source code and basic documentation can be found at dipcore/mstar-bin-tool Technical Guides

Detailed firmware modification guides are available on enthusiast forums like (Russian) and KenotronTV mstar-bin-tool

For a structural overview of how MStar upgrades work, refer to the MStarUpgrade.md documentation on GitHub Are you planning to modify a specific partition system.img ) or are you trying to bypass a secure boot dipcore/mstar-bin-tool - GitHub

The mstar-bin-tool is a set of Python-based utilities primarily used for unpacking and packing MStar binary firmware files commonly found in smart TVs, set-top boxes, and other IoT devices. Core Functionality

The toolset is designed to manipulate firmware images built on MStar hardware platforms (like those from Letv, TCL, or Sharp). Key scripts include:

unpack.py: Analyzes and extracts the contents of an MStar .bin firmware file into an output folder.

pack.py: Recompiles firmware components back into a single .bin file using a configuration file (e.g., .ini) to define the structure.

extract_keys.py: Retrieves AES and public RSA keys from the MBoot (MStar Bootloader) image. These keys are essential for decrypting or signing secure partitions.

secure_partition.py: Used to encrypt images and generate digital signatures for builds where SECURE_BOOT is enabled. Use Cases & Application dipcore/mstar-bin-tool - GitHub

🛠️ 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. -p : pack mode

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 decrypting the payload

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

1. Overview & Purpose

MStar firmware images typically come in a packed format containing a bootloader, kernel, and root filesystem. These binaries often lack public documentation regarding their internal structure.

mstar-bin-tool addresses this by providing a reverse-engineered implementation of the MStar packing format. Its primary purpose is to bridge the gap between raw hardware flash dumps and usable filesystem images, enabling:

  • Firmware Modification: Customizing boot logos, changing system configurations, or replacing the initramfs.
  • Security Analysis: Extracting filesystems to hunt for vulnerabilities, hardcoded credentials, or insecure binaries.
  • System Porting: Extracting kernel modules and hardware binaries (HALs) necessary for porting Linux distributions (e.g., Armbian, OpenWrt) to the hardware.

Error: "Python cannot find module 'crcmod'"

Fix: Run pip install crcmod. If on Windows, you may need pip install crcmod-win.

2. Why MStar Firmware is Unique

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:

  • A preamble header (size, version, chip ID).
  • XOR encryption (simple byte-wise XOR against a static key like 0x51 or 0xA5).
  • CRC32 / Checksum tables to verify integrity.
  • Padding to align with flash erase blocks.

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).

Scenario B: Kernel Replacement

A developer wants to test a newer Linux kernel on a set-top box.

  1. Compile the new kernel (zImage/uImage).
  2. Extract the stock firmware to determine the kernel partition size limits.
  3. Replace the extracted kernel image with the new one.
  4. Run the repack command. The tool adjusts the offsets to ensure the root filesystem is found correctly by the bootloader.

5.2 Pack firmware

After modifying unpacked files:

python mstar_bin_tool.py -f new_firmware.bin -c config.ini -p
  • -p : pack mode

The tool will read the same config and rebuild the image from the unpacked directory.

7.2 CPIO rootfs (initramfs)

cpio -idmv < rootfs.cpio
# modify
find . | cpio -o -H newc > new_rootfs.cpio