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