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

    Contracts And Components

    Librux separates datatype schemas, endpoint-level API contracts, app-facing capabilities, and component bundles. Keeping those layers separate is what lets gateway, component, compound, and app subsystems use different public contract surfaces without inventing package-local interfaces.

    The practical model is this.

    Layer Meaning Example
    message typed payload schema msg.core.spatial.v1/Pose
    endpoint one Event / Control / Procedure / Operation entry stop, mobile_base_state, move_j
    API contract endpoint-level contract composed from endpoints api.locomotion.velocity.v1
    capability app-facing robot ability contract capability.mobility.teleop.v1
    component replacement-compatible component bundle composed from API contracts component.mobile_base.v1

    When explaining the primitive spec stack, use this shorthand.

    message -> API contract
message -> capability API -> capability

    message, api, and capability are the primitive spec families. component is a named API bundle used by component-role subsystems. It is not the default contract type for every subsystem.

    Why The Layers Stay Separate

    API contracts are intentionally smaller than components. An API contract describes one coherent endpoint surface such as velocity control, digital output, camera capture, or a capability facade. A component says that a running component-role subsystem can be used as a recognizable replacement for a robot component.

    That gives Librux two useful checks.

    • endpoint compatibility is checked through the API contract set
    • replacement compatibility for component-role subsystems is expressed through one public component.* contract

    For example, a mobile-base controller is not just one velocity command. It also needs mobile-base state, stop behavior, limits, and fault state. The public contract should therefore be component.mobile_base.v1; the API contracts behind it define the exact endpoints.

    Gateway and compound subsystems are different.

    • a gateway owns device boundaries for physical hardware or simulator-backed devices, so it normally provides api.* contracts directly
    • a compound subsystem coordinates lower-level interfaces and normally provides capability.* contracts to applications
    • an app subsystem normally requires capability.* contracts and may provide an application-control API for operators and frontends

    Design Rule

    Use this boundary.

    • use msg.* for datatype references
    • use api.* for gateway contracts, endpoint references, and component conformance APIs
    • use component.* for component-role subsystem provides and for component slots in robot manifests
    • use capability.* for compound-provided robot abilities and app-facing requirements
    • use visibility: internal for tutorial/private wiring that intentionally does not claim public compatibility

    Do not repeat endpoint lists on public subsystem interfaces. Endpoints are owned by the referenced api.* contract, by a component's conformance API set, or by a capability's backing API contract.

    Repository Source

    The public taxonomy is stored in these paths.

    • spec/messages
    • spec/apis
    • spec/components
    • spec/capabilities

    The installed SDK and runtime package the same tree so loaders, validators, and the Web Console use one source of truth.