dcosnet
/
OreBolt-OS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
OreBolt-OS/ARCHITECTURE.md

10 KiB
Executable File
Raw Permalink Blame History

OreBolt OS v1.7 -- Architecture

1. Target hardware

Component Spec
Device Aigo Eros Q family: HiFiWalker H2, Surfans F20, Phinistec Z6, Agptek H3
SoC Ingenic X1000E (JZ4760 family), MIPS32r2, little-endian, hard-float
Memory 64 MB DDR2 (typical, some revisions 128 MB)
Display 320 x 240 RGB565 LCD (ILI9341-class controller)
Audio DAC ESS ES9018K2M
Headphone amp MAX97220
Storage MicroSD (boot), 8 MB SPI flash (bootloader)
USB USB-C (newer revisions) or Micro-USB (older revisions)
Bluetooth BLE (varies by revision; some have no BT)

SoC note: The H2 and its siblings use the Ingenic X1000E (JZ4760 family). The two SoCs share a peripheral family but differ in clock tree, GPIO banks, and USB PHY -- see HEADERS.md Section 4 for details.

2. Software stack

+----------------------------------------------------------+
|  17 OreBolt OS modules (LVGL UI panels, *.mod)              |
|  vault nettaps deploy studio probe vterm pauto              |
|  extract noise reset retro scalpel rfid glitch              |
|  pwdb proxalarm(unified) bitchat(AGPL)                       |
+----------------------------------------------------------+
|  retro_input_mapper (standalone uinput daemon, hardened)|
+----------------------------------------------------------+
|  liblvgl.so (MIT)         liborebolt.a (GPL-2.0+)        |
|  LVGL v8.3.11 UI          panic_purge, forensics, HID,   |
|                            radio_mux, ui_frame_graphics  |
+----------------------------------------------------------+
|  H2 stock Linux kernel 3.10.14 (Ingenic X1000E BSP)     |
|  + OreBolt OS init scripts (S98retro-input, S99broker,   |
|    bt_input_daemon.sh)                                    |
+----------------------------------------------------------+
|  Ingenic X1000E hardware (MIPS32r2, FPU, LCD, SD, USB,   |
|  SPI flash, BT, audio codec)                             |
+----------------------------------------------------------+

3. Module inventory (17 modules, v1.7)

ID Module License Purpose
0 vault GPL-2.0+ Crypto Security Token Vault (PIN auth, dual USB/BLE identity)
1 nettap GPL-2.0+ USB Virtual Network Tap (time-windowed packet capture)
2 scalpel GPL-2.0+ Acoustic Scalpel Live Sound Synthesizer
3 deploy GPL-2.0+ Flash Storage Manager (statvfs + manual sync)
4 studio GPL-2.0+ UAC2 Mixer Console (4-channel, USB Consumer Control HID)
5 probe GPL-2.0+ I2C Bus Hardware Scanner
6 vterm GPL-2.0+ FreeDOS Emulation Bridge
7 pauto GPL-2.0+ Payload Automation (HID keystroke injector)
8 extract GPL-2.0+ Mass Storage Extractor (recursive /mnt/target_media copy)
9 noise GPL-2.0+ USB Hardware TRNG Stream (getrandom via CDC ACM)
10 system (reset.mod) GPL-2.0+ System Tools: operational purge, Hiby Player restore, reboot. Detects user-installed Rockbox for reboot-to-Rockbox option.
11 retro GPL-2.0+ Universal Retro Game Launcher (17-type ROM database)
12 rfid GPL-2.0+ RFID/NFC reader module (stub)
13 glitch GPL-2.0+ Hardware glitch injector (stub)
14 pwdb GPL-2.0+ Password database (stub)
15 proxalarm GPL-2.0+ Unified proximity alarm / radar. 3-layer architecture: bledsp (BLE + WiFi stub RSSI scanning), proxvec (kinematics + alarm FSM), radar_ui (LVGL canvas radar display). NEXT key cycles RF source (BLE/WIFI).
16 bitchat AGPL-3.0-only Mesh chat networking (stub). Independent C implementation of the BitChat protocol. Not affiliated with, sponsored by, or endorsed by Permissionless Tech, LLC.
-- retro_input_mapper GPL-2.0+ Integrated uinput gamepad daemon (hardened build)

4. Build pipeline

build.sh
  Phase 0  host dep check + KERNEL_HEADERS probe
  Phase 1  toolchain verification (mipsel-linux-musl-*)
  Phase 2  workspace integrity check (17 modules + headers + scripts)
  Phase 3  overlay/ tree creation
  Phase 4  permission fixups on init scripts
  Phase 5  H2 Core v6.5 build (LVGL clone + liblvgl.so + h2_test + 17 modules + mapper)
  Phase 6  OreBolt OS v1.7 build (liborebolt.a + 150-payload matrix)
  Phase 7  artifact verification (MIPS LE ELF check + AGPL marker check)
  Phase 8  optional --deploy [--backup-stock] to SD card

