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

7.8 KiB
Raw Blame History

OreBolt OS v1.4 -- 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 128 MB DDR2 (typical)
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)

v1.4 correction: v1.3 listed the SoC as "Ingenic T31" (also known as X2000). The actual H2 hardware family uses the 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 the difference and why v1.3 was wrong.

2. Software stack

+----------------------------------------------------------+
|  16 OreBolt OS modules (LVGL UI panels, *.mod)              |
|  vault nettap deploy studio probe vterm radar ducky      |
|  extract noise reset emulate emulator_input_mapper       |
|  rfid wifi glitch pwdb BITCHAT(AGPL)                     |
+----------------------------------------------------------+
|  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 (16 modules, v1.4 reconciled)

ID Module License Purpose
0 vault GPL-2.0+ Encrypted credentials & payload vault
1 nettap GPL-2.0+ Network traffic capture and carving
2 deploy GPL-2.0+ Payload deploy and HID macro launcher
3 studio GPL-2.0+ On-device script studio / editor
4 probe GPL-2.0+ Network and USB probe / enumerator
5 vterm GPL-2.0+ Virtual terminal (FreeDOS bridge)
6 radar GPL-2.0+ Wireless noise radar / survey
7 ducky GPL-2.0+ USB Rubber Ducky payload engine
8 extract GPL-2.0+ Forensic extraction profiles
9 noise GPL-2.0+ Audio/RF noise generator
10 reset GPL-2.0+ Factory reset and purge coordinator
11 emulate GPL-2.0+ USB emulator (HID + mass storage + ACM)
12 emulator_input_mapper GPL-2.0+ Input mapper daemon for the emulator
13 rfid GPL-2.0+ RFID/NFC reader module (v1.4 restored)
14 wifi GPL-2.0+ WiFi adapter control + monitor mode (v1.4 restored)
15 glitch GPL-2.0+ Hardware glitch injector (X1000E GPIO) (v1.4 restored)
16 pwdb GPL-2.0+ Password database + bcrypt/argon2 verify (v1.4 restored)
17 bitchat AGPL-3.0-only Mesh chat networking (v1.4 NEW)

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 (16 modules + headers + scripts)
  Phase 3  overlay/ tree creation
  Phase 4  permission fixups on init scripts
  Phase 5  H2 Core v6.1 build (LVGL clone + liblvgl.so + h2_test + 16 modules)
  Phase 6  OreBolt OS v1.4 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 (v1.4 NEW)

                  +-----------------------------+
                  | 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 (v1.4 NEW)

  +-------------------+  +-------------------+  +-------------------+
  | 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
│   ├── ... (15 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/01..50.dd            # 50 macOS HID payloads (v1.4 NEW)
    │   ├── windows/01..50.dd          # 50 Windows HID payloads (v1.4 NEW)
    │   └── legacy/                    # v1.3 .macro files migrated here
    ├── 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.4 and OREBOLT_TARGET_SOC=X1000E env vars.
  5. h2_test initializes LVGL via fbdev, registers all 16 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.