Installation

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
`peaq-os-sdk`	≥ 0.0.2 (PyPI, pulled in by the workspace)
RPC	peaq mainnet or agung testnet EVM JSON-RPC
Optional	Base mainnet RPC for the peaq ↔ Base bridge

Workspace build

Docker (Humble)
Native (Jazzy)

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

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

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

Add peaq_ros2_tether, peaq_ros2_core, or peaq_ros2_openclaw 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 and fill in placeholders:

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"

  # Hosted MCR API. Use http://127.0.0.1:8000 to read from a local MCR server.
  api_url: "https://mcr.peaq.xyz"

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

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

  defaults:
    owner_address: ""
    machine_address: ""
    proxy_address: ""

  contracts:
    # Current peaq mainnet proxy addresses.
    identity_registry: "0xb53Af985765031936311273599389b5B68aC9956"
    identity_staking: "0x11c05A650704136786253e8685f56879A202b1C7"
    event_registry: "0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA"
    machine_nft: "0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9"
    did_registry: "0x0000000000000000000000000000000000000800"
    batch_precompile: "0x0000000000000000000000000000000000000805"
    # Required only for smart-account and peaq → Base bridge calls.
    machine_account_factory: "0x4A808d5A90A2c91739E92C70aF19924e0B3D527f"
    machine_nft_adapter: "0x9AD5408702EC204441A88589B99ADfC2514AFAE6"

  operational_limits:
    # All zeros disable SDK-side event limits.
    max_value_per_tx: 0
    rate_limit_max_events: 0
    rate_limit_window_seconds: 0

For agung testnet addresses see Install → Agung testnet contracts.

Environment overrides

The same overrides recognized by the Python SDK and JS SDK work here. Useful when you pin contract addresses externally:

export EVENT_REGISTRY_ADDRESS=0x...
export MACHINE_ACCOUNT_FACTORY_ADDRESS=0x...
export MACHINE_NFT_ADAPTER_ADDRESS=0x...
export BATCH_PRECOMPILE_ADDRESS=0x...

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 , faucet codes, or RPC tokens.
Keep peaq_os.wallet_registry.path on encrypted robot storage when possible. Permissions 0600.
Use a reliable peaq EVM and monitor rate limits.
Record pre/post balances for any production bridge or event-spend test.
Fund Base ETH on the before attempting Base → peaq .
Pin peaqOS contract addresses to the values in Install unless deployment docs change.

Troubleshooting

Service exits with `peaq-os-sdk not installed`

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 -c "import peaq_os_sdk; print(peaq_os_sdk.__version__)".

`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 `MachineNFTAdapter not configured`

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 — test bridging on peaq mainnet ↔ Base mainnet only.

Continue to the full service reference.

​Prerequisites

​Workspace build

​Unified config

​peaq_os block

​Environment overrides

​Run the node

​Production checklist

​Troubleshooting