LOX · Liquid Oxygen for Embedded Systems
LOX Boot
Firmware updates need validated slots, explicit handoff and rollback-oriented state.
A C99 bootloader core provides A/B state, UART update transport and adapter boundaries.
DevelopmentMITC99
01 / RESET-TO-APPLICATIONRESETLoad dual-copy stateprimary and backup in separate sectors →LISTENUART update windownormal boot resumes on timeout →SELECTChoose active/pending slotboot attempt policy applies →VERIFYCheck image CRC32then platform handoff
Boot decisions are explicit state transitions
loxboot is a synchronous C99 bootloader core with dual-copy boot state, A/B slot management, UART update sessions and adapter-based hardware access. The specification describes this sequence:
The core has zero heap, uses synchronous control flow and delegates flash reads/writes/erases and jump behavior to platform adapters. Its CRC checks detect accidental corruption; they do not authenticate firmware.
02 / A-B STATE AND ROLLBACK
Pending images must earn confirmation
An update targets the inactive slot. A successful commit marks the new image pending. On boot, the selected image is checked and attempt state is updated. The running application must confirm according to the integration flow; crash-loop or unconfirmed-image rules can return to the previous valid slot.
Persistent boot state uses primary and backup copies in distinct flash sectors. Slot A and B must not overlap each other, boot state, or the bootloader image. Both slots use the same configured size.
A/B DECISION
active slot A
↓write + validate inactive B
↓commit B as pending
↓boot B and confirm
missing confirmation → rollback policy selects prior valid image03 / UART FRAME AND SESSION
Transport framing is specified and bounded
| Bytes | Field | Meaning |
|---|---|---|
| 0 | SOF = 0x7E | Frame start |
| 1 | Command | HELLO, WRITE, COMMIT, ABORT, STATUS or REBOOT |
| 2–3 | Payload length | 16-bit little-endian; payload is bounded to 1024 bytes |
| 4… | Payload | Command-specific bytes |
| Tail | CRC16-CCITT | Little-endian; covers command through payload |
A session begins with HELLO. The first valid WRITE erases the target slot; later chunks do not erase again. Bounds are checked, commit requires the declared firmware size to equal bytes written, and the written image CRC is rechecked before commit. The boot flow checks CRC32 again before handoff.
Malformed frames are rejected before exposing command/payload bytes. Pre-session noise is ignored until HELLO; no HELLO within the listen window returns timeout so the caller can continue normal boot.
04 / CORE VS PLATFORM ADAPTERHOST ESP32-S3 STM32 OTHER TARGETS
Source support and board validation are distinct
Core and protocol
The repository's current platform report records 20/20 CTest binaries passing locally, including host logic, UART protocol, known CRC vectors, compile checks and package consumers.
Adapter plus recorded OTA evidence
The report records A/B handoff and pending-image rollback on an ESP32-S3 with ESP-IDF 5.5.1. Disconnect and power-loss behavior remain unverified.
Adapter code present
Adapter source and stub-friendly tests exist. Real HAL integration, flash geometry and hardware power-loss recovery are not verified in the report.
No general platform promise
ARM jump behavior is not verified on hardware. The report lists no adapter for ESP8266 or RISC-V.
05 / RECORDED HARDWARE RUNS
ESP32-S3 OTA evidence with stated gaps
The repository's hardware evidence file records two COM19 runs on 2026-06-11 using ESP-IDF 5.5.1 and an ESP32-S3 with 4 MB flash. The A/B handoff run records 11/11 checks passing: valid upload/commit/reboot, new slot active across the next reboot, and a corrupt update rejected at commit. The rollback run, also recorded as 11/11, disabled auto-confirm and observed the next boot return to the previously valid slot.
The run record does not name the board model. These results are limited to the recorded firmware, hardware configuration and test path. The same docs explicitly say disconnect/power-loss behavior is unverified; STM32 hardware is unavailable in this record.
Hardware run recordPlatform statusUART protocolPower-loss test plan
HOST · CMAKE / CTEST
cmake -S . -B build -DLOXBOOT_BUILD_TESTS=ON \
-DLOXBOOT_BUILD_UART_PORT=ON -DLOXBOOT_BUILD_EXAMPLES=ON
cmake --build build
ctest --test-dir build -C Debug --output-on-failure06 / SECURITY AND FAILURE BOUNDARIES
CRC is integrity detection, not authenticity
- CRC32 detects accidental image corruption. Firmware authenticity/signature verification is not implemented.
- UART retry/resume is not implemented; interrupted transfer recovery must not be assumed.
- Physical disconnect and power-loss behavior are not established by the recorded OTA runs.
- Target memory map, erase sectors, slot geometry and handoff mechanism are platform responsibilities.
- STM32 and ARM hardware jump/flash behavior are not verified in the repository's platform report.
- Successful host tests do not establish every board adapter's electrical behavior.