196 lines
6.3 KiB
Markdown
Executable File
196 lines
6.3 KiB
Markdown
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](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
|
||
|
||
```bash
|
||
sudo pacman -Syu --needed base-devel git make python3 rsync \
|
||
dosfstools e2fsprogs parted file
|
||
```
|
||
|
||
## 2. Cross toolchain
|
||
|
||
Option A — Rockbox prebuilt (recommended, ~5 min):
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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](HEADERS.md) for mirror URLs and the XBurst BSP
|
||
fallback path.
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
file overlay/usr/bin/h2_test
|
||
# expected: ELF 32-bit LSB executable, MIPS, MIPS32 version 1 ...
|
||
```
|
||
|
||
## 6. Deploy to SD card
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
# 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](LICENSE.md#4-operator-obligations-when-modifying-bitchat).
|
||
|
||
---
|
||
|
||
## What to read next
|
||
|
||
| When you want to... | Read |
|
||
|---|---|
|
||
| Understand module layout and boot sequence | [ARCHITECTURE.md](ARCHITECTURE.md) |
|
||
| Diagnose a toolchain or headers issue | [PREREQUISITES.md section 8](PREREQUISITES.md#8-troubleshooting) |
|
||
| Understand the AGPL/GPL split | [LICENSE.md](LICENSE.md) |
|
||
| See the full version history | [CHANGELOG.md](CHANGELOG.md) |
|
||
| Add a new module | `Makefile` header comment, steps 1–5 | |