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

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, and keeping file system work off the main loop (the file system worker, flash write stalls, write pacing)
• 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; keeping the main loop short and slow SysMod reporting
• 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, WiFi troubleshooting)
• 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) — downloads, and uploads (ufStart)
• File transfers over RICREST — upload and download message flow as clients see it
• OTA Update Flow — end-to-end view of HTTP-direct + file-stream firmware updates
• File upload over HTTP — 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
• Selecting Device Types — one file per record, DeviceTypeSources.json
• 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
• Camera (RaftCamera) — JPEG captures to flash or SD, interval captures, published frames

7. ROS 2 (RaftROS)

• RaftROS — a Raft application as a native ROS 2 node: auto-published device topics, services, parameters, /api/ros
• RaftROS Serial Link — the Zenoh session over the USB cable, switched on and off at run time
• Console Port Sharing — RaftConsolePort, how a binary link takes the console's port

8. Helper Classes and Utilities

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

9. Reference

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

10. Operations and Tooling

• Remote Logging — raft debug and the RaftRemote log destination
• Raft CLI — flash, monitor, OTA, debug, and files and device type records on a running device over HTTP, WebSocket, serial or BLE
• Raft Web Apps — the Device Types app and the Raft Flasher, in the browser with nothing to install

---

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
RaftROS	ROS 2 node SysMod (Zenoh, RTPS), device auto-publishing, services, parameters
RaftCamera	Camera SysMod (esp32-camera): still captures, interval captures, published frames
RaftCLI	The raft command-line tool: scaffold, build, flash, monitor, OTA, and device files and type records

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

Licences

The Raft libraries are MIT licensed. RaftCore also contains some third-party code and device type records with settings from third-party drivers: its THIRD_PARTY_NOTICES.md lists them with their licences, and the notices a product built with Raft should include in its documentation (with those of ESP-IDF and the other libraries it uses).