187 lines
6.5 KiB
Markdown
187 lines
6.5 KiB
Markdown
# OreBolt OS v1.4 -- Quickstart
|
|
|
|
> The fastest path from a fresh Arch Linux host to a deployed H2.
|
|
> For deep dives: [PREREQUISITES.md](PREREQUISITES.md) (host setup),
|
|
> [HEADERS.md](HEADERS.md) (kernel headers), [LICENSE.md](LICENSE.md) (AGPL).
|
|
> Total wall time: ~30 min if toolchain + kernel tree are pre-staged,
|
|
> ~75 min if building the toolchain from source.
|
|
|
|
---
|
|
|
|
## 0. What you need before you start
|
|
|
|
| Item | Where to get it | One-liner |
|
|
|---|---|---|
|
|
| Arch Linux host | any x86_64 Arch install | `pacman -Syu` |
|
|
| `mipsel-linux-musl` toolchain | Rockbox prebuilt tarball (recommended) | see step 2 |
|
|
| FiiO M3K GPL kernel tree | community mirror or FiiO's GPL download | see step 3 |
|
|
| MicroSD card (>= 2 GB) | any | -- |
|
|
|
|
> **Not on Arch?** Stop. The build pipeline is validated against Arch only.
|
|
> Other distros will require porting effort. See PREREQUISITES.md §1.
|
|
|
|
---
|
|
|
|
## 1. Host deps (one shot, ~2 min)
|
|
|
|
```bash
|
|
sudo pacman -Syu --needed base-devel git make python3 rsync \
|
|
dosfstools e2fsprogs parted file
|
|
```
|
|
|
|
## 2. Cross toolchain (~5 min if prebuilt, ~45 min if from source)
|
|
|
|
```bash
|
|
# Option A (recommended): Rockbox prebuilt
|
|
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
|
|
|
|
export PATH="/opt/mipsel-linux-musl/bin:$PATH"
|
|
echo 'export PATH="/opt/mipsel-linux-musl/bin:$PATH"' >> ~/.bashrc
|
|
|
|
# Verify
|
|
mipsel-linux-musl-gcc -dumpmachine # must print: mipsel-linux-musl
|
|
```
|
|
|
|
## 3. Kernel headers: FiiO M3K GPL tree (~3 min)
|
|
|
|
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.
|
|
|
|
```bash
|
|
sudo mkdir -p /opt/fiio-m3k-linux
|
|
# Either clone a community mirror, or extract FiiO's official GPL tarball:
|
|
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
|
|
|
|
# Verify
|
|
make headers-check
|
|
# Expected: [OK] kernel headers root: /opt/fiio-m3k-linux
|
|
```
|
|
|
|
> **Header missing from FiiO tree?** Fall back to the Ingenic XBurst BSP.
|
|
> See [HEADERS.md §3](HEADERS.md#3-ingenic-xburst-bsp-fallback).
|
|
|
|
## 4. Clone + build (~10 min)
|
|
|
|
```bash
|
|
git clone <your-repo-url> h2-workspace
|
|
cd h2-workspace
|
|
|
|
./build.sh
|
|
```
|
|
|
|
**What `build.sh` does, in one line each:**
|
|
- Phase 0-1: verifies host deps + toolchain + kernel headers
|
|
- Phase 2: workspace integrity check (16 modules + headers + scripts)
|
|
- Phase 3-4: creates `overlay/` tree, fixes permissions
|
|
- Phase 5: clones LVGL v8.3.11, builds `liblvgl.so`, `h2_test`, 16 modules
|
|
- Phase 6: builds `liborebolt.a`, regenerates 150-payload HID matrix
|
|
- Phase 7: verifies all artifacts are MIPS LE ELF + bitchat AGPL marker
|
|
- Phase 8: (only with `--deploy`) copies everything to SD card
|
|
|
|
## 5. Success looks like
|
|
|
|
```
|
|
[OK] OREBOLT OS v1.4 BUILD COMPLETE
|
|
```
|
|
|
|
With these artifacts on disk:
|
|
|
|
| Artifact | Path | What it is |
|
|
|---|---|---|
|
|
| `liblvgl.so` | `overlay/usr/lib/` | LVGL v8.3.11 shared lib (MIT) |
|
|
| `h2_test` | `overlay/usr/bin/` | Master launcher (registers 16 modules) |
|
|
| `emulator_input_mapper` | `overlay/usr/bin/` | 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 |
|
|
|
|
Verify a binary is actually MIPS:
|
|
|
|
```bash
|
|
file overlay/usr/bin/h2_test
|
|
# Expected: ELF 32-bit LSB executable, MIPS, MIPS32 version 1 ...
|
|
```
|
|
|
|
## 6. Deploy to SD card (~3 min)
|
|
|
|
```bash
|
|
# Identify the SD card (be SURE -- /dev/sda is usually your system disk!)
|
|
lsblk -o NAME,SIZE,TYPE,MOUNTPOINT
|
|
|
|
# Format (single-partition FAT32, simplest layout)
|
|
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
|
|
SD_CARD_MOUNT=/mnt/h2-sd ./build.sh --deploy
|
|
sync && sudo umount /mnt/h2-sd && sudo eject /dev/sdX
|
|
```
|
|
|
|
Pop the card into the H2, power on, and the LVGL UI should boot with
|
|
all 16 modules registered. Init order: `S98emulator-input` ->
|
|
`S99broker` (starts `h2_test`) -> `bt_input_daemon.sh` (BLE).
|
|
|
|
---
|
|
|
|
## Common failure modes (one-line fixes)
|
|
|
|
| Symptom | Fix |
|
|
|---|---|
|
|
| `[-] Missing toolchain binaries: mipsel-linux-musl-gcc` | `export PATH="/opt/mipsel-linux-musl/bin:$PATH"` |
|
|
| `[-] CRITICAL: KERNEL_HEADERS not found at /opt/fiio-m3k-linux` | install the FiiO M3K GPL tree (step 3 above) |
|
|
| `[-] BAD: h2_test -- ELF 64-bit LSB executable, x86-64` | `./build.sh --clean && ./build.sh` (host GCC leaked in) |
|
|
| `error: cannot find -lm` (soft-float vs hard-float) | switch from musl.cc to Rockbox toolchain (PREREQUISITES §2.1) |
|
|
| `fatal: unable to access 'https://github.com/lvgl/lvgl.git'` | pre-clone LVGL manually (PREREQUISITES §8) |
|
|
| `[-] bitchat.mod missing AGPL_BITCHAT marker` | should not happen via `./build.sh`; if building manually, add `-DAGPL_BITCHAT` to CFLAGS |
|
|
|
|
---
|
|
|
|
## Before you deploy bitchat (AGPL obligation)
|
|
|
|
If you ship a modified bitchat module that other operators will interact
|
|
with over the mesh, AGPL v3 §13 requires you to make your modified
|
|
source available. Two things to do **before** deploying:
|
|
|
|
```bash
|
|
# 1. Replace the placeholder URL with your real source repo / 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. Replace the AGPL license stub with the full canonical text
|
|
curl -o licenses/AGPL-3.0.txt https://www.gnu.org/licenses/agpl-3.0.txt
|
|
|
|
# 3. Rebuild
|
|
./build.sh --clean && ./build.sh
|
|
```
|
|
|
|
See [LICENSE.md §4](LICENSE.md#4-operator-obligations-when-modifying-bitchat)
|
|
for the full compliance checklist.
|
|
|
|
---
|
|
|
|
## What to read next
|
|
|
|
| When you want to... | Read |
|
|
|---|---|
|
|
| Understand the module layout and boot sequence | [ARCHITECTURE.md](ARCHITECTURE.md) |
|
|
| Diagnose a tricky toolchain or headers issue | [PREREQUISITES.md §8](PREREQUISITES.md#8-troubleshooting) |
|
|
| Understand why bitchat is AGPL and the rest is GPL | [LICENSE.md](LICENSE.md) |
|
|
| See the full v1.3 -> v1.4 diff | [CHANGELOG.md](CHANGELOG.md) |
|
|
| Add a new module | master `Makefile` header comment, steps 1-5 |
|