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

• Target SoC corrected (T31 -> X1000E)
• Kernel headers sourced from the FiiO M3K GPL tree (see HEADERS.md)
• Module count reconciled to 16 (was inconsistent in v1.3)
• New bitchat mesh module under AGPL-3.0-only (see 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

# 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 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	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	v1.4 NEW -- kernel headers sourcing strategy (FiiO M3K + XBurst BSP)	~10 min read
LICENSE.md	v1.4 NEW -- 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.3 -> v1.4 diff + rebrand notes	~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.