Coming from ROS 2
ROS 2 is an open-source framework of tools and libraries for robot applications. If you already know ROS 2, this page maps familiar ROS 2 concepts to their Peppy equivalents and compares the two across eleven core workflows.
All ROS 2 links refer to the Lyrical Luth distribution.
ROS 2 terms and Peppy terms
Section titled “ROS 2 terms and Peppy terms”| ROS 2 | Peppy |
|---|---|
| Node | Node (a single running copy is a node instance) |
| Topic | Topic |
| Service | Service |
| Action | Action |
Interface file (.msg, .srv, .action) | Message format inside peppy.json5 or a contract |
| Quality of Service settings | qos_profile on a topic |
| Parameter | Parameter |
Package (package.xml) | Node directory (peppy.json5) |
| Workspace | Repository: local directory or Git repo indexed for nodes, launchers, and contracts |
| Launch file | Launcher |
| ROS graph | Node stack |
ros2 command | peppy command |
ros2 run | peppy node run |
ros2 launch | peppy stack launch |
ros2 node list | peppy stack list |
ros2 node info | peppy node info |
ros2 topic echo | peppy node echo |
colcon build | peppy node build |
The graph
Section titled “The graph”ROS 2. Nodes create publishers and subscriptions at runtime in code (for example, create_publisher in Writing a simple publisher and subscriber (Python)). Discovery connects nodes dynamically after startup. You inspect the live graph with ros2 node list or rqt_graph (see Understanding ROS 2 Topics), assisted by the ROS 2 Daemon cache.
Peppy. Each machine’s daemon owns a node stack: a directed acyclic graph built from depends_on.nodes declarations in peppy.json5, not from runtime code. Edges are validated when nodes are added, before any instance starts. peppy stack list prints each daemon’s nodes, instance bindings, and dependencies (or JSON with --json). Contract dependencies do not add static graph edges; peppy stack list shows them as explicit instance bindings.
Interfaces and errors before the start
Section titled “Interfaces and errors before the start”ROS 2. .msg, .srv, and .action files define message types only (see Interface specifications), built via CMakeLists.txt and package.xml (Custom ROS 2 interfaces). Topic names are strings in node code. Because topics can have zero publishers (Topics), a misspelled topic name silently fails at runtime and receives no messages.
Peppy. peppy.json5 is the single source of truth for a node’s identity, interfaces, parameters, and build/run commands (Node). peppy node sync generates typed Rust or Python modules for every interface (Publishing messages), so node code never writes raw topic strings. Consumers declare sources in depends_on, and Peppy validates that every dependency exists and exposes the required interfaces before any instance starts (How dependencies work).
Running and testing one node alone
Section titled “Running and testing one node alone”ROS 2. ros2 run launches an executable containing one or more nodes (Node management), debuggable via --prefix 'gdb -ex run --args' (Getting Backtraces in ROS 2). Integration tests use launch_testing (Integration testing), where you write mock publisher/subscriber nodes by hand and synchronize with helpers like WaitForTopics.
Peppy. In standalone mode, a node runs directly with cargo run or uv run <node> under any IDE or debugger while still talking to the live stack (Debugging a node).
For automated tests, peppy node sync generates typed mocks for every dependency and an in-process test harness (What sync generates). Pass -r to resolve dependencies from repositories without adding them to the stack (Syncing against repositories). Tests run with no daemon, no external binaries, and no sleeps: startup uses deterministic readiness barriers (A first test).
Build tools
Section titled “Build tools”ROS 2. Uses its own build system (ament) and workspace tool (colcon) across CMake and setuptools packages (Creating a package, Colcon tutorial). You build the workspace with colcon build, run source install/local_setup.bash, and start a node with ros2 run.
Peppy. Has no custom build system. Nodes are standard language projects (cargo for Rust, uv for Python, or any tool such as pip, poetry, or pixi by adding the generated .peppy/libs/peppygen and peppylib paths). peppy.json5 specifies build_cmd and run_cmd (Execution). peppy node build runs build_cmd and caches the artifact; peppy node run executes run_cmd. Container nodes build through an Apptainer definition file instead of build_cmd.
Several machines
Section titled “Several machines”ROS 2. Nodes on the same network with the same ROS_DOMAIN_ID discover each other automatically (Discovery). However, ROS 2 launch files do not support ROS 1’s machine tag (Migrating Launch Files), so you start launch files separately on each machine (Security on Two).
Peppy. Launchers declare logical machine placeholders (core_nodes) instead of hostnames (Core node links). Run peppy platform login once on each machine to enroll it in the same project (Signing in), then launch the entire distributed stack with one command:
peppy stack launch --place robot_onboard@self \ --place cloud_inference@cn-atlas-h100 \ split_compute_manipulationPass --local to run the same multi-machine launcher on one workstation with no file edits (Developing without a second machine). You can also federate without the Peppy platform using your own Zenoh router (Federation outside the Peppy platform).
Contracts
Section titled “Contracts”ROS 2. Topics are anonymous: any publisher and subscriber sharing a topic name and message type connect automatically (Topics), making publishers swappable by convention. Interface files define message types only, not topic, service, or action names.
Peppy. A contract is a standalone document bundling named topics, services, and actions under a name:tag. Producers explicitly declare manifest.implements and cover every member (Producer); consumers declare depends_on.contracts (Consumer). The launcher wires a specific implementing instance to the consumer slot, and Peppy rejects any non-implementing instance before startup. Direct node dependencies (depends_on.nodes) remain available when you do not need abstraction.
Simulation and real hardware with one launcher
Section titled “Simulation and real hardware with one launcher”ROS 2. Launch files toggle between simulation (Simulation) and hardware using launch arguments (DeclareLaunchArgument / <arg>) paired with conditional checks (IfCondition / if) (Using substitutions).
Peppy. Launchers declare component axes: named slots with swappable options (such as mujoco, isaac_sim, or real) (Swapping parts at launch time). Each axis declares provides (the instance IDs every option defines) so links remain valid across swaps. Select options at launch time with --with <option>, as in the Quickstart: peppy stack launch openarm_simulation --with mujoco.
ROS 2. Does not ship a built-in Model Context Protocol (MCP) server (CLI tools, Related projects); you integrate third-party bridges separately.
Peppy. Includes an MCP server inside the peppy binary. An exposure document acts as a strict allowlist mapping contract members to MCP primitives: topics to resources, services to tools, and actions to action-backed tools or MCP tasks (What an exposure publishes). Add the exposure to a launcher and the daemon serves it automatically (Deploy it). Anything not listed in the exposure stays private.
The first run of a robot stack that another team made
Section titled “The first run of a robot stack that another team made”ROS 2: 7 steps with 4 tools (git, rosdep, colcon, and ros2). Steps follow Creating a workspace and Launching multiple nodes.
- Install ROS 2,
colcon,git, androsdep(Installation). - Source the ROS 2 environment:
source /opt/ros/<distro>/setup.bash. - Create a workspace and clone the source:
mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src && git clone <repository>. - Install package dependencies:
rosdep install -i --from-path src --rosdistro <distro> -y. - Build the workspace:
colcon build. - Open a new terminal, source ROS 2 again, and run
source install/local_setup.bash. - Start the stack:
ros2 launch <package> <launch file>.
Peppy: 2 steps with 1 tool (peppy). For launchers in the default repositories (Quickstart):
- Install Peppy:
curl -fsSL https://peppy.bot/install.sh | sh. This installs the CLI, registers the daemon, and indexes the default repositories (Installation). - Launch by name:
peppy stack launch <launcher>(Launching from a repository). Peppy fetches, builds, and starts all nodes in dependency order.
For a third-party Git repository (containing a committed peppy_repository.json5), register it once first with peppy repo add <repository> and peppy repo refresh (Add a repository). Non-container nodes require their build tool (uv, cargo, etc.) installed on the host.
A new message between two nodes
Section titled “A new message between two nodes”ROS 2: 5 steps (Creating custom msg and srv files):
- Add a
.msgfile inside themsg/directory of anament_cmakeinterface package. - Add
find_package(rosidl_default_generators REQUIRED)androsidl_generate_interfaces(...)toCMakeLists.txt. - Add
rosidl_default_generators,rosidl_default_runtime, androsidl_interface_packagesentries topackage.xml. - Build with
colcon build --packages-select <interface_pkg>. - Run
source install/setup.bashin a new terminal.
Then add the interface package to each consumer’s package.xml and rebuild (Test the new interfaces).
Peppy: 2 steps (Writing your first node):
- Declare the topic and its
message_formatunderinterfaces.topics.emitsin the producer’speppy.json5. - Run
peppy node syncin the node directory to generate the typed code.
On the consumer side, add the producer to depends_on.nodes and the topic to interfaces.topics.consumes, then run peppy node sync (or peppy node sync -r to read from repositories) (Consuming a topic).
The tools that build, run and test one node in Python
Section titled “The tools that build, run and test one node in Python”ROS 2: ament and colcon. Requires package.xml, setup.py, setup.cfg, a resource/ marker file, and a package directory inside a workspace (What makes up a ROS 2 package?):
- Build:
colcon buildfrom the workspace root. - Run: source ROS 2, run
source install/local_setup.bash, thenros2 run <package> <node>. - Test:
colcon test(Python testing).
Peppy: standard Python tools. peppy node init --toolchain uv creates a normal uv project with a peppy.json5, and peppy node sync generates its local bindings (Project structure). Run everything from the node directory:
- Build:
uv sync --no-editable(the same command listed inpeppy.json5). - Run standalone:
uv run <node>(Debugging a node). - Test:
uv run --group dev pytest(A first test).
Rust nodes follow the same pattern with cargo build --release, cargo run, and cargo test. When running inside the stack, peppy node build and peppy node run invoke the commands declared in peppy.json5.