OreBolt OS

A hackable firmware for the HiFiWalker H2 — a $30 MIPS digital audio player that ships with a Linux userspace, a 320×320 LCD, and 64 MB of RAM.

New here? Jump to QUICKSTART.md for the build-and-deploy walkthrough. This document is the project reference.

There is a particular class of consumer hardware that is cheap enough to be disposable, yet capable enough to run a real operating system with real peripherals. The HiFiWalker H2 sits squarely in that class. Under its rubberized shell is an Ingenic X1000E SoC — a MIPS32r2 hard-float core clocked at ~1.0 GHz, paired with 64 MB of DDR2 and an ESS ES9018K2M DAC that was designed for serious audio. The stock firmware plays music. OreBolt OS replaces it with a modular, LVGL-driven toolkit for hardware interrogation, RF sensing, payload delivery, and forensic extraction — all running on a device that fits in a shirt pocket and boots from a FAT32 MicroSD card.

The entire system is cross-compiled from an Arch Linux host using a mipsel-linux-musl toolchain (the Rockbox prebuilt is recommended). Every user-facing module is a single-position-independent .mod ELF binary that dynamically links against a shared liblvgl.so. A fork/exec broker in the master launcher (h2_test) loads them on demand, which means only one module's code segment lives in RAM at a time — a hard constraint when your whole working set is 64 MB and the kernel already claims its cut.

See CHANGELOG.md for the version history.

---

The H2 hardware family

The HiFiWalker H2 is one of five rebadged devices built on the same PCB — the Aigo Eros Q family. They are interchangeable from a firmware perspective. OreBolt OS and the stock Hiby Player both boot from the FAT32 MicroSD card; the SPI flash bootloader is never modified.

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

All share the X1000E SoC, ESS ES9018K2M DAC, and MAX97220 headphone amp. Multiple hardware revisions exist — some have Micro-USB, newer ones have USB-C. All share the same PCB and run the same OreBolt OS image.

Architecture at a glance

The build pipeline is a single ./build.sh invocation with eight phases: dependency verification, workspace integrity check, overlay tree creation, LVGL compilation, module compilation, hardware library archiving, artifact validation (MIPS ELF + AGPL marker check), and optional SD card deployment. The Makefile is split into a thin Makefile shell that delegates to Makefile.h2-core-v6.2, which knows how to build the core runtime, LVGL, and all modules in the correct dependency order.

At runtime the flow is: init scripts start the retro input mapper daemon (S98retro-input), then the master launcher (S99broker / h2_test), then the BLE input daemon. The launcher presents a scrollable LVGL menu of all registered modules. Selecting one causes the broker to fork() + execv() the corresponding .mod binary from overlay/apps/. When the module exits, control returns to the launcher menu. Only one module runs at a time.

The platform ships three core artifacts besides the modules themselves: liblvgl.so (LVGL v8.3.11, ~200 KB, MIT-licensed upstream), liborebolt.a (a static archive of hardware-level routines linked into every module), and a 150-payload HID macro matrix split across Linux, macOS, and Windows profiles.

Modules

Seventeen modules, each a self-contained .mod binary with its own LVGL screen. They group into four operational categories plus one networking module with a separate license tier.

Offense / payload delivery

These modules exist because the H2's USB port can be reconfigured into arbitrary gadget topologies through ConfigFS. That single capability — presenting the device as whatever USB composite the operator needs — is the foundation of the offense surface.

deploy.mod — Flash storage manager. Calls statvfs("/") to pull total, used, and free bytes from the SD card and renders them as a live storage dashboard. The PLAY button triggers a manual sync() flush. Not exciting on its own, but every operator needs to know how much space is left before dropping a 150-payload macro matrix onto a 2 GB card.

pauto.mod — Payload Automation, the HID keystroke injector. It parses OreBolt's custom macro command language and injects keystrokes through /dev/hidg0, the HID function endpoint exposed by the gadget subsystem. Each .dd payload file encodes an OS-specific key sequence (delay, modifier, scan code triples). The module selects the correct profile (Linux, macOS, or Windows) and plays it back at USB-speed. This is the module that turns the H2 from a music player into a BadUSB-class device.

retro.mod — Retro game launcher. Scans /data/roms/ recursively for ROM files across 11 systems (NES, SNES, Game Boy, Genesis, SMS, GameGear, PCE, Atari 2600, Neo Geo Pocket, and FDS/GBA), auto-detects the target system by file extension, and displays a filterable LVGL picker menu. Selecting a ROM forks the matching emulator binary (fceux, snes9x, gambatte, gpsp, dgen, mednafen, or stella) and monitors it — BACK sends SIGTERM to the emulator child. The companion retro_input_mapper daemon runs at boot via S98retro-input and creates a virtual uinput gamepad that maps the H2's rotary encoder and buttons to standard d-pad + ABXYLR

