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

    Communication Surfaces

    The subsystem model stays the same across Librux deployments, but communication realization changes when interaction crosses a host boundary.

    That is the main idea of this chapter.

    • inside one host, the runtime can use host-local transport paths
    • across hosts, the runtime has to use control-managed remote paths
    • subsystem code should keep declaring semantic intent rather than managing those transport details directly

    Why Realization Changes At The Host Boundary

    In Librux, subsystem-to-subsystem interaction is the semantic model.

    However, the actual transmission mechanism depends on whether the communicating subsystems are in one of these placements.

    • on the same host
    • or separated by a network boundary

    Inside one host, the runtime can use host-local memory and IPC-oriented paths.

    Across hosts, the runtime has to deal with these concerns.

    • remote visibility
    • forwarding and relay policy
    • route metadata
    • timing interpretation across machines

    So the subsystem relation may stay semantically the same, but its runtime realization changes at the host boundary.

    Packet Primitives And Surfaces

    At the packet level, Librux is built around two main primitives.

    • Stamped stream packet - time-stamped publish/subscribe data.
    • Timed exchange packet - point-to-point request/response with period, deadline, priority, and overrun-sensitive timing metadata.

    Those packet primitives are exposed through four user-facing interaction surfaces.

    Surface Packet primitive Use
    Event stamped stream packet state, telemetry, command streams, and fan-out observation
    Control timed exchange packet periodic control loops over timed exchange
    Procedure timed exchange packet bounded synchronous request/response
    Operation timed exchange + event asynchronous execution with feedback, state, and result

    Control request paths are implemented on timed exchange packets. New subsystem-facing documentation should use Control / Procedure / Operation unless the page is specifically discussing runtime implementation details.

    Event Across The Host Boundary

    Event remains the asynchronous data path regardless of deployment shape, but its transport path changes significantly at the host boundary.

    Inside One Host

    flowchart TB EA["Subsystem A"] --> LP["Local Event Path"] --> EB["Subsystem B"]

    Across Hosts

    flowchart TB RA["Subsystem A"] --> OA["Control Backend A"] --> OB["Control Backend B"] --> RB["Subsystem B"]

    Inside One Host

    Within one host, Event uses the host-local stamped stream runtime path.

    That path is optimized for local delivery.

    • shared-memory-oriented transport
    • descriptor-style delivery instead of direct socket payload copies
    • runtime-managed slot ownership and acknowledgement

    This is the local zero-copy-oriented side of Librux transport.

    Across Hosts

    Across hosts, Event stops being only a local memory problem and becomes a federation problem.

    At that point.

    • local publish/subscribe state must become remotely visible
    • control backends decide what is forwarded across the host boundary
    • remote delivery becomes host-to-host runtime forwarding rather than direct subsystem socket behavior

    So Event stays semantically the same, but the transport realization shifts from local event delivery to control-managed cross-host forwarding.

    Operational checks.

    Control Across The Host Boundary

    Control remains point-to-point, but the runtime owns how that point-to-point exchange crosses a host boundary.

    Inside One Host

    flowchart TB CA["Subsystem A"] --> CP["Local Control Path"] --> CB["Subsystem B"]

    Across Hosts

    flowchart TB SA["Subsystem A"] --> HA["Control Backend A"] --> HB["Control Backend B"] --> SB["Subsystem B"]

    Inside One Host

    Within one host, Control uses a host-local path selected by the runtime.

    This is centered on local IPC-style transport rather than forcing user code to expose arbitrary network sockets.

    On Linux, the local control path uses persistent Unix-socket channels.

    When the payload exceeds the local inline threshold, the payload is carried through a shared-memory lease instead of being copied inline into the control frame. The default threshold is 64 KiB and is configurable through timed_exchange.inline_payload_threshold.

    That means the control path and the large-payload path are related, but not identical.

    Across Hosts

    Across hosts, Control becomes a runtime-owned relay path.

    That means the following.

    • subsystem code does not open remote control sockets directly
    • target resolution stays tied to subsystem identity and runtime metadata
    • host-level runtime policy owns the relay path across the network boundary

    So Control keeps the same semantic role, but its actual realization changes from local control delivery to runtime-managed remote relay.

    Timing And Priority

    The host boundary matters especially for Control because this is where timing-sensitive traffic becomes a real distributed-systems problem.

    In that model.

    • timing intent is carried as runtime metadata
    • synchronized host clocks are used for cross-host interpretation
    • outbound control handling can use explicit priority metadata on shared remote paths

    This should be understood as runtime-level transport behavior, not as a full host-wide operating-system QoS framework.

    Operational checks.

    Procedure And Operation On Top Of Control

    At this level, Procedure and Operation only need a short clarification.

    Procedure does not introduce a third control transport. It is a bounded synchronous request/response surface built on the control exchange path.

    Operation splits long-running execution across the two packet primitives.

    • timed exchange for start, cancel, and query
    • Event for feedback, result, and state

    So the transport foundation stays the same even when the higher-level semantic model becomes richer.

    WebSocket Facade Outside The Native Runtime

    Not every client that needs to interact with Librux can participate in the native runtime path directly.

    Browser-based frontends and similar outside clients do not use the following.

    • host-local shared-memory Event transport
    • local control IPC channels
    • direct federation transport ownership

    For that reason, Librux exposes a control-owned WebSocket facade.

    That facade is not a third native transport primitive. It is an integration boundary for clients that stay outside the native subsystem runtime.

    In this model.

    • /api/v1/ws/events provides browser-facing event subscription only
    • /api/v1/ws/control provides browser-facing control requests
    • the control backend translates that facade traffic into the native Event / Control / Procedure / Operation path behind the runtime boundary
    • timed execution is not exposed through this facade and remains part of the native synchronized control path

    So the browser or frontend GUI does not talk to native control transport or federation directly. It talks to the control-owned WebSocket facade instead.

    Deep dive.

    Practical Rule

    The practical rule is simple.

    • if two subsystems interact inside one host, the runtime uses host-local transport paths
    • if they interact across hosts, the runtime uses control-managed remote paths
    • if a browser-facing or outside client needs access, it uses the control-owned WebSocket facade
    • subsystem code should stay focused on semantic declaration, not transport topology

    That separation is what lets Librux preserve one subsystem model while changing transport realization at the host boundary.