166 lines
10 KiB
Markdown
Executable File
166 lines
10 KiB
Markdown
Executable File
# 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.
|