Skip to content

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 2Peppy
NodeNode (a single running copy is a node instance)
TopicTopic
ServiceService
ActionAction
Interface file (.msg, .srv, .action)Message format inside peppy.json5 or a contract
Quality of Service settingsqos_profile on a topic
ParameterParameter
Package (package.xml)Node directory (peppy.json5)
WorkspaceRepository: local directory or Git repo indexed for nodes, launchers, and contracts
Launch fileLauncher
ROS graphNode stack
ros2 commandpeppy command
ros2 runpeppy node run
ros2 launchpeppy stack launch
ros2 node listpeppy stack list
ros2 node infopeppy node info
ros2 topic echopeppy node echo
colcon buildpeppy node build

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.

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

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

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.

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:

Terminal window
peppy stack launch --place robot_onboard@self \
--place cloud_inference@cn-atlas-h100 \
split_compute_manipulation

Pass --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).

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.

  1. Install ROS 2, colcon, git, and rosdep (Installation).
  2. Source the ROS 2 environment: source /opt/ros/<distro>/setup.bash.
  3. Create a workspace and clone the source: mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src && git clone <repository>.
  4. Install package dependencies: rosdep install -i --from-path src --rosdistro <distro> -y.
  5. Build the workspace: colcon build.
  6. Open a new terminal, source ROS 2 again, and run source install/local_setup.bash.
  7. Start the stack: ros2 launch <package> <launch file>.

Peppy: 2 steps with 1 tool (peppy). For launchers in the default repositories (Quickstart):

  1. Install Peppy: curl -fsSL https://peppy.bot/install.sh | sh. This installs the CLI, registers the daemon, and indexes the default repositories (Installation).
  2. 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.

ROS 2: 5 steps (Creating custom msg and srv files):

  1. Add a .msg file inside the msg/ directory of an ament_cmake interface package.
  2. Add find_package(rosidl_default_generators REQUIRED) and rosidl_generate_interfaces(...) to CMakeLists.txt.
  3. Add rosidl_default_generators, rosidl_default_runtime, and rosidl_interface_packages entries to package.xml.
  4. Build with colcon build --packages-select <interface_pkg>.
  5. Run source install/setup.bash in 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):

  1. Declare the topic and its message_format under interfaces.topics.emits in the producer’s peppy.json5.
  2. Run peppy node sync in 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?):

  1. Build: colcon build from the workspace root.
  2. Run: source ROS 2, run source install/local_setup.bash, then ros2 run <package> <node>.
  3. 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:

  1. Build: uv sync --no-editable (the same command listed in peppy.json5).
  2. Run standalone: uv run <node> (Debugging a node).
  3. 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.