Skip to main content
The peaqOS ROS 2 packages live in peaqnetwork/peaq-robotics-ros2.

​
Prerequisites

RequirementValue
ROS 2Humble (Docker) or Jazzy (native Ubuntu)
Python≥ 3.10
peaq-os-sdk≥ 0.2.0 (PyPI, pulled in by the workspace)
RPCpeaq mainnet or agung testnet EVM JSON-RPC
OptionalBase mainnet RPC for the peaq ↔ Base bridge

​
Workspace build

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

​
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

The workspace expects peaq-os-sdk>=0.2.0. Install it inside the same Python env that runs ros2:
pip install 'peaq-os-sdk>=0.2.0'
Verify with python3 -c "import peaq_os_sdk; print(peaq_os_sdk.__version__)".
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...'}"
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.