TAIL OSv0.9.0

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

What runs where in a TailOS robot applicationPeriodic nodes, aperiodic services, device drivers, servers and shell tools are each separate user-space processes. Nodes reach the microkernel through topics and services through requests; the drivers, servers and tools also run on the microkernel, which provides threads, scheduling, memory, IPC and topics.user spacetopicsrequestsperiodic nodessensor, estimator, controlleraperiodic servicesrequest and replydevice driversGPIO, I2C, PWM, stepperserversfile system, terminal, logshell toolstopic, node, param, logviewmicrokernelthreads, scheduling,memory, IPC, topics

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_after bound. 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 with lookup(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.

Next

Generated from doc/robotics_overview_public.md in the TAIL OS repository.