Choosing between a node and a shared library
Code shared across multiple parts of a robot has two possible homes:
- A node is an independent OS process managed by the Peppy daemon. Other nodes talk to it over topics, services, and actions.
- A shared library is a normal Rust crate or Python package compiled or imported directly into each node that calls it.
Use this page to decide which one fits. Once you decide on a node, see Choosing a communication pattern.
The decision comes down to two questions:
- Does the code need its own lifecycle? Nodes start, stop, crash, and restart independently, and Peppy monitors them. Libraries share the lifecycle and process of their caller.
- Can each call afford messaging overhead? Calling a node serializes a message over the transport layer. Calling a library is a direct in-process function call.
Side by side
Section titled “Side by side”| Node | Shared library | |
|---|---|---|
| Execution | Dedicated OS process per instance | Runs inside each calling node’s process |
| Interface | Declared in peppy.json5 (topics, services, actions) | Language-native functions and types |
| Callers | Rust or Python nodes on any machine, peppy node call, and MCP | Nodes in the same programming language |
| Data passed | Declared message formats (copied on the wire) | Any language type, by value or reference |
| Call cost | Serialization + messaging hop + deserialization | Function call |
| Fault isolation | Isolated; governed by its own restart policy | Crashes the calling node |
| Observability | Status, health, restarts, run log, OpenTelemetry export | None separately (part of caller’s log) |
| State | Single shared state across consumers | Separate copy per calling node |
| Versioning | One resolved version per launch | Independent version pinned per node |
| Distribution | Peppy repository | Language package manager (cargo, uv, etc.) |
Make it a node
Section titled “Make it a node”Choose a node when any of these apply:
- Standalone robot subsystem: Camera drivers, arm controllers, and motion planners have clear inputs/outputs and can run independently. Declaring them in
peppy.json5makes them inspectable (peppy node describe) and callable (peppy node call) with zero extra code. - Reusable across stacks: Launchers configure instances with parameters and bindings, and teams pull them by
name:tagfrom a repository (Sharing nodes). - Needs recording, monitoring, or benchmarking: Recorders and dashboards can only tap data sent over Peppy interfaces (contracts, observers,
peppy stack benchmark). In-process library return values are invisible to other nodes. - Cross-language callers: Rust and Python nodes exchange messages seamlessly via generated
peppygenbindings without writing FFI bridges. - Multi-robot or swappable: One generic node can serve multiple robots via parameters and contracts.
- Needs fault isolation or automatic restarts: Each instance has its own restart policy (exponential backoff 1 s to 60 s) and health checks (3 missed checks =
unhealthy, 60 s silent = kill and restart underon_failure/always; see Instance health and lifecycle). Consumers reconnect automatically. - Needs per-component observability: Appears in
peppy stack list, gets its own run log, and tags OpenTelemetry logs withservice.name(node) andservice.namespace(machine). - Needs its own runtime environment or host: Can run inside a container with isolated system dependencies or be placed on a GPU host via federation.
- Owns an exclusive resource: Hardware buses, shared maps, or GPU-resident models belong in one owning node that serves multiple consumers.
Make it a shared library
Section titled “Make it a shared library”Choose a shared library when any of these apply:
- Inside a tight control loop: High-frequency loops (such as 1 kHz inverse kinematics) cannot afford messaging latency. Measure actual messaging overhead on your hardware with
peppy stack benchmarkto check. - Zero transport failure tolerance: Critical checks (such as motor safety limits) must run synchronously in-process without risk of timeouts or dropped links.
- Pure computation with no lifecycle: Math utilities, parsers, wire protocols, and robot kinematics definitions have no independent state or streams.
- Rich in-memory types: Functions passing references into large maps, closures, or generics do not fit serialized message formats.
Tradeoffs of a library: it crashes with its caller, is invisible to Peppy monitoring, is single-language (unless you maintain FFI bindings), and each node links its own state and pinned version.
A node built on a library
Section titled “A node built on a library”You can combine both: put pure logic in a transport-free shared library, then wrap it in a thin node that handles peppy.json5 interfaces and parameters.
- High-frequency nodes link the library directly, while slower consumers call the wrapper node.
- Hardware drivers and simulated twins share the same library and implement the same contract.
- Unit tests test the library directly with
cargo testorpytest, while the test harness tests the node wrapper.
The Peppy hubs follow this pattern: public-peppy-libs holds transport-free kinematics, collision geometry, and motion planning libraries, while nodes-hub wraps them into arm nodes and motion_planner.
How a node takes a shared library
Section titled “How a node takes a shared library”Nodes pull libraries through their native package manager (cargo or uv):
- Inside the node directory: Use a local path dependency (for private code used only by that node).
- Shared across nodes: Pull from a Git repository or package registry. Because
peppy node addsnapshots only the node directory and never follows symlinks, relative paths outside the node directory (../shared) will fail to build.
Pin an exact Git commit (rev), not a branch, so builds stay reproducible across machines:
[project]dependencies = ["arm_kinematics"]
[tool.uv.sources.arm_kinematics]git = "https://github.com/acme/robot-libs"subdirectory = "arm_kinematics"rev = "<commit>"[dependencies]arm_kinematics = { git = "https://github.com/acme/robot-libs", rev = "<commit>" }When two communicating nodes must agree on shared calculations (such as unit conversions), pin them to the same commit.
Worked example: one arm
Section titled “Worked example: one arm”- Motor protocol (library): Called every control tick inside the driver; no shared state.
- Arm driver (node): Owns the motor bus, restarts independently, publishes joint states to controllers, dashboards, and recorders.
- Kinematics (library): Called in the 1 kHz controller loop and inside the motion planner.
- Motion planner (node): Takes ~1 s per request (messaging cost is negligible), works with any robot implementing its contracts, and can run on a remote compute machine.
- Robot description (library): Joint limits and meshes pinned at one commit so driver, simulator, and planner agree.
- Recorder (node): Taps driver and camera outputs without modifying either node.
Rule of thumb: Code with its own lifecycle or external consumers is a node; code that only computes for its caller is a library.