Message Theme Taxonomy

This document describes the public message-family taxonomy for Librux.

Design Rule

The taxonomy should reflect robotics semantics, not runtime implementation convenience.

That means the following.

• shared spatial and kinematic concepts belong in shared core.* families
• hardware-domain-bound payloads belong in component.*
• robot-level functions that can be shared across embodiments belong in system.*
• runtime-internal transport envelopes should not shape the public taxonomy

Public Families

msg.core.common.primitive.v1

Purpose.

• primitive wrappers
• empty bodies
• named scalar time values

msg.core.spatial.v1

Purpose.

• shared pose, frame-aware motion, wrench, and physical quantities

Messages.

• Vector3
• Quaternion
• Position
• Covariance6x6
• Pose
• Force
• Torque
• Wrench
• Twist
• Accel
• Inertia

This family exists because pose, twist, wrench, and related quantities are not I/O-specific. They are shared robotics concepts used by estimation, planning, control, manipulation, and locomotion.

It also follows an intentional split between.

• base math types such as Vector3 and Quaternion
• semantic wrappers such as Position, Force, and Torque
• rigid-body composites such as Pose, Wrench, Twist, and Accel

Even when two types share the same x, y, z field layout, they remain distinct when the robotics meaning is different. Angular quantities also keep x, y, z axis naming; the surrounding type carries the angular semantics. In particular, Twist should be read as rigid-body spatial velocity, not as a generic six-value velocity bundle.

Estimate-oriented composites should usually live outside msg.core.spatial.*. For example, msg.core.spatial.v1 may provide reusable Pose and Covariance6x6, while domain families such as msg.localization.v1 own messages like PoseEstimate.

msg.core.kinematics.v1

Purpose.

• articulated-chain and joint-space concepts

Messages.

• JointValues
• JointLimits
• JointState
• JointCommand
• KinematicChainState

msg.core.state.v1

Purpose.

• generic subsystem runtime state that should make sense across every subsystem role

Note.

• until the schema has an explicit enum or keyword type, these states are expressed as canonical string keywords

msg.core.diagnostics.v1

Purpose.

• structured diagnostics payloads

msg.core.timing.v1

Purpose.

• scheduled and synchronized execution semantics

This family is public because timing intent is part of the subsystem-facing contract model.

Digital and analog I/O do not keep a dedicated msg.io.* message family in the public model.

• simple channel-addressed IO requests reuse msg.core.common.primitive.v1
• IO remains visible at the interface/API contract layer rather than as a large component-specific message namespace

msg.sensor.camera.v1

Purpose.

• camera-frame delivery and calibration metadata for vision-capable hardware components

msg.actuator.servo.v1

Purpose.

• low-level servo actuation payloads that sit below higher-level semantic controllers

msg.motion.articulated.v1

Purpose.

• articulated-motion payloads shared by jointed mechanisms without tool- or TCP-specific semantics

Messages include the following.

• JointWayPoint

msg.motion.manipulator.v1

Purpose.

• manipulator-specific payloads built on shared spatial and kinematic foundations

Messages include the following.

• TCP
• Payload
• TaskWayPoint
• ToolSettings

Note.

• high-level manipulator motion semantics stop at tool, TCP, Cartesian task-space waypoint, and motion-state payloads; joint-space primitives live under msg.motion.articulated.*, and direct servo actuation belongs in msg.actuator.servo.*

msg.locomotion.velocity.v1

Purpose.

• shared timed body-velocity command, acknowledgement, limit, and stop payloads for locomotion controllers

msg.locomotion.mobile_base.v1

Purpose.

• wheeled mobile-base payloads for platform state, odometry, drive authority, fault state, and optional differential-drive surfaces

msg.locomotion.legged.v1

Purpose.

• locomotion-oriented payloads for legged systems

msg.localization.v1

Purpose.

• robot-level self-localization state that can be consumed above individual sensors

msg.mapping.v1

Purpose.

• shared map publication and map lifecycle state

msg.navigation.v1

Purpose.

• robot-level goal and path execution semantics

msg.perception.v1

Purpose.

• detections, object poses, and grasp candidates derived from one or more sensors

Practical Layering

The intended layering is this.

1. msg.core.common.primitive.* for universal wrappers
2. msg.core.spatial.* and msg.core.kinematics.* for shared robotics concepts
3. domain message families such as msg.motion.*, msg.locomotion.*, msg.actuator.*, and msg.sensor.*
4. robot-level domain families such as msg.localization.*, msg.mapping.*, msg.navigation.*, and msg.perception.*

What Is Intentionally Excluded

Runtime-only control envelopes such as internal timed-request headers are not part of the public message taxonomy. They may exist inside runtime implementations, but they should not be treated as public robotics-facing spec families.

Extension Areas

The taxonomy can be extended in areas such as the following.

• mobile-base-specific families
• camera and other sensor families
• broader state and diagnostics coverage
• richer system-level perception and planning catalogs

Shared spatial and physical concepts are public core.* concepts, not component-specific concepts.