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

219 lines
10 KiB
Markdown
Executable File
Raw 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](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](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.
Reference in New Issue View Git Blame Copy Permalink