Documentation Index Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt
Use this file to discover all available pages before exploring further.
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 blockpeaq_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 : "0x43c6c12eecAf4fB3F164375A9c44f8a6Efc139b9" 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 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 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 . 
