# 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.