> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Discover how digital twins revolutionize robotics development, testing, and deployment

## What is a Digital Twin?

A digital twin is a virtual replica of a physical robot that mirrors its behavior, capabilities, and environment in real-time.
It serves as a bridge between the physical and digital worlds, enabling you to simulate, test, and optimize your robots before deploying them.

<Info>
  ### Key Components

  * **3D Model:** Accurate geometric representation of your robot
  * **Physics Simulation:** Realistic movement and interaction dynamics
  * **Sensor Integration:** Virtual sensors that match your physical setup
  * **Real-time Sync:** Bidirectional communication with physical robots
</Info>

***

## Why Use Digital Twins?

Digital twins provide numerous benefits that accelerate development and reduce costs in robotics projects.

<CardGroup cols={2}>
  <Card title="Risk-Free Testing" icon="shield-check">
    Test dangerous or complex scenarios without risking physical hardware
  </Card>

  <Card title="Faster Development" icon="bolt">
    Iterate and optimize algorithms in simulation before deployment
  </Card>

  <Card title="Performance Analytics" icon="chart-line">
    Monitor and analyze robot performance with detailed metrics
  </Card>

  <Card title="Remote Monitoring" icon="monitor">
    Monitor and control robots from anywhere in the world
  </Card>

  <Card title="Cost Reduction" icon="piggy-bank">
    Reduce physical prototyping and testing costs significantly
  </Card>

  <Card title="Scalable Solutions" icon="globe">
    Test fleet behaviors and multi-robot coordination
  </Card>
</CardGroup>

***

## Common Use Cases

<CardGroup cols={3}>
  <Card title="Algorithm Testing" icon="microchip">
    Test path planning, navigation, and control algorithms
  </Card>

  <Card title="Safety Validation" icon="shield">
    Validate safety protocols and emergency procedures
  </Card>

  <Card title="Performance Optimization" icon="chart-bar">
    Optimize robot performance and energy efficiency
  </Card>
</CardGroup>

***

## Capabilities map (what unlocks what)

Twin behavior in Cyberwave is capability-driven.
The platform computes capabilities from each twin's `universal_schema`, and those values control which UI panels, controls, and SDK behaviors are available.

### Core capabilities

| Capability field                | Type    | What it represents                                                                                                |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `can_locomote`                  | boolean | Twin can move through the environment (navigation/locomotion).                                                    |
| `can_fly`                       | boolean | Twin supports aerial movement.                                                                                    |
| `can_grip`                      | boolean | Twin has a gripper/end-effector for grasping.                                                                     |
| `can_actuate`                   | boolean | Twin has actuators that can be commanded (for example joints).                                                    |
| `has_joints`                    | boolean | Twin has controllable joints.                                                                                     |
| `has_wheels`                    | boolean | Twin has wheel-based locomotion hardware.                                                                         |
| `has_legs`                      | boolean | Twin has legged locomotion hardware.                                                                              |
| `manipulator_count`             | number  | Number of manipulators/end-effectors.                                                                             |
| `payload_capacity_kg`           | number  | Max payload supported by manipulation system (kg).                                                                |
| `power_source`                  | enum    | Power source (`battery`, `tethered`, `rails`, `fuel`, `solar`, `hybrid`).                                         |
| `power_capacity_wh`             | number  | Power capacity in Wh (`-1` can mean unknown / not applicable).                                                    |
| `navigation_autonomy_level`     | enum    | Navigation autonomy mode (`manual`, `waypoint`, `path_following`, `semi_autonomous`, `fully_autonomous`, `none`). |
| `navigation_obstacle_avoidance` | boolean | Whether built-in obstacle avoidance is available.                                                                 |
| `locomotion_mode`               | enum    | Locomotion type (`stationary`, `wheeled`, `tracked`, `legged`, `aerial`, `surface`, `subsea`, `hybrid`).          |
| `locomotion_config`             | object  | Optional locomotion limits/config (for example max linear/angular velocity, DOF).                                 |
| `sensors`                       | array   | Sensor definitions attached to the twin.                                                                          |

