OreBolt-OS/README.md

# 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

### Core platform

| Component | Description | License |
|---|---|---|
| `h2_test` | Master launcher (LVGL UI, registers all 16 modules, runs the input dispatch loop) | GPL-2.0-or-later |
| `liblvgl.so` | LVGL v8.3.11 shared library (~200 KB, framebuffer + evdev backend) | MIT |
| `liborebolt.a` | Hardware library static archive (panic purge, forensics engine, HID core, radio mux, UI frame blitters) | GPL-2.0-or-later |
| `emulator_input_mapper` | Input mapper daemon (scroll wheel + buttons -> HID emulator events) | GPL-2.0-or-later |
| 3 init scripts | `S98emulator-input`, `S99broker`, `bt_input_daemon.sh` | GPL-2.0-or-later |
| 150 `.dd` payloads | HID macro matrix (50 Linux + 50 macOS + 50 Windows recovery routines) | GPL-2.0-or-later |

### Userland modules (16)

Every module is a single `.mod` binary in `overlay/apps/`, dynamically linked
against `liblvgl.so`.  Each registers with the launcher via
`h2_ui_register_module()` and renders its own LVGL screen.

#### Offense / payload delivery

| Module | Purpose | License |
|---|---|---|
| `deploy.mod` | Payload deploy and HID macro launcher.  Reads `Provision.txt` and dispatches `.dd`/`.macro` payloads to the active USB emulator endpoint. | GPL-2.0-or-later |
| `ducky.mod` | USB Rubber Ducky payload engine.  Parses DuckyScript, injects keystrokes via `mod_core_hid`. | GPL-2.0-or-later |
| `emulate.mod` | USB emulator -- presents the H2 to a host as a composite USB device (HID keyboard + consumer control + mass storage + CDC ACM + UAC2 audio) via the ConfigFS gadget at `/sys/kernel/config/usb_gadget/wh_tool`. | GPL-2.0-or-later |
| `glitch.mod` | Hardware glitch injector.  Drives X1000E GPIO lines to produce timed power/clock glitches on a target device. | GPL-2.0-or-later |

#### Forensics & extraction

| Module | Purpose | License |
|---|---|---|
| `extract.mod` | Forensic extraction profiles UI.  Operator-facing launcher that hands off to `mod_forensics` for OS-profile-aware payload dispatch (Linux/macOS/Windows). | GPL-2.0-or-later |
| `vault.mod` | Encrypted credentials & payload vault.  Stores operator-curated quick-launch lists (`Provision.txt`) and manages at-rest encryption for sensitive payload content. | GPL-2.0-or-later |
| `probe.mod` | Network and USB probe / enumerator.  Discovers USB devices, scans local network, fingerprints hosts. | GPL-2.0-or-later |
| `pwdb.mod` | Password database with bcrypt/argon2 verify.  Stores operator-managed credentials, supports verification of captured hashes against the local DB. | GPL-2.0-or-later |

#### Reconnaissance & sensing

| Module | Purpose | License |
|---|---|---|
| `nettaps.mod` | Network traffic capture and carving.  Wraps `tcpdump`-style capture into the LVGL UI; scalpel is the file-carving backend. | GPL-2.0-or-later |
| `radar.mod` | Wireless noise radar / survey.  Uses the WiFi adapter in monitor mode to map nearby APs and clients; renders a 320x240 heatmap. | GPL-2.0-or-later |
| `rfid.mod` | RFID/NFC reader module.  Drives an attached reader over UART/SPI to enumerate cards and dump tag memory. | GPL-2.0-or-later |
| `wifi.mod` | WiFi adapter control + monitor mode toggle.  Companion to `radar.mod` and `nettaps.mod` for adapter bring-up and channel selection. | GPL-2.0-or-later |

#### Environment & shell

| Module | Purpose | License |
|---|---|---|
| `vterm.mod` | Virtual terminal with FreeDOS bridge.  Provides a TTY-style shell in the LVGL UI; ships a minimal FreeDOS userland under `overlay/data/vterm/freedos/bin/`. | GPL-2.0-or-later |
| `studio.mod` | On-device script studio / editor.  Small LVGL text editor for writing and tweaking `.macro` payload files without a host PC. | GPL-2.0-or-later |
| `noise.mod` | Audio/RF noise generator.  Drives the DAC + radio hardware to produce calibrated noise for testing or jamming-adjacent scenarios. | GPL-2.0-or-later |
| `reset.mod` | Factory reset and purge coordinator.  Operator-facing UI that invokes `mod_panic_purge` and `mod_panic_hardware_purge` in the correct order for a clean wipe. | GPL-2.0-or-later |

### Networking (AGPL)

| Module | Purpose | License |
|---|---|---|
| `bitchat.mod` | Mesh chat networking.  The only OreBolt OS module licensed under AGPL-3.0-only.  Implements the bitchat wire protocol (`BITCHAT_MSG_*` message types), advertises its source-code Written Offer URL on every mesh HELLO via `BITCHAT_MSG_LICENSE`, and uses `mod_radio_input_multiplex` as its transport.  See [LICENSE.md](LICENSE.md) for the AGPL boundary analysis and operator compliance checklist. | **AGPL-3.0-only** |

### Hardware library (`liborebolt.a`)

Static archive linked into every `.mod` binary.  Source under `src/modules/`.

| File | Purpose | License |
|---|---|---|
| `mod_core_hid.c` | Core HID descriptor table shared by `ducky.mod` and `emulate.mod`.  Defines the keyboard + consumer-control HID report descriptors. | GPL-2.0-or-later |
| `mod_forensics.c` | Forensic extraction engine -- dispatches `.dd` payloads by OS profile.  Called by `extract.mod`. | GPL-2.0-or-later |
| `mod_panic_purge.c` | Software panic purge -- zeroes volatile state (RAM caches, temp files, `/data/vault/syslog.log`) before hardware purge runs. | GPL-2.0-or-later |
| `mod_panic_hardware_purge.c` | Hardware panic purge -- cuts SD card slot power and shorts SPI flash WP via X1000E GPIO.  Stubs when `HARDWARE_GPIO=0`, real GPIO when `HARDWARE_GPIO=1`. | GPL-2.0-or-later |
| `mod_radio_input_multiplex.c` | Radio input multiplexer (BLE + LoRa + 433 MHz).  Acts as the transport layer for `bitchat.mod`. | GPL-2.0-or-later |
| `mod_ui_frame_graphics.c` | LVGL frame graphics primitives -- RGB565 blitters, double-buffer management, scroll wheel input routing. | GPL-2.0-or-later |
| `mod_bitchat_mesh.c` | bitchat mesh networking implementation.  Compiled with `-DAGPL_BITCHAT` (build fails if this define is missing -- see `build.sh` Phase 7). | **AGPL-3.0-only** |

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