Skip to content

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:

  1. 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.
  2. 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.
NodeShared library
ExecutionDedicated OS process per instanceRuns inside each calling node’s process
InterfaceDeclared in peppy.json5 (topics, services, actions)Language-native functions and types
CallersRust or Python nodes on any machine, peppy node call, and MCPNodes in the same programming language
Data passedDeclared message formats (copied on the wire)Any language type, by value or reference
Call costSerialization + messaging hop + deserializationFunction call
Fault isolationIsolated; governed by its own restart policyCrashes the calling node
ObservabilityStatus, health, restarts, run log, OpenTelemetry exportNone separately (part of caller’s log)
StateSingle shared state across consumersSeparate copy per calling node
VersioningOne resolved version per launchIndependent version pinned per node
DistributionPeppy repositoryLanguage package manager (cargo, uv, etc.)

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.json5 makes 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:tag from 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 peppygen bindings 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 under on_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 with service.name (node) and service.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.

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 benchmark to 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.

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 test or pytest, 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.

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 add snapshots 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:

pyproject.toml
[project]
dependencies = ["arm_kinematics"]
[tool.uv.sources.arm_kinematics]
git = "https://github.com/acme/robot-libs"
subdirectory = "arm_kinematics"
rev = "<commit>"

When two communicating nodes must agree on shared calculations (such as unit conversions), pin them to the same commit.

  • 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.