### What is a sensor capability?

`sensors` is an array of sensor entries inside `capabilities`.\
If a twin has one or more sensor entries, sensor-driven features become available in both UI and SDK flows.

Each sensor entry can include:

| Sensor field                     | Type    | Description                                                              |
| -------------------------------- | ------- | ------------------------------------------------------------------------ |
| `id`                             | string  | Stable sensor identifier (for example `wrist_camera`).                   |
| `type`                           | enum    | Sensor type (`rgb`, `depth`, `lidar_2d`, `lidar_3d`, `lidar_4d`, `map`). |
| `model`                          | string  | Optional hardware/model label.                                           |
| `offset.position`                | object  | Position offset from twin origin (`x`, `y`, `z`).                        |
| `offset.rotation`                | object  | Rotation offset quaternion (`x`, `y`, `z`, `w`).                         |
| `fov_degrees`                    | number  | Optional camera FOV override.                                            |
| `width`, `height`                | number  | Optional image resolution (camera sensors).                              |
| `min_range`, `max_range`         | number  | Optional range values (depth/lidar sensors).                             |
| `fov_horizontal`, `fov_vertical` | number  | Optional horizontal/vertical FOV values.                                 |
| `points_per_second`              | number  | Optional lidar density/throughput hint.                                  |
| `velocity_sensing`               | boolean | Optional 4D lidar velocity support flag.                                 |
| `update_rate`                    | number  | Optional update frequency (Hz).                                          |

### Feature-to-capability matrix (UI + API)

| Feature                                                 | Capability condition                                                | Notes                                                                             |
| ------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Actuation: joint movement + joint editing**           | `can_actuate = true` (typically with `has_joints = true`)           | Right-panel actuation controls are shown only for actuated twins.                 |
| **Actuation: "Re-calibrate driver" action (Live mode)** | `can_actuate = true`                                                | Recalibration action is only available in Live mode for actuated twins.           |
| **Missions editor/simulation**                          | `can_locomote = true`                                               | Missions are enabled only for locomotion-capable twins.                           |
| **Sensor windows on right panel (Live + Simulate)**     | `sensors.length > 0`                                                | Real-time/live sensor cards and simulate sensor views require sensor capability.  |
| **Point cloud tools/rendering**                         | Sensor type includes `depth` or `lidar_*`                           | Advanced point-cloud controls appear for depth/lidar-capable twins.               |
| **Controller policy UI**                                | `has_joints OR can_locomote OR can_actuate OR can_grip`             | Control-policy attachment is shown for controllable twins.                        |
| **Edge connection status card (Live mode)**             | `sensors.length > 0` **OR** controllable twin                       | Live edge status appears for sensor twins or controllable twins.                  |
| **Python SDK twin class selection**                     | Combination of `can_locomote`, `can_fly`, `can_grip`, and `sensors` | `cw.twin(...)` returns the most specific twin class based on capabilities.        |
| **Python SDK camera streaming methods**                 | `sensors` includes camera sensors (`rgb`/`depth`)                   | Camera-enabled twins expose streaming helpers (camera/depth camera twin classes). |

<Info>
  `canHaveMissions` currently maps to `can_locomote`, and "controllable twin" maps to:
  `has_joints OR can_locomote OR can_actuate OR can_grip`.
</Info>

***

## Pairing a twin with physical hardware

<Warning>
  **STUB SECTION:** This section will be expanded with screenshots and a deeper troubleshooting guide in a future update.
</Warning>

A twin is just a model until it is paired with a physical device. Cyberwave supports two pairing paths depending on where the driver runs.

<CardGroup cols={2}>
  <Card title="Edge-device pairing (CLI)" icon="terminal">
    Run `cyberwave edge install` on the host that is physically wired to your hardware (Raspberry Pi, Jetson, industrial PC, laptop). The CLI authenticates, downloads the matching driver, and starts streaming.
  </Card>

  <Card title="Mobile pairing (QR code)" icon="qrcode">
    For hardware that runs through an Android phone tethered to a controller — e.g. a DJI drone with the DJI RC2 — open the twin page, click **Pair mobile device**, and scan the QR with the phone's camera.
  </Card>
</CardGroup>

### Path A — SSH into your edge device and run the CLI

Use this when the driver runs on a Linux host that is wired to your hardware.

1. Provision the edge host. Follow the platform-specific guide for the box you have:
   * [Raspberry Pi setup](/edge/raspberry-pi) — flash the Cyberwave OS image, onboard via the captive Wi-Fi portal, SSH in.
   * [Hardware overview](/overview/supported-hardware) — landing page with featured platforms (SO101, UGV Beast, Unitree Go2, UR7e, …).
   * [Other hardware (Linux + custom drivers)](/hardware) — generic flow for any Linux edge host.
2. SSH into the edge host and run `cyberwave edge install`. The CLI prompts for the twin you want to pair (or pass `--twin-uuid <uuid>` non-interactively), pulls the right driver from the catalog, and writes a local `.env` so subsequent restarts come up automatically.
3. Start streaming with `cyberwave edge start`. The driver registers with the cloud over MQTT and the twin's edge-device card on the twin page flips to **Connected**.

For platform-specific quick starts, jump straight to the relevant guide:

<CardGroup cols={2}>
  <Card title="Raspberry Pi" icon="microchip" href="/edge/raspberry-pi">
    Pre-built SD card image with SSH, Docker, and Wi-Fi onboarding ready to go.
  </Card>

  <Card title="SO101 arms" icon="hand" href="https://cyberwave.com/the-robot-studio/so101">
    USB-tethered 6-DOF manipulators for teleop and imitation learning.
  </Card>

  <Card title="UGV Beast" icon="truck-monster" href="https://cyberwave.com/waveshare/ugv-beast">
    Tracked rover, Pi + ESP32 dual-controller, ROS 2 stack.
  </Card>

  <Card title="Unitree Go2" icon="dog" href="https://cyberwave.com/unitree/go2">
    4D LiDAR quadruped with autonomous navigation.
  </Card>

  <Card title="Other hardware" icon="puzzle-piece" href="/hardware">
    Generic flow for any device with an API, serial, or network interface.
  </Card>

  <Card title="All hardware guides" icon="book-open" href="/overview/supported-hardware">
    Browse the full catalog of supported devices and platform-specific guides.
  </Card>
</CardGroup>

### Path B — Pair from the twin page with a QR code

Use this when the driver runs on an Android phone tethered to a controller — currently the **DJI Mini 4 Pro** via the DJI RC2 / RC-N2.

1. On the twin page, open the **Edge device** card and click **Pair mobile device**.
2. The dialog mints a fresh, workspace-scoped API token (so a screenshotted QR loses its key on the next dialog open) and renders a QR that encodes the API token, the twin slug, and the backend URL.
3. Open the Android phone's stock camera and aim at the QR. The verified Android App Link hands the URL straight to the **Cyberwave Edge for DJI** app, which writes the credentials into encrypted storage and starts streaming. If the app isn't installed yet, the camera opens an install page that points at the latest APK.
4. The credentials never reach the Cyberwave servers — the QR carries them in the URL fragment, which browsers do not transmit. There is nothing to copy or paste manually.

<Info>
  The **Pair mobile device** button only appears for twins whose asset declares an Android driver (`metadata.drivers.android`). Twins that run through `cyberwave edge install` on a Linux host show only the CLI affordance.
</Info>

***

## Ready to Get Started?

Creating your first digital twin is easy with Cyberwave. Follow our guides to set up your robot and start simulating.

<CardGroup cols={3}>
  <Card title="Quick Start Guide" icon="rocket" href="/overview/hello-robot">
    Get up and running with Cyberwave in minutes
  </Card>

  <Card title="Register Your Robot" icon="microchip" href="#pairing-a-twin-with-physical-hardware">
    Learn how to register and configure your robot
  </Card>

  <Card title="Browse Robot Catalog" icon="globe" href="https://cyberwave.com/catalog">
    Explore our collection of pre-built robots
  </Card>
</CardGroup>