6.3 KiB
Executable File
OreBolt OS -- Quickstart
Build and deploy OreBolt OS to a HiFiWalker H2 (or compatible rebadged DAP) from a fresh Arch Linux host. ~30 min if toolchain and kernel tree are pre-staged, ~75 min if building the toolchain from source.
Not on Arch? Stop. The build pipeline is validated against Arch only. Other distros will need porting effort. See PREREQUISITES.md section 1 for the full dependency rationale.
0. What you need
| Item | Where | Details |
|---|---|---|
| Arch Linux host (x86_64) | any Arch install | pacman -Syu first |
mipsel-linux-musl toolchain |
Rockbox prebuilt tarball (recommended) | step 2 below |
| FiiO M3K GPL kernel tree | community mirror or FiiO's GPL download | step 3 below |
| MicroSD card, 2 GB or larger | any | FAT32, single partition |
1. Host dependencies
sudo pacman -Syu --needed base-devel git make python3 rsync \
dosfstools e2fsprogs parted file
2. Cross toolchain
Option A — Rockbox prebuilt (recommended, ~5 min):
sudo mkdir -p /opt/mipsel-linux-musl
sudo tar xzf rockbox-mips-toolchain-*.tar.gz \
-C /opt/mipsel-linux-musl --strip-components=1
Option B — musl.cc fallback (less tuned, but works):
wget https://musl.cc/mipsel-linux-musl-cross.tgz -O - | \
sudo tar xz -C /opt/mipsel-linux-musl --strip-components=1
Either way, add to PATH and verify:
export PATH="/opt/mipsel-linux-musl/bin:$PATH"
echo 'export PATH="/opt/mipsel-linux-musl/bin:$PATH"' >> ~/.bashrc
mipsel-linux-musl-gcc -dumpmachine
# expected output: mipsel-linux-musl
3. Kernel headers
The FiiO M3K uses the same Ingenic X1000E SoC as the H2, so its GPL kernel tree is the canonical headers source — no reverse-engineering from Rockbox needed. See HEADERS.md for mirror URLs and the XBurst BSP fallback path.
sudo mkdir -p /opt/fiio-m3k-linux
sudo tar xzf fiio_m3k_kernel_*.tar.gz \
-C /opt/fiio-m3k-linux --strip-components=1
export KERNEL_HEADERS=/opt/fiio-m3k-linux
echo 'export KERNEL_HEADERS=/opt/fiio-m3k-linux' >> ~/.bashrc
make headers-check
# expected output: [OK] kernel headers root: /opt/fiio-m3k-linux
4. Build
git clone <your-repo-url> h2-workspace
cd h2-workspace
./build.sh
The build script runs eight phases in sequence:
| Phase | What it does |
|---|---|
| 0–1 | Verifies host deps, toolchain, and kernel headers |
| 2 | Workspace integrity check (all modules + headers + scripts present) |
| 3–4 | Creates overlay/ tree, fixes permissions |
| 5 | Clones LVGL v8.3.11, builds liblvgl.so, h2_test, all modules, mapper |
| 6 | Builds liborebolt.a, regenerates 150-payload HID matrix |
| 7 | Validates all artifacts are MIPS LE ELF; checks bitchat AGPL marker |
| 8 | (only with --deploy) Copies everything to SD card |
5. Verify the build
[OK] OREBOLT OS v1.7 BUILD COMPLETE
Artifacts you should see on disk:
| Artifact | Path | Notes |
|---|---|---|
liblvgl.so |
overlay/usr/lib/ |
LVGL v8.3.11 shared library (MIT) |
h2_test |
overlay/usr/bin/ |
Master launcher |
retro_input_mapper |
overlay/usr/bin/ |
Gamepad input mapper daemon |
17 *.mod files |
overlay/apps/ |
16 GPL modules + 1 AGPL bitchat |
liborebolt.a |
./ |
Hardware library static archive |
150 .dd payloads |
overlay/data/payloads/{linux,macos,windows}/ |
HID macro matrix |
Confirm a binary is actually MIPS, not accidentally built with host GCC:
file overlay/usr/bin/h2_test
# expected: ELF 32-bit LSB executable, MIPS, MIPS32 version 1 ...
6. Deploy to SD card
# Identify the card (be sure — /dev/sda is usually your system disk)
lsblk -o NAME,SIZE,TYPE,MOUNTPOINT
# Format: single-partition FAT32
sudo umount /dev/sdX1 2>/dev/null || true
sudo parted /dev/sdX --script mklabel msdos
sudo parted /dev/sdX --script mkpart primary fat32 1MiB 100%
sudo parted /dev/sdX --script set 1 boot on
sudo mkfs.vfat -F 32 -n OREBOLT /dev/sdX1
# Mount and deploy
sudo mkdir -p /mnt/h2-sd
sudo mount /dev/sdX1 /mnt/h2-sd
# First deploy: back up stock firmware, then deploy
SD_CARD_MOUNT=/mnt/h2-sd ./build.sh --deploy --backup-stock
# Subsequent deploys (stock backup already exists):
# SD_CARD_MOUNT=/mnt/h2-sd ./build.sh --deploy
sync && sudo umount /mnt/h2-sd && sudo eject /dev/sdX
Insert the card, power on the H2. The LVGL UI boots with all 17 modules
registered. Init order: S98retro-input → S99broker (starts
h2_test) → bt_input_daemon.sh (BLE).
Troubleshooting
| Symptom | Fix |
|---|---|
[-] Missing toolchain binaries: mipsel-linux-musl-gcc |
export PATH="/opt/mipsel-linux-musl/bin:$PATH" |
[-] CRITICAL: KERNEL_HEADERS not found |
Install FiiO M3K GPL tree (step 3) |
[-] BAD: h2_test -- ELF 64-bit LSB executable, x86-64 |
./build.sh --clean && ./build.sh (host GCC leaked in) |
error: cannot find -lm |
Switch to Rockbox toolchain (step 2, option A) |
fatal: unable to access 'https://github.com/lvgl/lvgl.git' |
Pre-clone LVGL manually (see PREREQUISITES.md section 8) |
[-] bitchat.mod missing AGPL_BITCHAT marker |
If building manually, add -DAGPL_BITCHAT to CFLAGS |
Before deploying bitchat (AGPL obligation)
If you modify the bitchat module and deploy it where other operators will interact with it over the mesh, AGPL v3 section 13 requires you to provide your modified source. Do this before deploying:
# 1. Replace the placeholder URL with your real source / Written Offer
sed -i 's|https://example.invalid/orebolt-bitchat-src|https://your-domain/orebolt-os-bitchat-src|' \
src/modules/mod_bitchat_mesh.c
# 2. Drop in the full AGPL license text
curl -o licenses/AGPL-3.0.txt https://www.gnu.org/licenses/agpl-3.0.txt
# 3. Rebuild
./build.sh --clean && ./build.sh
Full compliance checklist: LICENSE.md section 4.
What to read next
| When you want to... | Read |
|---|---|
| Understand module layout and boot sequence | ARCHITECTURE.md |
| Diagnose a toolchain or headers issue | PREREQUISITES.md section 8 |
| Understand the AGPL/GPL split | LICENSE.md |
| See the full version history | CHANGELOG.md |
| Add a new module | Makefile header comment, steps 1–5 |