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

# Installation

> Build the peaqOS ROS 2 packages and configure the unified peaq_robot.yaml.

The peaqOS ROS 2 packages live in [`peaqnetwork/peaq-robotics-ros2`](https://github.com/peaqnetwork/peaq-robotics-ros2).

## Prerequisites

| Requirement   | Value                                       |
| :------------ | :------------------------------------------ |
| ROS 2         | Humble (Docker) or Jazzy (native Ubuntu)    |
| Python        | ≥ 3.10                                      |
| `peaq-os-sdk` | ≥ 0.0.2 (PyPI, pulled in by the workspace)  |
| RPC           | peaq mainnet or agung testnet EVM JSON-RPC  |
| Optional      | Base mainnet RPC for the peaq ↔ Base bridge |

## Workspace build

<Tabs>
  <Tab title="Docker (Humble)">
    The Docker image ships with ROS 2 Humble, IPFS (Kubo), and Python deps preinstalled.

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git
    cd peaq-robotics-ros2

    docker build -t peaq-ros2:latest .

    docker run -it --rm \
      --name peaq-ros2-dev \
      -v "$(pwd)":/work \
      -w /work \
      -p 5001:5001 -p 8080:8080 \
      peaq-ros2:latest

    # Inside the container:
    source /opt/ros/humble/setup.bash
    colcon build --packages-select \
      peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
    source install/setup.bash
    ```
  </Tab>

  <Tab title="Native (Jazzy)">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    git clone https://github.com/peaqnetwork/peaq-robotics-ros2.git
    cd peaq-robotics-ros2

    pip install -r requirements.txt

    source /opt/ros/jazzy/setup.bash
    colcon build --packages-select \
      peaq_ros2_interfaces peaq_ros2_peaqos peaq_ros2_examples
    source install/setup.bash
    ```

    Add `peaq_ros2_tether`, `peaq_ros2_core`, or `peaq_ros2_openclaw` to the `--packages-select` list when you need the matching node alongside peaqOS.
  </Tab>
</Tabs>

## Unified config

The node reads from a single `peaq_robot.yaml`. Start from the example and fill in placeholders:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
cp peaq_ros2_examples/config/peaq_robot.example.yaml \
   peaq_ros2_examples/config/peaq_robot.yaml
```

### `peaq_os` block

```yaml theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
peaq_os:
  enabled: true

  # peaq EVM JSON-RPC used by peaq-os-sdk
  rpc_url: "https://quicknode1.peaq.xyz"

  # Hosted MCR API. Use http://127.0.0.1:8000 to read from a local MCR server.
  api_url: "https://mcr.peaq.xyz"

  faucet:
    base_url: "https://depinstation.peaq.network"
    qr_format: "svg"

  wallet_registry:
    path: "~/.peaq_robot/peaqos_wallets.json"

  defaults:
    owner_address: ""
    machine_address: ""
    proxy_address: ""

  contracts:
    # Current peaq mainnet proxy addresses.
    identity_registry: "0xb53Af985765031936311273599389b5B68aC9956"
    identity_staking: "0x11c05A650704136786253e8685f56879A202b1C7"
    event_registry: "0x43c6AF2E14dc1327dc3cc6c7117D1CD72fffEcbA"
    machine_nft: "0x2943F80e9DdB11B9Dd275499C661Df78F5F691F9"
    did_registry: "0x0000000000000000000000000000000000000800"
    batch_precompile: "0x0000000000000000000000000000000000000805"
    # Required only for smart-account and peaq → Base bridge calls.
    machine_account_factory: "0x4A808d5A90A2c91739E92C70aF19924e0B3D527f"
    machine_nft_adapter: "0x9AD5408702EC204441A88589B99ADfC2514AFAE6"

  operational_limits:
    # All zeros disable SDK-side event limits.
    max_value_per_tx: 0
    rate_limit_max_events: 0
    rate_limit_window_seconds: 0
```

For agung testnet addresses see [Install → Agung testnet contracts](/peaqos/install#agung-testnet-contracts).

### Environment overrides

The same overrides recognized by the [Python SDK](/peaqos/sdk-reference/sdk-python) and [JS SDK](/peaqos/sdk-reference/sdk-js) work here. Useful when you pin contract addresses externally:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
export EVENT_REGISTRY_ADDRESS=0x...
export MACHINE_ACCOUNT_FACTORY_ADDRESS=0x...
export MACHINE_NFT_ADAPTER_ADDRESS=0x...
export BATCH_PRECOMPILE_ADDRESS=0x...
```

## Run the node

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
ros2 run peaq_ros2_peaqos peaqos_node --ros-args \
  -p config.yaml_path:=peaq_ros2_examples/config/peaq_robot.yaml
```

Confirm services are registered:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
ros2 node list | grep peaqos_node
ros2 service list | grep /peaqos_node/
```

Run the node in the background and tail logs:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
nohup ros2 run peaq_ros2_peaqos peaqos_node --ros-args \
  -p config.yaml_path:=/work/peaq_ros2_examples/config/peaq_robot.yaml \
  > /tmp/peaqos_node.log 2>&1 &

tail -f /tmp/peaqos_node.log
```

If multiple ROS 2 environments share a host, isolate them with `ROS_DOMAIN_ID` to prevent service collisions.

## Production checklist

* Use a local `peaq_robot.yaml`; do not commit machine private keys, faucet codes, or RPC tokens.
* Keep `peaq_os.wallet_registry.path` on encrypted robot storage when possible. Permissions `0600`.
* Use a reliable peaq EVM RPC endpoint and monitor rate limits.
* Record pre/post balances for any production bridge or event-spend test.
* Fund Base ETH on the signer before attempting Base → peaq bridge.
* Pin peaqOS contract addresses to the values in [Install](/peaqos/install#peaq-mainnet-contracts) unless deployment docs change.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Service exits with `peaq-os-sdk not installed`">
    The workspace expects `peaq-os-sdk>=0.0.2`. Install it inside the same Python env that runs `ros2`:

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    pip install 'peaq-os-sdk>=0.0.2'
    ```

    Verify with `python3 -c "import peaq_os_sdk; print(peaq_os_sdk.__version__)"`.
  </Accordion>

  <Accordion title="`address`/`machine_id` parsed as a number in YAML payloads">
    Quote EVM addresses and large integers in `ros2 service call` payloads:

    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
    ros2 service call /peaqos_node/wallet/get \
      peaq_ros2_interfaces/srv/PeaqosGetWallet \
      "{address: '0xAbC...'}"
    ```
  </Accordion>

  <Accordion title="Bridge calls fail with `MachineNFTAdapter not configured`">
    `peaq_os.contracts.machine_nft_adapter` is required only when bridging from peaq. Set it in `peaq_robot.yaml` or export `MACHINE_NFT_ADAPTER_ADDRESS`. Agung has no LayerZero DVN routes — test bridging on peaq mainnet ↔ Base mainnet only.
  </Accordion>
</AccordionGroup>

Continue to the full [service reference](/peaqos/sdk-reference/ros2/services).