Architecture

A RosieOS cell is a small set of processes around one controller. The real-time core, rosie-rt-core, owns the drives. The Go adapter rt-control is the only public way to command it. Every client, whether the offline programming app, a pendant, a motion server or your own code, goes through rt-control and needs its lease to move anything.

Processes#

Ports, socket paths and environment variables are all listed in Ports, sockets and environment.

Public and private interfaces#

• Public: rt-control. This is HTTP/JSON over the Unix socket control.sock, with jog datagrams on jog.sock in the same directory. With --remote-listen it also serves the same API over mutual TLS on TCP, plus a WebSocket jog lane. Deployed cells pin that listener to 127.0.0.1:8443. The contract is rt-core/protocol/application-v1.schema.json, and the Go, C++ and TypeScript clients are generated from it. See rt-control HTTP API.
• Private: native IPC. rt-control talks to the core over a Unix socket plus shared-memory rings and a fast-control region. The layout is specified in rt-core/protocol/control.json and can change between releases. Never program against it.
• Service APIs. The OLP server, the weld planner and the dense daemon each have their own interface. They are clients of rt-control, not alternatives to it.

When installed with the host units, rosie-rt-core runs as user rosie-rt and rt-control as rosie-ctl. The public sockets live in /run/rosie-rt-core/public/, with symlinks at /run/rosie-rt-core/control.sock and /run/rosie-rt-core/jog.sock.

How motion reaches the drives#

There are three ways to move the robot. Each ends at the same motion start gate in the core. See the safety model.

Jog#

A jog is a stream of velocity updates, each with its own deadline. The client opens a jog generation with begin_jog, then sends 224-byte datagrams on jog.sock, or WebSocket frames on a remote cell. When the updates stop, the core ramps the axis to a hold.

Point-list moves#

A client can upload a short list of timed points with prepare_trajectory. Positions are in rad or m and times in ns from the plan start. The client then starts it with start_trajectory. OLP uses this for its joint and Cartesian moves. rtctl prepare and rtctl start send the same operations from a file.

Dense weld programs#

A planned weld program travels as an immutable dense trajectory, a .rdt file.

1. The OLP server sends a .weldplan to the weld planner.
2. The planner plans each seam and each connecting move, runs the verifier, and writes a .rdt only if every segment passes.
3. OLP's Load fetches the .rdt by digest from the planner and checks it against the robot and the cell. It then uploads it to rt-control with POST /v1/program (prepare_program).
4. Play sends start_program. rt-core interpolates the samples in the cycle.

The dense daemon offers the same upload-then-play path for other clients: TCP ingest on :8797, with play and stop over NATS under a leader lease. Programs that arrive through it are not re-verified.

See Motion paths and planning and Weld planning and verification.

Identity ties it together#

Several digests keep every process agreeing on which robot it is talking to:

• The robot description (robot_description/robots/<model>/) has a SHA-256 identity over the files its manifest registers.
• A machine config pins that description, and rtctl compile turns it into an immutable configuration_sha256.
• rt-control is started with that digest and a pair binding (pair id and revision). Every acquire must present the same binding.
• The planner stamps the robot and cell identity into each .rdt header. OLP refuses to load a plan made against a different robot or cell.

See Cells, machines and positioners and Robot description and coordinate frames.

Observation#

Anyone with access to the socket can read state without taking control:

• GET /v1/describe, GET /v1/status
• events from /v1/events, or as Server-Sent Events from /v1/events/stream
• binary telemetry batches from /v1/telemetry

On a remote listener, a client certificate is still required. rt-natspublisher republishes status and telemetry to NATS subjects robot/v4/rtcore.<host>.status and robot/v4/rtcore.<host>.telemetry.batch, for displays and archiving. Those subjects carry no command authority.

Maturity#