Home

Raft

Raft is an opinionated framework for embedded development. It picks up where the Arduino libraries stop and builds on the basic ideas of setup() and loop() to enable even the most complex applications to be built. Raft simplifies:

• Cooperative multi-tasking
• Configuration (smart, JSON-based)
• Networking (WiFi, BLE, Ethernet, serial)
• Communications (REST, WebSockets, MQTT, file transfer, BLE GATT)
• OTA update (unified mechanism over BLE, WiFi or serial)
• Web server (static files, REST API, WebSockets, SSE)
• I2C bus (auto-detection, identification, polling, recovery)
• Modular design (mix and match capabilities; few interdependencies)

Raft builds on Arduino setup() and loop() for configuration and async operations, and is opinionated about Convention over Configuration: most of what every connected device needs is provided by default, and configured with a single JSON document.

Raft currently targets the ESP32 family (ESP32, ESP32-S3, ESP32-C3, ESP32-C6) on top of ESP IDF.

---

1. Getting Started

• Quick Start — scaffold and build your first Raft app with Raft CLI
• Raft Architecture at a Glance — one-page system overview
• Writing Your First SysMod — end-to-end tutorial
• PlatformIO / Arduino Quick Start — using RaftCore as a PlatformIO library

2. Scaffolding and Building

• Raft CLI — the raft command-line tool
• SysTypes — variant-aware build configuration
• Top-Level SysType Configuration — keys at the root of the SysType JSON
• Raft Build Process — what happens between raft build and a flashed binary
• WebUI Build Pipeline — parcel/npm flow that bundles the Web UI into the FS image
• File System — LittleFS / SPIFFS / SD, including data files in the build, runtime API
• Partitions and Flash Layout — partition tables, OTA slot sizing, NVS
• Local Raft Development Libraries — overriding fetched components with local checkouts
• Library Developer Guide — unit tests, examples, raftdevlibs/, linux_unit_tests/ and devdocs/ conventions for working on a Raft library

3. Raft Architecture

• Architecture at a Glance — one-page system overview with diagram
• SysMods — anatomy of a Raft module
• SysManager — the supervisor that owns SysMods
• Configuration — configuration layering and access
• JSON / RaftJson — the JSON parser used everywhere
• Advanced RaftJson — chaining, prefix views, NVS, change callbacks
• Communications Stack Overview — channels, codecs, ProtocolExchange, REST endpoints

4. Built-in SysMods

Networking and connectivity:

• NetworkManager (settings)
• BLEManager (settings)
• WebServer
• MQTTManager

Comms channels:

• SerialConsole, CommandSerial, CommandSocket, CommandFile

Files, logging and updates:

• FileManager
• LogManager / Remote Logging
• ESPOTAUpdate

Publishing and state:

• StatePublisher (settings)
• Registering as a Data Source

Devices and buses:

• See section 6 below.

5. Communications and Protocols

• Adding REST API Endpoints — register endpoints from your SysMod
• Adding a Comms Channel — expose a transport as a Raft channel
• Adding an I2C Device Type — plug-and-play support for a new I²C sensor
• Built-in REST Endpoints — endpoints provided by Raft core/SysMods
• Subscription / publish endpoints (see RaftSysModAPI)
• Comms Channels — channel registration, transports, message flow
• ProtocolExchange — the dispatch hub for non-HTTP requests
• RICREST Protocol — wire formats used over BLE, serial and sockets
• Real-Time Streams — open-ended RICREST streams for low-latency bidirectional data
• File Download Protocol (OKTO)
• OTA Update Flow — end-to-end view of HTTP-direct + file-stream firmware updates
• File upload — see FileManager SysMod (fileupload)
• OTA update — see ESPOTAUpdate SysMod

6. Devices and Buses

• DeviceManager (settings, REST API)
• Device Factory and Classes
• Device Type Record Format
• Adding an I2C Device Type — step-by-step tutorial
• Device Data Publishing
• Data Logger
• I2C:
  • I2C Bus
  • I2C Device Scanning
  • I2C Device Identification and Polling
• MotorControl:
  • Overview
  • Configuration
  • Commands

7. Helper Classes and Utilities

• Helper Classes Index — RingBuffer, ThreadSafeQueue, ExpressionEval, NumericalFilters, DebounceButton, MiniHDLC, NamedValueProvider, SupervisorStats, ConfigPinMap, StatusIndicator, DNSResolver, ArPreferences, libb64
• LEDPixels (JSON config)

8. Reference

• Built-in REST endpoint list
• SysMod settings index
• Full API list
• SysManager settings

9. Operations and Tooling

• Remote Logging — raft debug and the RaftRemote log destination
• Raft CLI — flash, monitor, OTA, debug

---

Repository map

The Raft framework is split across several repositories:

Repo	Contents
RaftCore	Framework core: SysManager, SysMod base, comms stack, configuration, helper classes
RaftSysMods	Built-in SysMods: BLE, Network, MQTT, FileManager, LogManager, OTA, comms channels
RaftI2C	I2C bus driver, device scanning, identification, polling
RaftWebServer	HTTP / WebSocket / SSE web server with REST, static-file and upload handlers

Each repo also has a devdocs/ folder with internal design notes that may be promoted into this wiki over time.