• Start/Select, complete with a rotary-press axis toggle (vertical U/D vs. horizontal L/R) that auto-reverts after 3 seconds of idle.

glitch.mod — Hardware glitch injector. Drives X1000E GPIO lines to produce timed power and clock glitches against an externally-wired target. The module exposes controls for glitch width, trigger delay, and repeat count on the LVGL UI. It is the most hardware-dependent module in the stack — it requires physical access to the target's power or clock rail and assumes the operator has wired the glitch circuit correctly.

Forensics & extraction

extract.mod — Mass storage extractor. Recursively copies files from /mnt/target_media (a mount point for an attached USB mass storage device) into /data/loot_drop/extracted/. It walks the directory tree, skips symlinks (to avoid following loops into the host filesystem), copies in 4 KB chunks, and displays running file, directory, and byte counts on the LVGL screen. The forensic dispatch engine that selects which .dd payload to run against a detected OS lives in mod_forensics.c within liborebolt.a.

vault.mod — Encrypted credentials and payload vault. Provides PIN-based authentication and stores operator-curated quick-launch lists in Provision.txt. Sensitive payload content is encrypted at rest. The vault is the module you lock down before handing the device to someone else.

probe.mod — I2C bus scanner. Probes /dev/i2c-0 across the full address space (0x03–0x77) using ioctl(I2C_SLAVE) + i2c_smbus_read_byte(). Responding devices are highlighted green on the LVGL display. On the H2 this will typically enumerate the DAC, the audio codec, and any attached I2C peripherals. Five seconds of runtime tells you exactly what is on the bus.

pwdb.mod — Password database with bcrypt and argon2 verification. Stores operator-managed credential entries and supports verifying captured hashes against the local database. The hashing implementations are linked from liborebolt.a and run entirely on the MIPS core — no external crypto library dependency.

Reconnaissance & sensing

This is where the H2's Bluetooth radio and its (future) WiFi capability come into play. The X1000E has an on-die BLE controller, and the recon architecture supports WiFi scanning through nl80211 once a driver is available.

proxalarm.mod — The flagship recon module, built as a single .mod binary with three internal layers to keep the RAM footprint tight on a 64 MB device:

The bledsp layer handles RF scanning. It opens the BLE socket, pulls advertisements, and runs the RSSI values through a rolling-average low-pass filter implemented with MIPS DSP ASE intrinsics (__builtin_mips_q31 mul and shift operations) to smooth out the noise floor. A bledsp_poll_wifi() stub is wired in and ready for future nl80211 integration — when a WiFi driver lands, the same smoothing pipeline handles WiFi RSSI with no architectural change. The NEXT key cycles the RF source between BLE and WiFi.

The proxvec layer is the kinematics engine. It maintains a target table with unique device IDs, tracks per-target state machines (new / tracking / stale / expired), and computes radial velocity from the rate of change in smoothed RSSI over time (delta-distance divided by delta-time). This is not GPS-accurate positioning — it is coarse proximity estimation based on RF signal propagation, but on a device the size of a deck of cards, coarse is what you get and coarse is useful.

The radar_ui layer renders a 320×320 LVGL canvas with a rotating sweep line, four range rings, and color-coded blips for each tracked target. Blip color encodes signal strength (bright green for close, dim red for far), and velocity vectors show whether a target is approaching or receding. When a target crosses the alarm threshold, the display flashes an overlay. The ROTATE knob cycles through four sensitivity presets (−40 to −70 dBm floor), PLAY toggles pause/resume, BACK exits.

One binary, one scan loop, one set of smoothing buffers — the entire proximity sensing pipeline fits in a single module slot.

nettaps.mod — USB virtual network tap. Opens a raw AF_PACKET socket on usb0, captures IP packets, and parses them into a live LVGL console. A configurable time-window coalescer (30 s / 1 min / 2 min / 5 min / 10 min) aggregates packet counts before flushing to disk — important because the H2's SD card has limited write endurance. The flash-safe timed flush is the detail that separates a toy packet sniffer from something you can leave running on actual hardware.

rfid.mod — RFID/NFC reader. Drives an externally-attached reader over UART or SPI, enumerates cards in range, and dumps tag memory contents to the LVGL display. The module itself is straightforward; the complexity lives in the physical layer — which reader board, which antenna, which frequency band (125 kHz LF or 13.56 MHz HF).

