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 -- 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 for the full diff.

---

Quick Start

# 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 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	Start here -- fastest path to a working build	~5 min read
PREREQUISITES.md	Host setup, toolchain, kernel headers, SD card prep (deep reference)	~25 min read
HEADERS.md	Kernel headers sourcing strategy (FiiO M3K + XBurst BSP)	~10 min read
LICENSE.md	Multi-tier licensing (AGPL for bitchat, GPL for everything else)	~10 min read
ARCHITECTURE.md	Module layout, SoC, build pipeline	~8 min read
BUILD_MANIFEST.txt	Complete file inventory with SHA256	reference
CHANGELOG.md	v1.4 -> v1.5 diff	~8 min read
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 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.