Robot, Application, And Deployment

Librux treats a robot as one software-defined composition.

robot = platform + application + deployment
platform = what the robot is and what it can provide
application = what the robot should do
deployment = what runs, where it runs, and how it connects

This keeps a platform reusable. One platform can run different applications, and one application can target any platform whose capabilities satisfy the app requirements. Platform compatibility labels can narrow that match when an app is written for a specific robot family, but capability requirements are the main compatibility surface.

Platform

A platform is the reusable robot body and capability surface.

It is not one launch script and not one process. It is a declaration of the robot slots, robot structure, and robot-level capabilities that applications can use.

Platform slots are filled by subsystem instances.

Slot family	Typical provider	Purpose
gateway	`role: gateway` subsystem	device boundary for physical hardware or simulator-backed devices
component	`role: component` subsystem	reusable robotics function such as motion, perception, planning, or safety
compound	`role: compound` subsystem	robot-level capability facade that coordinates gateway and component interfaces

Device-level hardware is connected only through gateway subsystems. Servo drivers, fieldbus devices, sensors, cameras, and similar physical outlets are treated as hardware behind the gateway device boundary. Component subsystems consume gateway API contracts instead of opening those devices directly.

Application

An application is the selected behavior for the robot.

An app-role subsystem should require robot capabilities, not a particular vendor gateway, component, or host topology. For example, an application should require capability.manipulation.reach.v1 instead of depending on a private vendor_a_arm_controller identity.

The application process still appears as a subsystem instance at runtime. The top-level application field in a deployment selects which app-role subsystem is checked against the platform.

Deployment

A deployment makes the platform and application concrete.

It chooses package instances, launch mode, host placement, runtime parameters, slot assignments, and bindings between required and provided interfaces.

kind: librux.deployment
version: 1

robot: ./librux.robot.yaml
application: ./app/subsystem.yaml

instances:
  app.pick_place:
    manifest: ./app/subsystem.yaml
    launch: external
  gateway.arm:
    manifest: ./gateways/subsystem.yaml
    slots:
      arm_gateway: arm
    launch: managed
  compound.robot:
    manifest: ./compound/subsystem.yaml
    slots:
      compound: mobility
    launch: managed

bindings:
  app.pick_place.manipulation:
    to: compound.robot.manipulation
  compound.robot.arm_gateway:
    to: gateway.arm.arm

managed means Librux can launch the instance. external means the instance is started by a developer, debugger, IDE, simulator, or another process supervisor. federated reserves an instance identity for a remote host.

Subsystem Roles

After the platform, application, and deployment split is clear, Librux names the executable pieces inside the robot. Those pieces are subsystems.

Every executable piece uses a librux.subsystem manifest and declares one role.

Role	Meaning
`gateway`	device boundary for physical hardware or simulator-backed devices
`component`	reusable robotics function such as motion, perception, planning, or safety
`compound`	robot-level capability implementation that combines component and gateway interfaces
`app`	top-level app subsystem that represents the selected robot task

A subsystem role is not the same thing as a spec family. For example, role: component is a runtime role, while component.* is a public compatibility contract namespace for component-role subsystems.

Capability Implementation

Robot capabilities are app-facing semantic entries in the robot manifest. A capability declaration uses a public capability.* spec. That semantic spec resolves to a backing api.capability.* contract for endpoint validation.

The implementation target must be a public provided interface on a deployed subsystem, not a private package-local interface.

capabilities:
  manipulation.reach:
    capability: capability.manipulation.reach.v1
    implementation:
      kind: compound_subsystem
      subsystem: compound.robot
      interface: manipulation
      contract: capability.manipulation.reach.v1

Most robot-level behavior should be exposed through capability.* contracts. Simple pass-through cases may use kind: direct_binding to a public api.* or component.* interface. Behavior that requires state machines, retries, error handling, safety checks, or multi-step coordination should use kind: compound_subsystem.

The compound implementation is still a normal Librux subsystem with role: compound. It can use internal bindings behind its public capability surface to coordinate vendor-specific or tutorial-specific mechanics.

Deployment Levels

Not every deployment manifest is a full robot application. Librux accepts three useful levels.

Level	Fields	Purpose
Subsystem composition	`instances`, `bindings`	Launch or validate a partial subsystem set. There is no platform slot validation.
Platform bring-up	`robot`, `instances`, `bindings`	Start and validate an app-less platform. Slots, public contracts, and capability implementations are checked.
Full robot application	`robot`, `application`, `instances`, `bindings`	Run one selected application on one compatible platform. App requirements are checked against capabilities and optional platform compatibility labels.

Tutorial stage deployments can run without robot because they are partial composition stages. Platform bring-up adds robot without application so it can check the app-less platform. Final application deployments include both.

Diagram Model

The same manifests can be rendered as a static or live graph.

flowchart LR A["application subsystem"] --> B["compound subsystem<br/>capability provider"] B --> C["component and gateway subsystems<br/>standard contracts"] D["platform manifest"] -. "declares capability" .-> B

Static diagrams use robot, subsystem, and deployment manifests. Runtime diagrams add live session, route, lifecycle, and health status from the control backend.

Validation

Validation is the runtime-kernel check that the platform, application, and deployment composition is structurally coherent before it is treated as a robot. Conceptually, validation checks that:

robot manifest and app-role subsystem manifest exist
application-required platform compatibility labels are provided by the platform when label constraints are declared
application-required capabilities exist with compatible contracts
required robot slots are filled by subsystem instances
managed robot subsystems are attached to robot slots
instance roles match their robot slots
slot contracts are public Librux specs provided by the assigned instance interfaces
capability implementations point to deployed public interfaces
required subsystem bindings exist and contracts match

The command-level workflow lives in the Robot/Application/Deployment Manifests reference.