# OreBolt OS v1.4

A hackable pocket rig for the HiFiWalker H2 digital audio player and its
rebadged siblings (Surfans F20, Aigo Eros Q, Phinistec Z6, Agptek H3).
All of these devices share the same Ingenic **X1000E** (JZ4760 family)
SoC and run a Linux userspace that OreBolt OS extends with 16 LVGL UI
modules, a hardware panic-purge subsystem, a 150-payload HID macro
matrix, and an AGPL-licensed mesh networking layer.

> **New here? Start with [QUICKSTART.md](QUICKSTART.md)** -- the fastest
> path from a fresh Arch Linux host to a deployed H2 (~30 min if
> toolchain + kernel tree are pre-staged).

> **v1.4** is a build-and-licensing cleanup pass over v1.3.  See
> [CHANGELOG.md](CHANGELOG.md) for the full diff.  Highlights:
> - Target SoC corrected (T31 -> X1000E)
> - Kernel headers sourced from the FiiO M3K GPL tree (see [HEADERS.md](HEADERS.md))
> - Module count reconciled to 16 (was inconsistent in v1.3)
> - New **bitchat mesh module** under AGPL-3.0-only (see [LICENSE.md](LICENSE.md))
> - macOS and Windows payload folders now actually exist (v1.3 only had Linux)
> - Project rebranded from "Project Orebolt" to "OreBolt OS"

---

## Quick Start

```bash
# 1. Install host deps (Arch Linux only)
sudo pacman -Syu --needed base-devel git make python3 rsync dosfstools e2fsprogs parted file

# 2. Install the mipsel-linux-musl cross toolchain
#    See PREREQUISITES.md Section 2 (Rockbox toolchain recommended)
export PATH="/opt/mipsel-linux-musl/bin:$PATH"

# 3. v1.4 NEW: install the FiiO M3K GPL kernel tree
#    See HEADERS.md Section 2 for mirror URLs
sudo tar xzf fiio_m3k_kernel_*.tar.gz -C /opt/fiio-m3k-linux --strip-components=1
export KERNEL_HEADERS=/opt/fiio-m3k-linux
make headers-check

# 4. Build
./build.sh

# 5. Deploy to SD card (after formatting -- see PREREQUISITES.md Section 6)
SD_CARD_MOUNT=/mnt/h2-sd ./build.sh --deploy
```

## What ships in v1.4

| Component | Description | License |
|---|---|---|
| `h2_test` | Master launcher (LVGL UI, registers 16 modules) | GPL-2.0-or-later |
| `liblvgl.so` | LVGL v8.3.11 shared library | MIT |
| `liborebolt.a` | Hardware library (panic purge, forensics, HID core, etc.) | GPL-2.0-or-later |
| `emulator_input_mapper` | Input mapper daemon | GPL-2.0-or-later |
| 15 `*.mod` userland modules | vault, nettap, deploy, studio, probe, vterm, radar, ducky, extract, noise, reset, emulate, emulator_input_mapper, rfid, wifi, glitch, pwdb | GPL-2.0-or-later |
| `bitchat.mod` | Mesh networking module | **AGPL-3.0-only** |
| 150 `.dd` payloads | HID macro matrix (50 Linux + 50 macOS + 50 Windows) | GPL-2.0-or-later |
| 3 init scripts | S98emulator-input, S99broker, bt_input_daemon.sh | GPL-2.0-or-later |

## Documentation Index

| Doc | Purpose | Length |
|---|---|---|
| [QUICKSTART.md](QUICKSTART.md) | **Start here** -- fastest path to a working build | ~5 min read |
| [PREREQUISITES.md](PREREQUISITES.md) | Host setup, toolchain, kernel headers, SD card prep (deep reference) | ~25 min read |
| [HEADERS.md](HEADERS.md) | v1.4 NEW -- kernel headers sourcing strategy (FiiO M3K + XBurst BSP) | ~10 min read |
| [LICENSE.md](LICENSE.md) | v1.4 NEW -- multi-tier licensing (AGPL for bitchat, GPL for everything else) | ~10 min read |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Module layout, SoC, build pipeline | ~8 min read |
| [BUILD_MANIFEST.txt](BUILD_MANIFEST.txt) | Complete file inventory with SHA256 | reference |
| [CHANGELOG.md](CHANGELOG.md) | v1.3 -> v1.4 diff + rebrand notes | ~8 min read |
| [SHA256SUMS](SHA256SUMS) | Per-file integrity manifest | reference |

## The H2 hardware family

The H2 is part of a family of nearly-identical rebadged DAPs:

| Brand / Model | Notes |
|---|---|
| HiFiWalker H2 | Most widely known version, rubberized scroll wheel |
| Surfans F20 | Knurled metal scroll wheel; closest competitor |
| Aigo Eros Q | Original design base for the family |
| Phinistec Z6 | Common rebadged version |
| Agptek H3 | Same lineage of budget DAPs |

All share the Ingenic X1000E SoC (MIPS32r2), ESS ES9018K2M DAC, and
MAX97220 headphone amp.  All are Rockbox-compatible.  Multiple hardware
revisions exist; some have Micro-USB, newer ones have USB-C.  Always
check the port type if you are sourcing replacement parts.

## License

Multi-tier.  See [LICENSE.md](LICENSE.md) for the full strategy.

- **bitchat mesh module**: AGPL-3.0-only
- **All other OreBolt OS modules**: GPL-2.0-or-later
- **LVGL / lv_drivers**: MIT (upstream)
- **Documentation**: CC-BY-4.0

If you modify and deploy the bitchat module, you MUST make your modified
source available to anyone who interacts with your modified node over the
mesh, per AGPL v3 §13.  Replace the `BITCHAT_SOURCE_URL` placeholder in
`src/modules/mod_bitchat_mesh.c` before deploying.