ROS 2 machine runtime

This guide is for teams that use ROS 2 as the robot control plane and want peaqOS as the machine identity, credit, and asset layer. The ROS 2 wraps the same peaqOS capabilities documented in the JavaScript SDK and Python SDK, but changes the security boundary: callers pass addresses over ROS, while stay in a local registry file.

Prerequisites

ROS 2 Jazzy on a native host, or the repository Docker image with ROS 2 Humble
A peaq EVM
https://mcr.peaq.xyz for MCR reads
https://depinstation.peaq.network for flows
A funded peaq EVM signer for registration, , events, , and
ETH on the signer only if you need Base to peaq bridge operations

Configure

Create a local config:

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

Set the peaqOS section:

peaq_os:
  enabled: true
  rpc_url: "https://quicknode1.peaq.xyz"
  api_url: "https://mcr.peaq.xyz"

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

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

Do not commit peaq_robot.yaml after adding real addresses, local registry paths, or operational credentials.

Build and start

source /opt/ros/jazzy/setup.bash
# In the Docker image, use: source /opt/ros/humble/setup.bash
python3 -m pip install -r requirements.txt

colcon build --packages-select peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
source install/setup.bash

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

Open another terminal, source the same ROS environment, then call services.

1. Create a local machine wallet

ros2 service call /peaqos_node/wallet/create \
  peaq_ros2_interfaces/srv/PeaqosCreateWallet \
  "{label: 'robot-001'}"

Save the returned address. The private key is stored in the local registry and is not returned. You can inspect or remove local wallet metadata without exposing keys:

ros2 service call /peaqos_node/wallet/list \
  peaq_ros2_interfaces/srv/PeaqosListWallets \
  "{}"

ros2 service call /peaqos_node/wallet/get \
  peaq_ros2_interfaces/srv/PeaqosGetWallet \
  "{address: '<MACHINE_EVM_ADDRESS>'}"

The returned wallet JSON includes public peaq EVM account metadata: address, account_id, chain_id, network, label, and created_at.

2. Fund the machine wallet

Registration signs from the machine wallet and requires enough native peaq for plus the IdentityRegistry registration . Fund the returned <MACHINE_EVM_ADDRESS> before calling register. You can use the Gas Station flow with owner 2FA:

ros2 service call /peaqos_node/faucet/setup_2fa \
  peaq_ros2_interfaces/srv/PeaqosSetupFaucet2FA \
  "{owner_address: '<OWNER_EVM_ADDRESS>', qr_format: 'svg'}"

ros2 service call /peaqos_node/faucet/confirm_2fa \
  peaq_ros2_interfaces/srv/PeaqosConfirmFaucet2FA \
  "{owner_address: '<OWNER_EVM_ADDRESS>', two_factor_code: '123456'}"

ros2 service call /peaqos_node/wallet/fund \
  peaq_ros2_interfaces/srv/PeaqosFundWallet \
  "{owner_address: '<OWNER_EVM_ADDRESS>', target_address: '<MACHINE_EVM_ADDRESS>', chain_id: '3338', two_factor_code: '123456', request_id: ''}"

Or transfer native peaq directly to <MACHINE_EVM_ADDRESS> from an already funded wallet. Wait for the balance to be available before registration.

3. Register the machine

For a self-managed machine, the node looks up <MACHINE_EVM_ADDRESS> in the local registry and signs the registration transaction with that wallet. For a self-managed machine:

ros2 service call /peaqos_node/machine/register \
  peaq_ros2_interfaces/srv/PeaqosRegisterMachine \
  "{address: '<MACHINE_EVM_ADDRESS>'}"

For a :

ros2 service call /peaqos_node/machine/register_for \
  peaq_ros2_interfaces/srv/PeaqosRegisterFor \
  "{proxy_address: '<PROXY_EVM_ADDRESS>', machine_address: '<MACHINE_EVM_ADDRESS>'}"

Registration returns machine_id. This is the IdentityRegistry . It is not necessarily the .

4. Mint the Machine NFT and write DID attributes

ros2 service call /peaqos_node/nft/mint \
  peaq_ros2_interfaces/srv/PeaqosMintNft \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', machine_id: 1, recipient: '<MACHINE_EVM_ADDRESS>'}"

Read the Machine NFT token ID:

ros2 service call /peaqos_node/nft/token_id_of \
  peaq_ros2_interfaces/srv/PeaqosTokenIdOf \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', machine_id: 1}"

Link the machine’s to its Machine NFT and metadata endpoints:

ros2 service call /peaqos_node/did/write_machine_attributes \
  peaq_ros2_interfaces/srv/PeaqosWriteMachineDidAttributes \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', machine_id: 1, nft_token_id: 1, operator_did: 'did:peaq:<OPERATOR_EVM_ADDRESS>', documentation_url: 'https://docs.example/robot-001', data_api: 'https://api.example/robot-001', data_visibility: 'onchain'}"

