# OreBolt OS v1.7 -- 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 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 | reset | GPL-2.0+ | System Stack Purge/Reset (3-state machine) |
| 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 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. Filesystem layout on the device

```
/
├── usr/
│   ├── bin/
│   │   ├── h2_test                    # launcher
│   │   ├── retro_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/
│   ├── 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 (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. `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.