Robot Applications on TailOS: Concepts
TailOS is a microkernel real-time operating system for robots. User programs get the full Rust standard library, and Python runs on the same framework. A robot application is a set of small programs: nodes that run on a fixed period and exchange data on topics, and services that answer requests. This page names the pieces and shows where each one runs. The guides linked at the end show how to write them.
What runs where
Your nodes and services, the drivers, the servers and the tools are all separate user-space processes; the microkernel underneath provides only threads, scheduling, memory, IPC and topics.
The kernel does as little as it can: it creates processes and threads, schedules them by priority, isolates their memory, and carries messages between them. Everything else runs as an ordinary process with its own address space, so a fault in a driver or a server cannot corrupt the kernel or another program.
Two kinds of program
| Periodic node | Aperiodic service | |
|---|---|---|
| Runs | once per declared period: wake, read inputs, compute, publish | once per request: receive, handle, reply exactly once |
| Talks over | topics: many readers, the latest value | requests: one client, one reply |
| You write | one function with a #[periodic] attribute |
a trait, its implementation, and a client call |
| Typical use | sensor drivers, estimators, controllers, actuator commands | device drivers, configuration, anything asked for on demand |
A periodic node is the shape most robot code takes. You declare its period, what it does on an overrun, and what it reads and publishes; the framework owns the loop:
#[periodic(every = "20ms", on_overrun = Skip)]
fn brake(
#[subscribe(SENSOR_RANGE, stale_after = "70ms")] range: Cycle<Range>,
#[publish(CMD_VELOCITY)] command: Out<Twist>,
) {
command.publish(match range.get() {
Some(reading) if reading.range > 0.30 => cruise(),
_ => stop(), // too close, no reading, or a reading too old
});
}
What the framework does for every node:
- Fixed timing. Each release wakes at an absolute time on the period's grid, so the period never drifts. An overrun is detected, handled by the declared policy, and reported.
- Freshness. Each input has a
stale_afterbound. A reading that never arrived and a reading that is too old are the same case,None, so a node cannot act on stale data by accident. - All-or-nothing outputs. What the body publishes goes out when the body returns, in declaration order. A body that panics halfway publishes nothing.
An aperiodic service is a server: a client calls it and blocks until the one reply arrives. Drivers are services, and so is anything an application asks for on demand.
Topics and lanes
A topic is a named stream of fixed-size values, with any number of readers. Each reader gets the latest value; a slow reader misses values but never blocks the writer. A topic is defined once, in a crate both ends import, with its name, its payload type and its lane:
pub const SENSOR_RANGE: Topic<Range, SafeLane> = Topic::new("sensor/range");
pub const CMD_VELOCITY: Topic<Twist, KernelLane> = Topic::new("cmd/velocity");
| Lane | How a value travels | Safety class |
|---|---|---|
KernelLane |
copied in and out by the kernel, one system call per message; payloads up to 4 KiB | safety |
SafeLane |
zero-copy through shared memory; the kernel lets the writer change only the slot it is filling, so a published value cannot be corrupted | safety |
FastLane |
zero-copy through shared memory, no system call per message, no such protection | quality-managed |
Changing a topic's lane is a one-word edit to its definition; no node changes. A node
declared safety refuses to build if it reads or publishes a topic on a quality-managed
lane.
Both ends of a topic must agree on the payload. Every payload type has a layout identity computed from its fields, and an end whose payload differs in size or layout is refused when it opens the topic, with a message that says why.
Payloads and frames
- Standard payloads (
robot_messages):Vector3,Point,Quaternion,Pose,Twist,Range,Imu,Odometry, in SI units; sensor and odometry records carry a time stamp in nanoseconds since boot. Rust and Python read the same definitions, and the Python module is generated from the Rust structs by the build. - Your own payloads are plain structs that derive
WirePlain, which proves at build time that they have no padding and computes their layout identity. - Coordinate frames (
frames): a robot's frames are declared once as a tree, checked at build time, and looked up withlookup(target, source), with no allocation and a bounded cost. A moving link takes its value from a node input, so it goes stale like any other input.
Built into every node
| Feature | What you get |
|---|---|
| Run-time parameters | declare a gain with a default and a range; change it from the shell with param set while the node runs |
| Actions | a long-running goal (drive to a point, home an axis) with feedback, cancel and a dead-man lease |
| Release journal | every node with an output journals each release, so a recording can replay it |
| Description | every node announces its period, inputs, outputs and parameters, which node info prints |
Record, replay, inspect
tsh> topic record -o /recordings/run7.mcap & record every topic
tsh> lidar & brake & drive & run the robot
tsh> brake --replay /recordings/run7.mcap re-run one node against what it saw
replay: brake life 1: 2104 releases, 2103 compared, identical
Recordings are standard MCAP files. Replaying a node runs its body once per recorded release, with exactly the inputs, parameters and timing that release had, and compares every output. An edited node replays too, which answers "what would it have done?".
Languages
| Rust | Python | |
|---|---|---|
| Periodic nodes | #[periodic] attribute |
@periodic decorator |
| Parameters, actions, record and replay | yes | yes |
| Coordinate frames | yes | not yet |
| Services and device classes | yes | no |
A Rust node and a Python node exchange topics with each other; both use the same transports.
Current limits
- TailOS targets the Raspberry Pi 3. The robotics framework is tested on the QEMU emulation of that board. The Python interpreter is not yet on the board image.
- No process supervisor ships: a node that exits is not restarted.
- Run-time parameter values last for the node's life; a restart starts at the defaults.