Verify a single attribute:

ros2 service call /peaqos_node/did/read_attribute \
  peaq_ros2_interfaces/srv/PeaqosReadDidAttribute \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', did_address: '<MACHINE_EVM_ADDRESS>', name: 'machineId'}"

5. Query MCR and machine profile

ros2 service call /peaqos_node/mcr/query \
  peaq_ros2_interfaces/srv/PeaqosQueryMcr \
  "{did: 'did:peaq:<MACHINE_EVM_ADDRESS>'}"

ros2 service call /peaqos_node/mcr/machine \
  peaq_ros2_interfaces/srv/PeaqosQueryMachine \
  "{did: 'did:peaq:<MACHINE_EVM_ADDRESS>'}"

Newly registered machines can return Provisioned until enough history exists.

6. Validate and submit events

Validate before broadcasting:

ros2 service call /peaqos_node/events/validate \
  peaq_ros2_interfaces/srv/PeaqosValidateEvent \
  "{machine_id: 1, event_type: 1, value: 1, timestamp: 1770000000, raw_data_hex: '0x73656e736f723a6f6b', trust_level: 0, source_chain_id: 3338, source_tx_hash: '', metadata_hex: '0x7b7d'}"

Submit one event:

ros2 service call /peaqos_node/events/submit \
  peaq_ros2_interfaces/srv/PeaqosSubmitEvent \
  "{signer_address: '<MACHINE_EVM_ADDRESS>', machine_id: 1, event_type: 1, value: 1, timestamp: 1770000000, raw_data_hex: '0x73656e736f723a6f6b', trust_level: 0, source_chain_id: 3338, source_tx_hash: '', metadata_hex: '0x7b7d'}"

Batch submission uses events_json, a JSON array using the same event field names.

7. Predict or deploy a machine smart account

ros2 service call /peaqos_node/smart_account/address \
  peaq_ros2_interfaces/srv/PeaqosGetSmartAccountAddress \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', owner: '<OWNER_EVM_ADDRESS>', machine: '<MACHINE_EVM_ADDRESS>', daily_limit: '', salt: '0'}"

Deploy with the same parameters:

ros2 service call /peaqos_node/smart_account/deploy \
  peaq_ros2_interfaces/srv/PeaqosDeploySmartAccount \
  "{signer_address: '<SIGNER_EVM_ADDRESS>', owner: '<OWNER_EVM_ADDRESS>', machine: '<MACHINE_EVM_ADDRESS>', daily_limit: '', salt: '0'}"

8. Bridge Machine NFT from peaq to Base

ros2 service call /peaqos_node/bridge/nft \
  peaq_ros2_interfaces/srv/PeaqosBridgeNft \
  "{signer_address: '<OWNER_EVM_ADDRESS>', token_id: 1, source: 'peaq', destination: 'base', recipient: '<RECIPIENT_EVM_ADDRESS>', base_rpc_url: '', base_nft_address: '', options_hex: ''}"

Wait for the to appear on Base:

ros2 service call /peaqos_node/bridge/wait_arrival \
  peaq_ros2_interfaces/srv/PeaqosWaitForBridgeArrival \
  "{dst_rpc_url: 'https://mainnet.base.org', dst_nft_address: '0xee8A521eA434b11F956E2402beC5eBfa753Babfa', token_id: 1, timeout: 900}"

Production checklist

Keep peaq_os.wallet_registry.path local to the robot or machine.
Keep the wallet registry file permissioned as 0600.
Quote all EVM addresses in ROS YAML service payloads.
Record pre and post balances for production bridge or payment tests.
Confirm contract addresses before release if peaqOS publishes a new deployment.
Fund Base ETH before attempting Base to peaq bridge operations.

Welcome

Get Started

Concepts

Functions

Guides

ROS 2 machine runtime

Prerequisites

Configure

Build and start

1. Create a local machine wallet

2. Fund the machine wallet

3. Register the machine

4. Mint the Machine NFT and write DID attributes

5. Query MCR and machine profile

6. Validate and submit events

7. Predict or deploy a machine smart account

8. Bridge Machine NFT from peaq to Base

Production checklist

References

​Prerequisites

​Configure

​Build and start

​1. Create a local machine wallet

​2. Fund the machine wallet

​3. Register the machine

​4. Mint the Machine NFT and write DID attributes

​5. Query MCR and machine profile

​6. Validate and submit events

​7. Predict or deploy a machine smart account

​8. Bridge Machine NFT from peaq to Base

​Production checklist

​References

Prerequisites

Configure

Build and start

1. Create a local machine wallet

2. Fund the machine wallet

3. Register the machine

4. Mint the Machine NFT and write DID attributes

5. Query MCR and machine profile

6. Validate and submit events

7. Predict or deploy a machine smart account

8. Bridge Machine NFT from peaq to Base

Production checklist

References