Python Message Library

55+ typed message classes for Python robotics. Zero-copy shared memory transport, nanosecond timestamps, and binary-compatible cross-language IPC.

Which messages do I need?

Overview

Key Features:

• 55+ message types — All standard robotics messages available in Python
• Zero-copy IPC — POD types transfer via shared memory with no serialization overhead
• Cross-language compatible — Binary-compatible across all horus language bindings
• Nanosecond timestamps — All messages include timestamp_ns field
• Typed Topic support — Use Topic(CmdVel) for type-safe pub/sub

All message types are importable directly from the top-level horus module (e.g., from horus import CmdVel, LaserScan). Category-based imports (from horus.messages.geometry import Pose2D) are also supported.

Quick Reference — All 55+ Types

Geometry (13 types)

Sensor (13 types)

Control (7 types)

Navigation (9 types)

Diagnostics (8 types)

Force and Haptics (6 types)

Perception (13 types)

Vision (7 types)

Input and Audio (3 types)

Using Types with Topics

# simplified
import horus

# Typed topic — zero-copy Pod transport (~1.7us)
node = horus.Node(
    pubs=[horus.CmdVel],          # auto-creates topic named "cmd_vel"
    subs=[horus.LaserScan],       # auto-creates topic named "scan"
    tick=my_tick,
    rate=50
)

# String topic — GenericMessage with serialization (~6-12us)
node = horus.Node(
    pubs=["my_data"],             # GenericMessage — any dict works
    subs=["sensor_raw"],
    tick=my_tick,
    rate=50
)

# Send typed
node.send("cmd_vel", horus.CmdVel(linear=1.0, angular=0.0))

# Send dict (generic)
node.send("my_data", {"x": 1.0, "y": 2.0})

Typed topics auto-derive the topic name from the type's __topic_name__ class attribute (e.g., CmdVel.__topic_name__ = 'cmd_vel'). Override with dict syntax: pubs={'my_name': horus.CmdVel}.

Cross-Language Compatibility

All 55+ Python message types are binary-compatible with their counterparts in other horus language bindings via zero-copy shared memory. A Python node publishing CmdVel on a topic can be consumed by any other language node subscribed to the same topic, with no serialization overhead.

# simplified
# Python publisher
from horus import Topic, Twist
topic = Topic(Twist)
topic.send(Twist(linear_x=1.0, angular_z=0.5))

Any node subscribed to the same topic receives the exact same bytes with zero-copy semantics.

Usage Patterns

Robot Controller with Multiple Sensors

# simplified
from horus import Node, Topic, CmdVel, LaserScan, Imu

scan_topic = Topic(LaserScan)
imu_topic = Topic(Imu)
cmd_topic = Topic(CmdVel)

def controller_tick(node):
    scan = scan_topic.recv(node)
    imu = imu_topic.recv(node)
    if scan:
        closest = scan.min_range()
        if closest is not None and closest < 0.5:
            cmd_topic.send(CmdVel.zero(), node)  # Stop
        else:
            cmd_topic.send(CmdVel(linear=0.5, angular=0.0), node)

node = Node(name="controller", tick=controller_tick, rate=10,
            pubs=["cmd_vel"], subs=["scan", "imu"])

Safety Monitor

# simplified
from horus import Node, run, BatteryState, EmergencyStop, DiagnosticStatus, Topic

battery_topic = Topic(BatteryState)
estop_topic = Topic(EmergencyStop)
diag_topic = Topic(DiagnosticStatus)

def safety_monitor(node):
    battery = battery_topic.recv(node)
    if battery is None:
        return
    if battery.is_critical():
        estop_topic.send(
            EmergencyStop.engage("Battery critical").with_source("safety"),
            node
        )
    elif battery.is_low(20.0):
        diag_topic.send(
            DiagnosticStatus.warn(100, f"Battery at {battery.percentage:.0f}%"),
            node
        )
    else:
        diag_topic.send(DiagnosticStatus.ok("Battery OK"), node)

run(Node(tick=safety_monitor, rate=1,
         pubs=["estop", "diagnostics"], subs=["battery"]))

Design Decisions

Why 55+ types instead of a minimal set? Mixed-language systems are the norm in robotics: compiled languages for real-time control, Python for ML and prototyping. If Python lacked certain message types, cross-language pipelines would break. Full parity means any topic can be consumed from Python with binary-compatible zero-copy transport.

Why PyO3 bindings instead of Python dataclasses? PyO3 bindings expose the actual compiled structs, so Python messages are binary-identical in shared memory. Python dataclasses would require a serialization layer, adding latency and risking format mismatches. The tradeoff is that adding a new message type requires a compiled rebuild, but the horus.msggen module provides runtime custom messages for rapid iteration.

Why from horus import X instead of horus.messages.X? Flat imports reduce typing and match the convention used across all horus language bindings. All 55+ types are importable from the top-level horus module. Category-based imports (from horus.messages.geometry import Pose2D) are also supported for code organization.

Why nanosecond timestamps on every message? Nanosecond precision is needed for sensor fusion (IMU at 1kHz needs sub-millisecond accuracy) and for correlating events across nodes. Embedding the timestamp in every message (instead of a separate Header) keeps messages flat and Pod-compatible.

See Also

• Python Bindings — Full Python API guide
• Python Perception Types — DetectionList, TrackedObject, COCOPose
• Custom Messages — Runtime and compiled message generation
• Python API Reference — Complete Python API for Node, Scheduler, Topics
• Message Types Overview — Conceptual message type documentation