Skip to content
Librux Runtime Kernel for Robotics development
Librux Runtime Kernel for Robotics development

    Subsystems, Roles, And Interfaces

    A subsystem is the executable and contract-bearing runtime unit inside a Librux robot composition.

    It is not just a process name, a node name, or a transport endpoint. It is the minimum unit that the runtime can register, validate, route, observe, and manage through lifecycle transitions.

    Runtime Role Order

    Every subsystem declares one role in its librux.subsystem manifest.

    Role Primary responsibility Usual public surface
    gateway Own device boundaries for physical hardware or simulator-backed devices api.*
    component Provide a reusable robotics function component.* backed by api.*
    compound Expose robot-level capability by coordinating lower layers capability.*
    app Run the selected robot task or operator workflow app control API or no public surface

    The order matters. A component should not bypass a gateway to open device-level hardware directly. A normal application should not bind to low-level component or gateway topology when the platform exposes an appropriate capability.

    Gateway Subsystems

    Gateway subsystems are the device boundary.

    They are the standard place to connect servo drivers, fieldbus stacks, cameras, sensors, serial devices, CAN devices, EtherCAT-class links, simulator device bridges, or vendor SDKs.

    Gateways normally provide api.* contracts directly. They hide how a device is reached and expose the Librux API surface that higher layers consume.

    Component Subsystems

    Component subsystems implement reusable robotics functions such as mobile-base control, manipulator control, gripper control, perception, mapping, navigation, planning, safety, or diagnostics.

    A component subsystem may require gateway APIs or other component APIs, but it should not claim device-level hardware resources directly. CPU and scheduling claims are allowed when deterministic execution is required.

    The public compatibility promise of a component-role subsystem is usually a component.* contract. That contract is a named bundle of one or more api.* contracts.

    Compound Subsystems

    Compound subsystems turn lower-level component and gateway interfaces into robot-level capabilities.

    They are the right place for robot-specific coordination.

    • state machines
    • retries and recovery behavior
    • safety checks
    • multi-step behavior
    • robot-specific capability facades
    • direct gateway access for custom platform behavior when a standard component is not the right abstraction

    Compound subsystems normally provide capability.* contracts to applications. They may require component.* contracts for standard component providers and api.* contracts for direct platform-specific device access.

    App Subsystems

    App subsystems implement the selected behavior for one robot deployment.

    An app should normally require robot capabilities from the platform instead of binding to device or component topology directly. If an app includes a browser UI, the static frontend and instance context should be delivered through the managed package frontend path rather than by opening an unmanaged web server.

    Interfaces

    A subsystem manifest describes the subsystem from its own point of view.

    kind: librux.subsystem
version: 1

subsystem:
  name: component.manipulator
  role: component

requires:
  actuator_servo:
    contract: api.actuator.servo.v1
    required: true
    cardinality: one

provides:
  manipulator:
    contract: component.manipulator.v1

    provides means this subsystem implements an interface. requires means this subsystem needs another interface to do its work. The names under requires are logical names used by subsystem code; deployment decides which concrete provider satisfies them.

    Public And Internal Interfaces

    Public interfaces are compatibility boundaries. A public provides or requires contract must resolve to a Librux spec contract such as api.*, component.*, or capability.*.

    Private tutorial or product-internal wiring can be marked as internal.

    provides:
  service:
    contract: tutorial.transport.service.v1
    visibility: internal

    visibility: internal is useful for mechanics tutorials and private test wiring, but it is not a product platform slot and not an app-facing capability surface.

    Declaration And Registration

    Before a subsystem can participate in a runtime composition, Librux needs an explicit description of what it provides and requires.

    The conceptual flow is:

    message, API, component, and capability specs
  -> subsystem interface declaration
  -> subsystem registration
  -> lifecycle state
  -> heartbeat and status export
  -> runtime route visibility

    Registration makes the subsystem visible as a runtime participant rather than only a block of user code.

    Communication Surfaces

    Subsystems communicate through explicit semantic surfaces.

    Surface Use
    Event asynchronous state, telemetry, measurements, and feedback streams
    Control periodic timed exchange with deadline and overrun semantics
    Procedure bounded request and response
    Operation long-running execution with feedback, result, and state

    This page names the surfaces. Communication Surfaces explains how those surfaces are realized inside one host, across federation, and through the WebSocket facade.