SDK: ROS 2 - peaq

peaq_ros2_peaqos maps the peaqOS Python SDK capability surface into typed ROS 2 services. It is for robot teams that already run ROS 2 and want peaqOS primitives without passing private keys through ROS messages. ROS 2 stays the robot control plane; peaqOS becomes the machine economy and identity plane.

What it unlocks

Machine onboarding

Create local EVM machine wallets, register machines, and fund them through the Gas Station.

Machine identity

Mint Machine NFTs and write the standard DID attributes the MCR API understands.

Machine telemetry

Validate single events locally, submit one event, or batch-submit atomically through the peaq batch precompile.

Machine reputation

Query MCR, machine profiles, and operator fleets from the hosted MCR API.

Machine accounts

Preview and deploy deterministic ERC-4337 smart accounts through MachineAccountFactory.

Cross-chain assets

Bridge Machine NFTs between peaq and Base via LayerZero V2.

Security model

Robot process
  |
  | ROS 2 service call (address only, no keys)
  v
peaqos_node
  |
  | local wallet lookup by EVM address
  v
peaq-os-sdk (PyPI) ---> peaq EVM RPC, MCR API, Gas Station API, Base RPC
                         |
                         v
                  peaqOS contracts and services

Wallet private keys live in one local registry file on the robot or machine (default ~/.peaq_robot/peaqos_wallets.json, perms 0600).
ROS callers pass EVM addresses, not private keys.
The node never accepts or returns private keys over ROS.
Wallet list / get / delete expose only public metadata: address, account_id, chain_id, network, label, created_at.
Faucet 2FA codes are request-only and should not be logged.

Service map

Area	Service	Purpose
Wallet	`/peaqos_node/wallet/create`	Create a locally stored EVM wallet
Wallet	`/peaqos_node/wallet/list`	List local wallet public metadata
Wallet	`/peaqos_node/wallet/get`	Get one wallet’s public metadata
Wallet	`/peaqos_node/wallet/delete`	Delete one local wallet
Faucet	`/peaqos_node/faucet/setup_2fa`	Start faucet 2FA enrollment
Faucet	`/peaqos_node/faucet/confirm_2fa`	Confirm faucet 2FA
Faucet	`/peaqos_node/wallet/fund`	Request Gas Station funding
Onboarding	`/peaqos_node/machine/register`	Register the local machine wallet
Onboarding	`/peaqos_node/agent/register`	Same handler, agent-flavored alias
Onboarding	`/peaqos_node/machine/register_for`	Register a machine through a proxy operator
Onboarding	`/peaqos_node/agent/register_for`	Same handler, agent-flavored alias
NFT	`/peaqos_node/nft/mint`	Mint a Machine NFT
NFT	`/peaqos_node/nft/token_id_of`	Read a machine’s NFT token ID
DID	`/peaqos_node/did/read_attribute`	Read one DID precompile attribute
DID	`/peaqos_node/did/write_machine_attributes`	Write the standard machine DID attributes
DID	`/peaqos_node/did/write_proxy_attributes`	Write proxy/operator DID attributes
Events	`/peaqos_node/events/validate`	Validate event payload and compute data hash
Events	`/peaqos_node/events/submit`	Submit one event through `EventRegistry`
Events	`/peaqos_node/events/batch_submit`	Atomic batch submit through the batch precompile
MCR	`/peaqos_node/mcr/query`	Query Machine Credit Rating
MCR	`/peaqos_node/mcr/machine`	Query machine profile
MCR	`/peaqos_node/mcr/operator_machines`	Query an operator’s fleet
Smart account	`/peaqos_node/smart_account/address`	Predict deterministic smart-account address
Smart account	`/peaqos_node/smart_account/deploy`	Deploy machine smart account
Bridge	`/peaqos_node/bridge/nft`	Bridge Machine NFT between peaq and Base
Bridge	`/peaqos_node/bridge/wait_arrival`	Poll destination chain until bridged NFT arrives

Full service-by-service reference with example payloads is on Services. Bridge has its own page on Bridge.

Quickstart

Build and source the workspace, copy the example config, then start the node against your unified config:

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

source /opt/ros/jazzy/setup.bash
# Use /opt/ros/humble/setup.bash inside the Docker image.
# Native host only: python3 -m pip install -r requirements.txt

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

cp peaq_ros2_examples/config/peaq_robot.example.yaml peaq_ros2_examples/config/peaq_robot.yaml
# Edit peaq_ros2_examples/config/peaq_robot.yaml and set peaq_os.enabled: true.

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

The node reads one unified YAML file. See ROS 2 configuration for production settings and contract addresses. Create a wallet, register, mint, and submit an event:

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

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

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

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: '0x', trust_level: 1, source_chain_id: 3338, source_tx_hash: '', metadata_hex: '0x7b7d'}"

End-to-end commands are in ROS 2 machine runtime.

ROS distro support

Distro	Status
ROS 2 Humble	Supported (Docker image default)
ROS 2 Jazzy	Supported (native Ubuntu hosts)

Native install on non-Linux hosts is best done via Docker or WSL.

What’s tested on mainnet

This release path has been exercised on a ROS 2 Jazzy Ubuntu server against peaq mainnet:

Wallet create / list / get / delete public-metadata lifecycle
Machine NFT token lookup
DID readAttribute
MCR query, machine query, and operator machines query
Event validation, single submission, and batch submission via the batch precompile
Deterministic smart-account address calculation
Smart-account deployment through MachineAccountFactory
peaq to Base Machine NFT bridge through MachineNFTAdapter
Base arrival polling for the bridged Machine NFT

Reverse Base to peaq bridge requires Base ETH on the signer wallet for gas.

Keep going

Configuration

YAML fields, contract addresses, wallet registry, API URLs, and environment overrides.

Service catalog

Canonical machine endpoints plus documented agent aliases, with request fields and examples.

ROS 2 guide

Run the machine onboarding, event, MCR, smart-account, and bridge flow from ROS 2.

peaqOS Python SDK

The PyPI SDK surface wrapped by the ROS 2 node.

peaqOS JavaScript SDK

The JavaScript SDK surface used for peaqOS application integrations.

SDK Reference

Documentation Index

​What it unlocks