Skip to content
BranchesTags

Repository files navigation

HexMeow Buildroot external tree

本仓库是 HexMeow RK35xx 控制器的 BR2_EXTERNAL tree，包含板级 DTS、内核配置、 rootfs overlay、自定义 Buildroot package、systemd 服务和固件 CI。当前 defconfig 同时 包含 RK3568 与 RK3576 系列控制板所需的设备树。

公开 defconfig 生成完全开源的公共镜像。正式 release 还可以在公共镜像上叠加 hex-controller 的预编译 bundle，生成私有超集镜像；公共仓库不会包含私有二进制。

仓库结构

  • configs/hexmeow_chassis_ctrl_defconfig：公共镜像的 Buildroot 配置入口。
  • board/hexmeow-chassis-ctrl/：DTS、内核配置、boot script 和 post-build 脚本。
  • overlay/：安装进 rootfs 的配置、服务和工具。
  • package/：本项目维护的 Buildroot package。
  • .github/workflows/build.yml：公共镜像构建及内容契约检查。
  • .github/workflows/release.yml：公共/私有 release 镜像组装。
  • tools/udev/：Linux 主机访问 RK3576 rockusb 的 udev rule。
  • tools/upgrade_tool/：已在本项目验证的 Linux/macOS upgrade_tool v2.55。
  • .agents/skills/operate-hexmeow-controller/：供自动化 session 使用的构建、连接、 烧写和排障 runbook。

构建公共镜像

构建环境与依赖以 ci/Dockerfile 和 build.yml 为准。完整构建包含内核、Mesa、GStreamer 和 Docker，需要较多磁盘空间与时间，建议在 Linux 上进行。

git clone --depth=1 \
  https://github.com/buildroot/buildroot \
  -b 2026.02.1 buildroot
git clone https://github.com/hex-meow/br-external.git br-external

git -C buildroot apply \
  "$PWD/br-external/0001-package-mesa3d-allow-gallium-panfrost-without-target.patch"
make -C buildroot \
  BR2_EXTERNAL="$PWD/br-external" \
  hexmeow_chassis_ctrl_defconfig
make -C buildroot

不要使用 sudo make。已有 Buildroot tree 做增量构建时，先检查 buildroot/local.mk； 其中的 *_OVERRIDE_SRCDIR 会改为编译本地 checkout，因此这种产物不是由仓库 pin 完全复现的 release 镜像。

主要产物位于 buildroot/output/images/：

文件 用途
rootfs.ext2 未压缩的 ext4-compatible 文件系统；当前本地烧写流程使用它
rootfs.ext2.zst 用于发布/传输的压缩 ext2 镜像，不能直接交给下面的 DI -rootfs
rootfs.erofs 体积更小的只读文件系统产物；使用前需单独验证对应启动/烧写流程
rootfs.tar rootfs 内容归档，适合检查文件清单
Image、rockchip/*.dtb 内核与设备树，也会进入 rootfs 的 /boot

ext2 文件系统本身可离线读写挂载，但当前 boot script 给内核传入 ro，运行中的 rootfs 按只读策略启动；可变数据应写入独立的 userdata 分区。

构建后至少确认：

test -s buildroot/output/images/rootfs.ext2
sha256sum buildroot/output/images/rootfs.ext2
tar tf buildroot/output/images/rootfs.tar >/dev/null

公共镜像与私有超集镜像的完整内容门禁以两个 GitHub workflow 中的检查为准。

供 AI / 自动化工具按需生成 SDK

CI 和 GitHub Release 不再生成或发布 aarch64-buildroot-linux-gnu_sdk-buildroot.tar.gz。需要针对当前公共 rootfs 的 glibc、 ABI 和 sysroot 交叉编译应用时，应从目标 br-external commit 在本地按需生成。处理此 任务的 AI 或自动化工具必须遵守以下约束：

  • 以当前 build.yml 中的 BUILDROOT_VERSION、依赖列表、 patch 和 defconfig 为准，不要从旧 Release 下载 SDK，也不要重新把 SDK 加入 CI。
  • 开始前检查 br-external 与 Buildroot 的 git status --short。已有 Buildroot tree 还要 检查 local.mk；其中任何 *_OVERRIDE_SRCDIR 都会让 SDK 引用本地 checkout，而不是 仓库 pin 的源码。
  • 不要使用 sudo make，不要清理或覆盖用户已有的 Buildroot 输出。路径或状态不确定时， 使用新的 sibling Buildroot checkout。

在装有 ci/Dockerfile 所列依赖的 Linux 主机上，以下命令会从干净的 Buildroot tree 生成 SDK；make sdk 本身会完成所需的全量构建：

BR_EXT=$(git -C /path/to/br-external rev-parse --show-toplevel)
WORKSPACE=$(dirname "$BR_EXT")
BR=${BUILDROOT_DIR:-"$WORKSPACE/buildroot-sdk"}
BR2_DL_DIR=${BR2_DL_DIR:-"$WORKSPACE/dl"}

test "$(sed -n 's/^name: *//p' "$BR_EXT/external.desc")" = HEX_EMBEDDED
git -C "$BR_EXT" status --short
test ! -e "$BR"

