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

8.4 KiB
Executable File
Raw Blame History

OreBolt OS v1.6 -- Architecture

1. Target hardware

Component Spec
Device HiFiWalker H2 (and rebadged siblings: Surfans F20, Aigo Eros Q, 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 emulate scalpel rfid glitch              |
|  pwdb proxalarm(unified) bitchat(AGPL)                       |
+----------------------------------------------------------+
|  emulator_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 (S98emulator-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.6)

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 reset GPL-2.0+ System Stack Purge/Reset (3-state machine)
11 emulate 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 (absorbs old radar.mod + wifi.mod). 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.
-- emulator_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.3 build (LVGL clone + liblvgl.so + h2_test + 17 modules + mapper)
  Phase 6  OreBolt OS v1.5 build (liborebolt.a + 150-payload matrix)
  Phase 7  artifact verification (MIPS LE ELF check + AGPL marker check)
  Phase 8  optional --deploy 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. Filesystem layout on the device

/
├── usr/
│   ├── bin/
│   │   ├── h2_test                    # launcher
│   │   ├── emulator_input_mapper      # 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/
│   ├── S98emulator-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 (generated at build)
    │   ├── 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
    ├── forensics_bin/
    └── vterm/freedos/bin/

8. Boot sequence

  1. H2 bootloader (SPI flash) loads kernel from SD card.
  2. Linux boots, mounts rootfs, runs /etc/init.d/rcS.
  3. S98emulator-input starts emulator_input_mapper.
  4. S99broker starts h2_test with OREBOLT_VERSION=1.6 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.