Peaq ROS 2 Integration

---
name: peaq-robotics-c12286dc32ab
description: Control peaq-robotics-ros2 from OpenClaw by starting ROS 2 nodes and calling services (DID create/read, storage add/read, access control, tether USDT). Use when requests mention peaq ROS2, robot DID, blockchain storage, access roles/permissions, tether USDT, or ROS 2 service calls.
---

# Peaq ROS 2 Integration

## Overview

Use this skill to make OpenClaw operate a local peaq-robotics-ros2 workspace by starting ROS 2 nodes and calling their services for identity, storage, access control, and tether USDT operations.

## Install and share (first step)

1) Decide how other agents will install the skill:

- Same host, shared: place this folder at `~/.openclaw/skills/peaq-robotics` so all agents on the host see it.
- Per-workspace: place it at `<workspace>/skills/peaq-robotics`.
- Remote agents: publish to ClawHub/ClawdHub, or ship the packaged `peaq-robotics.skill` file.

2) Install the peaq-robotics-ros2 repo (defaults to `https://github.com/peaqnetwork/peaq-robotics-ros2` into `~/peaq-robotics-ros2`). This auto-copies `peaq_robot.example.yaml` to `peaq_robot.yaml`, pins mainnet WSS, and auto-runs `colcon build --symlink-install`:

- `{baseDir}/scripts/peaq_ros2.sh install`
- Optional overrides: `PEAQ_ROS2_REPO_URL=...` and/or `PEAQ_ROS2_REPO_REF=...`
- Update an existing clone: `{baseDir}/scripts/peaq_ros2.sh install --update`
- Skip build if you want to build later: `{baseDir}/scripts/peaq_ros2.sh install --skip-build`

**Requires:** ROS 2 + `colcon` on the host (the installer sources `ROS_SETUP`, default `/opt/ros/humble/setup.bash`).

Network pinning + fallback:
- `PEAQ_ROS2_NETWORK_PRIMARY` (default `wss://quicknode3.peaq.xyz`)
- `PEAQ_ROS2_NETWORK_FALLBACKS` (CSV, default `wss://quicknode1.peaq.xyz,wss://quicknode2.peaq.xyz,wss://peaq.api.onfinality.io/public-ws,wss://peaq-rpc.publicnode.com`)
- `core-configure` will auto-retry and switch networks if the primary fails.
- Set `PEAQ_ROS2_PIN_NETWORK=0` to leave the config network untouched.

Wallet path:
- `PEAQ_ROS2_WALLET_PATH` (optional) to set `wallet.path` during install. Defaults to `~/.peaq_robot/wallet.json`.

3) Configure env vars via OpenClaw skills config so every agent uses the same ROS 2 workspace:

- `PEAQ_ROS2_ROOT` - repo root of peaq-robotics-ros2
- `PEAQ_ROS2_CONFIG_YAML` - path to your config file
- `ROS_DOMAIN_ID` - optional ROS 2 domain isolation
- `PEAQ_ROS2_LOG_DIR` / `PEAQ_ROS2_PID_DIR` - optional overrides (defaults include `-<ROS_DOMAIN_ID>` suffix).

Note: when invoked from an OpenClaw workspace (where `AGENTS.md`/`TOOLS.md` exist) and `PEAQ_ROS2_CONFIG_YAML` is not set, the helper auto-creates a per-workspace config at `<workspace>/.peaq_robot/peaq_robot.yaml` with a workspace-local wallet (`<workspace>/.peaq_robot/wallet.json`). It also auto-assigns a stable `ROS_DOMAIN_ID` in the 100–199 range per workspace (overriding the default `0`) to avoid collisions.

4) Ensure the agent can run host commands (non-sandboxed session or ROS 2 inside the sandbox).

### Invite message templates (copy/paste)

ClawHub/ClawdHub install (preferred for remote agents):

```
clawhub install peaq-robotics && ~/.openclaw/skills/peaq-robotics/scripts/peaq_ros2.sh install
```

Local shared install (same host):

```
cp -R /path/to/peaq-robotics ~/.openclaw/skills/peaq-robotics && ~/.openclaw/skills/peaq-robotics/scripts/peaq_ros2.sh install
```

Restart the OpenClaw session after installing the skill.

## Bootstrap agent (funding source)

1) Ensure the ROS 2 workspace is built and you have a config YAML (usually `peaq_ros2_examples/config/peaq_robot.yaml`).
2) Start core node and activate it:

- `{baseDir}/scripts/peaq_ros2.sh core-start`
- `{baseDir}/scripts/peaq_ros2.sh core-configure`
- `{baseDir}/scripts/peaq_ros2.sh core-activate`

3) Get wallet address and DID (send address to yourself for funding):

- `{baseDir}/scripts/peaq_ros2.sh core-address`
- `{baseDir}/scripts/peaq_ros2.sh core-did`

4) Fund this address with peaq tokens. This becomes the funding source for new agents.

## New agent onboarding flow

1) Install the skill (shared host path, workspace path, or ClawHub/ClawdHub).
2) Set `PEAQ_ROS2_ROOT` and `PEAQ_ROS2_CONFIG_YAML` via skills config.
3) Start core node + configure + activate.
4) Run `{baseDir}/scripts/peaq_ros2.sh core-address` and ask the bootstrap agent to fund it.
5) After funding, run `{baseDir}/scripts/peaq_ros2.sh did-create '{"type":"robot"}'`.

### Core bootstrap (human-friendly)

```
~/.openclaw/skills/peaq-robotics/scripts/peaq_ros2.sh core-start && \
~/.openclaw/skills/peaq-robotics/scripts/peaq_ros2.sh core-configure && \
~/.openclaw/skills/peaq-robotics/scripts/peaq_ros2.sh core-activate
```