git clone --depth=1 \
  https://github.com/buildroot/buildroot \
  -b 2026.02.1 "$BR"
git -C "$BR" apply \
  "$BR_EXT/0001-package-mesa3d-allow-gallium-panfrost-without-target.patch"
make -C "$BR" \
  BR2_DL_DIR="$BR2_DL_DIR" \
  BR2_EXTERNAL="$BR_EXT" \
  hexmeow_chassis_ctrl_defconfig
make -C "$BR" BR2_DL_DIR="$BR2_DL_DIR" sdk

SDK="$BR/output/images/aarch64-buildroot-linux-gnu_sdk-buildroot.tar.gz"
test -s "$SDK"
sha256sum "$SDK"
ls -lh "$SDK"

如果公共镜像已经在一个确认过没有非预期 local.mk override 的 Buildroot tree 中成功 构建，只需对同一输出执行最后的 SDK target，然后做同样的校验：

make -C "$BR" BR2_DL_DIR="$BR2_DL_DIR" sdk
SDK="$BR/output/images/aarch64-buildroot-linux-gnu_sdk-buildroot.tar.gz"
test -s "$SDK" && sha256sum "$SDK" && ls -lh "$SDK"

交付时应报告 br-external commit、Buildroot 版本、defconfig、是否存在 local.mk override，以及 SDK 的绝对路径、大小和 SHA-256。SDK 解压到最终使用目录后，先运行其 顶层的 relocate-sdk.sh，再使用其中的交叉编译工具链；不要提交生成的压缩包到本仓库。

进入 Loader

系统仍可登录时，优先在控制器上执行：

sync
reboot loader

SSH 会被远端主动断开，这是正常行为。连接 HDMI 时，Loader 状态会显示 “Emergency Mode”。如果系统已无法登录，请使用对应硬件版本的 Loader/Maskrom 进入方法；本仓库不猜测未记录的按键或跳线流程。

USB 有两种互斥状态：

控制器状态 主机 USB ID 主机接口
正常运行 Linux 1d6b:0104 CDC ACM，通常为 /dev/ttyACM*
Loader/Maskrom 2207:350e rockusb，供 upgrade_tool/RKDevTool 使用

Loader 状态没有 /dev/ttyACM* 是正常的。

Linux 烧写

先安装仓库中限制到 RK3576 2207:350e 的 udev rule，使当前登录用户无需 sudo 使用 upgrade_tool：

sudo install -D -m 0644 \
  br-external/tools/udev/70-rockchip-rk3576.rules \
  /etc/udev/rules.d/70-rockchip-rk3576.rules
sudo udevadm control --reload-rules

安装后重新进入 Loader 或重新连接 USB。更多权限排障见 tools/udev/README.md。

下载并解压已验证的 upgrade_tool v2.55 for Linux （SHA-256：f0d77dbda97713edc93e2bc2a429ea365325f347d98baedf7c0eb98a4d643737）， 然后按以下顺序以普通用户执行：

