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

    Built-In Message Families

    Librux ships a canonical message tree under spec/messages. The message tree is the data vocabulary used by API contracts, components, generated SDK bindings, and the Web Console Spec Dictionary.

    This page explains how that tree is organized. For the message inventory itself, use the Message Index.

    Layering Model

    Layer Responsibility Examples
    core.* reusable concepts that are not tied to one robot body, component contract, or subsystem role primitive wrappers, timing, spatial math, kinematics
    domain families payloads whose meaning belongs to one robotics domain motion, locomotion, actuator, sensor, localization, mapping, navigation, perception

    The domain is part of the semantic contract. Moving a payload from one domain to another changes how users should interpret ownership, reuse, and compatibility. The component.* namespace is reserved for compatibility contracts, not message families.

    Family Map

    Family Responsibility Use when
    msg.core.common.primitive.v1 wrapper messages for primitive values, empty bodies, indexed IO values, timestamps, and durations an API contract needs a named scalar or generic channel-addressed payload
    msg.core.diagnostics.v1 structured diagnostics payloads a subsystem publishes optional remote diagnostics
    msg.core.kinematics.v1 articulated-chain and joint-space concepts multiple motion domains need shared joint state or command types
    msg.core.spatial.v1 pose, twist, wrench, acceleration, inertia, and related spatial quantities a payload needs reusable physical-space semantics
    msg.core.state.v1 generic subsystem lifecycle and health state the state applies to every subsystem role
    msg.core.timing.v1 timed execution metadata a control path needs synchronized execution directives or reports
    msg.actuator.servo.v1 low-level servo actuation payloads direct actuation sits below semantic motion controllers
    msg.motion.articulated.v1 jointed-mechanism motion primitives the payload is joint-space motion but not manipulator-specific
    msg.motion.manipulator.v1 manipulator payloads with tool, TCP, payload, and motion-result semantics a contract depends on manipulator-specific task-space meaning
    msg.locomotion.velocity.v1 shared timed body-velocity command, acknowledgement, limits, and stop payloads a locomotion controller accepts body velocity commands
    msg.locomotion.mobile_base.v1 wheeled mobile-base state, odometry, drive authority, and optional diff-drive payloads mobile base exposes mobile-base state, odometry, fault, or wheel-level surfaces
    msg.locomotion.legged.v1 legged locomotion payloads contact, foot, gait, balance, or support-polygon state is exchanged
    msg.sensor.camera.v1 camera calibration and RGB/depth frame delivery a camera-like component publishes image data or calibration metadata
    msg.localization.v1 pose estimation and localization status the result describes robot pose estimation rather than raw sensing
    msg.mapping.v1 occupancy-style map publication and map state a mapping subsystem publishes map products
    msg.navigation.v1 navigation goals, path following, feedback, result, and state a subsystem executes robot-level navigation tasks
    msg.perception.v1 detection, object pose, and grasp-candidate outputs perception results bridge sensor observations to robot-level meaning

    Placement Rules

    • Put broadly reusable math, state, timing, and joint concepts in core.*.
    • Put hardware-domain-bound or controller-domain-bound payloads in direct domain families such as msg.actuator.*, msg.sensor.*, msg.motion.*, and msg.locomotion.*.
    • Put composed robot-level function payloads in direct domain families such as msg.localization.*, msg.mapping.*, msg.navigation.*, and msg.perception.*.
    • Keep direct actuation separate from semantic motion control.
    • Do not create a new message family when an API contract only needs a named primitive wrapper; reuse msg.core.common.primitive.v1.
    • Prefer an API contract-specific method argument shape when a dedicated request message would only wrap one operation.

    IO Note

    Digital and analog IO API contracts intentionally reuse generic indexed primitive wrappers instead of defining a separate msg.io.* family. This keeps low-level channel IO compact while still giving every request and response a named schema.