SDK: ROS 2 - peaq

peaq_ros2_peaqos maps the peaqOS Python capability surface into typed ROS 2 services. It is for robot teams that already run ROS 2 and want peaqOS primitives without passing through ROS messages. ROS 2 stays the robot control plane; peaqOS becomes the machine economy and identity plane. The services wrap the Python SDK’s register_machine, register_for, mint_nft, and DID-attribute calls, which onboard machines on the Tokenomics 1.0 contracts. Economics 2.0 activation (activate_machine) has no ROS 2 service. See Activate.

What it does

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.

Machine telemetry

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

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

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 used for a single request. Do not log them.

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
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

The node also registers mcr/query, mcr/machine and mcr/operator_machines. They do not work with the MCR API, which covers Economics 2.0 machines only. Query MCR with the Python SDK or the MCR API instead. Full service-by-service reference with example payloads is on Services. Bridge has its own page on Bridge. A Base to peaq call needs Base ETH on the wallet for .

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: install requirements.txt into a venv created with --system-site-packages (see Installation).

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: set peaq_os.enabled: true,
# peaq_os.faucet.base_url: https://depinstation.peaq.xyz, and
# peaq_os.contracts.event_registry: 0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA
# (the example file ships an older faucet host and EventRegistry address).

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. Tokenomics 1.0 only: create a wallet, register, mint, and submit an event. New machines onboard with the Economics 2.0 flow in Activate, which has no ROS 2 service.

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: '0x7b7d', trust_level: 0, 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.

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.

Stream Edge Agent

Sign, encrypt, and sell machine data from a ROS 2 node, the on-machine half of Stream.

ROS 2 guide

Run the Tokenomics 1.0 onboarding, event, 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.

​What it does