unzip upgrade_tool_v2.55_for_linux.zip
cd upgrade_tool_v2.55_for_linux
chmod +x upgrade_tool
./upgrade_tool -v
./upgrade_tool LD
./upgrade_tool PL
./upgrade_tool DI -rootfs /absolute/path/to/buildroot/output/images/rootfs.ext2
./upgrade_tool RD

必须看到 Download image ok. 后才能执行 RD。这里正确的分区形式是 DI -rootfs；DI -r 表示 recovery 分区，不能用于 rootfs。不要把 .zst 压缩文件 传给该命令，也不要在一次下载未结束时启动第二个 upgrade_tool。

macOS 烧写

下载并解压已验证的 upgrade_tool v2.55 for macOS （SHA-256：0256f1340aaf02d749f60d3ba870af21b470226264bfce887824dabd3311017a）。 Loader 检查和 rootfs 分区名称与 Linux 相同：

unzip upgrade_tool_v2.55_for_mac.zip
cd upgrade_tool_v2.55_for_mac
chmod +x upgrade_tool
./upgrade_tool -v
./upgrade_tool LD
./upgrade_tool PL
./upgrade_tool DI -rootfs /absolute/path/to/rootfs.ext2
./upgrade_tool RD

执行前确认工具确实列出了目标设备和 rootfs 分区。工具包的来源、校验值和版本说明 也记录在 tools/upgrade_tool/README.md。

USB 串口恢复与查找 IP

正常启动后，Type-C device/OTG 口提供 CDC ACM recovery console。Linux 主机可先确认 USB identity，再连接：

tio -L
ls -l /dev/serial/by-id /dev/ttyACM* 2>/dev/null
udevadm info -q property -n /dev/ttyACM0 | \
  grep -E '^(ID_VENDOR_ID|ID_MODEL_ID|ID_MODEL|ID_SERIAL_SHORT)='
tio -b 115200 -d 8 -p none -s 1 -f none /dev/ttyACM0

打开后按一次 Enter。使用 Ctrl-T q 退出 tio；Ctrl-D 会发送给控制器，并不是 tio 的退出快捷键。

登录控制器后，可用以下命令取得不会依赖历史 DHCP 地址的身份和网络信息：

cat /etc/machine-id
hostname
ip -brief address
networkctl status end0
ip -6 address show dev end0 scope link

end0 同时启用 DHCPv4、IPv4LL (169.254.0.0/16) 与 IPv6 link-local。使用 fe80::/64 地址 SSH 时，要在主机端添加接口 scope，例如 root@fe80::1234%enp5s0。

更完整的串口、CanoKey SSH、直连网线和烧写排障流程见 operate-hexmeow-controller。

分区说明

当前固件使用以下主要分区：

  • uboot：启动引导程序，普通 rootfs 更新不应修改。
  • resource：只读资源分区，开机后挂载到 /mnt/resource。
  • rootfs：本仓库生成的操作系统镜像。
  • userdata：持久化用户数据；恢复出厂设置会清空它。

/root 从 /userdata/root-home bind mount，/etc/dropbear 指向 /userdata/dropbear。因此 DI -rootfs 正常会保留 SSH authorized keys、Dropbear host keys、Wi-Fi 配置及 /userdata/hexmeow；格式化 userdata 则会删除这些内容。

私有镜像的开发 SSH key 由私有 external tree 中的独立 Buildroot package 安装。它不把 key 写进会被 bind mount 遮住的 rootfs /root，而是在 Dropbear 启动前把受管理的 key 块合并进 /userdata/root-home/.ssh/authorized_keys。这样既能随私有 rootfs 更新轮换 开发 key，又会保留用户自行添加的其他 key；公共 defconfig 不选择该 package。每次 启动只在 /run 的 tmpfs 中生成候选内容；内容和元数据均未变化时，不会在 userdata 创建临时文件，也不会替换 authorized_keys。

由于 userdata 不随 rootfs-only 烧写清空，从私有镜像切换到公共镜像时，已经写入 userdata 的受管理 key 块也会继续保留；要得到完全干净的公共设备状态，应执行 userdata/factory reset，或通过串口明确删除该 marker 区块。公共 rootfs 产物本身不含 key seed、安装器或 Dropbear drop-in。

相关文档

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages