SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsopenwrt-amlogic-remake

openwrt-amlogic-remake

Deployment & operations

View repository

Updated 10-16 09:56

About this skill

Amlogic box OpenWrt image remastering (ophub remake)

Remaster the official OpenWrt armsr/armv8 rootfs.tar.gz into a bootable multi-partition image for Amlogic/Rockchip/Allwinner boxes. Board models, DTB, and u-boot facts are always taken from the board database and the ophub kernel packages; when uncertain, stop—do not fabricate.

Determine Task Type

  1. Remaster image: given an existing rootfs.tar.gz, produce .img.gz — follow §Workflow.
  2. Customize firmware contents(add packages/change config): use Image Builder FILES= to produce a custom rootfs.tar.gz and feed it to remake; do not modify the make-openwrt/openwrt-files/inside the remake repo (zero-commit discipline, see Pitfalls).
  3. Board model/kernel/eMMC consultation: answers must land on a board database row, a kernel package, or upstream documentation; read the corresponding reference before answering.
  4. Build error troubleshooting: locate the failing stage against the 6-step pipeline, then read the reference.

Prerequisites / Preflight

Verify each item at runtime; if any is missing, stop:

  • Linux x86_64/arm64 + root: the script self-checks id -u == 0(remake L1356). Verify uname -m、cat /etc/os-release。
  • toolchain is complete:for c in losetup parted mkfs.vfat mkfs.btrfs btrfs mkfs.ext4 tar curl git sha256sum; do command -v $c; done(required throughout the make_image/extract/replace stages).
  • Free disk space: a single board with a single kernel needs several GiB; remake skips that board's build when ≤3 GiB remains (L1325-1332), so do not start at the 3 GiB edge.
  • macOS/Windows cannot run directly: depends on losetup/btrfs/mount, with no host equivalent. Routing: container emulation fw-emulation, or upstream GitHub Actions (action.yml runs L114 with sudo ./remake ; input convention openwrt/bin/targets/*/*/*rootfs.tar.gz L12）。
  • Input files in place:openwrt-armsr/*rootfs.tar.gz — find_openwrt only recognizes that directory and that glob (remake L56-57, L436-446); putting it elsewhere is the same as not putting it there at all.

Offline Baseline

  • OpenWrt upstream-refs：25.12.5(read-through 2026-09-02, not automatically updated).
  • ophub/amlogic-s9xxx-openwrt: upstream HEAD c593d56(2026-08-27, read-through 2026-09-02). All line numbers in this document refer to that version of the remake script.
  • Default kernel line:stable_kernel=("6.12.y" "6.18.y")(L93); for the default values of the other lines, see references/kernel-lines.md.
  • Default partitions: boot 384 MiB / root 1280 MiB (L121-122).

Contracts (no fabrication when uncertain)

  • Input contract：openwrt-armsr/*rootfs.tar.gz contains etc/openwrt_release; remake reads DISTRIB_SOURCEREPO/SOURCECODE/SOURCEBRANCH for naming and the Amlogic box download tag (L449-465).
  • Board model contract: the board id can only be taken from model_database.conf column 14 BOARD. The board id of N1 is s905d, not n1(conf L52). FDTFILE/UBOOT_OVERLOAD/MAINLINE_UBOOT/BOOTLOADER_IMG/KERNEL_TAGS/BOOT_CONF are all based on that row — see references/board-database.md for details.
  • Partition contract (Amlogic): 4 MiB reserved at the head + msdos table + p1 FAT32 (BOOT) + p2 btrfs (ROOTFS,compress=zstd:6）（L762-766、L801-826、L164）。Rockchip=16 MiB+GPT+ext4 boot；Allwinner=16 MiB+msdos+FAT32（L767-776）。
  • u-boot contract (Amlogic): two dd segments at the head of the image (bs=1 count=444 and bs=512 skip=1 seek=1, L832-837); for files, prefer MAINLINE_UBOOT, fall back to BOOTLOADER_IMG; bootfs also holds the entire set of overload files (L933-941).
  • Kernel contract: the three ophub packages boot-*.tar.gz / dtb-<platform>-*.tar.gz / modules-*.tar.gz, and if sha256sums is present, verify each file (L952-957, L613-627). FDTFILE must be verifiable within the dtb package — if the DTB filename or partition offset is uncertain, stop。
  • Installation contract: eMMC installation capability comes from luci-app-amlogic (Amlogic Box) injected at packaging time (L85, L551-566); the remake process itself does not perform eMMC installation — see references/emmc-install.md.

Capability Boundaries + Hand-off

Not doing: compiling OpenWrt rootfs from source; generating or modifying DTB; local builds on macOS; developing an eMMC installer; real-device acceptance.

User Intent Assigned To
Build armsr rootfs.tar.gz, IB package selection,FILES= injection customization openwrt-image-build
No Linux environment but want to emulate running remake, QEMU image verification fw-emulation
Serial/first-boot/HIL real-device verification after flashing fw-hil-testing

Workflow

  1. Determine board model: grep the model/alias in the board model library → get BOARD, FDTFILE, BOOT_CONF, KERNEL_TAGS. read-when: the user gives a product name/alias, or asks "can this one be flashed" → read board-database。

  2. Determine kernel line: read-when: involves -u/-k/-a parameters or "which kernel version to use" → read kernel-lines。

  3. Group commands(expected form):

    sudo ./remake -b s905d -k 6.12.y
# -u flippy        换内核 tag 线（自动剥 kernel_ 前缀）
# -s 512/2560      boot/root 容量（boot≥256、root≥1024，L293-294）
# -p 192.168.2.1   改默认 LAN IP（正则校验，L247-254）
# -n <name>        构建者签名（写入 banner 与 release 文件）

  4. Execute: the six-step pipeline executes in sequence, and failure at any step means exit 1 (loop_make L1335-1340): make_image → extract_openwrt → replace_kernel → refactor_bootfs → refactor_rootfs → clean_tmp

  5. Collect artifacts：openwrt/out/openwrt_[official_]amlogic_s905d_k6.12.y_YYYY.MM.DD.img.gz(naming rule L794; pigz preferred, fallback to gzip, L1294-1299).

    • At the pattern level: this is the release naming template for "<源码别名>_<平台>_<板型>_<内核线>_<日期>"; each release process can extend segments on this pattern, and the template itself is not bound to a specific project.

  6. To change content: go back to openwrt-image-build and use IB FILES= to regenerate rootfs.tar.gz, then feed it to remake — do not modify this repository's openwrt-files (see Pitfalls).

Validation Gates

Layer by evidence strength; mark whichever layer is missing, and do not skip levels to declare success:

  1. Artifact exists：ls openwrt/out/*.img.gz；gzip -t *.img.gz passes;file shows gzip data.
  2. Structural spot check(Linux): after extraction, fdisk -l should show FAT32 p1 + btrfs p2;losetup -P mount and verify that /boot/uEnv.txt dtb matches the board model library FDTFILE, andetc/flippy-openwrt-release BOARD/KERNEL_VERSION are correct.
  3. Real-device acceptance: USB boot → LuCI reachable → Amlogic Box install to eMMC → reboot and boot from eMMC. Only after reaching this step can "usable" be declared; if only 1-2 are completed, mark Build Verification Only, and if real-device evidence is missing, mark Pending HIL。
  4. Failure path: any step error_msg means exit 1; the last section of the log (n/6) points to the failed stage; locate by stage (partitioning/unpacking/kernel/bootfs/rootfs/cleanup).

Pitfalls

  • Do notuse n1 as the -b value — board id is column 14 of the board model library s905d（conf L52）。
  • Do notfabricate DTB filenames or generate DTB locally — FDTFILE must be verifiable in the ophub dtb package (runtime verification); this is the anti-hallucination red line.
  • Do notrun remake directly on macOS/Windows — it depends on losetup/btrfs; route through fw-emulation or GitHub Actions.
  • Do notmodify make-openwrt/openwrt-files/ for customization — fork zero-commit discipline: customize via Image Builder FILES= to produce rootfs.tar.gz and then feed it to remake (this pattern has been verified in a real-world repository: tinynas-files README L3 declares it as "via Image Builder FILES= Firmware injection, multi-architecture packaging shared single-source overlay"), otherwise upstream sync will inevitably conflict.
  • Do notself-develop an eMMC installation script — Amlogic Box is already injected during packaging, and reimplementing it will conflict with openwrt-install-amlogic.
  • Do notuse less than boot 256 MiB / root 1024 MiB (L293-294 directly reports an error and exits).
  • Do nottreat 6.x.y as the real version — it is actually four lines: 6.1/6.6/6.12/6.18 (conf header comment L26-27).
  • Do notstart when remaining disk space is <3 GiB — it will be silently skipped and mistaken for success (L1325-1332).

Official Sources

Privacy

  • Does not collect or send user data externally;-n signature and date written into the image are information actively provided by the user.
  • Troubleshooting may touch /etc configuration within the user's rootfs (keys, passwords): analyze only locally, do not copy into skill output, do not upload.
  • Default LAN IP 192.168.1.1 (L115) written into the image is expected; the intranet address customized by the user via -p is sensitive information, remind not to send it out with screenshots.