# OreBolt OS v1.5

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 19 LVGL UI
modules, a hardware panic-purge subsystem, a 150-payload HID macro
matrix, a BLE proximity alarm, 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.5** restores all 12 original module implementations from the v1.3
> upstream source set, adds the scalpel audio synthesizer, upgrades vault
> to full PIN auth and studio to a UAC2 mixer console, integrates the
> emulator input mapper with hardened build flags, and rebrands the
> payload injector module from "ducky" to "pauto" (Payload Automation).
> v1.6 adds the proxalarm BLE proximity alarm (3-layer architecture).
> See [CHANGELOG.md](CHANGELOG.md) for the full diff.

---

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

### Core platform

| Component | Description | License |
|---|---|---|
| `h2_test` | Master launcher (LVGL UI, registers all 19 modules, fork/exec broker) | 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` | Integrated uinput gamepad daemon (hardened build, ROM dirs) | 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 (19)

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` | Flash storage manager.  Displays total/used/free storage statistics via statvfs("/"), manual sync() via PLAY button. | GPL-2.0-or-later |
| `pauto.mod` | Payload Automation -- HID keystroke injector.  Parses OreBolt macro command language, injects keystrokes via `/dev/hidg0`. | 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` | Mass storage extractor.  Recursively copies files from /mnt/target_media to /data/loot_drop/extracted/, skips symlinks, 4KB chunk copy, displays file/dir/byte counts. | 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` | I2C bus hardware scanner.  Probes /dev/i2c-0 address space 0x03-0x77, displays responding devices with green highlighting. | 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 |
|---|---|---|
| `proxalarm.mod` | BLE proximity alarm (tripwire detector).  3-layer architecture: **bledsp** (BLE scanning + RSSI DSP smoothing), **proxvec** (kinematics engine with per-target state machine and velocity tracking), **radar_ui** (LVGL canvas radar display with sweep animation, range rings, color-coded blips, and flashing alarm overlay).  Falls back to simulation mode when no BT hardware is present.  ROTATE cycles sensitivity (4 presets: -40 to -70 dBm), PLAY pauses/resumes scanning, BACK exits.  Future: WiFi RSSI source stub ready. | GPL-2.0-or-later |
| `nettaps.mod` | USB virtual network tap.  Selectable time-window coalescer (30s/1m/2m/5m/10m), raw AF_PACKET capture on usb0, IP packet parsing, live LVGL console, flash-safe timed disk flush. | 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` | UAC2 Mixer Console.  4-channel mixer (GAME/DISCORD/MIC/MUSIC) with per-channel volume bars, NEXT/PREV channel switching, PLAY toggles hardware mute.  Sends USB Consumer Control HID commands via `/dev/hidg1`. | GPL-2.0-or-later |
| `noise.mod` | USB hardware TRNG stream.  Generates 32-byte true entropy blocks via getrandom(GRND_RANDOM), pipes to host over CDC ACM serial (/dev/ttyGS0) at 100Hz. | 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.  Independent C implementation of the BitChat protocol -- not affiliated with, sponsored by, or endorsed by Permissionless Tech, LLC.  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, nominative fair use rationale, 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 `pauto.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) | Kernel headers sourcing strategy (FiiO M3K + XBurst BSP) | ~10 min read |
| [LICENSE.md](LICENSE.md) | 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.4 -> v1.5 diff | ~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.