Orange Pi Android SD Image Builder

Experimental tools for inspecting Allwinner/PhoenixSuite Android firmware images and rebuilding them into a raw SD-card image that can be written with standard Unix tooling.

This was built for Orange Pi Zero 2W / H618 Android images, where the vendor firmware is a PhoenixSuite/PhoenixCard container rather than a normal dd-able SD-card image.

Why this exists

Some Allwinner Android board vendors distribute Android firmware as a PhoenixSuite .img container. PhoenixCard writes bootloader areas, GPT data, and Android partition payloads to specific LBAs. Writing the vendor .img directly with Etcher or dd does not reproduce that layout.

This project reconstructs an experimental raw SD image by extracting those pieces and placing them at the offsets described by the firmware metadata.

What it does

• accepts a PhoenixSuite .img or a .tar.gz containing one;
• extracts firmware members via sunxi-fw;
• reads sunxi_gpt.fex and sys_partition.fex;
• writes protective MBR, primary GPT, backup GPT;
• writes Allwinner boot areas such as boot0_sdcard.fex and boot_package.fex;
• writes Android partition payloads to the GPT partition LBAs;
• expands Android sparse images while writing;
• outputs a regular sparse raw image file.

Non-goals

• This does not include vendor firmware files.
• This does not include PhoenixCard, PhoenixSuit, APKs, or proprietary blobs.
• This does not automatically write to an SD card.
• This is not guaranteed to boot every board/image combination.

Requirements

• Python 3.10+
• tar, file, shasum, standard Unix tools
• sunxi-fw or a compatible sunxi-fw binary placed at:

tools/sunxi-fw/sunxi-fw

The analyzer can also use phoenix_info if available at:

tools/sunxi-tools/phoenix_info

Quick start

git clone https://github.com/the-luap/orangepi-android-sd-image-builder.git
cd orangepi-android-sd-image-builder

# Put or symlink your sunxi-fw binary here:
mkdir -p tools/sunxi-fw
cp /path/to/sunxi-fw tools/sunxi-fw/sunxi-fw
chmod +x tools/sunxi-fw/sunxi-fw

# Inspect the firmware first:
scripts/analyze_allwinner_android_image.sh /path/to/vendor-android-image.tar.gz

# Build an experimental raw SD image:
scripts/build_raw_android_sd_image.py   /path/to/vendor-android-image.tar.gz   build/orangepi-android.raw

Burning to SD card

This project intentionally does not automate destructive disk writes. If you write the generated image to real media, identify the target disk manually and use the whole disk device, not a partition.

macOS example:

diskutil list
# verify target disk carefully, e.g. /dev/diskN
diskutil unmountDisk /dev/diskN
sudo dd if=build/orangepi-android.raw of=/dev/rdiskN bs=4m conv=sync status=progress
sync
diskutil eject /dev/diskN

Linux example:

lsblk
# verify target disk carefully, e.g. /dev/sdX
sudo umount /dev/sdX* || true
sudo dd if=build/orangepi-android.raw of=/dev/sdX bs=4M conv=fsync status=progress
sync

Safety

See docs/safety.md. The short version: a wrong dd target can destroy your laptop/desktop disk. This tool builds a file; you are responsible for any physical write.

Status

Experimental. The raw image structure can be validated, but boot success depends on board revision, firmware version, SD card, and Allwinner boot ROM expectations. UART logs are the best next diagnostic if the board powers on but does not show a usable display.

License

MIT