5. Headers sourcing

                  +-----------------------------+
                  | KERNEL_HEADERS env var      |
                  | (default /opt/fiio-m3k-linux)|
                  +--------------+--------------+
                                 |
              +------------------+------------------+
              v                                     v
  +-----------------------+              +------------------------+
  | FiiO M3K GPL kernel   |              | Ingenic XBurst BSP     |
  | (primary, same X1000E)|              | (fallback, raw SDK)    |
  +-----------------------+              +------------------------+
              |
              v
  +-----------------------+
  | Makefiles add -I:     |
  |  include/uapi         |
  |  include              |
  |  arch/mips/include    |
  |  arch/mips/include/   |
  |   asm/mach-jz4760     |
  +-----------------------+
              |
              v
  +-----------------------+
  | Rockbox tree          |
  | (OPTIONAL, bare-metal |
  |  reference only)      |
  +-----------------------+

See HEADERS.md for the full strategy.

6. Licensing tiers

  +-------------------+  +-------------------+  +-------------------+
  | LVGL (MIT)        |  | liborebolt.a      |  | bitchat.mod       |
  |                   |  | (GPL-2.0+)        |  | (AGPL-3.0-only)   |
  | shared lib        |  | static archive    |  | separate .mod     |
  +-------------------+  +-------------------+  +-------------------+
          |                       |                       |
          +----------+------------+                       |
                     v                                    |
          +-------------------+                            |
          | 15 userland .mod  |                            |
          | (GPL-2.0+)        |<--- bitchat links TO ----+
          +-------------------+    them (not vice versa)

The AGPL boundary is the single bitchat.mod binary. bitchat links to liblvgl.so and liborebolt.a; those libraries do not become AGPL just because bitchat links against them. See LICENSE.md Section 4 for the full boundary analysis.

7. Firmware coexistence (SD-card-only)

OreBolt OS and the stock Hiby Player both boot from the FAT32 MicroSD card. The 8 MB SPI flash holds only the bootloader and is never modified by OreBolt OS.

Environment SD card presence Boot method
Hiby Player (stock) Factory files in /usr/bin/ (hiby_player), /etc/, /res/ Stock bootloader loads kernel + stock init
OreBolt OS /apps/*.mod, /usr/bin/h2_test, /usr/lib/liblvgl.so, /etc/init.d/S99broker Stock bootloader loads kernel, S99broker starts h2_test

If a user has separately installed Rockbox on the same SD card (a third-party, user-managed firmware), the System Tools module detects its presence and offers a reboot option. OreBolt OS does not ship, bundle, or install Rockbox. The user installs and manages Rockbox independently.

Switching between Hiby Player and OreBolt OS is a matter of which files are on the SD card. The System Tools module (reset.mod, displayed as "system" in the menu) handles the stock restore. The stock firmware backup is created at deploy time with --backup-stock.

8. Filesystem layout on the device

/
├── usr/
│   ├── bin/
│   │   ├── h2_test                    # OreBolt OS launcher
│   │   ├── retro_input_mapper         # uinput gamepad daemon
│   │   ├── enable_vault_usb.sh        # ConfigFS USB gadget setup
│   │   └── enable_vault_ble.sh        # BT bringup
│   └── lib/
│       └── liblvgl.so                 # LVGL v8.3.11
├── apps/
│   ├── vault.mod
│   ├── nettaps.mod
│   ├── ... (13 GPL modules)
│   └── bitchat.mod                    # AGPL
├── etc/init.d/
│   ├── S98retro-input
│   ├── S99broker
│   └── bt_input_daemon.sh
├── data/
│   ├── payloads/
│   │   ├── linux/01..50.dd            # 50 Linux HID payloads
│   │   ├── macos/51..62.dd            # 12 macOS HID payloads
│   │   ├── windows/01..50.dd          # 50 Windows HID payloads
│   │   ├── lnx_*_profile_*.macro      # 200 Linux macro profiles
│   │   ├── win_*_profile_*.macro      # 200 Windows macro profiles
│   │   └── mac_*_profile_*.macro      # 200 macOS macro profiles
│   ├── vault/
│   │   ├── payloads/Provision.txt     # operator-edited quick-launch list
│   │   ├── syslog.log                 # rotating log
│   │   └── failures.dat               # binary failure log
│   ├── stock_backup/                  # Stock firmware snapshot (--backup-stock)
│   │   ├── usr/bin/                   # Stock binaries (hiby_player)
│   │   ├── etc/                       # Stock init configuration
│   │   ├── res/                       # Stock resources
│   │   └── setting/                   # Stock player settings
│   ├── forensics_bin/
│   ├── roms/                          # Retro game ROM directories
│   │   ├── nes/ snes/ gb/ gbc/ gba/
│   │   ├── genesis/ sms/ gg/
│   │   └── pce/ atari2600/ ngp/
│   └── vterm/freedos/bin/

9. Boot sequence

  1. H2 bootloader (SPI flash) loads kernel from SD card.
  2. Linux boots, mounts rootfs, runs /etc/init.d/rcS.
  3. S98retro-input starts retro_input_mapper.
  4. S99broker starts h2_test with OREBOLT_VERSION=1.7 and OREBOLT_TARGET_SOC=X1000E env vars.
  5. h2_test initializes LVGL via fbdev, registers all 17 modules, and enters the LVGL tick loop.
  6. bt_input_daemon.sh brings up hci0 for BLE pairing.
  7. bitchat.mod advertises its AGPL source URL via the first mesh HELLO.