186 lines
7.8 KiB
Markdown
186 lines
7.8 KiB
Markdown
# 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](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](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.
|