dcosnet
/
OreBolt-OS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
OreBolt-OS/QUICKSTART.md

6.5 KiB
Raw Blame History

OreBolt OS v1.4 -- Quickstart

The fastest path from a fresh Arch Linux host to a deployed H2. For deep dives: PREREQUISITES.md (host setup), HEADERS.md (kernel headers), 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)

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)

# 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.

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.

4. Clone + build (~10 min)

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:

file overlay/usr/bin/h2_test
# Expected: ELF 32-bit LSB executable, MIPS, MIPS32 version 1 ...

6. Deploy to SD card (~3 min)

# 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:

# 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 for the full compliance checklist.

What to read next

When you want to... Read
Understand the module layout and boot sequence ARCHITECTURE.md
Diagnose a tricky toolchain or headers issue PREREQUISITES.md §8
Understand why bitchat is AGPL and the rest is GPL LICENSE.md
See the full v1.3 -> v1.4 diff CHANGELOG.md
Add a new module master Makefile header comment, steps 1-5