A tiny, Rust-first real-time OS that makes one board — or a hundred — feel teachable.
The AI · Robot · IoT nexus for microcontrollers: explicit contracts, static memory,
deadline discipline, and host-readable diagnostics — small enough to read in an afternoon.
中文名：糙哥RTOS — 面向 AI 机器人、IoT 与智能控制的超轻量嵌入式实时操作系统。 为什么叫“糙哥”？因为好用到没朋友！
no_std · static capacity · deadline-aware · NOBRO_* reports · AI + ROS bridges
NobroRTOS is built for microcontrollers where a servo pulse, an I2C transaction, a radio slot, and a recovery decision all have to coexist inside tight memory and timing budgets. It is not a desktop OS in miniature. It is a small, inspectable control plane for robotics nodes that need to grow from one board to many boards without turning every driver into a private universe.
The project starts with nRF52840-class boards and a deliberately compact kernel surface: manifests, quotas, capability grants, static sample pools, health reports, recovery policy, bounded AI inference contracts, and a service abstraction layer for hardware, communication, and edge intelligence.
Repository: https://github.com/dunknowcoding/NobroRTOS Author: dunknowcoding (YouTube NiusRobotLab) License: Apache-2.0
You need Rust + the embedded target, and a way to flash an nRF52840 (a SEGGER J-Link, or any board with a UF2 bootloader).
rustup target add thumbv7em-none-eabihf
rustup component add llvm-tools-preview
git clone https://github.com/dunknowcoding/NobroRTOS && cd NobroRTOS
# Build + flash + read a real sensor, self-certified, in ONE command:
python tools/nobro_hw_eval.py imuIt builds the IMU demo, flashes the development board, reads the kernel's host-readable report
straight out of RAM, and prints PASS/FAIL. No debug probe? Flash usb_cdc_demo
and just open the board's COM port.
| You are a… | NobroRTOS gives you |
|---|---|
| Beginner / maker | One-command build-flash-verify, an Arduino-style setup()/loop() in C++, and reports that say exactly what failed |
| Embedded engineer | no_std, no heap, static capacity, deadline contracts, capability-scoped resources, and the embedded-hal driver ecosystem |
| Robotics / AI builder | Bounded on-device inference + ROS-style bridge contracts kept off the hard-realtime path |
| Researcher | A small, inspectable control plane (manifest → admission → runtime → recovery) behind a stable host ABI you can measure |
| Porting from another RTOS | A thin SAL + C ABI so Zephyr/Embassy/bare-metal drivers and C/C++ logic drop in — see docs/PORTING_FROM.md |
flowchart TB
app["Apps<br/>firmware composition"] --> sal["SAL<br/>bus stream radio actuator sensor crypto"]
app --> kernel["Kernel<br/>manifest admission quota IPC alarms recovery"]
sal --> adapters["Adapters<br/>thin device/library bindings"]
adapters --> hal["HAL<br/>board facts leases timers PWM bus capture"]
kernel --> reports["NOBRO_* Reports<br/>fixed ABI diagnostics"]
hal --> reports
reports --> host["Host Tools<br/>first-fault decoding and review"]
classDef core fill:#111827,stroke:#38bdf8,color:#f8fafc;
classDef edge fill:#0f766e,stroke:#99f6e4,color:#ecfeff;
classDef host fill:#312e81,stroke:#c4b5fd,color:#f5f3ff;
class app,kernel core;
class sal,adapters,hal edge;
class reports,host host;
Module logic — not just config — can be written in Rust, C, or C++
over one extern "C" C ABI. The kernel admits your module and drives init /
poll; your code reaches hardware only through bounded host services. All three are
verified on hardware reading the same IMU.
// C++ (Arduino style) -- bindings/cpp/examples/arduino_imu.cpp
#include "nobro_app.hpp"
void setup() { const uint8_t wake[2] = {0x6B, 0x01}; nobro::I2c::write(0x68, wake, 2); }
void loop() { /* read the IMU via nobro::I2c, then nobro::publish_imu(...) */ }
NOBRO_ARDUINO_MODULE()/* C -- bindings/c/examples/imu_module.c */
#include "nobro_app.h"
int32_t nobro_app_init(void) { uint8_t w[2] = {0x6B, 0x01}; return nobro_i2c_write(0x68, w, 2); }
int32_t nobro_app_poll(void) { /* nobro_i2c_write_read(...) + nobro_publish_imu(...) */ return 0; }Prefer pure config? A JSON contract generates a compiling Rust firmware. Prefer
existing drivers? The embedded-hal adapter runs unmodified embedded-hal device
crates as-is. Authoring details: bindings/c/README.md and
bindings/cpp/README.md.
Robotics firmware often grows in an uncomfortable direction: a board package owns the pins, a driver owns timing, an app owns recovery, a host script owns the truth, and every new board adds another private rule. NobroRTOS pushes those rules into explicit contracts so the system remains teachable, debuggable, and portable.
The design target is a friendly RTOS with strong engineering bones:
| Pillar | What NobroRTOS Does |
|---|---|
| Deadline discipline | Keeps deadline contracts visible in scheduling and module specs |
| Static memory | Uses fixed-capacity pools, reports, mailboxes, alarms, and ledgers |
| Compatibility | Treats board layout, capacity, pins, and boot profile as data |
| Modularity | Keeps apps, adapters, SAL, kernel, HAL, and host contracts separated |
| Diagnostics | Exports stable NOBRO_* symbols for first-fault host decoding |
| Recovery | Routes faults through health counters, event logs, and module-scoped actions |
| Edge AI | Treats local inference, sidecars, cloud APIs, and model metadata as bounded RTOS contracts |
| Robotics bridges | Keeps ROS-style topics, services, actions, and parameters outside hard-realtime hot paths |
NobroRTOS boot visibility is designed as a chain. Host tooling should report the first non-passing stage and stop guessing.
stateDiagram-v2
[*] --> BoardProfile
BoardProfile --> BoardPackage
BoardPackage --> Manifest
Manifest --> AdapterCompatibility
AdapterCompatibility --> Admission
Admission --> Runtime
Runtime --> Running
BoardProfile --> FirstFault: missing/corrupt/fail
BoardPackage --> FirstFault: invalid layout or capacity
Manifest --> FirstFault: invalid contract
AdapterCompatibility --> FirstFault: adapter/profile mismatch
Admission --> FirstFault: graph/quota/capability failure
Runtime --> FirstFault: lifecycle or control-plane failure
| Report Symbol | Purpose |
|---|---|
NOBRO_BOARD_PROFILE_REPORT |
Selected board identity, flash origin, budgets, and critical pins |
NOBRO_BOARD_PACKAGE_REPORT |
Boot layout, flash/RAM regions, capacity, pins, and package validation |
NOBRO_MANIFEST_REPORT |
Module graph, capability, budget, and validation summary |
NOBRO_ADAPTER_COMPAT_REPORT |
Adapter inventory and profile compatibility |
NOBRO_ADMISSION_REPORT |
Startup ordering, quota seeding, and grant construction result |
NOBRO_RUNTIME_REPORT |
Runtime state, mailbox pressure, alarm schedule, quota usage, and event pressure |
The software control plane is the deepest-tested area. Local Rust tests cover manifests, quota accounting, capability grants, runtime disable paths, mailbox cleanup, alarm cleanup, watchdog cleanup, degraded-mode reports, board-package validation, boot assembly, host-readable diagnostics, and Python simulators for quota, degraded-mode, scheduler, event-log, recovery, sensor, actuator, combined runtime-drill flows, and safely materialized plus validated contract-first project templates with VS Code task metadata and Python board bridge onboarding.
That control plane is now verified on real hardware (nRF52840 + an IMU),
and module logic can be authored in Rust, C, or C++ over one kernel and one
extern "C" C ABI - all three providers admitted by the kernel and reading a sensor
end to end on the development board (see bindings/c/README.md). On-hardware results: the deadline
scheduler holds 2 us jitter / 0 misses, the EGU->PPI->CAPTURE path 1 us
latency, and usb_cdc_demo streams diagnostics over USB serial so probe-less
boards self-verify by opening a COM port.
mindmap
root((NobroRTOS))
Kernel
Manifest
Admission
Runtime
Recovery
Reports
HAL
BoardDesc
BoardPackage
Leases
Capture
SAL
Bus
Stream
Radio
Actuator
Sensor
Crypto
AI
Host
JSON Contract
Status Labels
First Faults
Near-term engineering focus:
- connect app assembly patterns to
BootAssemblywithout hiding contracts - keep board profile and board package fixtures aligned
- harden adapter manifests and compatibility examples
- grow AI inference and ROS/micro-ROS bridge contracts without adding heap pressure to realtime paths
- expand host decoding examples for
NOBRO_*reports - keep every hardware-facing feature backed by a software validation gate
NobroRTOS/
|-- core/
| |-- crates/
| | |-- nobro_kernel/ # manifest, admission, runtime, recovery, reports
| | |-- nobro_hal/ # board data, leases, timers, PWM, bus, capture
| | |-- nobro_sal/ # portable service traits
| | `-- nobro_host/ # host report decoders and stable labels
| |-- adapters/ # thin SAL implementations
| |-- apps/ # firmware compositions and evaluation apps
| `-- boards/ # board-facing notes and layout policy
|-- sdk/ # standalone SDK packaging surface
|-- packages/ # Arduino and PlatformIO package surfaces
|-- bindings/ # C, C++, and Python-facing wrappers
|-- tools/ # package builders, validators, generators
|-- docs/ # user, API, architecture, porting, operations
|-- host/ # JSON mirror of the host contract
`-- LICENSE
The Rust crate package names use the nobro-* API prefix, while repository
folders use the nobro_* project prefix.
Every claim below is checked on a real board and self-certifies through a fixed
NOBRO_* report (read over J-Link mem32, or over USB serial for probe-less boards).
| Area | On-board result |
|---|---|
| Real-time scheduler | 2 µs deadline jitter, 0 misses; EGU→PPI→CAPTURE 1 µs latency; 50 Hz PWM |
| Kernel control plane | 13 subsystems — quota · event log · mailbox · KV · alarms · watchdog · degrade · admission · capability · retry · lifecycle · health · sample-pool — all pass |
| SAL admission | AI route policy (local/edge/remote/hybrid + stale-snapshot fallback) · AI invocation preflight — all pass |
| Recovery | watchdog expiry → Degraded/Notify; repeated errors → Recovering/RebootModule |
| Edge AI | bounded AiInferenceSal motion model — IDLE at 99.6% in its 2 ms budget; live over USB-CDC |
| ROS bridge | bounded topic bridge — 2148 messages published + transmitted, 0 dropped, peak depth 1/8 |
| Robot closed loop | IMU → servo pulse → PWM → readback, 1373/1373 readbacks exact |
| Sensors | MPU-9250 over the TWIM HAL (accel+temp+gyro in one burst), incl. 9-pulse stuck-bus recovery |
| Module authoring | the same module admitted + run in Rust, C, and C++ over one extern "C" ABI |
| Driver ecosystem | unmodified embedded-hal I2C drivers run via the adapter |
| Diagnostics | usb_cdc_demo streams reports over USB serial so probe-less boards self-verify on a COM port — verified on the development board (genuine nRF52840) and a clone-silicon nRF52840 board (with a quirky USBD), the latter via a patched nrf-usbd + a self-DFU watchdog |
Reproduce any of these in one command: python tools/nobro_hw_eval.py imu
(also sal, sched); the kernel/AI/ROS/recovery/closed-loop demos flash + read their
report over J-Link.
| Area | Status | Notes |
|---|---|---|
| Kernel manifest model | Present | Fixed-capacity module specs, criticality, capability bits, budgets |
| Startup planning | Present | Graph planner with cycle and capacity checks |
| Runtime control plane | Present | Mailbox, alarms, KV, quotas, watchdog, health, recovery |
| Boot assembly facade | Present | No-heap app startup helper preserving manifest/admission reports |
| Board package validation | Present | Boot layout, flash/RAM region, capacity, critical pins |
| Board package fixtures | Present | Host-reviewable package list for current boot layouts |
| Host ABI contract | Present | JSON contract plus nobro-host layouts and status helpers |
| Adapter compatibility | Present | Descriptor sets, preflight, compatibility report |
| AI adapter contract | Present | Bounded inference request/result contract, route policy, and host-readable model reports |
| AI route policy | Present | Local, edge, remote, and hybrid inference routing with stale snapshot fallback |
| On-device inference (verified) | Present | Bounded AiInferenceSal motion classifier runs on the development board — IDLE at 99.7% confidence in 9 us, inside its 2 ms timeout |
| Multi-board expansion | In progress | Data-first board profiles in core/boards/ (validated by tools/check_board_profiles.py) mirror the BoardDesc/BoardPackage fixtures; the HAL targets nRF52840, and the portable core (kernel/SAL/net/crypto/ML/sensor + drivers) cross-compiles for 6 MCU families - Cortex-M0+/M3/M4F/M33 and RISC-V rv32imc/imac - via tools/check_portability.sh |
| Host tooling UX | In progress | Host, report, boot, and distribution metadata checks are available |
| ROS bridge (verified) | Present | Bounded topic/service/action/parameter contracts + SAL bridge trait; a RosBridgeSal IMU bridge runs on the development board — 2148 messages published + transmitted, 0 dropped, peak depth 1/8 |
| SDK packaging | Validated | Standalone SDK, Arduino, and PlatformIO metadata contract-checked + manifest paths validated (tools/check_sdk_manifest.py) |
| Hardware bring-up | Present | An nRF52840 development board verified: IMU, scheduler (2 us jitter), PPI capture (1 us), PWM, USB-CDC diagnostics |
| Module authoring (Rust / C / C++) | Present | Author module logic over the extern "C" C ABI (nobro_app.h / .hpp); kernel admits + drives it. All three verified on hardware |
| embedded-hal compatibility | Present | embedded_hal::i2c::I2c adapter - unmodified embedded-hal drivers run on NobroRTOS |
| C/C++/Python interfaces | Present | Module authoring in C/C++/Rust; report/AI/ROS C & C++ views; Python builders, decoders, validators, board bridge |
Install Rust and the embedded target:
rustup target add thumbv7em-none-eabihfRun host-side validation from the workspace:
cd core
$env:CARGO_TARGET_DIR = (Resolve-Path '..\_work').Path + '\cargo-target'
cargo test -p nobro-kernel --target x86_64-pc-windows-msvc
cargo test -p nobro-sal --target x86_64-pc-windows-msvc
cargo test -p nobro-host --target x86_64-pc-windows-msvcCheck the embedded build graph:
cd core
$env:CARGO_TARGET_DIR = (Resolve-Path '..\_work').Path + '\cargo-target'
cargo check --workspaceUse _work/ for local build products, downloaded tools, logs, and scratch
artifacts. It is intentionally ignored by Git.
Validate public contracts and package metadata:
python tools/nobro_contract_tool.py check-host-contract
python tools/nobro_contract_tool.py check-distribution-metadata
python tools/nobro_contract_tool.py check-public-headersBoard-facing examples are kept as library and contract references. Lab bring-up notes, one-off wiring combinations, and board-specific evaluation scripts stay outside the public package surface.
| Guide | Use It For |
|---|---|
| User Manual | Setup, app assembly, diagnostics, common workflows |
| API Manual | Public crate contracts and examples |
| System Architecture | Layering, memory discipline, recovery model |
| Porting Guide | Adding boards and preserving board/package contracts |
| Host Contract | NOBRO_* ABI, checksum rules, stage order |
| Operations Guide | Maintenance habits and validation gates |
NobroRTOS borrows carefully from proven embedded systems ideas:
- hardware description as data, inspired by Zephyr devicetree
- static async direction, inspired by Embassy
- isolation through Rust boundaries, inspired by Tock
- bounded mixed-criticality discipline, inspired by seL4 MCS
The project keeps those ideas small enough for approachable robotics firmware.