Use `fund-request` separately to ask for funds.

### Funding request template (copy/paste)

```
peaq-robotics funding request:
address: <PASTE_CORE_ADDRESS>
reason: initial DID creation + storage/access ops
amount: <AMOUNT> PEAQ
```

### Funding (agent → agent)

Use the funded agent to transfer PEAQ to a new agent address:

- Check balance: `{baseDir}/scripts/peaq_ros2.sh balance [address]`
- Fund another agent: `{baseDir}/scripts/peaq_ros2.sh fund <to_address> <amount>`
- Generate a request: `{baseDir}/scripts/peaq_ros2.sh fund-request [amount] [reason]`
- Auto-send request to a funder agent: `{baseDir}/scripts/peaq_ros2.sh fund-request-send <funder_agent_id> [amount] [reason]`

Notes:
- `fund` uses the local agent wallet from `wallet.path` in config.
- Amount is in PEAQ by default; use `--planck` to send raw planck units.
- If a fund transfer returns a transient websocket error, the script checks for a balance delta before failing.
- Storage bridge defaults to local IPFS when Pinata is not configured (`storage.mode` missing or pinata.jwt empty).

### One-line funding request (copy/paste)

```
peaq-robotics fund-request: address=<ADDRESS> amount=<AMOUNT> PEAQ reason="DID + storage init"
```

### Auto-message the funder (agent → agent)

If you know the funder agent id, use OpenClaw’s agent-to-agent tool to send the request line:

1) Generate the line: `{baseDir}/scripts/peaq_ros2.sh fund-request [amount] [reason]`
2) Send it via `sessions_send` to the funder agent.

If you’re running outside the agent runtime, you can also use the helper:
`{baseDir}/scripts/peaq_ros2.sh fund-request-send <funder_agent_id> [amount] [reason]`

### Agent-to-agent messaging (OpenClaw)

Agents can talk via OpenClaw sessions:

1) Create another agent: `openclaw agents add <agent-id> --workspace <dir> --non-interactive`
2) Send a message: `openclaw agent --agent <agent-id> --message "<your message>"`

Use this to send the `fund-request` line to your funding agent.

## Identity card (DID-linked contact record)

Use identity cards to make DIDs actionable as agent contact records (name, roles, endpoints). These are embedded in the DID document during creation.

- Build JSON (no chain write): `{baseDir}/scripts/peaq_ros2.sh identity-card-json [name] [roles_csv] [endpoints_json] [metadata_json]`
- Create DID with identity card metadata: `{baseDir}/scripts/peaq_ros2.sh identity-card-did-create [name] [roles_csv] [endpoints_json] [metadata_json]`
- Read identity card from DID: `{baseDir}/scripts/peaq_ros2.sh identity-card-did-read`

Schema (identity card JSON):
```
{
  "schema": "peaq.identityCard.v1",
  "name": "Agent Name",
  "roles": ["funder", "operator"],
  "endpoints": {"openclaw": {"agentId": "funder"}},
  "metadata": { "any": "extra fields" }
}
```

Notes:
- `name` defaults to the OpenClaw agent id (if available), else hostname.
- For existing DIDs, updates are not supported by the ROS2 core service (create-only). Create the identity card during DID creation.

## Core workflows

### Start nodes (typical)

1) Start the core node and activate it:

- `{baseDir}/scripts/peaq_ros2.sh core-start`
- `{baseDir}/scripts/peaq_ros2.sh core-configure`
- `{baseDir}/scripts/peaq_ros2.sh core-activate`

Run `fund-request` separately once the core is active.

2) Optional nodes:

- Storage bridge: `{baseDir}/scripts/peaq_ros2.sh storage-start`
- Events node: `{baseDir}/scripts/peaq_ros2.sh events-start`
- Tether node: `{baseDir}/scripts/peaq_ros2.sh tether-start` (requires tether config + npm install in `peaq_ros2_tether/js`)
- Humanoid bridge: `{baseDir}/scripts/peaq_ros2.sh humanoid-start`

### Call services

Use the helper script subcommands for the common service calls:

- Create DID (defaults to `{"type":"robot"}` if omitted): `{baseDir}/scripts/peaq_ros2.sh did-create`
- Create DID with metadata JSON or full DID doc JSON: `{baseDir}/scripts/peaq_ros2.sh did-create '{"type":"robot"}'`
- Create DID from file: `{baseDir}/scripts/peaq_ros2.sh did-create @/path/to/did_doc.json`
- Read DID: `{baseDir}/scripts/peaq_ros2.sh did-read`
- Store data: `{baseDir}/scripts/peaq_ros2.sh store-add sensor_data '{"temp":25.5}' FAST`
- Read data: `{baseDir}/scripts/peaq_ros2.sh store-read sensor_data`
- Access control: `{baseDir}/scripts/peaq_ros2.sh access-create-role operator 'Robot operator'`

Notes:
- `did-create` treats JSON with DID fields (`id`, `controller`, `services`, `verificationMethods`, etc.) as a full DID document.
- Plain metadata JSON is wrapped into a DID `services` entry (`type: peaqMetadata`) so it is preserved on-chain.

For full service/parameter mappings and raw ROS 2 topic/service names, read `references/peaq_ros2_services.md`.

## Safety and guardrails

- Confirm before actions that incur on-chain cost or real funds (DID creation, storage writes, access changes, USDT transfers).
- Never pass private keys or mnemonics through ROS 2 services; tether operations use address-only calls.
- If running multiple ROS 2 graphs on one host, set `ROS_DOMAIN_ID` per environment to avoid collisions.

## References

- Service map: `references/peaq_ros2_services.md`