peaq-robotics

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