tritium-edge — Embodied Runtime + Fleet Server

Embodied runtime — firmware, HAL modules, and fleet management — that turns hardware (sensor boards, robotics processors, autonomous vehicles, mesh radios) into independent machines the simulator can also pretend to be. The first supported family is Waveshare ESP32-S3 touchscreen boards. Each device runs a shell with apps, HAL modules for sensors and networking, and a web dashboard. The fleet server handles provisioning and OTA updates.

New here? Two paths:

• System-wide (clone, run Command Center, play): tritium/docs/QUICKSTART.md
• Just edge (PlatformIO, flash a board, see it heartbeat): docs/QUICKSTART.md

The public SDK that lets a closed-source cognition stack drive these machines is at tritium-sc/docs/EMBODIMENTS.md. Glossary: tritium/docs/GLOSSARY.md.

Architecture

flowchart TB
    subgraph Device["ESP32-S3 Device"]
        main["main.cpp — entry point"]
        shell["LVGL Shell — launcher, settings, lock screen"]
        hals["HAL modules — WiFi, BLE, mesh, sensors, OTA..."]
        apps["Apps — starfield, camera, system, diag..."]
        web["Embedded web dashboard"]
    end

    subgraph Fleet["Fleet Server :8080"]
        fastapi["FastAPI — provisioning, OTA, monitoring"]
    end

    Device <-->|MQTT| sc[Command Center :8000]
    Device <-->|REST| Fleet
    Device <-->|ESP-NOW| other[Other ESP32 devices]

    style Device fill:#0e1a2b,stroke:#05ffa1,color:#05ffa1
    style Fleet fill:#0e1a2b,stroke:#00f0ff,color:#00f0ff

Loading

Supported boards

All boards: ESP32-S3 dual-core 240 MHz, 16 MB flash, 8 MB PSRAM, WiFi, BLE 5, USB-C.

Board	Resolution	Display	Status
ESP32-S3-Touch-LCD-4.3C-BOX	800x480	ST7262 RGB	Primary dev board — build-verified, WiFi tested
ESP32-S3-Touch-AMOLED-2.41-B	450x600	RM690B0 QSPI	Compiles, display verified in earlier waves
ESP32-S3-Touch-LCD-3.5B-C	320x480	AXS15231B QSPI	Compiles, display+camera verified in earlier waves
ESP32-S3-Touch-LCD-3.49	172x640	AXS15231B QSPI	Compiles, display verified in earlier waves
ESP32-S3-AMOLED-1.91-M	240x536	RM67162 QSPI	Compiles, not recently tested on hardware
ESP32-S3-Touch-AMOLED-1.8	368x448	SH8601Z QSPI	Compiles only

Adding a new board means writing a pin header, a display config, and a PlatformIO environment. See docs/ADDING_A_BOARD.md.

Quick start

# Install PlatformIO and udev rules
./scripts/setup.sh

# Build and flash
make build BOARD=touch-lcd-35bc
make flash BOARD=touch-lcd-35bc

# Serial monitor
make monitor

# List available boards and apps
make list-boards
make list-apps

Directory structure

tritium-edge/
├── src/              Entry point (main.cpp)
├── include/          Shared headers + per-board pin definitions
│   └── boards/       One .h per board (pin maps)
├── lib/              HAL modules + display drivers + OS services
│   ├── display/      esp_lcd driver, per-board configs
│   ├── hal_wifi/     Multi-network WiFi with NVS
│   ├── hal_mqtt/     MQTT client (heartbeat, sighting, cmd)
│   ├── hal_ble*/     BLE scanner, features, history (blocked by coex issue)
│   ├── hal_espnow/   ESP-NOW mesh networking
│   ├── hal_ota/      Over-the-air firmware updates
│   ├── hal_webserver/ REST API + WebSocket
│   ├── os_shell/     LVGL window manager, launcher, lock screen
│   └── ...           acoustic, camera, IMU, NTP, power, etc.
├── apps/             Application modules + template
│   ├── starfield/    Default screensaver demo
│   ├── camera/       OV5640 preview (3.5B-C only)
│   ├── system/       Hardware dashboard
│   └── ...           diag, effects, ota, test, ui_demo, wifi_setup
├── server/           Fleet management server (FastAPI :8080)
├── web/              Embedded web pages (dashboard, OTA, mesh, terminal)
├── scripts/          Build, flash, monitor scripts
├── platformio.ini    Build environments (one per board+app combo)
└── Makefile          Build automation

How it grows

The HAL layer is the extensibility point. Each hal_* module is a self-contained capability — WiFi scanning, BLE fingerprinting, acoustic detection, mesh networking, etc. Adding a new sensor means writing a new HAL module that publishes to the same MQTT topics the Command Center already subscribes to.

Apps are display-facing programs (starfield, system dashboard, camera preview). Adding a new app means implementing the App interface with setup() and loop(). See docs/ADDING_AN_APP.md.

Where to go next

• CLAUDE.md — Code conventions, pitfalls, build commands
• docs/ARCHITECTURE.md — System design
• docs/GETTING_STARTED.md — First build guide
• docs/TRITIUM-OS-VISION.md — OS roadmap
• lib/README.md — HAL module details

Known limitations

• BLE disabled — WiFi/BLE coexistence issue on ESP32-S3. BLE code exists but runs stubs.
• NimBLE header not found — BLE serial and BLE OTA blocked by build issue.
• Primary dev board only — most work happens on the 43C. Other boards compile but aren't regularly tested.

---

Built on ESP-IDF 5.5.2 | AGPL-3.0 | Copyright 2026 Valpatel Software LLC