Environment & shell

vterm.mod — Virtual terminal with a FreeDOS bridge. Provides a TTY-style shell rendered inside an LVGL text area. Ships a minimal FreeDOS userland under overlay/data/vterm/freedos/bin/ for x86 emulation scenarios. On the H2's MIPS core this is necessarily slow, but it demonstrates that the module system can host an entire foreign userland.

studio.mod — UAC2 Mixer Console. Four-channel mixer (GAME / DISCORD / MIC / MUSIC) with per-channel volume bars. NEXT and PREV cycle the active channel, PLAY toggles hardware mute. Volume adjustments are sent as USB Consumer Control HID commands through /dev/hidg1. The module turns the H2 into a physical audio mixer — plug it into a host, twist the scroll wheel, and the host's volume changes.

noise.mod — True random number generator. Pulls 32-byte entropy blocks from the kernel via getrandom(GRND_RANDOM) and pipes them to the host over CDC ACM serial (/dev/ttyGS0) at 100 Hz. The entropy source is the hardware TRNG on the X1000E, not a software PRNG — the output is suitable for cryptographic seeding.

system.mod (file: reset.mod) — System Tools, inspired by Rockbox's tools menu on the Aigo Eros Q platform. Four-option menu:

• Purge — Operational cleanup. Kills child processes (dosbox, emulators), brings usb0 down, wipes /data/loot_drop/, calls sync(). Does not touch any firmware files.
• Hiby Player — Restores the stock firmware from /data/stock_backup/ (created at deploy time with --backup-stock), removes all OreBolt OS files, and reboots into the original music player.
• Rockbox — If the user has separately installed Rockbox on the SD card, this option reboots the device so Rockbox can load. OreBolt OS does not ship or install Rockbox; the user manages it independently. OreBolt OS files are not removed.
• Reboot — Standard warm reboot.

The Hiby Player and OreBolt OS coexist on the same hardware through SD card file management alone. If the user has installed Rockbox separately, it can also share the SD card.

Networking

bitchat.mod — Mesh chat, and the only module under AGPL-3.0-only. An independent C implementation of the BitChat wire protocol — not affiliated with, sponsored by, or endorsed by Permissionless Tech, LLC. The name is used under nominative fair use (see LICENSE.md section 8). It implements the full BITCHAT_MSG_* message type set, advertises its Written Offer URL on every mesh HELLO via BITCHAT_MSG_LICENSE, and uses mod_radio_input_multiplex (BLE + LoRa + 433 MHz) as its transport layer. The mesh implementation itself lives in mod_bitchat_mesh.c within liborebolt.a, compiled with a mandatory -DAGPL_BITCHAT flag — the build fails without it, enforced in build.sh Phase 7.

Hardware library (liborebolt.a)

A static archive linked into every .mod binary. Source lives under src/modules/. These are the low-level routines that modules call but do not implement themselves.

File	Purpose
mod_core_hid.c	HID descriptor tables shared by pauto.mod and retro.mod
mod_forensics.c	Forensic extraction engine — dispatches .dd payloads by OS profile
mod_panic_purge.c	Software panic purge — zeroes volatile state before hardware purge
mod_panic_hardware_purge.c	Hardware panic purge — GPIO-driven SD power cut and SPI flash WP
mod_radio_input_multiplex.c	Radio input multiplexer (BLE + LoRa + 433 MHz); bitchat transport
mod_ui_frame_graphics.c	RGB565 blitters, double-buffer management, scroll wheel routing
mod_bitchat_mesh.c	BitChat mesh networking (AGPL-3.0-only; -DAGPL_BITCHAT required)

Documentation

Doc	What it covers
QUICKSTART.md	Build and deploy from scratch (~30 min)
PREREQUISITES.md	Host setup, toolchain, kernel headers, SD card prep
HEADERS.md	Kernel headers strategy (FiiO M3K + XBurst BSP fallback)
ARCHITECTURE.md	Module layout, SoC details, build pipeline internals
LICENSE.md	Multi-tier licensing, AGPL boundary analysis, compliance
CHANGELOG.md	Version-to-version diff
BUILD_MANIFEST.txt	Complete file inventory with SHA256
SHA256SUMS	Per-file integrity manifest

License

Multi-tier. Full analysis in LICENSE.md.

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

Modifying and deploying the bitchat module triggers AGPL v3 section 13 — you must make your modified source available to anyone who interacts with your node over the mesh. Replace the BITCHAT_SOURCE_URL placeholder in src/modules/mod_bitchat_mesh.c before deploying.