Installation

Build the peaqOS ROS 2 packages and configure the unified peaq_robot.yaml.

The peaqOS ROS 2 packages live in peaqnetwork/peaq-robotics-ros2.

Prerequisites

Requirement	Value
ROS 2	Humble (Docker) or Jazzy (native Ubuntu)
Python	≥ 3.10 (Humble) or ≥ 3.12 (Jazzy)
peaq-os-sdk	≥ 0.0.2 (PyPI, pulled in by the workspace). The services drive the Tokenomics 1.0 flow
RPC	peaq mainnet or agung testnet EVM JSON-RPC
Optional	Base mainnet RPC for the peaq ↔ Base bridge

Workspace build

Docker (Humble)

The Docker image ships with ROS 2 Humble, IPFS (Kubo), and Python deps preinstalled.

git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git
cd peaq-robotics-ros2

docker build -t peaq-ros2:latest .

docker run -it --rm \
  --name peaq-ros2-dev \
  -v "$(pwd)":/work \
  -w /work \
  -p 5001:5001 -p 8080:8080 \
  peaq-ros2:latest

# Inside the container:
source /opt/ros/humble/setup.bash
colcon build --packages-select \
  peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
source install/setup.bash

Native (Jazzy)

git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git
cd peaq-robotics-ros2

# Ubuntu 24.04 blocks system-wide pip installs (PEP 668), so use a venv
python3 -m venv --system-site-packages .venv
touch .venv/COLCON_IGNORE
source .venv/bin/activate
pip install -r requirements.txt

source /opt/ros/jazzy/setup.bash
colcon build --packages-select \
  peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
source install/setup.bash

Run source .venv/bin/activate in every shell before ros2 run.

Add peaq_ros2_tether, peaq_ros2_core, or peaq_ros2_humanoids to the --packages-select list when you need the matching node alongside peaqOS.

Unified config

The node reads from a single peaq_robot.yaml. Start from the example, then set peaq_os.faucet.base_url as below and copy the peaq_os.contracts addresses from ROS 2 configuration: the example ships an expired faucet host and an EventRegistry address with no contract behind it.

cp peaq_ros2_examples/config/peaq_robot.example.yaml \
   peaq_ros2_examples/config/peaq_robot.yaml

peaq_os block

peaq_os:
  enabled: true

  # peaq EVM JSON-RPC used by peaq-os-sdk
  rpc_url: "https://quicknode1.peaq.xyz"

  faucet:
    base_url: "https://depinstation.peaq.xyz"
    qr_format: "svg"

  wallet_registry:
    path: "~/.peaq_robot/peaqos_wallets.json"

This block runs the wallet services, faucet access and local event validation. Registration, NFT, DID, event-submission, smart-account and bridge services also need the contract addresses. Mainnet contract addresses, their environment-variable overrides, optional owner/machine/proxy defaults, and operational limits are on ROS 2 configuration. For agung testnet addresses see Install → Agung testnet contracts.

Run the node

ros2 run peaq_ros2_peaqos peaqos_node --ros-args \
  -p config.yaml_path:=peaq_ros2_examples/config/peaq_robot.yaml

Confirm services are registered:

ros2 node list | grep peaqos_node
ros2 service list | grep /peaqos_node/

Run the node in the background and tail logs:

nohup ros2 run peaq_ros2_peaqos peaqos_node --ros-args \
  -p config.yaml_path:=/work/peaq_ros2_examples/config/peaq_robot.yaml \
  > /tmp/peaqos_node.log 2>&1 &

tail -f /tmp/peaqos_node.log

If multiple ROS 2 environments share a host, isolate them with ROS_DOMAIN_ID to prevent service collisions.

Production checklist

• Use a local peaq_robot.yaml; do not commit machine private keys, faucet codes, or RPC tokens.
• Keep peaq_os.wallet_registry.path on encrypted robot storage when possible. Permissions 0600.
• Use a reliable peaq EVM RPC endpoint and monitor rate limits.
• Record pre/post balances for any production bridge or event-spend test.
• Fund Base ETH on the signer before attempting Base → peaq bridge.
• Pin peaqOS contract addresses to the values in Install.

Troubleshooting

Service calls fail with No module named 'peaq_os_sdk'

The workspace expects peaq-os-sdk>=0.0.2. Install it inside the same Python env that runs ros2:

pip install 'peaq-os-sdk>=0.0.2'

Verify with python3 -m pip show peaq-os-sdk.

address/machine_id parsed as a number in YAML payloads

Quote EVM addresses and large integers in ros2 service call payloads:

ros2 service call /peaqos_node/wallet/get \
  peaq_ros2_interfaces/srv/PeaqosGetWallet \
  "{address: '0xAbC...'}"

Bridge calls fail with peaq_os.contracts.machine_nft_adapter is required

peaq_os.contracts.machine_nft_adapter is required only when bridging from peaq. Set it in peaq_robot.yaml or export MACHINE_NFT_ADAPTER_ADDRESS. Agung has no LayerZero DVN routes, so test bridging on peaq mainnet ↔ Base mainnet only.

Continue to the full service reference.