# RosieOS

> Documentation for RosieOS, the open-source software that runs a Rosie welding cell, from the real-time controller to offline programming and the teach pendant.

RosieOS is the software for one Rosie welding cell. It covers the real-time controller, the motion servers, the weld planner, offline programming and the teach pendant. These docs cover how to run it, program it and build on it.

Source code: https://github.com/advanced-metal-research/RosieOS

Every page is also available as Markdown: add `.md` to a page URL (`/docs/concepts/architecture` -> `/docs/concepts/architecture.md`, `/` -> `/index.md`, `/docs/` -> `/docs/index.md`). Links below point at the Markdown versions.

## Robot data

- [For AI agents: robot data and downloads](https://advancedmetalresearch.com/agents.md): URDF, MuJoCo, STEP, meshes and robot.json of every Rosie, how to fetch them (any User-Agent, no login, CORS open)
- [Rosie sim kits index (JSON)](https://advancedmetalresearch.com/assets/sim/index.json): every kit and every file URL

## Overview

- [RosieOS](https://advancedmetalresearch.com/docs/index.md): Documentation for RosieOS, the open-source software that runs a Rosie welding cell, from the real-time controller to offline programming and the teach pendant.

## Get started

- [Install the toolchain](https://advancedmetalresearch.com/docs/get-started/installation.md): The host, compilers and package managers RosieOS needs, which component needs which tool, and how to clone the repository.
- [Quickstart: simulated cell](https://advancedmetalresearch.com/docs/get-started/quickstart.md): Build the real-time core, start a simulated Rosie cell with dev-stack.sh, and jog a joint from the offline programming app, with no hardware.
- [Your first motion (simulation)](https://advancedmetalresearch.com/docs/get-started/first-motion.md): Start the simulated core directly, then acquire control, enable, arm, jog one joint, stop and release from a short Go program using the rt-core SDK.
- [Safety model](https://advancedmetalresearch.com/docs/get-started/safety-model.md): What RosieOS software does and does not do to keep a cell safe, how the hardware E-stop, software stops, the motion start gate and program verification fit together, and the claims you may make about them.
- [For AI agents](https://advancedmetalresearch.com/docs/get-started/for-ai-agents.md): A quick orientation for coding agents and language models building against RosieOS, covering where the machine-readable docs and specs are, the interfaces to use and the safety rules to respect.

## Concepts

- [Architecture](https://advancedmetalresearch.com/docs/concepts/architecture.md): The RosieOS processes, the hosts they run on, the sockets and ports between them, and how jog, moves and weld programs travel from a client to the drives.
- [Robot description and coordinate frames](https://advancedmetalresearch.com/docs/concepts/robot-description-and-frames.md): What a RosieOS robot description contains, how its hashed identity is pinned, served and checked at Load, how a cell's calibration narrows it, and the frames, joints and units of the Rosie 1400 and Rosie 1420.
- [Control authority: leases, fences and the jog lane](https://advancedmetalresearch.com/docs/concepts/control-authority.md): How rt-control admits one controller at a time, using an expiring lease, a session and generation fence, idempotent retries and a separate jog lane with its own deadlines.
- [The real-time core](https://advancedmetalresearch.com/docs/concepts/real-time-core.md): How rosie-rt-core runs the cyclic control loop, drives CiA402 servo drives over EtherCAT, gates every motion start, applies a final output permit each cycle, latches faults and records telemetry.
- [Motion paths and planning](https://advancedmetalresearch.com/docs/concepts/motion-and-planning.md): The four ways a RosieOS client moves the robot, who holds authority on each path, which rt-control lane each one uses, and what is verified before and during the motion.
- [Weld planning, verification and evidence](https://advancedmetalresearch.com/docs/concepts/weld-planning-and-verification.md): How a CAD part becomes a verified joint trajectory, what the weld planner's verifier and admission check prove and do not prove, and what the plan result records.
- [Cells, machines and positioners](https://advancedmetalresearch.com/docs/concepts/cells-and-positioners.md): How drive, robot, machine and cell configuration layer and pin each other, how a cell's identity is checked, and how the Rosie 1400 H-frame positioner is modelled.
- [Process I/O and sensing: current status](https://advancedmetalresearch.com/docs/concepts/process-io-and-sensing.md): What RosieOS does today with cell digital I/O, why torch outputs are refused everywhere, and the fact that no seam tracking or sensing is implemented.

## Guides

- [Run everything in simulation](https://advancedmetalresearch.com/docs/guides/run-in-simulation.md): Use dev-stack.sh to run the simulated core, rt-control, the dense daemon, NATS, the virtual pendant, the weld planner and the offline programming app on one machine, and check it with the smoke test.
- [Simulate a Rosie robot](https://advancedmetalresearch.com/docs/guides/simulate-a-rosie-robot.md): Download the URDF, MuJoCo model, STEP and robot.json of the Rosie 600, 1000 or 1400 and run it in PyBullet, MuJoCo or ROS 2, with the robot's own kinematics, joint limits, speeds, torques and mass properties.
- [Program a weld from CAD](https://advancedmetalresearch.com/docs/guides/offline-programming.md): Create a program in offline programming, import and place a STEP part, define welds from its edges with the seam search, plan and verify them with the weld planner, replay the result in simulation, and read a refusal.
- [Teach waypoints and moves](https://advancedmetalresearch.com/docs/guides/teach-waypoints.md): Record taught waypoints from a measured robot pose or the preview, make them joint, linear or circular moves, set their speeds, add dwell, I/O and Home events, and plan and verify them with the weld planner.
- [Program from the Steam Deck pendant](https://advancedmetalresearch.com/docs/guides/program-from-the-pendant.md): Use the native v5 teach pendant on a Steam Deck to connect a cell, arm, jog with the hold-to-enable trigger, record waypoints, edit the program, plan it with the weld planner, preview it and run it.
- [Connect to a cell and run a program](https://advancedmetalresearch.com/docs/guides/connect-a-cell.md): Commission a cell for offline programming, describe it in the cell catalogue, select it, and Home, Arm, Load, Play and Stop a planned weld program, with the checks OLP makes at each step and how to read its refusals.
- [Install rt-core on a cell host](https://advancedmetalresearch.com/docs/guides/install-on-a-cell-host.md): Provision a Linux cell host for rt-core, build and install a runtime package with inactive systemd units, bind it to a compiled machine configuration, optionally set up mutual TLS, check the host, start the services and roll back.
- [Build and install the pendant](https://advancedmetalresearch.com/docs/guides/install-the-pendant.md): Build the v5 Steam Deck teach pendant, test it, run it on a workstation, package and deploy it to a Deck with hash checks, add it as a Steam shortcut with its controller layout, and write the per-Deck site files.
- [Run the weld planner](https://advancedmetalresearch.com/docs/guides/run-the-weld-planner.md): Install the weld planner's pixi environments, check the GPU, serve the motion planner on port 8796 bound safely, connect OLP to it, plan from the command line, and run its tests.
- [Add a robot model](https://advancedmetalresearch.com/docs/guides/add-a-robot-model.md): Create a new RosieOS robot description, from URDF and meshes through config.json, rtcore_definition.json and collision spheres, register it with the manifest tool, and pin it from a machine config.
- [Use the virtual pendant](https://advancedmetalresearch.com/docs/guides/virtual-pendant.md): Run the browser Steam Deck pendant against the simulated core, take control, arm, home and jog joints, and know what it cannot do.

## APIs

- [rt-control HTTP API](https://advancedmetalresearch.com/docs/apis/rt-control-http.md): Reference for rt-control, the public control API of RosieOS. It covers all 33 operations, the request and response envelopes, every schema type and the reason codes each operation can return.
- [Events and telemetry streams](https://advancedmetalresearch.com/docs/apis/rt-control-events-telemetry.md): How to follow rt-control's event log over polling or Server-Sent Events, and how to read the full-rate binary telemetry stream, with cursors, loss reporting and the exact record layout.
- [Remote access (mTLS) and remote jog](https://advancedmetalresearch.com/docs/apis/remote-access-mtls.md): How to expose rt-control to other machines over mutual TLS 1.3, provision the component CA and client certificates, connect from Go, C++ or curl, and jog over the WebSocket lane.
- [Go SDK (rosieos/rt-core/sdk/control)](https://advancedmetalresearch.com/docs/apis/go-sdk.md): The Go client for rt-control. Dial the local socket or mutual TLS, acquire and renew authority, jog, upload and start programs, follow events and telemetry, and handle typed refusals.
- [C++ client](https://advancedmetalresearch.com/docs/apis/cpp-client.md): The header-only C++17 client for rt-control, used by the motion servers. Connect, acquire and renew, upload and start programs, jog locally or over WebSocket, and handle the exception types.
- [TypeScript contracts](https://advancedmetalresearch.com/docs/apis/typescript-types.md): The generated TypeScript types, constants and telemetry decoders for rt-control. There is no HTTP client; use them with your own transport, and mind uint64 precision.
- [Offline programming HTTP API](https://advancedmetalresearch.com/docs/apis/olp-http.md): Every route of the OLP server on port 8794, including the dense-execution machine-control API for Home, Arm, jog, moves, Load, Play and Stop, with request bodies, units, target fencing and error codes.
- [Weld planner HTTP API](https://advancedmetalresearch.com/docs/apis/weld-planner-http.md): The weld planner's four routes on port 8796, for health, progress, planning a .weldplan and fetching the verified dense trajectory, with query parameters, units, the result document and error codes.
- [Cartesian motion server](https://advancedmetalresearch.com/docs/apis/cartesian-motion-server.md): robot-v4-cartesiand, the Cartesian jog server, with its command-line bindings, the UDP intent packet, the NATS leader lease and robot commands, the status document and the resolve-only JSON protocol OLP uses.
- [Dense trajectory daemon](https://advancedmetalresearch.com/docs/apis/dense-trajectory-daemon.md): The joint_trajectory_daemon store-and-play service for .rdt programs, with its config file, command-line flags, TCP ingest protocol, NATS leader lease and play commands, status document and refusal codes.

## Reference

- [rtctl command reference](https://advancedmetalresearch.com/docs/reference/rtctl.md): Every rtctl subcommand and flag, with defaults and exit codes, for compiling and validating machine configurations, checking a cell host, inspecting a running cell through rt-control, and converting telemetry dumps.
- [Configuration files (drive, machine, cell)](https://advancedmetalresearch.com/docs/reference/configuration.md): Field reference for rt-core machine, drive and cell configuration, with units, allowed ranges and defaults, plus what rtctl compile writes, the three identity digests, and the warnings and refusals the compiler returns.
- [Robot description files](https://advancedmetalresearch.com/docs/reference/robot-description.md): Field reference for a RosieOS robot description: the manifest and its identity algorithm, config.json, rtcore_definition.json, spheres.json and a cell's machine_planning_calibration.json, with units, rules and the tools that check them.
- [Mechanical interfaces (base and tool flange)](https://advancedmetalresearch.com/docs/reference/mechanical-interfaces.md): How to mount Rosie 1400 and attach tooling. Base-plate anchor pattern, tool-flange hole pattern, interface frames and dimensions measured from the CAD, with STEP, PDF and JSON downloads.
- [Dense trajectory (.rdt) format](https://advancedmetalresearch.com/docs/reference/rdt-format.md): The robot.v4.dense-joint-trajectory.v1 binary format for immutable joint programs, with its header fields, sample records, content digest, validation rules and the extra checks rt-control applies at admission.
- [Program format (robot.v4.program.v2)](https://advancedmetalresearch.com/docs/reference/program-format.md): The robot.v4.program.v2 document that OLP, the pendant and the weld planner share, with its top-level fields, node types, the single-line ordering rule, weld geometry, taught moves, units and digests.
- [Weld program and .weldplan container](https://advancedmetalresearch.com/docs/reference/weld-program-format.md): The seam model that weld nodes use (curves, arc length, the seam frame, work and travel angles, bands and tolerances), the .weldplan plan request container and its checks, and the seam worker's stdin protocol.
- [Error codes and fault states](https://advancedmetalresearch.com/docs/reference/error-codes.md): Every rt-control reason code (all 153), the numeric native command, jog and grant reasons, execution fault bits with their recovery classes, and axis readiness states.
- [NATS subjects and streams](https://advancedmetalresearch.com/docs/reference/nats-subjects.md): Every NATS subject and JetStream stream RosieOS publishes or subscribes to, with payload schemas, the processes on each side, and which subjects carry command authority.
- [Pendant controls](https://advancedmetalresearch.com/docs/reference/pendant-controls.md): Every control of the v5 Steam Deck teach pendant, including the hold-to-enable trigger, joint and Cartesian jog, teaching, arming, stop, navigation, touch and keyboard, and the Steam Input layout.
- [Ports, sockets and environment variables](https://advancedmetalresearch.com/docs/reference/ports-and-environment.md): Every TCP port, Unix socket and environment variable used by the RosieOS services, the dev stack and the offline programming launcher, with defaults.

## Contributing

- [Repository layout](https://advancedmetalresearch.com/docs/contributing/repo-layout.md): Where each RosieOS component lives in the repository, which versioned folders are current and which are legacy, and which files are generated from contracts rather than edited by hand.
- [Building and testing](https://advancedmetalresearch.com/docs/contributing/building-and-testing.md): Build and test commands for each RosieOS component, the environment the rt-core tests expect, and what each CI workflow runs and gates.
- [Code style and quality checks](https://advancedmetalresearch.com/docs/contributing/code-style.md): The quality runner's gate and report commands, what each one checks, and the conventions RosieOS code follows for constants, units, provenance, errors and tests.
- [Releasing](https://advancedmetalresearch.com/docs/contributing/releasing.md): How rt-core runtime packages are built, identified and verified, how robot-stack bundles are assembled offline, and what a release does and does not claim. Provisional.
- [Licence](https://advancedmetalresearch.com/docs/contributing/license.md): RosieOS is open source under the Apache License, Version 2.0.

## Machine-readable

- [rt-control OpenAPI 3.1](https://advancedmetalresearch.com/docs/openapi/rt-control.json): the public robot control API, generated from the RosieOS contract rt-core/protocol/application-v1.schema.json
- [rt-control contract (original)](https://advancedmetalresearch.com/docs/openapi/rt-control.contract.json): the contract file itself: capabilities, types, rules and the closed catalogue of reason codes
- [Offline programming OpenAPI 3.1](https://advancedmetalresearch.com/docs/openapi/offline-programming.json): OLP server routes on port 8794, derived from the Go source
- [Weld planner OpenAPI 3.1](https://advancedmetalresearch.com/docs/openapi/weld-planner.json): weld planner routes on port 8796, derived from the Python source
- [Error codes (JSON)](https://advancedmetalresearch.com/docs/data/error-codes.json): every rt-control reason code with its meaning, group, HTTP status and the operations that return it
- [NATS subjects (JSON)](https://advancedmetalresearch.com/docs/data/nats-subjects.json): every NATS subject and stream, with publishers, subscribers and payload schemas
- [Docs search index (JSON)](https://advancedmetalresearch.com/assets/docs/search.json): title, section, URL, Markdown URL, description, headings and text of every docs page

## Optional

- [All RosieOS docs in one file](https://advancedmetalresearch.com/docs/llms-full.txt): 51 pages as Markdown
- [Advanced Metal Research site index](https://advancedmetalresearch.com/llms.txt): company, products and the full site