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

# SDK: ROS 2

> ROS 2 services that turn a robot into an on-chain machine actor.

`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

<CardGroup cols={2}>
  <Card title="Machine onboarding" icon="id-card">
    Create local EVM machine wallets, register machines, and fund them through the Gas Station.
  </Card>

  <Card title="Machine identity" icon="fingerprint">
    Mint Machine NFTs and write the standard DID attributes the MCR API understands.
  </Card>

  <Card title="Machine telemetry" icon="bolt">
    Validate single events locally, submit one event, or batch-submit atomically through the peaq batch precompile.
  </Card>

  <Card title="Machine reputation" icon="chart-line">
    Query MCR, machine profiles, and operator fleets from the hosted MCR API.
  </Card>

  <Card title="Machine accounts" icon="wallet">
    Preview and deploy deterministic ERC-4337 smart accounts through `MachineAccountFactory`.
  </Card>

  <Card title="Cross-chain assets" icon="globe">
    Bridge Machine NFTs between peaq and Base via LayerZero V2.
  </Card>
</CardGroup>

## Security model

```text theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
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](/peaqos/sdk-reference/ros2/services). Bridge has its own page on [Bridge](/peaqos/sdk-reference/ros2/bridge).

## Quickstart

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

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
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](/peaqos/sdk-reference/ros2/configuration) for production settings and contract addresses.

Create a wallet, register, mint, and submit an event:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
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](/peaqos/guides/ros2-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

<CardGroup cols={1}>
  <Card title="Configuration" icon="sliders" href="/peaqos/sdk-reference/ros2/configuration">
    YAML fields, contract addresses, wallet registry, API URLs, and environment overrides.
  </Card>

  <Card title="Service catalog" icon="square-terminal" href="/peaqos/sdk-reference/ros2/services">
    Canonical machine endpoints plus documented agent aliases, with request fields and examples.
  </Card>

  <Card title="ROS 2 guide" icon="book-open" href="/peaqos/guides/ros2-machine-runtime">
    Run the machine onboarding, event, MCR, smart-account, and bridge flow from ROS 2.
  </Card>

  <Card title="peaqOS Python SDK" icon="python" href="/peaqos/sdk-reference/sdk-python">
    The PyPI SDK surface wrapped by the ROS 2 node.
  </Card>

  <Card title="peaqOS JavaScript SDK" icon="js" href="/peaqos/sdk-reference/sdk-js">
    The JavaScript SDK surface used for peaqOS application integrations.
  </Card>
</CardGroup>