# Work with the GRID agent
Source: https://docs.generalrobotics.dev/v2.3/cli/agent

Write and review robot tasks in the terminal, or call the agent from your own application.

The GRID agent reads documentation, writes Python skills and runs approved code
through your robot's GRID development session. You review the proposed action before it runs. A saved script, a finished
process and a verified task are three different results.

## Start a conversation

Set `ANTHROPIC_API_KEY` in the shell that starts GRID and sign in to GRID as usual.
Inside the GRID terminal, run:

```text theme={null}
agent --robot <robot-name> help me write and test a task
```

Use `agent --no-robot` to write code without connecting to hardware. Running
`agent` without either option reuses your current live robot connection. If
there is no live connection, it offers an online-robot picker. Use `--no-robot`
when you want to author code without attaching to that connection.

Recent tool calls stay visible while the agent works. Press Tab for the full
trace, and use arrow keys or Page Up / Page Down to scroll. Saved filenames are
terminal hyperlinks. Escape cancels and closes the conversation after cleanup.
Conversation history is retained between turns, but cannot be resumed after a
CLI restart.

## Review, run and check

1. The agent reads the docs, then saves a draft in your skill library,
   `~/.grid/skills/`, the same wherever you start GRID. **Draft saved**
   means the code has not run. The agent can also revise an existing skill after
   reading it; if someone changed the file meanwhile, GRID refuses the save.
2. Before an action, review its target, source, arguments, limits and success
   condition. Press `y` then Enter to approve, or Enter / `n` to deny. Changes to
   the approved program or inputs require another approval. Read-only tools do
   not need approval.
3. GRID runs approved Python through the same runner as `skill run`, captures
   its output and reports the process result. After a completed run, an unchanged
   program may retry within its approved trial limit. A run that fails, times out
   or is cancelled needs a new approval.
4. After the process ends, GRID asks you to check the robot, stop it if needed,
   and confirm it has stopped. It then asks whether the approved task succeeded,
   failed, or remains unclear. An exit code or the model's answer does not prove
   task success.

The person testing remains responsible for the prepared robot and its motion
limits. Python runs with your host's permissions; this is process supervision,
not an OS sandbox. Connecting establishes a GRID session; it does not check
physical readiness. V0 does not automatically inspect the robot or send a hardware
stop. Cancellation ends the task process. You remain responsible for stopping
the hardware, and GRID blocks another agent run until you confirm it stopped.

## Call the agent without the terminal UI

Create a request file. `query` and all four `limits` fields are required; omit
`robot` to work without a selected robot.

```json theme={null}
{
  "robot": "lab-robot",
  "query": "Inspect the setup and write a task. Try at most twice.",
  "limits": {
    "maxActions": 60,
    "maxSeconds": 900,
    "maxCostUsd": 3,
    "maxTrials": 2
  },
  "approvalDirectory": "/private/grid-approvals",
  "approvalTimeoutSeconds": 600,
  "answers": []
}
```

```sh theme={null}
grid --json --exec "agent --request /absolute/path/request.json"
```

The final JSON result goes to stdout. Live approval notices go to stderr as JSON
lines, so your application can watch for decisions while keeping stdout parsable
as one document. Omitting `approvalDirectory` denies actions, but still permits
read-only work and authoring.

For each approval, the notice gives `proposalPath`, `decisionPath`,
`approvalHash`, `requestId` and `decideBy`. Your application or an operator must:

1. Read the complete proposal and decide whether to allow it.
2. Write this decision to a temporary file beside `decisionPath`.
3. Atomically rename that file to the exact `decisionPath` from the notice.

```json theme={null}
{"approvalHash": "<hash from this proposal>", "approved": true}
```

Use `false` to deny. Every request has new paths, including retries. An expired,
used or mismatched decision cannot approve a later request. The directory must
belong to the current user and must not be writable by other users. The default
wait is 600 seconds; `approvalTimeoutSeconds` accepts 60–3600 seconds. File
approvals are unavailable on Windows; program execution requires POSIX process
groups.

`answers` supplies replies to the agent's ordinary questions. It cannot approve
execution or confirm a task outcome or a stopped robot. V0 headless runs can
execute approved Python and return logs, but physical outcomes stay `unknown`.
Without live operator confirmation, another run stays blocked until someone
checks the robot and reconciles stopping in an interactive session.

The final result's `data.host` reports denials, action failures, cancellation,
stop confirmation and task verification. Check the overall `ok` and `code` as
well as the model's text. `needs_attention` means a host check prevented success;
`invalid_request` means the input was rejected, and `setup_failed` includes a
missing model key. A model failure may supply its own error code.

## Limits and recovery

Interactive defaults are 60 tool calls, 900 seconds of working time, 10 Python
starts and a \$3 model budget. Waiting for a person is excluded from working time.
A trial counts a Python start, not each robot movement inside the program.
Headless requests supply these limits explicitly.

Session evidence is saved in `~/.grid/agent/sessions/<id>/events.jsonl`. Keep any
unresolved stop record: deleting it bypasses the block without establishing that
the robot stopped. Check the robot and follow GRID's recovery message in an
interactive session. Recovery also checks that the old process has ended; it
does not pre-approve another task.

Documentation comes from the hosted GRID docs MCP. `GRID_DOCS_MCP_URL` overrides
that endpoint for a custom deployment. See the [CLI reference](/v2.3/cli/reference)
for the other GRID commands.


# CLI reference
Source: https://docs.generalrobotics.dev/v2.3/cli/reference

Every command in the grid shell

The `grid` shell is the entry point to the platform — install it with the
one-liner from the portal, run `grid`, and type `help` at any time. This
page lists every available command.

## Robots

| Command | Description |
| - | - |
| `robot add [--config <yaml>] [--local [--root <dir> --dry-run]] [--existing-config overwrite] [--take-over]` | Onboard a robot — the wizard in the REPL; headless calls require --config; SSH needs a connection section; --local is dev-profile-only; --root \<dir> --dry-run (paired) rehearses it under a scratch root; --take-over answers the take-over confirm headlessly when the robot is already set up and its edge service is running |
| `robot configure <robot> [--config <yaml>]` | Re-run install → enable → verify over an explicit SSH connection, or apply a full profile and its connection with --config (confirms; headless calls require --config) |
| `robot list` | Connected robots — name, owner, team or personal, when its config last changed, and type. Agent: read-only. |
| `robot show <robot>` | One connected robot in detail: type, args, sensors and capabilities from its registration. Agent: read-only. |
| `robot status <robot> [--config <yaml>]` | Inspect service state, config status and versions over an explicit SSH connection; the REPL prompts, and headless calls require --config |
| `robot logs <robot> [--config <yaml>] [--follow]` | Read the edge service's journal over an explicit SSH connection — the last 200 lines, or follow until Esc; the REPL prompts, and headless calls require --config |
| `robot stop <robot>` | Stop a robot you hold and release it — closes this machine's session first. Agent: approval required. |
| `agent [--robot <name> \| --no-robot] [query] \| --request <json-file>` | Compose and review bounded robot tasks in a conversation; with no robot named, reuse the open robot connection or pick an online one. The model runtime authenticates with ANTHROPIC\_API\_KEY from your environment |

## Skills

| Command | Description |
| - | - |
| `skill run [path] [--robot <robot>] [--dev \| --deploy] [-- script-args...]` | Choose an online robot and run a Python file; --dev opens a workspace (path optional, defaults to the current folder); --deploy confirms. Headless runs require --robot |
| `skill stop [run-id]` | Stop a run or development session started from this machine — confirms for deployments. Agent: approval required. |
| `skill logs [run-id] [--follow]` | Logs of a run — the latest one when no id is given. Agent: read-only. |

## Simulation

| Command | Description |
| - | - |
| `sim start [--local] [--name\|-n <name>] [--resume <id>] [--config <yaml\|json>]` | Allocate a simulator runtime — robot → simulator → scene wizard, or a config file; --resume restores a stopped one. Agent: approval required. |
| `sim list` | Every sim runtime you can reach — name, simulator, state, age. Agent: read-only. |
| `sim open [id]` | Open a running sim's browser workspace; with one running, the id is optional |
| `sim stop [id]` | Release a sim runtime and its GPU — confirms; -y to skip. Agent: approval required. |

## Navigation

| Command | Description |
| - | - |
| `nav start [--no-open]` | Start the Navigation editor in the shared local web app using the active cluster login. Keep GRID running while editing |
| `nav view <robot> [--no-open]` | Visualize the live position, route and mission of the robot in this GRID process's skill run --dev session, in the shared local web app. Run it in the REPL that holds the session; closing the page leaves the robot running |

## Environment

| Command | Description |
| - | - |
| `context list` | Every known context — host and active marker; kind (cluster \| node \| local) in dev builds. Agent: read-only. |
| `context show <host>` | One context in detail: origin, portal, Cortex and signaling endpoints, auth state. Agent: read-only. |
| `context use [host]` | Switch the active context; with no host, open the REPL picker; headless calls require a host |
| `context add --url <portal-url>` | Register a cluster by its portal URL and switch to it; re-adding a known one just switches |
| `context remove <host>` | Forget a cluster — its session and API key are cleared too |
| `key show` | The public prefix of the GRID API key stored for the active cluster |
| `key remove` | Forget the active cluster's GRID API key so the startup gate asks for a new one; the session is kept |
| `login [--headless [--url <portal-url>] [--timeout <s>]]` | Log in to the active GRID cluster in your browser; --headless prints the authorize URL and waits |
| `logout` | Drop the active cluster's session locally — your API key and context are kept |
| `status` | Where you are and what is running from this machine — active context, robot session, skill runs and recorded simulations with live state. Agent: read-only. |

## Arms

| Command | Description |
| - | - |
| `device add` | Register a leader device on this machine |
| `device list` | List the leader devices registered on this machine |
| `device calibrate [device] [--robot <robot>]` | Align a leader device against a robot, once per physical setup |
| `device check [robot] [--leader <device>]` | Report whether teleop would start — the robot is never moved |
| `device teleop [robot] [--leader <device>] [--dataset <name>] [--task <text>] [--max-image-size <px>]` | Teleoperate a robot from a registered leader device |
| `dataset list` | List datasets recorded on this machine |
| `dataset visualize <dataset> [episode] [--no-open]` | Play a recorded episode back — cameras and joint plots on one timeline |
| `finetune submit <dataset> [--name <label>] [--robot-type <type>] [--steps <n>] [--batch-size <n>] [--action-horizon <n>] [--save-after-step <n>] [--save-interval <n>]` | Start a training run, uploading the dataset first if the cloud lacks it; the REPL opens a form for the knobs |
| `finetune list` | List finetune jobs submitted from this account |
| `finetune cancel <job-id>` | Stop a running finetune job |
| `rollout [--job-id <id>] [--step <n\|latest>] [--robot <robot>] [-- rollout-args...]` | Run a GRID Arms checkpoint in dev mode — choose a job, saved step and robot; uses the built-in UR5e PI05 workflow. The task prompt is user-supplied, not fetched from the checkpoint. Headless runs require --job-id, --step and --robot |

## Troubleshooting

| Command | Description |
| - | - |
| `error` | Show details of the last error |
| `diagnostics` | Bundle logs + config into an unscoped tarball for support; takes no arguments |
| `debug [on\|off]` | Toggle verbose logging with inline stack traces |

## Utilities

| Command | Description |
| - | - |
| `help [command]` | Show help information |
| `theme [grid\|mono]` | Switch the color theme for this session — mono renders grayscale |
| `clear` | Clear the terminal |
| `exit` | Exit GRID CLI |


# Camera Calibration
Source: https://docs.generalrobotics.dev/v2.3/deployment/camera-calibration

Extrinsic calibration of a fixed camera against a robot arm

## Overview

Camera calibration finds where a **fixed (external) camera** sits relative to a
robot's base — the `camera_wrt_base` transform that skills such as pick-and-place
read to turn what the camera sees into where the arm should move. It runs from
the `grid` CLI, drives the arm hand-guided, and records the result on the
robot's camera automatically.

<Note>
  This calibrates **fixed cameras only** — a camera mounted on a tripod or rig
  looking at the workspace, not one riding the end-effector. The arm moves the
  **target** through the camera's view; the camera stays put.
</Note>

## Step 1: Print the calibration target

The calibration uses a **12×9 radon checkerboard with 16.5 mm squares**. Generate
it with OpenCV's [`gen_pattern.py`](https://github.com/opencv/opencv/blob/master/doc/pattern_tools/gen_pattern.py):

```bash theme={null}
python gen_pattern.py -o radon_checkerboard_12x9_16.5mm.svg \
  --rows 12 --columns 9 --type radon_checkerboard -s 16.5 -m 4 6 4 7 5 6
```

Print it and attach it to a rigid flat board. Make sure:

* **Scale is exact** — print at **100%** (no "fit to page"), then measure a
  printed square; it must be 16.5 mm. Printer scaling silently shrinks the board
  and biases every result.
* There is a **white border** of at least one square-width on all sides.
* The surface is **non-reflective**, with no creases or unevenness.
* The mount is **rigid** (a 3D-printed mount is ideal; tape works). The board
  and camera must never wiggle during a run.

Attach the printed board to the arm's **end-effector**, and mount the camera at
a **fixed** location looking at the workspace. During the run you hand-guide the
arm to move the board through the camera's view.

## Step 2: Run the calibration

Calibration is offered at the end of `robot add`, from the `grid` CLI:

1. Run `robot add` and complete the setup for your robot.
2. At the final step the wizard flags any camera that has not been calibrated.
   Press **`c`** to calibrate now (or **enter** to skip and finish). If more than
   one camera is uncalibrated, pick the one to calibrate.

A window opens at the camera's own size: the camera feed with the detected
target on the **left**, a panel on the **right** with everything you need to
judge the run, and a key strip along the **bottom**. Its keys are in **that
window**, not the terminal:

| Key | Action |
| - | - |
| `SPACE` | Collect a sample |
| `C` | Calibrate and finish |
| `P` | Toggle the collected-point overlay |
| `F` | Toggle full-screen |
| `Q` | Cancel |

Hand-guide the arm to a variety of poses and collect a sample at each. **Hold
the arm still** at the instant you press space, so the pose and the frame match.
15–20 well-distributed samples generally suffice; more is better.

Amber always means *still needed*, never a fault. Red is reserved for the two
things that need you to act: a **consistency** check that failed, and a sample
the run **rejected or dropped**.

<img alt="Calibration window: the camera view with the detected target, the coverage panel, and the next step" />

### The four meters

| Meter | What it measures | How to fill it |
| - | - | - |
| **Scale** | how much of the frame the board fills | move the board closer to and farther from the camera |
| **Roll** | the board's sideways tilt | tilt the board left and right |
| **Pitch** | the board's forward/back tilt | tilt the board towards and away from the camera |
| **Axes** | how much rotation you have collected **about the least-used axis** | see below |

Each meter is a track: white ticks are the samples you captured, the blue dot is
the pose you are holding now, and the amber band is the range still missing. A
meter gets a green dot once its samples span enough range with no large gap in
the middle, so a cluster of similar poses leaves it an empty ring however many
samples you take.

**Axes** decides whether the solve is well-posed at all. It needs the wrist to
turn about genuinely different axes between samples; if every move is a
variation on the same twist, the solve has nothing to pin the remaining
direction down. To fill it, between samples change **at least two of** these
three, by roughly 30–45° each — and move the board to a different part of the
frame as you go:

* tilt the board forward/back,
* tilt it sideways,
* **twist it in its own plane** (rotate it about the camera's viewing direction
  — this is the one most people skip).

### The live estimate

* **`Est. error`** is the reprojection error your current samples produce,
  re-solved after every capture and shown in px and mm. It is reported, not
  graded — see [Step 3](#step-3-read-the-result). It is
  badged *preliminary* until there are enough samples for it to mean anything.
  Pressing `C` re-solves from exactly these samples, so **the number you watched
  is the number that gets saved**.
* **`Consistency`** shows two checks that compare the data against itself and
  need no camera pose, so they are meaningful within the first few samples.
  **Rotation** red means the arm's end-effector orientation is reported in a
  different convention than assumed, or the board is not rigidly fixed to the
  gripper. **Scale** red means a wrong printed square size, wrong units, or
  wrong camera intrinsics. Neither improves with more samples — stop and fix the
  cause.
* **`Next step`** names the single most useful next action. Follow it and
  ignore everything else.

### Samples the run rejects for you

There is no undo key: bad samples are removed automatically, and every removal
is announced in the panel.

* **Arm was moving** when you pressed space — hold still and re-capture.
* **Corners were not crisp** (blur, or a mis-ordered detection) — steady the
  board and re-capture.
* **Inconsistent sample dropped**, once 8 or more samples exist — one sample
  disagreed with all the others. Re-capture at that pose if you want it back.

<Note>
  If the target isn't detected, confirm it is non-reflective and that the board is
  12×9 **squares**. OpenCV sometimes counts interior corners (one fewer per side).
</Note>

## Step 3: Read the result

Press `C` to solve. The **reprojection error** is the one you were already
watching on the `Est. error` tile — the solve runs over exactly the samples you
kept. The window closes and the terminal prints the final line only: the camera
name and the error, in pixels and in millimetres.

```
Calibrated scene_cam · 6.72 px (≈6.8 mm)
```

The millimetre figure is the pixel error carried out to the board's distance
(`error_px × distance ÷ focal length`). It is how far, per sample, the arm's
reported pose and the camera's view of the board disagree out in the world,
which is the number your task actually cares about.

**The tool does not judge it.** There is no good/bad threshold and no advice to
re-run, because only you know what your application tolerates — a few
millimetres is fine for one task and not another. What does flag a real problem
is the `Consistency` pills and the samples the run rejects for you; both catch
a wrong pose convention, scale or intrinsics without depending on the solve at
all. The CLI records the calibration on the robot's camera and pushes it to the
robot's config. Skills that need the extrinsic then read it over Nexus — no
copying by hand.

`C` is refused, with a notice and you left collecting, only when there is no
solution at all yet — too few samples, or a solve that degenerated. That is the
absence of a result, not a judgement on one.

<Tip>
  If the error stays high despite good coverage, check the arm's end-effector
  pose. A wrong rotation-representation conversion in a robot driver gives the
  end-effector frame the wrong orientation, which the solve cannot recover from.
  A red `Consistency` pill points at the same family of causes — **rot** at the
  pose convention, **scale** at the square size, units, or intrinsics — and says
  so within the first few samples instead of after a full run.
</Tip>


# Common FAQs
Source: https://docs.generalrobotics.dev/v2.3/faq/common-faqs



## Install & login

**The installer finished but `grid` is not found**

* Open a new terminal (the installer appends to your shell profile), or run
  `export PATH="$HOME/.grid/bin:$PATH"` in the current one.

**`login` opens the browser but the CLI never completes**

* The login flow runs a one-shot local callback server — make sure the
  browser and the CLI are on the same machine (over SSH, forward the port the
  CLI prints, or use a machine with a local browser). `context use` lets you
  pick a different cluster if your organization has more than one.

**Where does my cluster URL come from?**

* Your organization's GRID admin portal shows the install one-liner
  pre-filled with `--cluster-url` on its Welcome screen. If you installed
  without it, re-run the installer with that flag from the portal.

## Robots & sessions

**`robot list` shows nothing / my robot is offline**

* The robot's GRID edge runtime must be running and able to reach the
  network. Re-run `robot add` to re-verify the setup — it detects an existing
  installation and offers to reuse, repair, or overwrite it.

**Deploy fails with "No GRID API key found"**

* The runtime key is generated in the admin portal and saved for the cluster
  you paste it into. GRID asks for one at startup when the cluster it's
  pointed at hasn't got one; `robot add` asks too. Paste it there and deploy
  again. The footer names the cluster whose key is in use.

**Can I run more than one sim?**

* Yes — sims are independent. `sim list` shows the simulations available in
  the selected context; `sim stop <name>` ends one you're done with.
  `status` checks simulations started or resumed from this machine, even after
  restarting the CLI or changing context. If a simulation cannot be checked,
  its state is shown as unavailable or unknown, not stopped.

## When something breaks

**Get help fast**

* `diagnostics` — bundles redacted logs + config into
  `~/grid-diagnostics-*.tar.gz`; attach it to your support ticket.
* `error` — recalls the last failure in full, including the correlation ID
  support will ask for.
* `debug on` — verbose logging for the current session; the full log lives
  at `~/.grid/logs/cli.log`.

## Isaac Sim

**How do I make the camera follow my robot?**

Add this to your session configuration:

```yaml theme={null}
viewer:
  eye: [-3.0, 0.0, 1.5] # camera location (x, y, z)
  lookat: [0.0, 0.0, 0.0]
  origin_type: asset_root
  env_index: 0
  asset_name: robot # asset name to follow
```


# Your first session
Source: https://docs.generalrobotics.dev/v2.3/get-started/first-session

Start a cloud simulator from the GRID shell and watch it come alive — no robot required

You've [installed the CLI and logged in](/v2.3/get-started/installation). This page
takes the shortest path to a robot you can program: a **cloud simulator
session**. No hardware, about five minutes, and you end up inside a live
workspace where real robot code runs.

## 1. Start a sim

```text theme={null}
GRID # sim start
```

## 2. Pick a robot and a scene

The wizard opens with a **New Sim Session** card that fills in as you pick.
First, the robot — tabs group them by form factor (**←/→** to switch tabs):

```text theme={null}
Select a robot:

Arms │ Mobile arms │ Quadrupeds │ Humanoids │ Wheeled │ Aerial │ Controllers

▸ Flexiv Rizon 4
  Franka Panda
  Kinova Gen 3
  SO-101
  …
```

Pick **Franka Panda**. It runs on one simulator, so the wizard jumps straight
to scenes (robots available on more than one simulator get a simulator step
in between):

```text theme={null}
Select scene for isaac:

▸ tabletop       · Empty tabletop environment
  tabletop_objs  · Tabletop with objects for manipulation
```

Pick **tabletop\_objs**, then review. The card now shows every choice plus a
generated session name (`{robot}-{scene}-{date}-{time}`) — press **enter** to
launch. If you want to see exactly what you're deploying, press **e** at any
step: the session config opens as YAML in your editor, and your edits carry
into the launch.

## 3. Watch it boot

```text theme={null}
Starting session...
  Requesting GPU (isaac)...
  Allocated — franka-panda-tabletop-objs-0727-163950 (service: service-grid--bro104ajnv)
  Waiting for pod route...
  Route ready — connecting to pod
  Session ready
  Opening franka-panda-tabletop-objs-0727-163950 in browser

● Sim franka-panda-tabletop-objs-0727-163950 running on <your-cluster>
  sim list to view · sim open to reopen the workspace
  UI: https://<your-portal-host>/grid-service/service-grid--bro104ajnv/vscode/?tkn=<session-token>
```

Your cluster allocated a GPU, booted Isaac Sim next to a browser IDE, and
opened the workspace. Two things to notice in the shell:

* The **statusline** at the bottom now shows `●` with your session name —
  green means this shell has a live session attached.
* The **UI link** is durable. Close the tab, reopen the link — same session.

## 4. It's alive

The workspace is VS Code in your browser, running on the session pod. On
first open it asks *"Do you trust the authors of the files in this folder?"* —
this is your own session workspace, so choose **Yes, I trust the authors**.

<img alt="The session workspace: the seeded welcome notebook open in the browser IDE, first cell connected to the simulated Franka arm in the Isaac tabletop scene" />

What you're looking at:

* **`sessions/<session-name>/notebook.ipynb`** — a welcome notebook seeded
  for the robot you picked, already open, kernel ready.
* **Sample Notebooks** (the GRID icon in the activity bar on the left) —
  ready-made notebooks for common tasks; open any of them to explore. The
  sidebar starts here; the file explorer is one click away above it.
* **Sim Streaming** and **Visualization** panels — the live scene view and
  camera/sensor streams for this session.

## 5. Do one real thing

Run the notebook's first cell (**shift+enter**):

```python theme={null}
from grid_sim_client.isaac.robot import IsaacArm

isaac_arm_0 = IsaacArm()
```

It goes green in about a second. That's not a mock — your code is now holding
a connection to the Franka in the running scene. The second cell connects the
other half of GRID, cloud models:

```python theme={null}
from grid_cortex_client import CortexClient

client = CortexClient()  # reads GRID_CORTEX_API_KEY + GRID_CORTEX_BASE_URL from env
print(client.get_info())
```

`get_info()` lists the models actually deployed in your cluster, and
`client.help("<model>")` shows usage for any of them — see the
[model catalog](/v2.3/models/overview) and the
[grid-cortex-client reference](/v2.3/python-api/grid-cortex-client/overview) for
what you can call.

## 6. Housekeeping

Back in the shell (or any new terminal), list the simulations available in the
selected context:

```text theme={null}
GRID # sim list

Active
●  franka-panda-tabletop-objs-0727-163950  isaac  running  0m ago
```

Use `status` to check simulations started or resumed from this machine,
including after restarting the CLI or switching context. It shows each
simulation's original context and live state; unreachable or unknown state is
reported explicitly. Opening or listing a simulation does not
add it to this machine's launch records.

`sim open` reopens the workspace UI — with one sim running it needs no name.
When you're done, stop it (release the GPU — sims don't stop themselves):

```text theme={null}
GRID # sim stop franka-panda-tabletop-objs-0727-163950

Stop sim "franka-panda-tabletop-objs-0727-163950"? (y/N) y
Stopping sim franka-panda-tabletop-objs-0727-163950...
Sim stopped
● Sim franka-panda-tabletop-objs-0727-163950 stopped
```

With no name, `sim stop` lets you pick from the active sims; either way it
confirms before stopping (in a script, pass `-y`). One timing note: the GPU
takes \~20 seconds to return to the pool, so if an immediate restart reports
`no GPU available`, wait a moment and retry.

If anything misbehaves, three commands have your back:

* `error` — replay the last failure in full detail.
* `diagnostics` — bundle redacted logs + config into a tarball for support.
* `debug on` — verbose logging with inline stack traces for this shell.

## Where next

You have a live robot and a workspace — the next two pages are the same
staircase with more weight on it:

* **Write real robot code**: [Your first skill](/v2.3/get-started/first-skill)
* **Point it at hardware**: `robot add` onboards your robot, then
  `skill run <your-skill.py> --dev` lets you choose an online robot and opens
  this same workspace at your skill's folder, wired to the physical machine — see
  [Deployment](/v2.3/deployment/camera-calibration)
* **Every command in the shell**: the [CLI reference](/v2.3/cli/reference)


# Your first skill
Source: https://docs.generalrobotics.dev/v2.3/get-started/first-skill

Write and run Python against your live robot, all from the GRID CLI

A **skill** is plain Python that drives your robot through GRID's APIs. You
develop it against a *live* robot in a generated notebook — no environment
setup, because the CLI provisions the Python environment for you.

## 1. Open a dev session

Start the GRID shell from your project folder, then run:

```text theme={null}
GRID # skill run --dev
```

Choose an online robot. The CLI opens a VS Code workspace in the current
folder with `dev.ipynb` and the Python environment configured. Run the notebook's
connection cell, then write your code. You can also create Python files or
additional notebooks in the editor; no existing script is needed to get started.

To open a different project folder:

```text theme={null}
GRID # skill run ./my-project --dev
```

The folder must already exist. You can also pass an existing file to open its
containing folder. Direct execution and deployment still take a Python file:
`skill run my_skill.py` or `skill run my_skill.py --deploy`. Each run asks you
to choose an online robot in the GRID shell. To target a robot explicitly, add
`--robot <robot>`; headless commands require this flag.

The notebook connects using the robot you selected, for example:

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("my-go2")
print(f"Connected: {robot}")
```

## 2. Find out what your robot can do

`make_robot()` returns a [`RemoteRobot`](/v2.3/python-api/grid-nexus-client/remoterobot).
Its attributes are the robot's own methods, discovered live when you connect —
so the fastest way to see the surface is to ask it:

```python theme={null}
for name in robot.session.methods_info():
    print(f"  {name}")
```

Those methods come from the [Robot interface](/v2.3/python-api/robot-interface/overview),
which is the same whether the robot is physical or simulated. A quadruped gets
[`Quadruped`](/v2.3/python-api/robot-interface/quadruped), an arm gets
[`Arm`](/v2.3/python-api/robot-interface/arm), and every robot gets the shared
[`Robot`](/v2.3/python-api/robot-interface/robot) methods like `getState()` and
`getImage()`.

## 3. Drive it

State, motion, and camera all work directly from notebook cells:

```python theme={null}
from grid_types import Velocity

robot.getState()

# standUp and moveByVelocity are a quadruped's. Every robot exposes its own
# methods — print them with robot.session.methods_info().
robot.standUp()
robot.moveByVelocity(Velocity(0.1, 0.0, 0.0), Velocity(0.0, 0.0, 0.0))
```

<Warning>
  Motion cells move the robot physically. Make sure it has clearance, and run
  `robot.shutdown()` when you're done — it releases the session cleanly.
</Warning>

Sensors, arms, and end effectors nest as attributes, so you can reach into a
subcomponent the same way:

```python theme={null}
image = robot.getImage("front")
wrist = robot.left_arm.wrist_cam.getImage()
```

## 4. Add perception

Anything you capture can go straight to a hosted Cortex model. This finds a
water bottle in the robot's camera frame:

```python theme={null}
from grid_cortex_client import CortexClient

cortex = CortexClient()  # reads GRID_CORTEX_API_KEY from the environment
image = robot.getImage("front")
detections = cortex.run("owlv2", image_input=image, prompt="water bottle")
print(detections["scores"])
```

From there it's ordinary Python — loop over frames, check a score threshold,
and command the robot when you see what you're looking for:

```python theme={null}
import time

robot.standUp()
while True:
    image = robot.getImage("front")
    detections = cortex.run("owlv2", image_input=image, prompt="water bottle")
    scores = detections.get("scores", [])
    if len(scores) > 0 and max(scores) > 0.3:
        robot.stop()
        break
    robot.moveByVelocity(Velocity(0.0, 0.0, 0.0), Velocity(0.0, 0.0, 0.4))
    time.sleep(0.5)
```

## Where next

* Every method your robot exposes: [Robot interface](/v2.3/python-api/robot-interface/overview)
* The full Cortex model catalog for perception in your skills:
  [AI models](/v2.3/models/overview)
* Calling models from Python: [grid-cortex-client](/v2.3/python-api/grid-cortex-client/overview)
* Every shell command: [CLI reference](/v2.3/cli/reference)


# Get started
Source: https://docs.generalrobotics.dev/v2.3/get-started/installation

Install the GRID CLI, connect your account, and run your first session

Everything in GRID starts from the `grid` CLI — an interactive shell that
onboards robots, starts simulator and robot sessions, and deploys programs.

## 1. Install the CLI

```bash theme={null}
curl -fsSL https://generalrobotics.dev/install.sh | bash
```

Your organization's **GRID admin portal** shows this same command on its
Welcome screen, pre-filled with your cluster:

```bash theme={null}
curl -fsSL https://generalrobotics.dev/install.sh | bash -s -- \
  --cluster-url <your-cluster-url>
```

Prefer the portal variant — it registers your cluster so `login` connects to
the right place immediately. (Windows support is coming soon; use WSL in the
meantime.) On Linux, watching a robot live (`nav view`) needs glibc 2.34 or
newer on x86-64 (Ubuntu 22.04 or later) and 2.30 or newer on ARM64; the rest
of GRID runs on older systems.

The installer verifies a signed binary, installs it to `~/.grid/bin/grid`,
adds it to your `PATH`, and offers the GRID Studio VS Code extension. Open a
new terminal and run:

```bash theme={null}
grid
```

## 2. Log in

Inside the shell, authenticate with your browser:

```text theme={null}
GRID # login
```

Your tokens are stored per cluster; `context use` switches the active cluster
if your organization has more than one (`context list` shows them).

## 3. Get your Cortex API key

Cloud model inference (detection, depth, grasping, VLAs) is authenticated by a
separate runtime key. Generate it in the **admin portal** (the same site that
showed your install command — ask your org admin for its URL if you don't
have it), and paste it when `robot add` asks — the CLI persists it for every
later session.

## 4. Onboard a robot

```text theme={null}
GRID # robot add
```

The wizard walks you through connecting your robot to the GRID network. Once
added, it shows up for everyone in your organization:

```text theme={null}
GRID # robot list
```

## 5. Start working

```text theme={null}
GRID # sim start
```

`sim start` allocates a cloud simulator (it opens a browser workspace with a
live scene). To work against your physical robot, run `skill run --dev` and
choose an online robot. The CLI opens a VS Code workspace in the current folder
with `dev.ipynb` and Python configured. You can start in the notebook or create
a Python file in the editor.

## Where next

* Watch a simulator come alive, no hardware needed: [Your first session](/v2.3/get-started/first-session)
* Write and deploy your first robot program: [Your first skill](/v2.3/get-started/first-skill)
* Every command: the [CLI reference](/v2.3/cli/reference)
* Call cloud models from Python: [grid-cortex-client](/v2.3/python-api/grid-cortex-client/overview)
* The hosted model catalog: [AI models](/v2.3/models/overview)
* Something wrong? `diagnostics` bundles redacted logs for support, and
  `error` recalls the last failure in full.


# The Intelligence Grid for Physical AI
Source: https://docs.generalrobotics.dev/v2.3/introduction

GRID makes robots useful now — and adaptable over time. Onboard a robot, develop against it live, call state-of-the-art AI on its sensors, and deploy skills, all from one CLI.

<div>
  <div>
    <Frame>
      <img alt="The GRID CLI connected to a robot fleet" />
    </Frame>
  </div>

  <div>
    <CardGroup>
      <Card title="Install GRID" icon="download" href="/v2.3/get-started/installation">
        One command to the whole platform — from zero to a running session in
        ten minutes.
      </Card>

      <Card title="Write your first skill" icon="pen-to-square" href="/v2.3/get-started/first-skill">
        Drive your live robot from a generated notebook — state, motion,
        cameras, and cloud AI in plain Python.
      </Card>

      <Card title="Try a simulator session — no robot required" icon="cube" href="/v2.3/get-started/first-session">
        Spin up a GPU-backed Isaac Sim scene in the cloud and drive a robot
        from a notebook, before any hardware is involved.
      </Card>
    </CardGroup>
  </div>
</div>

<Note>
  GRID runs on Apple Silicon macOS and Linux (Windows via WSL for now). You'll
  need access to your organization's GRID cluster to open sessions. A physical
  robot is only needed for the real-robot paths — the simulator path needs none.
</Note>

## What you can do with the GRID CLI

Everything below runs from the one [GRID CLI](/v2.3/cli/reference):

<CardGroup>
  <Card title="Connect your robots" icon="plug" href="/v2.3/cli/reference">
    Onboard robots to your organization's cluster with `robot add` — once
    connected, every teammate can open a session against them.
  </Card>

  <Card title="Build and test in simulation" icon="cube" href="/v2.3/get-started/first-session">
    Start cloud simulator sessions on NVIDIA Isaac Sim or AirGen from the CLI —
    a GPU-backed 3D scene with your robot, open in the browser in minutes.
  </Card>

  <Card title="Build and test with a real robot" icon="code" href="/v2.3/get-started/first-skill">
    Develop in a VS Code workspace wired to the live robot: state, motion,
    cameras, and cloud AI calls from a notebook, no environment setup.
  </Card>

  <Card title="Look up what your robot can do" icon="rocket-launch" href="/v2.3/python-api/robot-interface/overview">
    One robot interface across physical machines, AirGen, and Isaac — the same
    `standUp()` and `getImage()` everywhere.
  </Card>
</CardGroup>

## Call AI models on your robot's data

GRID Cortex hosts detection, depth, segmentation, grasping, VLMs, and VLA
policies behind one Python call — no GPUs to manage:

```python theme={null}
from grid_cortex_client import CortexClient, ModelType

client = CortexClient()
detections = client.run(ModelType.OWLV2, image_input=frame, prompt="pallet.")
```

`CortexClient()` reads your `GRID_CORTEX_API_KEY` from the environment —
inside GRID session workspaces it's already configured. Browse the full
hosted catalog under [Models](/v2.3/models/overview), or the client reference
under [API Reference](/v2.3/python-api/grid-cortex-client/overview).

## Stay in the loop

<CardGroup>
  <Card title="Community" icon="discord" href="https://discord.gg/yPtfUNDe5M">
    Questions, bugs, or robots doing something great? Join the Discord.
  </Card>

  <Card title="Blog" icon="newspaper" href="https://www.generalrobotics.company/research#blogs">
    Research and product updates from General Robotics.
  </Card>
</CardGroup>


# OrbbecCamera
Source: https://docs.generalrobotics.dev/v2.3/python-api/cameras/orbbeccamera

An Orbbec depth camera providing RGB, depth, and stereo infrared images

```python theme={null}
from grid_robot_api.sensor.camera import OrbbecCamera
```

An Orbbec depth camera providing RGB, depth, and stereo infrared images.

Framesets are captured continuously in a background thread, so the image
getters return the most recently captured frames without blocking on the
device.

Suits the Gemini stereo-vision family (e.g. Gemini 305 / 330 series), whose
depth is produced from a left + right infrared (IR) sensor pair alongside a
separate RGB color sensor. The left and right IR images form the stereo pair
(`getStereoImagePair`). By default depth is returned in its native geometry,
which matches the left IR image; pass `align_depth_to_color=True` to instead
align depth onto the color frame's pixel grid for RGB-D fusion.

Not every Orbbec model exposes both IR sensors. When the connected device
lacks the left/right IR streams they are skipped at startup, and requesting
them later raises `RuntimeError`.

When the config declares an `identity` block with a `serial_number`,
that serial *selects* the camera in place of `device_index`: bring-up
opens exactly that unit and fails loudly when it is not connected, rather
than streaming from a different one. USB enumeration order (and hence
`device_index`) is not stable across reboots and replugs, so a rig with
several Orbbec cameras should pin each config node's serial.

## Constructor

```python Signature theme={null}
OrbbecCamera(
    resolution: Optional[Tuple[int, int]] = None,
    fps: Optional[int] = None,
    *,
    enable_depth: bool = True,
    enable_ir: bool = True,
    align_depth_to_color: bool = False,
    device_index: int = 0,
)
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `capture_specs()`

```python Signature theme={null}
capture_specs() -> Tuple[StreamSpec, ...]
```

Declare the V4L2 capture of a configured Orbbec camera.

**Returns:**

One V4L2 stream on the color node. The config supplies the
`device` path edge streaming opens, or a declared
`identity.serial_number` resolves it through target-local
discovery — and only to a node discovery confirms is the color
endpoint, since an Orbbec's depth and infrared nodes are capture
endpoints of their own.

### `cleanup()`

```python Signature theme={null}
cleanup() -> None
```

Stop the capture thread and pipeline, and release the camera.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getAllImages()`

```python Signature theme={null}
getAllImages() -> Tuple[Image, Image]
```

Return the RGB and depth images from a single frameset.

When the camera was constructed with `align_depth_to_color=True` the
depth image shares the color frame's pixel grid; otherwise depth is in its
native geometry.

**Returns:**

A tuple `(rgb_image, depth_image)` where `rgb_image` is HxWx3 uint8
and `depth_image` is HxW uint16 in raw device units.

**Raises:**

RuntimeError: If the depth stream is disabled, or either frame is
missing from the frameset.

### `getCameraExtrinsics()`

```python Signature theme={null}
getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

Returns the camera's extrinsic transformation matrix — the camera pose
relative to a reference frame. The recorded calibration takes
precedence: when a calibration run has stored a transform on this
camera's config, that 4x4 is returned (read off the config, not
hand-pasted by a consumer), so a consumer can ask a freshly connected
robot where its camera is. It overrides any transform set via
`setCameraExtrinsics`, and a warning is logged when both are
present. Otherwise the value set via `setCameraExtrinsics` is
returned, or `None` when neither is available.

Calibration is fixed-camera only, so a recorded transform is always
camera-with-respect-to-base — use it as `camera_wrt_base` directly.
Reads no hardware, so it is callable before `start()`.

**Returns:**

The (4, 4) homogeneous transform as a float array, or `None` when
the camera has neither a recorded calibration nor a set extrinsic.

### `getCameraIntrinsics()`

```python Signature theme={null}
getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

Retrieves the camera's intrinsic calibration parameters used for
image projection and rectification.

**Returns:**

Optional\[tuple\[float, float, float, float]]: Camera intrinsics as
(fx, fy, cx, cy) or None if not configured

### `getCameraMatrix()`

```python Signature theme={null}
getCameraMatrix(image_type: Optional[str] = None) -> np.ndarray
```

Return the 3x3 camera intrinsic matrix K for a stream.

K has the form `[[fx, 0, cx], [0, fy, cy], [0, 0, 1]]`.

<ParamField>
  `"color"` / `"rgb"` / None for the color camera (default), or `"depth"` for the depth camera.
</ParamField>

**Returns:**

The 3x3 intrinsic matrix.

**Raises:**

ValueError: If `image_type` is not a recognized value.
RuntimeError: If intrinsics could not be read from the device.

### `getCameraSettings()`

```python Signature theme={null}
getCameraSettings() -> CameraSettings
```

Get the camera settings.

**Returns:**

CameraSettings: Current camera configuration and parameters

### `getData()`

```python Signature theme={null}
getData() -> Image
```

Get the image from the camera.

Implements the Sensor interface by delegating to getImage().

**Returns:**

Image: The captured image from the camera

### `getDistortionCoefficients()`

```python Signature theme={null}
getDistortionCoefficients(image_type: Optional[str] = None) -> np.ndarray
```

Return the radial/tangential distortion coefficients for a stream.

<ParamField>
  `"color"` / `"rgb"` / None for the color camera (default), or `"depth"` for the depth camera.
</ParamField>

**Returns:**

The distortion coefficients as `[k1, k2, p1, p2, k3, k4, k5, k6]`.

**Raises:**

ValueError: If `image_type` is not a recognized value.
RuntimeError: If distortion data could not be read from the device.

### `getExtrinsics()`

```python Signature theme={null}
getExtrinsics(source_image_frame: str, target_image_frame: str) -> np.ndarray
```

Return the transform of the target frame with respect to the source frame.

The returned 4x4 homogeneous matrix transforms a 3D point (in meters) from
the source sensor frame into the target sensor frame.

<ParamField>
  Source sensor frame. One of `"color"` / `"rgb"` or `"depth"`.
</ParamField>

<ParamField>
  Target sensor frame. One of `"color"` / `"rgb"` or `"depth"`.
</ParamField>

**Returns:**

The 4x4 homogeneous transformation matrix.

**Raises:**

ValueError: If either frame name is not a recognized value.
RuntimeError: If extrinsics could not be read from the device.

### `getFrameCount()`

```python Signature theme={null}
getFrameCount() -> int
```

Return the total number of framesets successfully captured so far.

The counter is incremented by the background capture thread on every
successful capture and is safe to call from any thread.

**Returns:**

Total framesets captured since the camera was opened.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(
    *,
    image_type: Optional[str] = None,
    compressed: bool = False,
    resolution: Optional[Tuple[int, int]] = None,
    keep_aspect_ratio: bool = False,
) -> Image
```

Return a single image of the requested type from the latest frameset.

<ParamField>
  One of `"rgb"` (default), `"depth"`, `"depth_meters"`, `"left"` / `"infrared"` / `"ir"`, or `"right"`. `"rgb"` returns an HxWx3 uint8 RGB image. `"depth"` returns an HxW uint16 image in raw device units. `"depth_meters"` returns an HxW float32 image in meters. `"left"`, `"infrared"` and `"ir"` return the left IR image; `"right"` returns the right IR image — each a single-channel HxW image (uint16 for a Y16 stream, else uint8).
</ParamField>

<ParamField>
  When True, JPEG-encode the RGB frame and return it as an `Image` with `encoding_format="jpeg"` (\~15-25x smaller on the wire); call `Image.decode()` on the result to get an RGB ndarray. Compression is supported only for `image_type="rgb"`.
</ParamField>

<ParamField>
  Target `(width, height)` in pixels to resize the image to before any JPEG encoding — bilinear for RGB, nearest-neighbor for depth/IR so no-data zeros are never blended into fabricated values. None (default) keeps the native resolution. Requires OpenCV. Resized pixels no longer correspond to `getCameraMatrix()`, which keeps returning native-resolution intrinsics — scale fx/fy/cx/cy by the resize factors before deprojecting.
</ParamField>

<ParamField>
  Used only when `resolution` is given. When True, preserve the aspect ratio and center the scaled image on a zero background (black for RGB, no-data for depth/IR); when False (default), stretch to exactly `resolution`.
</ParamField>

**Returns:**

The requested image, or JPEG bytes tagged `encoding_format="jpeg"`
when `compressed` is True for RGB.

**Raises:**

ValueError: If `image_type` is not a recognized value.
RuntimeError: If depth/IR is requested but the corresponding stream is
disabled or unavailable, the frame is missing from the frameset,
OpenCV is unavailable for JPEG encoding, JPEG encoding fails, or
the camera stopped delivering frames.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getStereoImagePair()`

```python Signature theme={null}
getStereoImagePair() -> Tuple[Image, Image]
```

Return the left and right infrared images from a single frameset.

The two images come from the camera's stereo IR sensor pair and are
captured at the same instant, suitable for stereo correspondence.

**Returns:**

A tuple `(left_ir_image, right_ir_image)`, each a single-channel HxW
image (uint16 for a Y16 stream, else uint8).

**Raises:**

RuntimeError: If either infrared stream is unavailable or disabled, or
its frame is missing from the frameset.

### `recordCalibration()`

```python Signature theme={null}
recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

Swaps the recorded calibration block on the live camera object, so the
current session serves the new extrinsic without a rebuild. A falsy
value clears the recorded calibration. A non-empty block is validated
against the calibration schema before being installed and stored in the
same normalized form `from_config` records, so a malformed remote call
is rejected at the boundary rather than stored raw.

<ParamField>
  The recorded calibration block (transform plus provenance), as a calibration run produces it. A falsy value clears any recorded calibration.
</ParamField>

**Raises:**

ConfigValidationError: If a non-empty block does not satisfy the
calibration schema — e.g. a `status="calibrated"` block
missing its transform, a non-4x4 transform, or an unknown field.

### `reloadCalibration()`

```python Signature theme={null}
reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

Lets a running session pick up a recalibration in place, without
reconnecting. Available on a camera built from a config-file source
(see `grid_robot_api.config.record_calibration_sources`); a
co-located caller can pass the block to `recordCalibration`
directly instead.

**Returns:**

The calibration block that was installed, or `&#123;&#125;` when the config
names none for this camera.

**Raises:**

RuntimeError: If this camera was not built from a config-file source.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setCameraExtrinsics()`

```python Signature theme={null}
setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

Configures the camera's extrinsic transformation matrix representing
the camera pose relative to a reference frame.

<ParamField>
  4x4 homogeneous transformation matrix
</ParamField>

**Raises:**

ValueError: If transform is not a 4x4 matrix

### `setCameraIntrinsics()`

```python Signature theme={null}
setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

Configures the camera's intrinsic calibration parameters for
accurate image projection and rectification.

<ParamField>
  Focal length in x direction (pixels)
</ParamField>

<ParamField>
  Focal length in y direction (pixels)
</ParamField>

<ParamField>
  Principal point x coordinate (pixels)
</ParamField>

<ParamField>
  Principal point y coordinate (pixels)
</ParamField>

### `setCameraSettings()`

```python Signature theme={null}
setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

<ParamField type="CameraSettings">
  New camera configuration to apply
</ParamField>

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Cameras
Source: https://docs.generalrobotics.dev/v2.3/python-api/cameras/overview

Cameras a robot can carry

Cameras a robot can carry — attached by the robot's config under a name you choose, and reached as `robot.<name>` or `robot.sensors["<name>"]`. Each class lists what that camera can do beyond a plain `getImage()`: a stereo pair, its intrinsics, its extrinsics.

## Install

```bash theme={null}
# Preinstalled in every GRID session workspace and in the Python environment the
# GRID CLI prepares when you run a program with `skill run`. Nothing to install.
```

## Quickstart

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<robot-name>")
print(list(robot.sensors))                    # the camera names this robot was configured with

# A ZED attached as "zed_usb_1": the robot-level read forwards to it,
# and the stereo methods are reached on the camera itself.
rgb = robot.getImage("zed_usb_1").data
left, right = robot.sensors["zed_usb_1"].getStereoImagePair()
K = robot.sensors["zed_usb_1"].getCameraMatrix()
```

Which camera a robot carries is set in its config when it is added. Values returned are **grid-types** (`Image`; call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). The robot pages under **Robots** say when a camera is built in rather than attached.

## Classes

* [`ZedUSBCamera`](/v2.3/python-api/cameras/zedusbcamera)
* [`ZedCamera`](/v2.3/python-api/cameras/zedcamera)
* [`RealsenseCamera`](/v2.3/python-api/cameras/realsensecamera)
* [`OrbbecCamera`](/v2.3/python-api/cameras/orbbeccamera)
* [`USBCamera`](/v2.3/python-api/cameras/usbcamera)
* [`RtspCamera`](/v2.3/python-api/cameras/rtspcamera)


# RealsenseCamera
Source: https://docs.generalrobotics.dev/v2.3/python-api/cameras/realsensecamera

A RealSense depth camera providing RGB, depth, and infrared images

```python theme={null}
from grid_robot_api.sensor.camera import RealsenseCamera
```

A RealSense depth camera providing RGB, depth, and infrared images.

Construction only builds the SDK objects; `start()` opens the
device and reads its intrinsics. The image getters also initialize
the device on first use, so a camera used without `start()` still
works.

When the config declares an `identity` block with a
`serial_number`, that serial *selects* the camera: the pipeline is
restricted to exactly that unit, and bring-up fails loudly when it
is not connected rather than streaming from a different one. USB
enumeration order is not stable across reboots and replugs, so a rig
with several RealSense cameras should pin each config node's serial.

## Constructor

```python Signature theme={null}
RealsenseCamera()
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `capture_specs()`

```python Signature theme={null}
capture_specs() -> Tuple[StreamSpec, ...]
```

Declare the V4L2 capture of a configured RealSense camera.

**Returns:**

One V4L2 stream on the camera's color node. Depth and infrared
stay robot-API only — edge streaming carries color.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getAllImages()`

```python Signature theme={null}
getAllImages() -> tuple
```

Get all images from RealSense camera (RGB, Depth, and IR), aligned to RGB

**Returns:**

tuple: (rgb\_image, depth\_image, ir\_image) as Images

### `getCameraExtrinsics()`

```python Signature theme={null}
getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

Returns the camera's extrinsic transformation matrix — the camera pose
relative to a reference frame. The recorded calibration takes
precedence: when a calibration run has stored a transform on this
camera's config, that 4x4 is returned (read off the config, not
hand-pasted by a consumer), so a consumer can ask a freshly connected
robot where its camera is. It overrides any transform set via
`setCameraExtrinsics`, and a warning is logged when both are
present. Otherwise the value set via `setCameraExtrinsics` is
returned, or `None` when neither is available.

Calibration is fixed-camera only, so a recorded transform is always
camera-with-respect-to-base — use it as `camera_wrt_base` directly.
Reads no hardware, so it is callable before `start()`.

**Returns:**

The (4, 4) homogeneous transform as a float array, or `None` when
the camera has neither a recorded calibration nor a set extrinsic.

### `getCameraIntrinsics()`

```python Signature theme={null}
getCameraIntrinsics() -> dict
```

Get all camera intrinsic parameters, including the focal length and centerpoint,
distortion\_coefficients, distortion model, image size, etc.

**Returns:**

dict: camera intrinsics

### `getCameraMatrix()`

```python Signature theme={null}
getCameraMatrix(image_type: str = None) -> np.ndarray
```

Get the camera matrix K as a numpy array of shape (3, 3)
K = \[\[fx, 0, cx], \[0, fy, cy], \[0, 0, 1]]

<ParamField>
  str, Describes which camera sensor to get the matrix for. Valid values are: - "color" or "rgb" or None: the color camera (default) - "left" or "infrared": the left infrared camera - "right": the right infrared camera
</ParamField>

**Returns:**

np.ndarray: camera matrix

### `getCameraSettings()`

```python Signature theme={null}
getCameraSettings() -> CameraSettings
```

Get the camera settings.

**Returns:**

CameraSettings: Current camera configuration and parameters

### `getData()`

```python Signature theme={null}
getData() -> Image
```

Get the image from the camera.

Implements the Sensor interface by delegating to getImage().

**Returns:**

Image: The captured image from the camera

### `getDistortionCoefficients()`

```python Signature theme={null}
getDistortionCoefficients() -> np.ndarray
```

Get distortion coefficients as a numpy array of shape (5,)

**Returns:**

np.ndarray: distortion coefficients

### `getExtrinsics()`

```python Signature theme={null}
getExtrinsics(source_image_frame: str, target_image_frame: str) -> np.ndarray
```

Get the transform of the target sensor frame with respect to the source sensor frame as
a 4x4 homogeneous transformation matrix.

This transform transforms a 3D point (in meters) from the source frame to the target frame.

<ParamField>
  The frame of the source sensor. Valid values are 'color', 'rgb', 'left', 'right'.
</ParamField>

<ParamField>
  The frame of the target sensor. Valid values are 'color', 'rgb', 'left', 'right'.
</ParamField>

**Returns:**

np.ndarray: 4x4 homogeneous transformation matrix

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(
    *,
    image_type: Optional[str] = None,
    resolution: Optional[Tuple[int, int]] = None,
    keep_aspect_ratio: bool = False,
) -> Image
```

Get image from RealSense camera

<ParamField>
  Type of image to retrieve ("rgb", "depth", "infrared"). Defaults to rgb.
</ParamField>

<ParamField>
  Target `(width, height)` in pixels to resize the image to — bilinear for RGB, nearest-neighbor for depth/infrared so no-data zeros are never blended into fabricated values. None (default) keeps the native resolution. Resized pixels no longer correspond to the camera's native-resolution intrinsics — scale fx/fy/cx/cy by the resize factors before deprojecting.
</ParamField>

<ParamField>
  Used only when `resolution` is given. When True, preserve the aspect ratio and center the scaled image on a zero background; when False (default), stretch to exactly `resolution`.
</ParamField>

**Returns:**

Image: requested image as numpy array

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getStereoImagePair()`

```python Signature theme={null}
getStereoImagePair() -> tuple
```

Get the left and right infrared images, which can be used for stereo vision.

**Returns:**

tuple of Images: (left\_ir\_image, right\_ir\_image)

### `init_camera()`

```python Signature theme={null}
init_camera() -> None
```

Initialize the RealSense camera.

**Raises:**

RuntimeError: If the config declares an
`identity.serial_number` and no RealSense with that
serial is connected.

### `recordCalibration()`

```python Signature theme={null}
recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

Swaps the recorded calibration block on the live camera object, so the
current session serves the new extrinsic without a rebuild. A falsy
value clears the recorded calibration. A non-empty block is validated
against the calibration schema before being installed and stored in the
same normalized form `from_config` records, so a malformed remote call
is rejected at the boundary rather than stored raw.

<ParamField>
  The recorded calibration block (transform plus provenance), as a calibration run produces it. A falsy value clears any recorded calibration.
</ParamField>

**Raises:**

ConfigValidationError: If a non-empty block does not satisfy the
calibration schema — e.g. a `status="calibrated"` block
missing its transform, a non-4x4 transform, or an unknown field.

### `reloadCalibration()`

```python Signature theme={null}
reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

Lets a running session pick up a recalibration in place, without
reconnecting. Available on a camera built from a config-file source
(see `grid_robot_api.config.record_calibration_sources`); a
co-located caller can pass the block to `recordCalibration`
directly instead.

**Returns:**

The calibration block that was installed, or `&#123;&#125;` when the config
names none for this camera.

**Raises:**

RuntimeError: If this camera was not built from a config-file source.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setCameraExtrinsics()`

```python Signature theme={null}
setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

Configures the camera's extrinsic transformation matrix representing
the camera pose relative to a reference frame.

<ParamField>
  4x4 homogeneous transformation matrix
</ParamField>

**Raises:**

ValueError: If transform is not a 4x4 matrix

### `setCameraIntrinsics()`

```python Signature theme={null}
setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

Configures the camera's intrinsic calibration parameters for
accurate image projection and rectification.

<ParamField>
  Focal length in x direction (pixels)
</ParamField>

<ParamField>
  Focal length in y direction (pixels)
</ParamField>

<ParamField>
  Principal point x coordinate (pixels)
</ParamField>

<ParamField>
  Principal point y coordinate (pixels)
</ParamField>

### `setCameraSettings()`

```python Signature theme={null}
setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

<ParamField type="CameraSettings">
  New camera configuration to apply
</ParamField>

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# RtspCamera
Source: https://docs.generalrobotics.dev/v2.3/python-api/cameras/rtspcamera

A camera that reads frames from an RTSP stream

```python theme={null}
from grid_robot_api.sensor.camera import RtspCamera
```

A camera that reads frames from an RTSP stream.

## Constructor

```python Signature theme={null}
RtspCamera(url: str, resolution_width: int = 256, resolution_height: int = 256)
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `capture_specs()`

```python Signature theme={null}
capture_specs() -> Optional[Tuple[StreamSpec, ...]]
```

Declare how a configured instance is captured (customization point).

Edge streaming opens this camera's pixels for itself, and how that
is done — the capture source (`v4l2`, `udp`, `test`, …) and
the defaults that source takes — is a property of the camera type.
A camera class declares it here; a configured instance supplies the
rest, its `args` retuning resolution/fps/device and its
`identity` pinning the physical unit.

Like `Component.builtin_subcomponents`, the declaration is
pure data and must be readable off the bare class — no
instantiation, no driver import, no hardware — because the
setup-time stream resolver reads it on a machine that has none of
the cameras attached.

**Returns:**

The `StreamSpec` entries a configured instance of this camera
resolves to. The default is `None`: the class declares
nothing, and its registry entry's `stream_specs` decides. An
empty tuple is a declaration of its own — the camera is
reachable through the robot API and advertises no edge stream.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getCameraExtrinsics()`

```python Signature theme={null}
getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

Returns the camera's extrinsic transformation matrix — the camera pose
relative to a reference frame. The recorded calibration takes
precedence: when a calibration run has stored a transform on this
camera's config, that 4x4 is returned (read off the config, not
hand-pasted by a consumer), so a consumer can ask a freshly connected
robot where its camera is. It overrides any transform set via
`setCameraExtrinsics`, and a warning is logged when both are
present. Otherwise the value set via `setCameraExtrinsics` is
returned, or `None` when neither is available.

Calibration is fixed-camera only, so a recorded transform is always
camera-with-respect-to-base — use it as `camera_wrt_base` directly.
Reads no hardware, so it is callable before `start()`.

**Returns:**

The (4, 4) homogeneous transform as a float array, or `None` when
the camera has neither a recorded calibration nor a set extrinsic.

### `getCameraIntrinsics()`

```python Signature theme={null}
getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

Retrieves the camera's intrinsic calibration parameters used for
image projection and rectification.

**Returns:**

Optional\[tuple\[float, float, float, float]]: Camera intrinsics as
(fx, fy, cx, cy) or None if not configured

### `getCameraSettings()`

```python Signature theme={null}
getCameraSettings() -> CameraSettings
```

Get the camera settings.

**Returns:**

CameraSettings: Current camera configuration and parameters

### `getData()`

```python Signature theme={null}
getData() -> Image
```

Get the image from the camera.

Implements the Sensor interface by delegating to getImage().

**Returns:**

Image: The captured image from the camera

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(
    *,
    resolution: Optional[Tuple[int, int]] = None,
    keep_aspect_ratio: bool = False,
) -> Image
```

return the image

<ParamField>
  Target `(width, height)` in pixels to resize the frame to (bilinear). None (default) keeps the native resolution.
</ParamField>

<ParamField>
  Used only when `resolution` is given. When True, preserve the aspect ratio and center the scaled image on a zero (black) background; when False (default), stretch to exactly `resolution`.
</ParamField>

**Returns:**

Image: Image type containing the requested image.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `get_video_manager()`

```python Signature theme={null}
get_video_manager()
```

Return the shared PyVideoStreamManager instance, creating it if necessary.

**Returns:**

The singleton PyVideoStreamManager instance.

### `recordCalibration()`

```python Signature theme={null}
recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

Swaps the recorded calibration block on the live camera object, so the
current session serves the new extrinsic without a rebuild. A falsy
value clears the recorded calibration. A non-empty block is validated
against the calibration schema before being installed and stored in the
same normalized form `from_config` records, so a malformed remote call
is rejected at the boundary rather than stored raw.

<ParamField>
  The recorded calibration block (transform plus provenance), as a calibration run produces it. A falsy value clears any recorded calibration.
</ParamField>

**Raises:**

ConfigValidationError: If a non-empty block does not satisfy the
calibration schema — e.g. a `status="calibrated"` block
missing its transform, a non-4x4 transform, or an unknown field.

### `reloadCalibration()`

```python Signature theme={null}
reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

Lets a running session pick up a recalibration in place, without
reconnecting. Available on a camera built from a config-file source
(see `grid_robot_api.config.record_calibration_sources`); a
co-located caller can pass the block to `recordCalibration`
directly instead.

**Returns:**

The calibration block that was installed, or `&#123;&#125;` when the config
names none for this camera.

**Raises:**

RuntimeError: If this camera was not built from a config-file source.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setCameraExtrinsics()`

```python Signature theme={null}
setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

Configures the camera's extrinsic transformation matrix representing
the camera pose relative to a reference frame.

<ParamField>
  4x4 homogeneous transformation matrix
</ParamField>

**Raises:**

ValueError: If transform is not a 4x4 matrix

### `setCameraIntrinsics()`

```python Signature theme={null}
setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

Configures the camera's intrinsic calibration parameters for
accurate image projection and rectification.

<ParamField>
  Focal length in x direction (pixels)
</ParamField>

<ParamField>
  Focal length in y direction (pixels)
</ParamField>

<ParamField>
  Principal point x coordinate (pixels)
</ParamField>

<ParamField>
  Principal point y coordinate (pixels)
</ParamField>

### `setCameraSettings()`

```python Signature theme={null}
setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

<ParamField type="CameraSettings">
  New camera configuration to apply
</ParamField>

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# USBCamera
Source: https://docs.generalrobotics.dev/v2.3/python-api/cameras/usbcamera

A USB camera that continuously captures frames in a background thread

```python theme={null}
from grid_robot_api.sensor.camera import USBCamera
```

A USB camera that continuously captures frames in a background thread.

Construction validates the device path only; `start()` opens the
device and starts the capture thread (`make_robot`/`make_sensor`
and `with` blocks do that for you).

## Constructor

```python Signature theme={null}
USBCamera(
    device: str,
    resolution: Optional[Tuple[int, int]] = None,
    fps: Optional[int] = None,
    exposure: Optional[int] = None,
)
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `capture_specs()`

```python Signature theme={null}
capture_specs() -> Tuple[StreamSpec, ...]
```

Declare the V4L2 capture of a configured USB camera.

**Returns:**

One V4L2 stream on the configured `device`, at the same
resolution and frame rate the driver opens it with.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getAvailableImageTypes()`

```python Signature theme={null}
getAvailableImageTypes() -> List[ImageType]
```

Return the list of image types supported by this camera.

**Returns:**

A list containing only ImageType.RGB.

### `getCameraExtrinsics()`

```python Signature theme={null}
getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

Returns the camera's extrinsic transformation matrix — the camera pose
relative to a reference frame. The recorded calibration takes
precedence: when a calibration run has stored a transform on this
camera's config, that 4x4 is returned (read off the config, not
hand-pasted by a consumer), so a consumer can ask a freshly connected
robot where its camera is. It overrides any transform set via
`setCameraExtrinsics`, and a warning is logged when both are
present. Otherwise the value set via `setCameraExtrinsics` is
returned, or `None` when neither is available.

Calibration is fixed-camera only, so a recorded transform is always
camera-with-respect-to-base — use it as `camera_wrt_base` directly.
Reads no hardware, so it is callable before `start()`.

**Returns:**

The (4, 4) homogeneous transform as a float array, or `None` when
the camera has neither a recorded calibration nor a set extrinsic.

### `getCameraIntrinsics()`

```python Signature theme={null}
getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

Retrieves the camera's intrinsic calibration parameters used for
image projection and rectification.

**Returns:**

Optional\[tuple\[float, float, float, float]]: Camera intrinsics as
(fx, fy, cx, cy) or None if not configured

### `getCameraSettings()`

```python Signature theme={null}
getCameraSettings() -> CameraSettings
```

Get the camera settings.

**Returns:**

CameraSettings: Current camera configuration and parameters

### `getData()`

```python Signature theme={null}
getData() -> Image
```

Get the image from the camera.

Implements the Sensor interface by delegating to getImage().

**Returns:**

Image: The captured image from the camera

### `getExposure()`

```python Signature theme={null}
getExposure() -> float
```

Return the current exposure value reported by the driver.

**Returns:**

The current exposure value. Units are driver-defined (typically
100 µs steps on V4L2).

**Raises:**

RuntimeError: If the camera is not open.

### `getFPS()`

```python Signature theme={null}
getFPS() -> float
```

Return the capture frame rate reported by the driver.

**Returns:**

The current frame rate in frames per second.

**Raises:**

RuntimeError: If the camera is not open.

### `getFrameCount()`

```python Signature theme={null}
getFrameCount() -> int
```

Return the total number of frames successfully captured so far.

The counter is incremented by the background capture thread on every
successful read and is safe to call from any thread.

**Returns:**

Total frames captured since the camera was opened.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(
    *,
    compressed: bool = False,
    resolution: Optional[Tuple[int, int]] = None,
    keep_aspect_ratio: bool = False,
) -> Image
```

Return the most recently captured frame.

<ParamField>
  When True, JPEG-encode the frame and return it as an `Image` with `encoding_format="jpeg"` (\~15-25x smaller on the wire); call `Image.decode()` on the result to get an RGB ndarray. When False (default), return a raw RGB ndarray `Image`.
</ParamField>

<ParamField>
  Target `(width, height)` in pixels to resize the frame to (bilinear) before any JPEG encoding. None (default) keeps the native resolution.
</ParamField>

<ParamField>
  Used only when `resolution` is given. When True, preserve the aspect ratio and center the scaled image on a zero (black) background; when False (default), stretch to exactly `resolution`.
</ParamField>

**Returns:**

The latest RGB image from the camera.

**Raises:**

RuntimeError: If JPEG encoding fails when `compressed` is True.

### `getResolution()`

```python Signature theme={null}
getResolution() -> Tuple[int, int]
```

Return the current capture resolution reported by the driver.

**Returns:**

A (width, height) tuple in pixels.

**Raises:**

RuntimeError: If the camera is not open.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `recordCalibration()`

```python Signature theme={null}
recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

Swaps the recorded calibration block on the live camera object, so the
current session serves the new extrinsic without a rebuild. A falsy
value clears the recorded calibration. A non-empty block is validated
against the calibration schema before being installed and stored in the
same normalized form `from_config` records, so a malformed remote call
is rejected at the boundary rather than stored raw.

<ParamField>
  The recorded calibration block (transform plus provenance), as a calibration run produces it. A falsy value clears any recorded calibration.
</ParamField>

**Raises:**

ConfigValidationError: If a non-empty block does not satisfy the
calibration schema — e.g. a `status="calibrated"` block
missing its transform, a non-4x4 transform, or an unknown field.

### `reloadCalibration()`

```python Signature theme={null}
reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

Lets a running session pick up a recalibration in place, without
reconnecting. Available on a camera built from a config-file source
(see `grid_robot_api.config.record_calibration_sources`); a
co-located caller can pass the block to `recordCalibration`
directly instead.

**Returns:**

The calibration block that was installed, or `&#123;&#125;` when the config
names none for this camera.

**Raises:**

RuntimeError: If this camera was not built from a config-file source.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setAutoExposure()`

```python Signature theme={null}
setAutoExposure() -> None
```

Re-enable automatic exposure control.

**Raises:**

RuntimeError: If the camera is not open.

### `setCameraExtrinsics()`

```python Signature theme={null}
setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

Configures the camera's extrinsic transformation matrix representing
the camera pose relative to a reference frame.

<ParamField>
  4x4 homogeneous transformation matrix
</ParamField>

**Raises:**

ValueError: If transform is not a 4x4 matrix

### `setCameraIntrinsics()`

```python Signature theme={null}
setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

Configures the camera's intrinsic calibration parameters for
accurate image projection and rectification.

<ParamField>
  Focal length in x direction (pixels)
</ParamField>

<ParamField>
  Focal length in y direction (pixels)
</ParamField>

<ParamField>
  Principal point x coordinate (pixels)
</ParamField>

<ParamField>
  Principal point y coordinate (pixels)
</ParamField>

### `setCameraSettings()`

```python Signature theme={null}
setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

<ParamField type="CameraSettings">
  New camera configuration to apply
</ParamField>

### `setExposure()`

```python Signature theme={null}
setExposure(exposure: int) -> None
```

Disable auto-exposure and apply a fixed exposure value.

Auto-exposure is turned off before writing the value so the driver does
not override it. A warning is logged when the driver-reported value
differs from the requested one.

<ParamField>
  Absolute exposure value to set. Units are driver-defined; on V4L2 each step is typically 100 µs.
</ParamField>

**Raises:**

RuntimeError: If the camera is not open.

### `setFPS()`

```python Signature theme={null}
setFPS(fps: int) -> None
```

Set the capture frame rate.

The driver will use the nearest supported rate if the exact value is
unavailable. A warning is logged when the applied rate differs from the
requested one by more than 0.5 Hz.

<ParamField>
  Desired capture frame rate.
</ParamField>

**Raises:**

RuntimeError: If the camera is not open.

### `setResolution()`

```python Signature theme={null}
setResolution(width: int, height: int) -> None
```

Set the capture resolution.

The driver will use the nearest supported mode if the exact resolution
is unavailable. A warning is logged when the applied resolution differs
from the requested one.

<ParamField>
  Desired frame width in pixels.
</ParamField>

<ParamField>
  Desired frame height in pixels.
</ParamField>

**Raises:**

RuntimeError: If the camera is not open.

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# ZedCamera
Source: https://docs.generalrobotics.dev/v2.3/python-api/cameras/zedcamera

A ZED stereo camera providing RGB, depth, and point cloud data

```python theme={null}
from grid_robot_api.sensor.camera import ZedCamera
```

A ZED stereo camera providing RGB, depth, and point cloud data.

When the config declares an `identity` block with a
`serial_number`, that serial *selects* the camera: the SDK is told
to open exactly that unit, and bring-up fails loudly when it is not
connected rather than opening a different one. USB enumeration order
is not stable across reboots and replugs, so a rig with several ZEDs
should pin each config node's serial.

## Constructor

```python Signature theme={null}
ZedCamera(
    resolution: Union[str, None] = 'AUTO',
    depth_mode: Union[str, None] = 'NEURAL',
    fps: Union[int, None] = 30,
    positional_tracking: bool = False,
)
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `capture_specs()`

```python Signature theme={null}
capture_specs() -> Optional[Tuple[StreamSpec, ...]]
```

Declare how a configured instance is captured (customization point).

Edge streaming opens this camera's pixels for itself, and how that
is done — the capture source (`v4l2`, `udp`, `test`, …) and
the defaults that source takes — is a property of the camera type.
A camera class declares it here; a configured instance supplies the
rest, its `args` retuning resolution/fps/device and its
`identity` pinning the physical unit.

Like `Component.builtin_subcomponents`, the declaration is
pure data and must be readable off the bare class — no
instantiation, no driver import, no hardware — because the
setup-time stream resolver reads it on a machine that has none of
the cameras attached.

**Returns:**

The `StreamSpec` entries a configured instance of this camera
resolves to. The default is `None`: the class declares
nothing, and its registry entry's `stream_specs` decides. An
empty tuple is a declaration of its own — the camera is
reachable through the robot API and advertises no edge stream.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getCameraExtrinsics()`

```python Signature theme={null}
getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

Returns the camera's extrinsic transformation matrix — the camera pose
relative to a reference frame. The recorded calibration takes
precedence: when a calibration run has stored a transform on this
camera's config, that 4x4 is returned (read off the config, not
hand-pasted by a consumer), so a consumer can ask a freshly connected
robot where its camera is. It overrides any transform set via
`setCameraExtrinsics`, and a warning is logged when both are
present. Otherwise the value set via `setCameraExtrinsics` is
returned, or `None` when neither is available.

Calibration is fixed-camera only, so a recorded transform is always
camera-with-respect-to-base — use it as `camera_wrt_base` directly.
Reads no hardware, so it is callable before `start()`.

**Returns:**

The (4, 4) homogeneous transform as a float array, or `None` when
the camera has neither a recorded calibration nor a set extrinsic.

### `getCameraIntrinsics()`

```python Signature theme={null}
getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

Retrieves the camera's intrinsic calibration parameters used for
image projection and rectification.

**Returns:**

Optional\[tuple\[float, float, float, float]]: Camera intrinsics as
(fx, fy, cx, cy) or None if not configured

### `getCameraMatrix()`

```python Signature theme={null}
getCameraMatrix(image_type: str = None) -> np.ndarray
```

Get the camera matrix K as a numpy array of shape (3, 3)
K = \[\[fx, 0, cx], \[0, fy, cy], \[0, 0, 1]]

<ParamField>
  str, Describes which camera sensor to get the intrinsics of. Valid image\_types are: 'left', 'color', 'rgb' (all refer to left camera), or 'right'
</ParamField>

**Returns:**

np.ndarray: camera matrix

### `getCameraSettings()`

```python Signature theme={null}
getCameraSettings() -> CameraSettings
```

Get the camera settings.

**Returns:**

CameraSettings: Current camera configuration and parameters

### `getData()`

```python Signature theme={null}
getData() -> Image
```

Get the image from the camera.

Implements the Sensor interface by delegating to getImage().

**Returns:**

Image: The captured image from the camera

### `getDistortionCoefficients()`

```python Signature theme={null}
getDistortionCoefficients(image_type: str = 'left') -> np.ndarray
```

Get distortion coefficients as a numpy array of shape (5,)

<ParamField>
  str,  Describes which camera sensor to get the intrinsics of. Valid image\_types are: 'left', 'right'
</ParamField>

**Returns:**

np.ndarray: distortion coefficients

### `getExtrinsics()`

```python Signature theme={null}
getExtrinsics(source_image_frame: str, target_image_frame: str) -> np.ndarray
```

Get the transform of the target sensor frame with respect to the source sensor frame as a
4x4 homogeneous transformation matrix.

This transform transforms a 3D point (in meters) from the source frame to the target frame.

<ParamField type="str">
  the frame of the source sensor. Valid values are 'color', 'rgb', 'left', 'right'
</ParamField>

<ParamField type="str">
  the frame of the target sensor. Valid values are 'color', 'rgb', 'left', 'right'
</ParamField>

**Returns:**

np.ndarray: 4x4 homogeneous transformation matrix

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(
    *,
    image_type: str = 'rgb',
    camera_name: str = 'left',
    resolution: Optional[Tuple[int, int]] = None,
    keep_aspect_ratio: bool = False,
)
```

Grab and return the requested image from the ZED camera.

<ParamField>
  One of "rgb", "left", "right", "depth", "depth\_meters", or "point\_cloud".
</ParamField>

<ParamField>
  Used only when `image_type == "rgb"` to pick the monocular view. One of "left" or "right".
</ParamField>

<ParamField>
  Target `(width, height)` in pixels to resize the image to — bilinear for color, nearest-neighbor for depth so no-data values are never blended. None (default) keeps the native resolution; ignored for "point\_cloud". Resized pixels no longer correspond to the camera's native-resolution intrinsics — scale fx/fy/cx/cy by the resize factors before deprojecting.
</ParamField>

<ParamField>
  Used only when `resolution` is given. When True, preserve the aspect ratio and center the scaled image on a zero background; when False (default), stretch to exactly `resolution`.
</ParamField>

**Returns:**

The requested `Image` (or `PointCloud` for "point\_cloud"), or
None when the grab fails or depth is unavailable.

**Raises:**

ValueError: If `image_type` or `camera_name` is not a
recognized value.

### `getOrientation()`

```python Signature theme={null}
getOrientation()
```

### `getPose()`

```python Signature theme={null}
getPose()
```

### `getPosition()`

```python Signature theme={null}
getPosition()
```

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getStereoImagePair()`

```python Signature theme={null}
getStereoImagePair() -> tuple
```

Get a synchronized pair of left and right images for stereo vision.

**Returns:**

tuple of Images: (left\_ir\_image, right\_ir\_image)

### `recordCalibration()`

```python Signature theme={null}
recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

Swaps the recorded calibration block on the live camera object, so the
current session serves the new extrinsic without a rebuild. A falsy
value clears the recorded calibration. A non-empty block is validated
against the calibration schema before being installed and stored in the
same normalized form `from_config` records, so a malformed remote call
is rejected at the boundary rather than stored raw.

<ParamField>
  The recorded calibration block (transform plus provenance), as a calibration run produces it. A falsy value clears any recorded calibration.
</ParamField>

**Raises:**

ConfigValidationError: If a non-empty block does not satisfy the
calibration schema — e.g. a `status="calibrated"` block
missing its transform, a non-4x4 transform, or an unknown field.

### `reloadCalibration()`

```python Signature theme={null}
reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

Lets a running session pick up a recalibration in place, without
reconnecting. Available on a camera built from a config-file source
(see `grid_robot_api.config.record_calibration_sources`); a
co-located caller can pass the block to `recordCalibration`
directly instead.

**Returns:**

The calibration block that was installed, or `&#123;&#125;` when the config
names none for this camera.

**Raises:**

RuntimeError: If this camera was not built from a config-file source.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setCameraExtrinsics()`

```python Signature theme={null}
setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

Configures the camera's extrinsic transformation matrix representing
the camera pose relative to a reference frame.

<ParamField>
  4x4 homogeneous transformation matrix
</ParamField>

**Raises:**

ValueError: If transform is not a 4x4 matrix

### `setCameraIntrinsics()`

```python Signature theme={null}
setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

Configures the camera's intrinsic calibration parameters for
accurate image projection and rectification.

<ParamField>
  Focal length in x direction (pixels)
</ParamField>

<ParamField>
  Focal length in y direction (pixels)
</ParamField>

<ParamField>
  Principal point x coordinate (pixels)
</ParamField>

<ParamField>
  Principal point y coordinate (pixels)
</ParamField>

### `setCameraSettings()`

```python Signature theme={null}
setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

<ParamField type="CameraSettings">
  New camera configuration to apply
</ParamField>

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# ZedUSBCamera
Source: https://docs.generalrobotics.dev/v2.3/python-api/cameras/zedusbcamera

ZED stereo camera over UVC USB, without the Stereolabs SDK

```python theme={null}
from grid_robot_api.sensor.camera import ZedUSBCamera
```

ZED stereo camera over UVC USB, without the Stereolabs SDK.

Opens the camera with OpenCV as a side-by-side stereo UVC device,
rectifies the left and right halves against the camera's factory
calibration, and exposes the rectified result via the same method
names as `ZedCamera`. A background thread continuously
drains the OS capture buffer so `getImage` and
`getStereoImagePair` always return the most recent frame.

Calibration is loaded from a local `.conf` (`calib_path`) if
supplied, otherwise from
`~/.config/grid_robot_api/zed_calibrations/SN&lt;serial>.conf`,
downloading it from Stereolabs' calibration server on first use.
If `serial` is omitted, it is auto-detected by reading USB
descriptors via sysfs (Linux only).

When the config declares an `identity` block with a
`serial_number`, that serial *selects* the camera: bring-up
resolves it to the capture node of exactly that physical unit and
keys the calibration on it, and fails loudly if that camera is not
on the bus rather than opening a different one. USB enumeration
order is not stable across reboots and replugs, so a rig with
several identical ZEDs should pin each config node's serial.

## Constructor

```python Signature theme={null}
ZedUSBCamera(
    device: Optional[str] = None,
    resolution: str = _DEFAULT_RESOLUTION,
    fps: int = _DEFAULT_FPS,
    *,
    serial: Optional[str] = None,
    calib_path: Optional[Union[str, Path]] = None,
)
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `capture_specs()`

```python Signature theme={null}
capture_specs() -> Tuple[StreamSpec, ...]
```

Declare the V4L2 capture of a configured ZED USB camera.

**Returns:**

One V4L2 stream carrying the side-by-side stereo frame, on the
capture node detection resolves — the declared
`identity.serial_number` when the config pins one, exactly as
bring-up resolves it.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getAvailableImageTypes()`

```python Signature theme={null}
getAvailableImageTypes() -> List[ImageType]
```

Return the image types supported by this camera.

**Returns:**

A single-element list containing `ImageType.RGB`.
Depth and point-cloud types require the Stereolabs SDK
and are not supported here.

### `getCameraExtrinsics()`

```python Signature theme={null}
getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

Returns the camera's extrinsic transformation matrix — the camera pose
relative to a reference frame. The recorded calibration takes
precedence: when a calibration run has stored a transform on this
camera's config, that 4x4 is returned (read off the config, not
hand-pasted by a consumer), so a consumer can ask a freshly connected
robot where its camera is. It overrides any transform set via
`setCameraExtrinsics`, and a warning is logged when both are
present. Otherwise the value set via `setCameraExtrinsics` is
returned, or `None` when neither is available.

Calibration is fixed-camera only, so a recorded transform is always
camera-with-respect-to-base — use it as `camera_wrt_base` directly.
Reads no hardware, so it is callable before `start()`.

**Returns:**

The (4, 4) homogeneous transform as a float array, or `None` when
the camera has neither a recorded calibration nor a set extrinsic.

### `getCameraIntrinsics()`

```python Signature theme={null}
getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

Retrieves the camera's intrinsic calibration parameters used for
image projection and rectification.

**Returns:**

Optional\[tuple\[float, float, float, float]]: Camera intrinsics as
(fx, fy, cx, cy) or None if not configured

### `getCameraMatrix()`

```python Signature theme={null}
getCameraMatrix(image_type: Optional[str] = None) -> np.ndarray
```

Get the rectified 3x3 camera matrix `K`.

Because the returned frames are rectified, the left and right
cameras share intrinsics — this method returns the same matrix
regardless of `image_type`.

<ParamField>
  Accepted for API parity with `ZedCamera` (`"left"`, `"right"`, `"color"`, `"rgb"`, or `None`). Validated but otherwise ignored.
</ParamField>

**Returns:**

`np.ndarray` of shape `(3, 3)`:
`[[fx, 0, cx], [0, fy, cy], [0, 0, 1]]`.

**Raises:**

ValueError: If `image_type` is not a recognized frame.

### `getCameraSettings()`

```python Signature theme={null}
getCameraSettings() -> CameraSettings
```

Get the camera settings.

**Returns:**

CameraSettings: Current camera configuration and parameters

### `getData()`

```python Signature theme={null}
getData() -> Image
```

Get the image from the camera.

Implements the Sensor interface by delegating to getImage().

**Returns:**

Image: The captured image from the camera

### `getDistortionCoefficients()`

```python Signature theme={null}
getDistortionCoefficients(image_type: str = 'left') -> np.ndarray
```

Get distortion coefficients for the rectified image.

Rectified frames have zero distortion by construction, so this
always returns zeros.

<ParamField>
  Accepted for API parity (`"left"` or `"right"`). Validated but otherwise ignored.
</ParamField>

**Returns:**

`np.ndarray` of shape `(5,)` filled with zeros, in
OpenCV order `[k1, k2, p1, p2, k3]`.

**Raises:**

ValueError: If `image_type` is not a recognized frame.

### `getExtrinsics()`

```python Signature theme={null}
getExtrinsics(source_image_frame: str, target_image_frame: str) -> np.ndarray
```

Get the 4x4 homogeneous transform between rectified sensor frames.

The returned matrix takes a 3D point (in meters) from
`source_image_frame` to `target_image_frame`. Since the
rectified left and right cameras differ only by a pure
`+baseline` translation along the rectified `+X` axis, the
result is rotation-free.

<ParamField>
  One of `"color"`, `"rgb"`, `"left"`, `"right"`. `"color"` and `"rgb"` are aliases for `"left"`.
</ParamField>

<ParamField>
  Same valid values as `source_image_frame`.
</ParamField>

**Returns:**

`np.ndarray` of shape `(4, 4)`.

**Raises:**

ValueError: If either frame name is unrecognized.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(
    *,
    image_type: str = 'rgb',
    camera_name: str = 'left',
    compressed: bool = False,
    resolution: Optional[Tuple[int, int]] = None,
    keep_aspect_ratio: bool = False,
) -> Image
```

Return the most recent rectified image.

<ParamField>
  One of `"rgb"`, `"left"`, `"right"`. `"rgb"` and `"left"` both return the left camera. Depth and point-cloud types are not supported by this class — use `ZedCamera` (SDK) for those.
</ParamField>

<ParamField>
  Used only when `image_type == "rgb"` to disambiguate which monocular view to return. One of `"left"` or `"right"`.
</ParamField>

<ParamField>
  When True, JPEG-encode the rectified image and return it as an `Image` with `encoding_format="jpeg"` (\~15-25x smaller on the wire); call `Image.decode()` on the result to get an RGB ndarray. When False (default), return a raw RGB ndarray `Image`.
</ParamField>

<ParamField>
  Target `(width, height)` in pixels to resize the frame to (bilinear) before any JPEG encoding. None (default) keeps the native resolution. Resized pixels no longer correspond to `getCameraMatrix()`, which keeps returning native-resolution intrinsics — scale fx/fy/cx/cy by the resize factors before deprojecting.
</ParamField>

<ParamField>
  Used only when `resolution` is given. When True, preserve the aspect ratio and center the scaled image on a zero (black) background; when False (default), stretch to exactly `resolution`.
</ParamField>

**Returns:**

An `Image` holding an `(H, W, 3)` `uint8` RGB array, or
JPEG bytes tagged `encoding_format="jpeg"` when `compressed`.

**Raises:**

ValueError: If `image_type` or `camera_name` is not one
of the documented values.
RuntimeError: If JPEG encoding fails when `compressed` is True.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getStereoImagePair()`

```python Signature theme={null}
getStereoImagePair() -> Tuple[Image, Image]
```

Get a synchronized rectified left/right RGB pair.

Both halves come from the same UVC frame, so they are
inherently time-synchronized.

**Returns:**

`(left, right)` as `Image` objects with `(H, W, 3)`
`uint8` RGB data.

### `recordCalibration()`

```python Signature theme={null}
recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

Swaps the recorded calibration block on the live camera object, so the
current session serves the new extrinsic without a rebuild. A falsy
value clears the recorded calibration. A non-empty block is validated
against the calibration schema before being installed and stored in the
same normalized form `from_config` records, so a malformed remote call
is rejected at the boundary rather than stored raw.

<ParamField>
  The recorded calibration block (transform plus provenance), as a calibration run produces it. A falsy value clears any recorded calibration.
</ParamField>

**Raises:**

ConfigValidationError: If a non-empty block does not satisfy the
calibration schema — e.g. a `status="calibrated"` block
missing its transform, a non-4x4 transform, or an unknown field.

### `reloadCalibration()`

```python Signature theme={null}
reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

Lets a running session pick up a recalibration in place, without
reconnecting. Available on a camera built from a config-file source
(see `grid_robot_api.config.record_calibration_sources`); a
co-located caller can pass the block to `recordCalibration`
directly instead.

**Returns:**

The calibration block that was installed, or `&#123;&#125;` when the config
names none for this camera.

**Raises:**

RuntimeError: If this camera was not built from a config-file source.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setCameraExtrinsics()`

```python Signature theme={null}
setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

Configures the camera's extrinsic transformation matrix representing
the camera pose relative to a reference frame.

<ParamField>
  4x4 homogeneous transformation matrix
</ParamField>

**Raises:**

ValueError: If transform is not a 4x4 matrix

### `setCameraIntrinsics()`

```python Signature theme={null}
setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

Configures the camera's intrinsic calibration parameters for
accurate image projection and rectification.

<ParamField>
  Focal length in x direction (pixels)
</ParamField>

<ParamField>
  Focal length in y direction (pixels)
</ParamField>

<ParamField>
  Principal point x coordinate (pixels)
</ParamField>

<ParamField>
  Principal point y coordinate (pixels)
</ParamField>

### `setCameraSettings()`

```python Signature theme={null}
setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

<ParamField type="CameraSettings">
  New camera configuration to apply
</ParamField>

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Fanuc CRX-30iA Arm
Source: https://docs.generalrobotics.dev/v2.3/python-api/fanuccrx30/fanuccrx30

The Fanuc CRX-30iA Arm as GRID drives it

The Fanuc CRX-30iA Arm as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `FanucCRX30`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<fanuccrx30-name>")
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `activate_end_effector()`

```python Signature theme={null}
activate_end_effector(*, auto_suspend_stream_motion: bool = True) -> None
```

Run the end effector's one-time activation sequence, if it has one.

Robotiq's adaptive and EPick grippers need a rising edge on their
activation bit before any grasp or release call works. A gripper left
at `activate_on_start=True` runs this from its own bring-up hook;
call it here when activation was deferred, and again after a
controller power-cycle.

**Commands physical motion** on an adaptive gripper: activation drives
a reference sweep in which the jaws stroke to relearn their travel, so
anything between the fingers is dropped or crushed. Run it with the
cell clear.

No-op for an arm with no end effector, for a gripper on the Stream
Motion channel, and for one whose TP programs need no activation — so
it is safe to call unconditionally.

<ParamField>
  Pause a running Stream Motion session around the activation. A live `STREAM_MOTN` holds controller execution and `FRC_Call` only replies once its program has completed, so without this the call blocks until the RMI socket times out. Defaults to True.
</ParamField>

**Raises:**

NotImplementedError: If the gripper needs activation but the arm
was constructed without an RMI backend.
RuntimeError: If the arm was constructed with `read_only=True`.
FanucFault: If the controller reports an alarm while activating;
the pendant codes are on `FanucFault.codes`.

### `addNamedPose()`

```python Signature theme={null}
addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses
(overriding any existing pair).

<ParamField>
  Name of the pose to define
</ParamField>

<ParamField>
  List of joint angles in radians
</ParamField>

**Raises:**

ValueError: If the length of joint\_angles list does match the length of other named
poses

### `followJointTrajectory()`

```python Signature theme={null}
followJointTrajectory(
    angles: list,
    duration: 'Optional[float | list[float]]' = None,
    *,
    speed_override: Optional[int] = None,
    term_value: Optional[int] = None,
    blocking: bool = True,
    prefer: str = 'auto',
    auto_suspend_stream_motion: bool = True,
    payload_kg: Optional[float] = None,
) -> None
```

Stream a joint-space trajectory through Stream Motion or RMI.

Routes by `prefer`, except that a backend-specific argument forces its
own backend: `speed_override`/`term_value` force RMI,
`blocking=False` forces Stream Motion, and mixing the two raises. On
`prefer="auto"` Stream Motion is tried first; if the trajectory asks
for more speed, acceleration or jerk than the arm allows, the call falls
back to RMI and logs a warning. When the call lands on RMI
while Stream Motion is running, Stream Motion is paused for the move and
resumed after. Blocks until the trajectory finishes unless
`blocking=False`.

See the Fanuc guide (`examples/arm/pick_and_place/fanuc.md`) for the
full routing table.

<ParamField>
  Ordered joint-angle targets in radians; each entry has one value per joint, as long as `getJointAngles()`.
</ParamField>

<ParamField>
  Trajectory duration in seconds — a single float for the total (split evenly across segments), or one duration per segment, in which case its length must equal `len(angles)` (the leading segment from the current pose to `angles[0]` plus each inter-waypoint segment). Every entry must be positive. Defaults to None (backend default).
</ParamField>

<ParamField>
  RMI speed override in percent (1-100). RMI only, and passing it forces RMI. Defaults to None.
</ParamField>

<ParamField>
  RMI blend radius, 0 (FINE) to 100 (full blend). RMI only, and passing it forces RMI. Defaults to None (`CNT_SMOOTH`).
</ParamField>

<ParamField>
  Wait for the trajectory to finish. Stream Motion only; passing False forces Stream Motion. Defaults to True.
</ParamField>

<ParamField>
  Routing preference — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"auto"`.
</ParamField>

<ParamField>
  Pause an active Stream Motion session for the duration of a move that lands on RMI, and resume after. Ignored when the call routes to SM. Defaults to True.
</ParamField>

<ParamField>
  Mass at the flange in kilograms (>= 0). A heavier load lowers the speed and acceleration the arm is allowed, so this sets what the safety check measures against. Defaults to None, which assumes the robot's rated maximum payload — the cautious reading when the caller has not said what is mounted. Pass 0.0 for an empty flange, the gripper's mass for an empty gripper, or gripper plus workpiece after grasping; nothing tracks what is on the wrist for you.
</ParamField>

**Raises:**

ValueError: If RMI-specific and Stream Motion-specific arguments are
mixed, if `prefer` is not one of the accepted values, if
`duration` is the wrong length or not positive, if
`payload_kg` is negative, or if the trajectory would exceed the
arm's speed, acceleration or jerk limits for the given payload.
NotImplementedError: If the arguments force a backend that is not
configured.

### `getCommandedJointAngles()`

```python Signature theme={null}
getCommandedJointAngles() -> list[float]
```

Return the joint angles the controller is currently commanding, in radians.

Asks the Stream Motion backend for the controller's commanded
position (the value the servo loop is targeting and the position SM
holds at between trajectories), which is where a streamed trajectory
must depart from — starting from the feedback position instead
injects the servo follow-error as a one-cycle step that the
controller's per-cycle jerk check reads as a spike (MOTN-722).

Resolves through the same
`FanucStreamMotion.command_anchor` the streaming thread uses,
so a trajectory planned from this value is streamed from that same
value. Resolving the two separately is what put an 80 ms buffer
lag on the wire as a one-cycle step at every stream-to-stream
boundary — see `command_anchor` for the full account.

Falls back to `getJointAngles` (feedback) when the Stream
Motion backend is not configured or the controller does not answer
the command-position request in time.

**Returns:**

Commanded joint angles in radians, ordered by joint index,
length `num_joints`.

### `getEndEffectorPose()`

```python Signature theme={null}
getEndEffectorPose() -> Pose
```

Return the full end-effector pose from the RMI backend.

**Returns:**

Pose: End-effector pose (position + orientation).

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> list[float]
```

Return current joint angles in radians.

Routed to the preferred joint-read backend (Stream Motion if
configured, else RMI).

**Returns:**

list\[float]: Current joint angles in radians, ordered by
joint index.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getNamedPose()`

```python Signature theme={null}
getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

<ParamField>
  Name of the pose to get (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose, or None if the named pose does not exist

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Orientation
```

Return the end-effector orientation from the RMI backend.

**Returns:**

Orientation: End-effector orientation as a quaternion.

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `getPose()`

```python Signature theme={null}
getPose() -> Pose
```

Return the current end-effector pose from the RMI backend.

**Returns:**

Pose: End-effector pose (position + orientation).

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Position
```

Return the end-effector position from the RMI backend.

**Returns:**

Position: End-effector position in meters.

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `grasp()`

```python Signature theme={null}
grasp(
    *,
    position: Optional[float] = None,
    force: Optional[float] = None,
    expect_grasp: Optional[bool] = None,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Close the gripper.

Which transport carries it is fixed when the gripper is built, not
chosen here: a gripper given an `io=` mapping is driven as a binary
digital-I/O device over Stream Motion, and any other gripper runs its
TP programs over RMI. On the Stream Motion channel the session is
managed for you — brought up if it is not running and put back
afterwards — so this works between planned moves, which leave no
session open.

Commands no arm travel. On the Stream Motion channel it may command a
zero-displacement hold to get the streaming thread going: the arm holds
its pose, it does not travel.

This never confirms the grip. Check with `validateGrasp`.

<ParamField>
  Target opening in the gripper's own units. RMI only, and only for a gripper whose TP programs take it. Defaults to None.
</ParamField>

<ParamField>
  Target grip force in the gripper's own units. RMI only, on the same terms as `position`. Defaults to None.
</ParamField>

<ParamField>
  Use the program that fails when nothing ends up between the fingers. RMI only. Defaults to None, meaning True on the RMI channel.
</ParamField>

<ParamField>
  Pause a running Stream Motion session around the grasp. RMI path only. Some gripper programs move the arm, and those would wait forever while Stream Motion holds it, so pausing is the safe default. Pass False if you know your gripper program only toggles I/O. Defaults to True.
</ParamField>

**Raises:**

NotImplementedError: If no end effector is attached, or the chosen
transport is not configured.
ValueError: If an RMI-only argument is passed to a gripper on the
Stream Motion channel, or if the gripper's TP programs do not
accept `position` / `force`.
RuntimeError: If a staged Stream Motion write was not sent before
the stream was released, or the controller reports a latched
alarm while bringing Stream Motion up.
TypeError: If the attached end effector is neither a Stream Motion
I/O gripper nor an RMIGripper.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    *,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Command a Cartesian velocity via the RMI backend.

<ParamField type="Velocity">
  Linear velocity command in m/s along each axis.
</ParamField>

<ParamField type="Velocity">
  Angular velocity command in rad/s about each axis.
</ParamField>

<ParamField type="str">
  Reference frame for the velocity command ("body" or "world"). Defaults to "body".
</ParamField>

<ParamField type="bool">
  If True (default) and Stream Motion is currently active, transparently pause it around this RMI move. See `moveToPose` for why this is required.
</ParamField>

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `moveToDeltaPose()`

```python Signature theme={null}
moveToDeltaPose(
    delta_pose: Pose,
    blocking: bool = True,
    *,
    prefer: str = 'auto',
    payload_kg: float = 0.0,
    pointcloud: Optional[Sequence] = None,
    speed_scale: float = _DEFAULT_SPEED_SCALE,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    speed: Optional[float] = None,
    continuous: Optional[bool] = None,
    term_value: Optional[int] = None,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Move the end-effector by a relative Cartesian delta.

Routes exactly as `moveToPose` does — an arm in Stream Motion mode
plans a collision-aware route to the composed pose, one in RMI mode
drives a straight line — so the two Cartesian verbs honor the arm's mode
alike. The composition itself is the base
`Arm.moveToDeltaPose` one: position added, orientation composed.

<ParamField type="Pose">
  Pose offset composed with the current end-effector pose (position added, orientation composed).
</ParamField>

<ParamField type="bool">
  Wait for movement to complete. RMI only; a planned move always blocks. Defaults to True.
</ParamField>

<ParamField type="str">
  Which path to take — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"auto"`.
</ParamField>

<ParamField type="float">
  Mass held at the flange in kilograms (>= 0). Planned path only. Defaults to 0.0.
</ParamField>

<ParamField type="Optional[Sequence]">
  Scene point cloud in the robot base frame (meters) to plan around. Planned path only. Defaults to None, meaning the robot avoids only itself.
</ParamField>

<ParamField type="float">
  How fast to move, as a fraction of the arm's rated limits. Planned path only.
</ParamField>

<ParamField type="Optional[float]">
  Total move duration in seconds. RMI only; rejected on the planned path. Defaults to None, meaning 0.5 on the RMI path.
</ParamField>

<ParamField type="Optional[float]">
  Acceleration ramp duration in seconds. RMI only; rejected on the planned path. Defaults to None, meaning 0.2 on the RMI path.
</ParamField>

<ParamField type="Optional[float]">
  Cartesian linear speed in m/s. RMI only; rejected on the planned path. Defaults to None, meaning 0.1 on the RMI path.
</ParamField>

<ParamField type="Optional[bool]">
  Use CNT blending instead of FINE. RMI only; rejected on the planned path. Defaults to None, meaning False on the RMI path.
</ParamField>

<ParamField type="Optional[int]">
  CNT blend radius (0-100). RMI only; rejected on the planned path. Defaults to None, meaning `CNT_MAX` on the RMI path.
</ParamField>

<ParamField type="bool">
  If True (default) and Stream Motion is currently active, transparently pause it around this RMI move. See `moveToPose` for why this is required.
</ParamField>

**Raises:**

ValueError: If `prefer` is not one of the accepted values, or if an
RMI-only argument is passed explicitly and the planned path is
taken.
NotImplementedError: If the chosen path's backend is not configured.
RuntimeError: On the planned path, if GRACE is not installed, if this
robot model has no `ROBOT_MODEL_NAME`, or if no collision-free
route to the composed pose exists.

### `moveToHome()`

```python Signature theme={null}
moveToHome(blocking: bool = True) -> None
```

Move the arm to its predefined home pose.

Equivalent to `moveToNamedPose("home", blocking=blocking)`. The
`"home"` entry is registered in `named_poses` from the abstract
`home_pose` property during `Arm.__init__`, so every concrete
arm has it. Subclasses may add hardware-specific tuning parameters as
keyword-only arguments after `blocking`.

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `moveToNamedPose()`

```python Signature theme={null}
moveToNamedPose(
    pose_name: str,
    blocking: bool = True,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
    *,
    speed_override: Optional[int] = None,
    prefer: str = 'rmi',
    auto_suspend_stream_motion: bool = True,
) -> None
```

Move to a previously registered named pose.

Named poses live on the composite (`self.named_poses`) and the move
executes via `setJointAngles`. Routes to RMI by default: named
poses are usually setup or recovery moves that swing the joints a long
way (from anywhere back to home), which the controller's own planner
handles smoothly, whereas Stream Motion's stricter smoothness check would
turn the same move down at the default duration.

<ParamField>
  Name of a pose previously registered via `setNamedPose`.
</ParamField>

<ParamField>
  Wait for the movement to complete. Defaults to True.
</ParamField>

<ParamField>
  Total move duration in seconds. Defaults to 2.0.
</ParamField>

<ParamField>
  Acceleration ramp duration in seconds. Defaults to 0.75.
</ParamField>

<ParamField>
  RMI speed override in percent (1-100). RMI only, and passing it forces RMI. Defaults to None.
</ParamField>

<ParamField>
  Routing preference forwarded to `setJointAngles` — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"rmi"`.
</ParamField>

<ParamField>
  Pause an active Stream Motion session for the duration of a move that lands on RMI. Defaults to True.
</ParamField>

**Raises:**

ValueError: If `pose_name` is not a registered named pose.

### `moveToPose()`

```python Signature theme={null}
moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    prefer: str = 'auto',
    payload_kg: float = 0.0,
    pointcloud: Optional[Sequence] = None,
    speed_scale: float = _DEFAULT_SPEED_SCALE,
    avoid_force: bool = True,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    speed: Optional[float] = None,
    continuous: Optional[bool] = None,
    term_value: Optional[int] = None,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Move the end-effector to a Cartesian pose.

Two ways to get there, and by default the arm picks the one matching the
mode it is in — **RMI** drives a straight line and hits whatever is in the
way; **Stream Motion** plans a collision-aware route around the robot (and
around a `pointcloud` if you pass one) and streams it, which needs GRACE
installed and does not travel in a straight line. Pass `prefer` to force
one for a single call without changing the arm's mode.

Args below are marked for the path they apply to; the other path ignores
them. See `examples/arm/pick_and_place/fanuc.md` for the routing table.

<ParamField>
  Target end-effector pose in the base frame (position in meters, orientation as a unit quaternion).
</ParamField>

<ParamField>
  Wait for the movement to complete. RMI only; a planned move always blocks. Defaults to True.
</ParamField>

<ParamField>
  Which path to take — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"auto"`.
</ParamField>

<ParamField>
  Mass held at the flange in kilograms (>= 0), which lowers the speed and acceleration a planned move is allowed. Planned path only. Defaults to 0.0.
</ParamField>

<ParamField>
  Scene point cloud in the robot base frame (meters) to plan around. Planned path only; the grasped object is not included. Defaults to None, meaning the robot avoids only itself.
</ParamField>

<ParamField>
  How fast to move, as a fraction of the arm's rated limits, from just above 0 up to 1.0. Scales speed, acceleration and jerk together. Planned path only; lower is slower with more margin.
</ParamField>

<ParamField>
  Accepted for signature parity with the other arms and with `FanucRMI`. It is a no-op on this arm on both paths — no Cartesian force limit is applied. Defaults to True.
</ParamField>

<ParamField>
  Total move duration in seconds. RMI only; rejected on the planned path. Defaults to None, meaning 2.0 on the RMI path.
</ParamField>

<ParamField>
  Acceleration ramp duration in seconds. RMI only; rejected on the planned path. Defaults to None, meaning 0.5 on the RMI path.
</ParamField>

<ParamField>
  Cartesian linear speed in m/s. RMI only; rejected on the planned path. Defaults to None, meaning 0.1 on the RMI path.
</ParamField>

<ParamField>
  Blend through the target instead of stopping on it. RMI only; rejected on the planned path. Defaults to None, meaning False on the RMI path.
</ParamField>

<ParamField>
  Blend radius, 0 (stop exactly) to 100 (full blend). RMI only; rejected on the planned path. Defaults to None, meaning `CNT_MAX` on the RMI path.
</ParamField>

<ParamField>
  Pause a running Stream Motion session for the duration of an RMI move and resume it after, since Stream Motion holds the arm and an RMI move issued underneath it would wait forever. RMI path only. Defaults to True.
</ParamField>

**Raises:**

ValueError: If `prefer` is not one of the accepted values, or if an
RMI-only argument is passed explicitly and the planned path is
taken.
NotImplementedError: If the chosen path's backend is not configured.
RuntimeError: On the planned path, if GRACE is not installed, if this
robot model has no `ROBOT_MODEL_NAME`, or if no collision-free
route to `pose` exists.

### `nativeToUrdfJoints()`

```python Signature theme={null}
nativeToUrdfJoints(angles: list[float]) -> list[float]
```

Convert FANUC wire-convention joints to the serial (URDF) convention.

FANUC controllers report and accept J3 world-referenced — the
controller folds J2 motion out of J3 (the J2/J3 interaction) — while
a serial-chain URDF expresses J3 relative to the upper arm. The
mapping is `J3_serial = J3_wire + J2`, verified on a real CRX-30iA
(FK of `J3_wire + J2` reproduces the controller's own Cartesian
TCP; the raw wire values do not). This is a reporting-convention
difference, not geometry: both the RMI and Stream Motion backends
deliberately speak the raw wire convention, so the conversion lives
here at the arm boundary, never in the URDF.

`urdfToNativeJoints` is the exact inverse.

<ParamField>
  Joint vector in FANUC wire convention (radians), ordered J1..Jn with n >= 3.
</ParamField>

**Returns:**

The same physical configuration in serial (URDF) convention
(radians), as a new list (`result[2] = angles[2] + angles[1]`).

**Raises:**

ValueError: If `angles` has fewer than 3 entries — the J2/J3
conversion needs at least joints J1..J3.

### `network_addresses()`

```python Signature theme={null}
network_addresses(args: dict) -> list[str]
```

Controller addresses a routing check should verify for these args.

<ParamField>
  Config `args` for this robot, as the wizard collected them.
</ParamField>

**Returns:**

The controller address, or none when no address is configured.

### `readFaultCodes()`

```python Signature theme={null}
readFaultCodes(fault: RobotFault) -> list[str]
```

Return the controller alarm codes for a caught fault, best-effort.

Uses the codes already attached to `fault` when it has them. RMI faults
usually do not, so for those this asks the controller for its current
alarm codes instead. Only ask while the arm is idle — call this where you
catch the fault, not mid-motion. It never raises: if the read fails you
get the fault's own codes back (possibly none), so this can never block
your recovery path.

<ParamField>
  The caught controller fault to resolve codes for.
</ParamField>

**Returns:**

list\[str]: Alarm codes in `"XXXX-NNN"` form (e.g.
`["MOTN-722"]`), most-recent first. Empty when none were
attached to the fault and none could be read back (no RMI
backend configured, or the read-back failed).

### `recoverFromFault()`

```python Signature theme={null}
recoverFromFault(fault: RobotFault) -> bool
```

Try to clear a controller fault and get the arm ready to move again.

Call this where you catch a fault, before retrying whatever failed. It
clears the alarm and puts Stream Motion back the way it was, so a retry
starts from a known state rather than a half-torn-down one.

A fault the driver marked unrecoverable is not worth resetting, so this
returns False without touching the arm. Otherwise a False means the alarm
is still latched — an emergency stop or a servo alarm — and somebody has
to clear it on the teach pendant before the robot will move.

Never raises: a failed reset is an answer (False), not an error, so your
recovery path is never itself the thing that crashes.

<ParamField>
  The controller fault you caught.
</ParamField>

**Returns:**

True when the arm is cleared and ready to retry, False when it is not
and a human needs to intervene.

### `release()`

```python Signature theme={null}
release(
    *,
    force: Optional[float] = None,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Open the gripper.

Mirrors `grasp`, including the transport choice and the Stream
Motion session handling. On the Stream Motion channel it drives the
open pattern, holds it for the mapping's `release_hold_s`, then
returns the gripper to idle — FANUC outputs latch, so otherwise the
release solenoid would stay energized indefinitely.

<ParamField>
  Target release force in the gripper's own units. RMI only, and only for a gripper whose TP programs take it. Defaults to None.
</ParamField>

<ParamField>
  Pause a running Stream Motion session around the release. RMI path only; see `grasp` for why this is the safe default. Defaults to True.
</ParamField>

**Raises:**

NotImplementedError: If no end effector is attached, or the chosen
transport is not configured.
ValueError: If `force` is passed to a gripper on the Stream
Motion channel, or if the gripper's TP programs do not accept
it.
RuntimeError: If a staged Stream Motion write was not sent before
the stream was released, or the controller reports a latched
alarm while bringing Stream Motion up.
TypeError: If the attached end effector is neither a Stream Motion
I/O gripper nor an RMIGripper.

### `removeNamedPose()`

```python Signature theme={null}
removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

<ParamField>
  Name of the pose to remove (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose that was removed, or None if the named
pose did not exist

### `reset()`

```python Signature theme={null}
reset() -> None
```

Reset / reconnect every configured backend.

Errors from one backend do not prevent the others from being
reset. The first encountered error is re-raised after every
backend has been reset.

**Raises:**

Exception: The first error raised by any backend, after all
backends have been asked to reset.

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = True,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    *,
    speed_override: Optional[int] = None,
    continuous: bool = False,
    term_value: Optional[int] = None,
    max_joint_speed_rad_s: Optional[float] = None,
    prefer: str = 'auto',
    auto_suspend_stream_motion: bool = True,
) -> None
```

Move the arm to the given joint angles.

Routes by `prefer`, except that a backend-specific argument forces its
own backend: `speed_override`, `continuous=True` or `term_value`
force RMI, `max_joint_speed_rad_s` forces Stream Motion, and mixing the
two sets raises. When the call lands on RMI while Stream Motion is
active, SM is paused for the move and resumed after.

<ParamField>
  Target joint angles in radians, one per joint.
</ParamField>

<ParamField>
  Wait for the movement to complete. Defaults to True.
</ParamField>

<ParamField>
  Movement duration in seconds. Defaults to None (backend default).
</ParamField>

<ParamField>
  Acceleration ramp time in seconds. Defaults to None.
</ParamField>

<ParamField>
  RMI speed override in percent (1-100). RMI only, and passing it forces RMI. Defaults to None.
</ParamField>

<ParamField>
  Use RMI CNT blending instead of FINE. RMI only, and passing True forces RMI. Defaults to False.
</ParamField>

<ParamField>
  RMI blend radius, 0 (FINE) to 100 (full blend). RMI only, and passing it forces RMI. Defaults to None (`CNT_MAX`).
</ParamField>

<ParamField>
  Stream Motion peak joint speed in rad/s, used to derive the duration when `moving_time` is None. Stream Motion only, and passing it forces SM. Defaults to None.
</ParamField>

<ParamField>
  Routing preference — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"auto"`.
</ParamField>

<ParamField>
  Pause an active Stream Motion session for the duration of a move that lands on RMI. Ignored when the call routes to SM. Defaults to True.
</ParamField>

**Raises:**

ValueError: If RMI-specific and Stream Motion-specific arguments are
mixed, or if `prefer` is not one of the accepted values.
NotImplementedError: If the arguments force a backend that is not
configured.

### `setPayload()`

```python Signature theme={null}
setPayload(schedule_number: int) -> None
```

Select a payload schedule on the controller.

<ParamField type="int">
  Payload schedule number on the controller (1-based).
</ParamField>

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `setSpeedOverride()`

```python Signature theme={null}
setSpeedOverride(speed_override: int) -> None
```

Set the controller's global speed override percentage.

<ParamField type="int">
  Speed override as percent (1-100).
</ParamField>

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `start_stream_motion()`

```python Signature theme={null}
start_stream_motion(timeout_s: float = _RESUME_CMD_READY_TIMEOUT_S) -> None
```

Start Stream Motion so high-rate joint streaming can run.

This is both the first-time start for an arm built with
`use_stream_motion=False`, and the counterpart to
`stop_stream_motion` after an RMI move paused the session. It
clears the position the controller was last told to hold, hands motion
control over, starts the controller-side program and waits until the
controller is accepting commands.

If an alarm is still latched this refuses to start rather than quietly
clearing it — acknowledge the alarm first with `reset` or on the
teach pendant.

Idempotent: a no-op when no Stream Motion backend is configured, or when
a session is already running.

<ParamField>
  Seconds to wait for the controller to report it is accepting commands. Defaults to 5.0.
</ParamField>

**Raises:**

RuntimeError: If `stream_motion` is configured but `rmi` is not
(RMI is what relaunches the program), or if the controller
reports a latched alarm.
TimeoutError: If the controller does not report itself ready within
`timeout_s`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

### `stop_stream_motion()`

```python Signature theme={null}
stop_stream_motion() -> None
```

Pause Stream Motion so RMI moves can run.

While a Stream Motion session is running it holds the arm, and any RMI
move issued underneath it would simply wait forever. This stops the
session so RMI can take over. Joint feedback keeps flowing throughout —
only command control is handed back — so reads still work while paused,
and `start_stream_motion` resumes.

Idempotent: a no-op when no Stream Motion backend is configured, or when
it is already paused.

**Raises:**

RuntimeError: If `stream_motion` is configured but `rmi` is not —
RMI is what stops the controller-side program.

### `urdfToNativeJoints()`

```python Signature theme={null}
urdfToNativeJoints(angles: list[float]) -> list[float]
```

Convert serial-convention (URDF) joints to the FANUC wire convention.

Exact inverse of `nativeToUrdfJoints`
(`result[2] = angles[2] - angles[1]`). Apply to every joint vector
produced by a motion planner before handing it to this arm's
execution methods — the RMI and Stream Motion backends speak the raw
FANUC wire convention, in which J3 is world-referenced (the J2/J3
interaction). Executing serial-convention joints raw moves the elbow
wrong by exactly J2.

<ParamField>
  Joint vector in serial (URDF) convention (radians), ordered J1..Jn with n >= 3.
</ParamField>

**Returns:**

The same physical configuration in FANUC wire convention
(radians), as a new list.

**Raises:**

ValueError: If `angles` has fewer than 3 entries — the J2/J3
conversion needs at least joints J1..J3.

### `validateGrasp()`

```python Signature theme={null}
validateGrasp() -> bool
```

Report whether the gripper is currently holding a part.

On the **Stream Motion** channel this takes a fresh reading rather than
trusting a cached one: it brings the session up if needed, discards the
previous value, waits for the sensor to settle from live status
packets, and puts the session back. A part can be lost while nothing is
streaming, so a cached value could report a part that is gone.

Commands physical motion when the streaming thread is not already
running: a zero-displacement hold at the current joint angles. The arm
holds its pose; it does not travel.

On the **RMI** channel this asks the gripper itself, and the base
gripper has no sensor to ask — grip state lives on the controller.

**Returns:**

bool: True when a gripped part is detected. False when the sensor
reads open, and also when no stable reading arrives within the
mapping's `confirm_timeout_s` — an unknown state never reads as
"holding".

**Raises:**

NotImplementedError: On the RMI channel, where the gripper has no
grip sensor; or on the Stream Motion channel when the mapping
configures no feedback point.
RuntimeError: If no end effector is attached, or the controller
reports a latched alarm while bringing Stream Motion up.
TimeoutError: If Stream Motion does not become ready to accept
commands.

## Properties on the robot

Read as `robot.<property>`; each read runs the getter on the robot.

<ResponseField name="home_pose" type="list[float]">
  Joint angles (radians) defining the CRX-30iA home pose.
</ResponseField>

<ResponseField name="named_poses" type="Dict[str, List[float]]">
  Registered poses as `&#123;name: joint angles in radians&#125;` (a copy).

  Mutating the returned mapping does not change what the arm knows:
  register and remove entries with `addNamedPose` and
  `removeNamedPose`, or assign a whole mapping to replace them all.
</ResponseField>

<ResponseField name="total_payload_kg" type="float">
  Worst-case total mass at the flange.

  Always returns the robot's rated `max_payload_kg` (or 0.0
  if the subclass doesn't define one). The end-effector spec's
  `mass_kg` and `held_mass_kg` fields are NOT auto-applied
  here, deliberately: an end-effector picks up and drops
  workpieces, and any host-side count of "what's currently on
  the wrist" is fragile (one missed update and the pre-flight
  runs against a too-permissive limit, controller alarms).

  To opt into a lower payload for a specific motion, pass
  `payload_kg=...` per call. That makes the assumption
  explicit at the call site instead of buried in cached state.
  For a fully-empty arm: `payload_kg=0.0`. For a known
  gripper-only weight: `payload_kg=ee.mass_kg`. For a
  gripper carrying a known workpiece:
  `payload_kg=ee.mass_kg + workpiece_kg`.
</ResponseField>

## Configured children

* `robot.end_effector` — the gripper, chosen in the robot's configuration; when one is fitted, its methods are the [`EndEffector`](/v2.3/python-api/robot-interface/endeffector) interface's.

## Not implemented on this robot

Declared by the interface, raises `NotImplementedError` here: `endFreeDrive`, `startFreeDrive`.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the children this class always ships with (customization point).
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()` — Describe the config `args` the setup wizard should offer.
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# Fanuc LR Mate 200iD Arm
Source: https://docs.generalrobotics.dev/v2.3/python-api/fanuclrmate200id/fanuclrmate200id

The Fanuc LR Mate 200iD Arm as GRID drives it

The Fanuc LR Mate 200iD Arm as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `FanucLRMate200iD`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<fanuclrmate200id-name>")
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `activate_end_effector()`

```python Signature theme={null}
activate_end_effector(*, auto_suspend_stream_motion: bool = True) -> None
```

Run the end effector's one-time activation sequence, if it has one.

Robotiq's adaptive and EPick grippers need a rising edge on their
activation bit before any grasp or release call works. A gripper left
at `activate_on_start=True` runs this from its own bring-up hook;
call it here when activation was deferred, and again after a
controller power-cycle.

**Commands physical motion** on an adaptive gripper: activation drives
a reference sweep in which the jaws stroke to relearn their travel, so
anything between the fingers is dropped or crushed. Run it with the
cell clear.

No-op for an arm with no end effector, for a gripper on the Stream
Motion channel, and for one whose TP programs need no activation — so
it is safe to call unconditionally.

<ParamField>
  Pause a running Stream Motion session around the activation. A live `STREAM_MOTN` holds controller execution and `FRC_Call` only replies once its program has completed, so without this the call blocks until the RMI socket times out. Defaults to True.
</ParamField>

**Raises:**

NotImplementedError: If the gripper needs activation but the arm
was constructed without an RMI backend.
RuntimeError: If the arm was constructed with `read_only=True`.
FanucFault: If the controller reports an alarm while activating;
the pendant codes are on `FanucFault.codes`.

### `addNamedPose()`

```python Signature theme={null}
addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses
(overriding any existing pair).

<ParamField>
  Name of the pose to define
</ParamField>

<ParamField>
  List of joint angles in radians
</ParamField>

**Raises:**

ValueError: If the length of joint\_angles list does match the length of other named
poses

### `followJointTrajectory()`

```python Signature theme={null}
followJointTrajectory(
    angles: list,
    duration: 'Optional[float | list[float]]' = None,
    *,
    speed_override: Optional[int] = None,
    term_value: Optional[int] = None,
    blocking: bool = True,
    prefer: str = 'auto',
    auto_suspend_stream_motion: bool = True,
    payload_kg: Optional[float] = None,
) -> None
```

Stream a joint-space trajectory through Stream Motion or RMI.

Routes by `prefer`, except that a backend-specific argument forces its
own backend: `speed_override`/`term_value` force RMI,
`blocking=False` forces Stream Motion, and mixing the two raises. On
`prefer="auto"` Stream Motion is tried first; if the trajectory asks
for more speed, acceleration or jerk than the arm allows, the call falls
back to RMI and logs a warning. When the call lands on RMI
while Stream Motion is running, Stream Motion is paused for the move and
resumed after. Blocks until the trajectory finishes unless
`blocking=False`.

See the Fanuc guide (`examples/arm/pick_and_place/fanuc.md`) for the
full routing table.

<ParamField>
  Ordered joint-angle targets in radians; each entry has one value per joint, as long as `getJointAngles()`.
</ParamField>

<ParamField>
  Trajectory duration in seconds — a single float for the total (split evenly across segments), or one duration per segment, in which case its length must equal `len(angles)` (the leading segment from the current pose to `angles[0]` plus each inter-waypoint segment). Every entry must be positive. Defaults to None (backend default).
</ParamField>

<ParamField>
  RMI speed override in percent (1-100). RMI only, and passing it forces RMI. Defaults to None.
</ParamField>

<ParamField>
  RMI blend radius, 0 (FINE) to 100 (full blend). RMI only, and passing it forces RMI. Defaults to None (`CNT_SMOOTH`).
</ParamField>

<ParamField>
  Wait for the trajectory to finish. Stream Motion only; passing False forces Stream Motion. Defaults to True.
</ParamField>

<ParamField>
  Routing preference — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"auto"`.
</ParamField>

<ParamField>
  Pause an active Stream Motion session for the duration of a move that lands on RMI, and resume after. Ignored when the call routes to SM. Defaults to True.
</ParamField>

<ParamField>
  Mass at the flange in kilograms (>= 0). A heavier load lowers the speed and acceleration the arm is allowed, so this sets what the safety check measures against. Defaults to None, which assumes the robot's rated maximum payload — the cautious reading when the caller has not said what is mounted. Pass 0.0 for an empty flange, the gripper's mass for an empty gripper, or gripper plus workpiece after grasping; nothing tracks what is on the wrist for you.
</ParamField>

**Raises:**

ValueError: If RMI-specific and Stream Motion-specific arguments are
mixed, if `prefer` is not one of the accepted values, if
`duration` is the wrong length or not positive, if
`payload_kg` is negative, or if the trajectory would exceed the
arm's speed, acceleration or jerk limits for the given payload.
NotImplementedError: If the arguments force a backend that is not
configured.

### `getCommandedJointAngles()`

```python Signature theme={null}
getCommandedJointAngles() -> list[float]
```

Return the joint angles the controller is currently commanding, in radians.

Asks the Stream Motion backend for the controller's commanded
position (the value the servo loop is targeting and the position SM
holds at between trajectories), which is where a streamed trajectory
must depart from — starting from the feedback position instead
injects the servo follow-error as a one-cycle step that the
controller's per-cycle jerk check reads as a spike (MOTN-722).

Resolves through the same
`FanucStreamMotion.command_anchor` the streaming thread uses,
so a trajectory planned from this value is streamed from that same
value. Resolving the two separately is what put an 80 ms buffer
lag on the wire as a one-cycle step at every stream-to-stream
boundary — see `command_anchor` for the full account.

Falls back to `getJointAngles` (feedback) when the Stream
Motion backend is not configured or the controller does not answer
the command-position request in time.

**Returns:**

Commanded joint angles in radians, ordered by joint index,
length `num_joints`.

### `getEndEffectorPose()`

```python Signature theme={null}
getEndEffectorPose() -> Pose
```

Return the full end-effector pose from the RMI backend.

**Returns:**

Pose: End-effector pose (position + orientation).

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> list[float]
```

Return current joint angles in radians.

Routed to the preferred joint-read backend (Stream Motion if
configured, else RMI).

**Returns:**

list\[float]: Current joint angles in radians, ordered by
joint index.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getNamedPose()`

```python Signature theme={null}
getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

<ParamField>
  Name of the pose to get (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose, or None if the named pose does not exist

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Orientation
```

Return the end-effector orientation from the RMI backend.

**Returns:**

Orientation: End-effector orientation as a quaternion.

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `getPose()`

```python Signature theme={null}
getPose() -> Pose
```

Return the current end-effector pose from the RMI backend.

**Returns:**

Pose: End-effector pose (position + orientation).

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Position
```

Return the end-effector position from the RMI backend.

**Returns:**

Position: End-effector position in meters.

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `grasp()`

```python Signature theme={null}
grasp(
    *,
    position: Optional[float] = None,
    force: Optional[float] = None,
    expect_grasp: Optional[bool] = None,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Close the gripper.

Which transport carries it is fixed when the gripper is built, not
chosen here: a gripper given an `io=` mapping is driven as a binary
digital-I/O device over Stream Motion, and any other gripper runs its
TP programs over RMI. On the Stream Motion channel the session is
managed for you — brought up if it is not running and put back
afterwards — so this works between planned moves, which leave no
session open.

Commands no arm travel. On the Stream Motion channel it may command a
zero-displacement hold to get the streaming thread going: the arm holds
its pose, it does not travel.

This never confirms the grip. Check with `validateGrasp`.

<ParamField>
  Target opening in the gripper's own units. RMI only, and only for a gripper whose TP programs take it. Defaults to None.
</ParamField>

<ParamField>
  Target grip force in the gripper's own units. RMI only, on the same terms as `position`. Defaults to None.
</ParamField>

<ParamField>
  Use the program that fails when nothing ends up between the fingers. RMI only. Defaults to None, meaning True on the RMI channel.
</ParamField>

<ParamField>
  Pause a running Stream Motion session around the grasp. RMI path only. Some gripper programs move the arm, and those would wait forever while Stream Motion holds it, so pausing is the safe default. Pass False if you know your gripper program only toggles I/O. Defaults to True.
</ParamField>

**Raises:**

NotImplementedError: If no end effector is attached, or the chosen
transport is not configured.
ValueError: If an RMI-only argument is passed to a gripper on the
Stream Motion channel, or if the gripper's TP programs do not
accept `position` / `force`.
RuntimeError: If a staged Stream Motion write was not sent before
the stream was released, or the controller reports a latched
alarm while bringing Stream Motion up.
TypeError: If the attached end effector is neither a Stream Motion
I/O gripper nor an RMIGripper.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    *,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Command a Cartesian velocity via the RMI backend.

<ParamField type="Velocity">
  Linear velocity command in m/s along each axis.
</ParamField>

<ParamField type="Velocity">
  Angular velocity command in rad/s about each axis.
</ParamField>

<ParamField type="str">
  Reference frame for the velocity command ("body" or "world"). Defaults to "body".
</ParamField>

<ParamField type="bool">
  If True (default) and Stream Motion is currently active, transparently pause it around this RMI move. See `moveToPose` for why this is required.
</ParamField>

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `moveToDeltaPose()`

```python Signature theme={null}
moveToDeltaPose(
    delta_pose: Pose,
    blocking: bool = True,
    *,
    prefer: str = 'auto',
    payload_kg: float = 0.0,
    pointcloud: Optional[Sequence] = None,
    speed_scale: float = _DEFAULT_SPEED_SCALE,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    speed: Optional[float] = None,
    continuous: Optional[bool] = None,
    term_value: Optional[int] = None,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Move the end-effector by a relative Cartesian delta.

Routes exactly as `moveToPose` does — an arm in Stream Motion mode
plans a collision-aware route to the composed pose, one in RMI mode
drives a straight line — so the two Cartesian verbs honor the arm's mode
alike. The composition itself is the base
`Arm.moveToDeltaPose` one: position added, orientation composed.

<ParamField type="Pose">
  Pose offset composed with the current end-effector pose (position added, orientation composed).
</ParamField>

<ParamField type="bool">
  Wait for movement to complete. RMI only; a planned move always blocks. Defaults to True.
</ParamField>

<ParamField type="str">
  Which path to take — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"auto"`.
</ParamField>

<ParamField type="float">
  Mass held at the flange in kilograms (>= 0). Planned path only. Defaults to 0.0.
</ParamField>

<ParamField type="Optional[Sequence]">
  Scene point cloud in the robot base frame (meters) to plan around. Planned path only. Defaults to None, meaning the robot avoids only itself.
</ParamField>

<ParamField type="float">
  How fast to move, as a fraction of the arm's rated limits. Planned path only.
</ParamField>

<ParamField type="Optional[float]">
  Total move duration in seconds. RMI only; rejected on the planned path. Defaults to None, meaning 0.5 on the RMI path.
</ParamField>

<ParamField type="Optional[float]">
  Acceleration ramp duration in seconds. RMI only; rejected on the planned path. Defaults to None, meaning 0.2 on the RMI path.
</ParamField>

<ParamField type="Optional[float]">
  Cartesian linear speed in m/s. RMI only; rejected on the planned path. Defaults to None, meaning 0.1 on the RMI path.
</ParamField>

<ParamField type="Optional[bool]">
  Use CNT blending instead of FINE. RMI only; rejected on the planned path. Defaults to None, meaning False on the RMI path.
</ParamField>

<ParamField type="Optional[int]">
  CNT blend radius (0-100). RMI only; rejected on the planned path. Defaults to None, meaning `CNT_MAX` on the RMI path.
</ParamField>

<ParamField type="bool">
  If True (default) and Stream Motion is currently active, transparently pause it around this RMI move. See `moveToPose` for why this is required.
</ParamField>

**Raises:**

ValueError: If `prefer` is not one of the accepted values, or if an
RMI-only argument is passed explicitly and the planned path is
taken.
NotImplementedError: If the chosen path's backend is not configured.
RuntimeError: On the planned path, if GRACE is not installed, if this
robot model has no `ROBOT_MODEL_NAME`, or if no collision-free
route to the composed pose exists.

### `moveToHome()`

```python Signature theme={null}
moveToHome(blocking: bool = True) -> None
```

Move the arm to its predefined home pose.

Equivalent to `moveToNamedPose("home", blocking=blocking)`. The
`"home"` entry is registered in `named_poses` from the abstract
`home_pose` property during `Arm.__init__`, so every concrete
arm has it. Subclasses may add hardware-specific tuning parameters as
keyword-only arguments after `blocking`.

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `moveToNamedPose()`

```python Signature theme={null}
moveToNamedPose(
    pose_name: str,
    blocking: bool = True,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
    *,
    speed_override: Optional[int] = None,
    prefer: str = 'rmi',
    auto_suspend_stream_motion: bool = True,
) -> None
```

Move to a previously registered named pose.

Named poses live on the composite (`self.named_poses`) and the move
executes via `setJointAngles`. Routes to RMI by default: named
poses are usually setup or recovery moves that swing the joints a long
way (from anywhere back to home), which the controller's own planner
handles smoothly, whereas Stream Motion's stricter smoothness check would
turn the same move down at the default duration.

<ParamField>
  Name of a pose previously registered via `setNamedPose`.
</ParamField>

<ParamField>
  Wait for the movement to complete. Defaults to True.
</ParamField>

<ParamField>
  Total move duration in seconds. Defaults to 2.0.
</ParamField>

<ParamField>
  Acceleration ramp duration in seconds. Defaults to 0.75.
</ParamField>

<ParamField>
  RMI speed override in percent (1-100). RMI only, and passing it forces RMI. Defaults to None.
</ParamField>

<ParamField>
  Routing preference forwarded to `setJointAngles` — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"rmi"`.
</ParamField>

<ParamField>
  Pause an active Stream Motion session for the duration of a move that lands on RMI. Defaults to True.
</ParamField>

**Raises:**

ValueError: If `pose_name` is not a registered named pose.

### `moveToPose()`

```python Signature theme={null}
moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    prefer: str = 'auto',
    payload_kg: float = 0.0,
    pointcloud: Optional[Sequence] = None,
    speed_scale: float = _DEFAULT_SPEED_SCALE,
    avoid_force: bool = True,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    speed: Optional[float] = None,
    continuous: Optional[bool] = None,
    term_value: Optional[int] = None,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Move the end-effector to a Cartesian pose.

Two ways to get there, and by default the arm picks the one matching the
mode it is in — **RMI** drives a straight line and hits whatever is in the
way; **Stream Motion** plans a collision-aware route around the robot (and
around a `pointcloud` if you pass one) and streams it, which needs GRACE
installed and does not travel in a straight line. Pass `prefer` to force
one for a single call without changing the arm's mode.

Args below are marked for the path they apply to; the other path ignores
them. See `examples/arm/pick_and_place/fanuc.md` for the routing table.

<ParamField>
  Target end-effector pose in the base frame (position in meters, orientation as a unit quaternion).
</ParamField>

<ParamField>
  Wait for the movement to complete. RMI only; a planned move always blocks. Defaults to True.
</ParamField>

<ParamField>
  Which path to take — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"auto"`.
</ParamField>

<ParamField>
  Mass held at the flange in kilograms (>= 0), which lowers the speed and acceleration a planned move is allowed. Planned path only. Defaults to 0.0.
</ParamField>

<ParamField>
  Scene point cloud in the robot base frame (meters) to plan around. Planned path only; the grasped object is not included. Defaults to None, meaning the robot avoids only itself.
</ParamField>

<ParamField>
  How fast to move, as a fraction of the arm's rated limits, from just above 0 up to 1.0. Scales speed, acceleration and jerk together. Planned path only; lower is slower with more margin.
</ParamField>

<ParamField>
  Accepted for signature parity with the other arms and with `FanucRMI`. It is a no-op on this arm on both paths — no Cartesian force limit is applied. Defaults to True.
</ParamField>

<ParamField>
  Total move duration in seconds. RMI only; rejected on the planned path. Defaults to None, meaning 2.0 on the RMI path.
</ParamField>

<ParamField>
  Acceleration ramp duration in seconds. RMI only; rejected on the planned path. Defaults to None, meaning 0.5 on the RMI path.
</ParamField>

<ParamField>
  Cartesian linear speed in m/s. RMI only; rejected on the planned path. Defaults to None, meaning 0.1 on the RMI path.
</ParamField>

<ParamField>
  Blend through the target instead of stopping on it. RMI only; rejected on the planned path. Defaults to None, meaning False on the RMI path.
</ParamField>

<ParamField>
  Blend radius, 0 (stop exactly) to 100 (full blend). RMI only; rejected on the planned path. Defaults to None, meaning `CNT_MAX` on the RMI path.
</ParamField>

<ParamField>
  Pause a running Stream Motion session for the duration of an RMI move and resume it after, since Stream Motion holds the arm and an RMI move issued underneath it would wait forever. RMI path only. Defaults to True.
</ParamField>

**Raises:**

ValueError: If `prefer` is not one of the accepted values, or if an
RMI-only argument is passed explicitly and the planned path is
taken.
NotImplementedError: If the chosen path's backend is not configured.
RuntimeError: On the planned path, if GRACE is not installed, if this
robot model has no `ROBOT_MODEL_NAME`, or if no collision-free
route to `pose` exists.

### `nativeToUrdfJoints()`

```python Signature theme={null}
nativeToUrdfJoints(angles: list[float]) -> list[float]
```

Convert FANUC wire-convention joints to the serial (URDF) convention.

FANUC controllers report and accept J3 world-referenced — the
controller folds J2 motion out of J3 (the J2/J3 interaction) — while
a serial-chain URDF expresses J3 relative to the upper arm. The
mapping is `J3_serial = J3_wire + J2`, verified on a real CRX-30iA
(FK of `J3_wire + J2` reproduces the controller's own Cartesian
TCP; the raw wire values do not). This is a reporting-convention
difference, not geometry: both the RMI and Stream Motion backends
deliberately speak the raw wire convention, so the conversion lives
here at the arm boundary, never in the URDF.

`urdfToNativeJoints` is the exact inverse.

<ParamField>
  Joint vector in FANUC wire convention (radians), ordered J1..Jn with n >= 3.
</ParamField>

**Returns:**

The same physical configuration in serial (URDF) convention
(radians), as a new list (`result[2] = angles[2] + angles[1]`).

**Raises:**

ValueError: If `angles` has fewer than 3 entries — the J2/J3
conversion needs at least joints J1..J3.

### `network_addresses()`

```python Signature theme={null}
network_addresses(args: dict) -> list[str]
```

Controller addresses a routing check should verify for these args.

<ParamField>
  Config `args` for this robot, as the wizard collected them.
</ParamField>

**Returns:**

The controller address, or none when no address is configured.

### `readFaultCodes()`

```python Signature theme={null}
readFaultCodes(fault: RobotFault) -> list[str]
```

Return the controller alarm codes for a caught fault, best-effort.

Uses the codes already attached to `fault` when it has them. RMI faults
usually do not, so for those this asks the controller for its current
alarm codes instead. Only ask while the arm is idle — call this where you
catch the fault, not mid-motion. It never raises: if the read fails you
get the fault's own codes back (possibly none), so this can never block
your recovery path.

<ParamField>
  The caught controller fault to resolve codes for.
</ParamField>

**Returns:**

list\[str]: Alarm codes in `"XXXX-NNN"` form (e.g.
`["MOTN-722"]`), most-recent first. Empty when none were
attached to the fault and none could be read back (no RMI
backend configured, or the read-back failed).

### `recoverFromFault()`

```python Signature theme={null}
recoverFromFault(fault: RobotFault) -> bool
```

Try to clear a controller fault and get the arm ready to move again.

Call this where you catch a fault, before retrying whatever failed. It
clears the alarm and puts Stream Motion back the way it was, so a retry
starts from a known state rather than a half-torn-down one.

A fault the driver marked unrecoverable is not worth resetting, so this
returns False without touching the arm. Otherwise a False means the alarm
is still latched — an emergency stop or a servo alarm — and somebody has
to clear it on the teach pendant before the robot will move.

Never raises: a failed reset is an answer (False), not an error, so your
recovery path is never itself the thing that crashes.

<ParamField>
  The controller fault you caught.
</ParamField>

**Returns:**

True when the arm is cleared and ready to retry, False when it is not
and a human needs to intervene.

### `release()`

```python Signature theme={null}
release(
    *,
    force: Optional[float] = None,
    auto_suspend_stream_motion: bool = True,
) -> None
```

Open the gripper.

Mirrors `grasp`, including the transport choice and the Stream
Motion session handling. On the Stream Motion channel it drives the
open pattern, holds it for the mapping's `release_hold_s`, then
returns the gripper to idle — FANUC outputs latch, so otherwise the
release solenoid would stay energized indefinitely.

<ParamField>
  Target release force in the gripper's own units. RMI only, and only for a gripper whose TP programs take it. Defaults to None.
</ParamField>

<ParamField>
  Pause a running Stream Motion session around the release. RMI path only; see `grasp` for why this is the safe default. Defaults to True.
</ParamField>

**Raises:**

NotImplementedError: If no end effector is attached, or the chosen
transport is not configured.
ValueError: If `force` is passed to a gripper on the Stream
Motion channel, or if the gripper's TP programs do not accept
it.
RuntimeError: If a staged Stream Motion write was not sent before
the stream was released, or the controller reports a latched
alarm while bringing Stream Motion up.
TypeError: If the attached end effector is neither a Stream Motion
I/O gripper nor an RMIGripper.

### `removeNamedPose()`

```python Signature theme={null}
removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

<ParamField>
  Name of the pose to remove (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose that was removed, or None if the named
pose did not exist

### `reset()`

```python Signature theme={null}
reset() -> None
```

Reset / reconnect every configured backend.

Errors from one backend do not prevent the others from being
reset. The first encountered error is re-raised after every
backend has been reset.

**Raises:**

Exception: The first error raised by any backend, after all
backends have been asked to reset.

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = True,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    *,
    speed_override: Optional[int] = None,
    continuous: bool = False,
    term_value: Optional[int] = None,
    max_joint_speed_rad_s: Optional[float] = None,
    prefer: str = 'auto',
    auto_suspend_stream_motion: bool = True,
) -> None
```

Move the arm to the given joint angles.

Routes by `prefer`, except that a backend-specific argument forces its
own backend: `speed_override`, `continuous=True` or `term_value`
force RMI, `max_joint_speed_rad_s` forces Stream Motion, and mixing the
two sets raises. When the call lands on RMI while Stream Motion is
active, SM is paused for the move and resumed after.

<ParamField>
  Target joint angles in radians, one per joint.
</ParamField>

<ParamField>
  Wait for the movement to complete. Defaults to True.
</ParamField>

<ParamField>
  Movement duration in seconds. Defaults to None (backend default).
</ParamField>

<ParamField>
  Acceleration ramp time in seconds. Defaults to None.
</ParamField>

<ParamField>
  RMI speed override in percent (1-100). RMI only, and passing it forces RMI. Defaults to None.
</ParamField>

<ParamField>
  Use RMI CNT blending instead of FINE. RMI only, and passing True forces RMI. Defaults to False.
</ParamField>

<ParamField>
  RMI blend radius, 0 (FINE) to 100 (full blend). RMI only, and passing it forces RMI. Defaults to None (`CNT_MAX`).
</ParamField>

<ParamField>
  Stream Motion peak joint speed in rad/s, used to derive the duration when `moving_time` is None. Stream Motion only, and passing it forces SM. Defaults to None.
</ParamField>

<ParamField>
  Routing preference — `"auto"`, `"rmi"` or `"stream_motion"`. Defaults to `"auto"`.
</ParamField>

<ParamField>
  Pause an active Stream Motion session for the duration of a move that lands on RMI. Ignored when the call routes to SM. Defaults to True.
</ParamField>

**Raises:**

ValueError: If RMI-specific and Stream Motion-specific arguments are
mixed, or if `prefer` is not one of the accepted values.
NotImplementedError: If the arguments force a backend that is not
configured.

### `setPayload()`

```python Signature theme={null}
setPayload(schedule_number: int) -> None
```

Select a payload schedule on the controller.

<ParamField type="int">
  Payload schedule number on the controller (1-based).
</ParamField>

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `setSpeedOverride()`

```python Signature theme={null}
setSpeedOverride(speed_override: int) -> None
```

Set the controller's global speed override percentage.

<ParamField type="int">
  Speed override as percent (1-100).
</ParamField>

**Raises:**

NotImplementedError: If no RMI backend is configured.

### `start_stream_motion()`

```python Signature theme={null}
start_stream_motion(timeout_s: float = _RESUME_CMD_READY_TIMEOUT_S) -> None
```

Start Stream Motion so high-rate joint streaming can run.

This is both the first-time start for an arm built with
`use_stream_motion=False`, and the counterpart to
`stop_stream_motion` after an RMI move paused the session. It
clears the position the controller was last told to hold, hands motion
control over, starts the controller-side program and waits until the
controller is accepting commands.

If an alarm is still latched this refuses to start rather than quietly
clearing it — acknowledge the alarm first with `reset` or on the
teach pendant.

Idempotent: a no-op when no Stream Motion backend is configured, or when
a session is already running.

<ParamField>
  Seconds to wait for the controller to report it is accepting commands. Defaults to 5.0.
</ParamField>

**Raises:**

RuntimeError: If `stream_motion` is configured but `rmi` is not
(RMI is what relaunches the program), or if the controller
reports a latched alarm.
TimeoutError: If the controller does not report itself ready within
`timeout_s`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

### `stop_stream_motion()`

```python Signature theme={null}
stop_stream_motion() -> None
```

Pause Stream Motion so RMI moves can run.

While a Stream Motion session is running it holds the arm, and any RMI
move issued underneath it would simply wait forever. This stops the
session so RMI can take over. Joint feedback keeps flowing throughout —
only command control is handed back — so reads still work while paused,
and `start_stream_motion` resumes.

Idempotent: a no-op when no Stream Motion backend is configured, or when
it is already paused.

**Raises:**

RuntimeError: If `stream_motion` is configured but `rmi` is not —
RMI is what stops the controller-side program.

### `urdfToNativeJoints()`

```python Signature theme={null}
urdfToNativeJoints(angles: list[float]) -> list[float]
```

Convert serial-convention (URDF) joints to the FANUC wire convention.

Exact inverse of `nativeToUrdfJoints`
(`result[2] = angles[2] - angles[1]`). Apply to every joint vector
produced by a motion planner before handing it to this arm's
execution methods — the RMI and Stream Motion backends speak the raw
FANUC wire convention, in which J3 is world-referenced (the J2/J3
interaction). Executing serial-convention joints raw moves the elbow
wrong by exactly J2.

<ParamField>
  Joint vector in serial (URDF) convention (radians), ordered J1..Jn with n >= 3.
</ParamField>

**Returns:**

The same physical configuration in FANUC wire convention
(radians), as a new list.

**Raises:**

ValueError: If `angles` has fewer than 3 entries — the J2/J3
conversion needs at least joints J1..J3.

### `validateGrasp()`

```python Signature theme={null}
validateGrasp() -> bool
```

Report whether the gripper is currently holding a part.

On the **Stream Motion** channel this takes a fresh reading rather than
trusting a cached one: it brings the session up if needed, discards the
previous value, waits for the sensor to settle from live status
packets, and puts the session back. A part can be lost while nothing is
streaming, so a cached value could report a part that is gone.

Commands physical motion when the streaming thread is not already
running: a zero-displacement hold at the current joint angles. The arm
holds its pose; it does not travel.

On the **RMI** channel this asks the gripper itself, and the base
gripper has no sensor to ask — grip state lives on the controller.

**Returns:**

bool: True when a gripped part is detected. False when the sensor
reads open, and also when no stable reading arrives within the
mapping's `confirm_timeout_s` — an unknown state never reads as
"holding".

**Raises:**

NotImplementedError: On the RMI channel, where the gripper has no
grip sensor; or on the Stream Motion channel when the mapping
configures no feedback point.
RuntimeError: If no end effector is attached, or the controller
reports a latched alarm while bringing Stream Motion up.
TimeoutError: If Stream Motion does not become ready to accept
commands.

## Properties on the robot

Read as `robot.<property>`; each read runs the getter on the robot.

<ResponseField name="home_pose" type="list[float]">
  Joint angles defining the LR Mate 200iD home pose.
</ResponseField>

<ResponseField name="named_poses" type="Dict[str, List[float]]">
  Registered poses as `&#123;name: joint angles in radians&#125;` (a copy).

  Mutating the returned mapping does not change what the arm knows:
  register and remove entries with `addNamedPose` and
  `removeNamedPose`, or assign a whole mapping to replace them all.
</ResponseField>

<ResponseField name="total_payload_kg" type="float">
  Worst-case total mass at the flange.

  Always returns the robot's rated `max_payload_kg` (or 0.0
  if the subclass doesn't define one). The end-effector spec's
  `mass_kg` and `held_mass_kg` fields are NOT auto-applied
  here, deliberately: an end-effector picks up and drops
  workpieces, and any host-side count of "what's currently on
  the wrist" is fragile (one missed update and the pre-flight
  runs against a too-permissive limit, controller alarms).

  To opt into a lower payload for a specific motion, pass
  `payload_kg=...` per call. That makes the assumption
  explicit at the call site instead of buried in cached state.
  For a fully-empty arm: `payload_kg=0.0`. For a known
  gripper-only weight: `payload_kg=ee.mass_kg`. For a
  gripper carrying a known workpiece:
  `payload_kg=ee.mass_kg + workpiece_kg`.
</ResponseField>

## Configured children

* `robot.end_effector` — the gripper, chosen in the robot's configuration; when one is fitted, its methods are the [`EndEffector`](/v2.3/python-api/robot-interface/endeffector) interface's.

## Not implemented on this robot

Declared by the interface, raises `NotImplementedError` here: `endFreeDrive`, `startFreeDrive`.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the children this class always ships with (customization point).
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()` — Describe the config `args` the setup wizard should offer.
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# Flexiv Rizon Arm
Source: https://docs.generalrobotics.dev/v2.3/python-api/flexiv-rizon/flexivrizon

The Flexiv Rizon Arm as GRID drives it

The Flexiv Rizon Arm as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `FlexivRizon`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<flexiv_rizon-name>")
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `addNamedPose()`

```python Signature theme={null}
addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses
(overriding any existing pair).

<ParamField>
  Name of the pose to define
</ParamField>

<ParamField>
  List of joint angles in radians
</ParamField>

**Raises:**

ValueError: If the length of joint\_angles list does match the length of other named
poses

### `endFreeDrive()`

```python Signature theme={null}
endFreeDrive() -> None
```

Exit free-drive mode and return to position control.

The arm is no longer movable by hand and again responds to
position-control commands such as `moveToPose` and
`setJointAngles`.

### `followJointTrajectory()`

```python Signature theme={null}
followJointTrajectory(
    angles: List[List[float]],
    duration: Union[float, List[float]],
    blocking: bool = True,
) -> None
```

Move the arm through a sequence of joint configurations.

Each waypoint in `angles` is visited in order. The arm briefly
stops at every intermediate waypoint — this implementation is a
per-segment loop over `setJointAngles`, not a blended
trajectory.

<ParamField>
  Sequence of joint configurations (radians) to visit in order. Each inner list must have 7 elements.
</ParamField>

<ParamField>
  Either a single positive float giving the total trajectory time in seconds (split evenly across segments), or a list of positive floats with the same length as `angles` giving the duration of each segment from the previous pose to `angles[i]`.
</ParamField>

<ParamField>
  Wait for the final segment to complete before returning. Intermediate segments are always blocking.
</ParamField>

**Raises:**

ValueError: If `angles` is empty, `duration` is not
positive, list-form `duration` length does not match
`angles`, or a waypoint is invalid.
RobotFault: If the controller reports a fault during a segment.
RuntimeError: If a segment stops short of its waypoint or does not
arrive before its deadline.

### `getEndEffectorForce()`

```python Signature theme={null}
getEndEffectorForce() -> float
```

Get the measured finger force in Newtons.

**Returns:**

Finger force in Newtons; positive is an opening force, negative a
closing force. Reads 0 if the gripper has no force sensing.

**Raises:**

RuntimeError: If no gripper is configured.

### `getEndEffectorGraspDetected()`

```python Signature theme={null}
getEndEffectorGraspDetected() -> bool
```

Report whether the gripper is holding an object.

**Returns:**

True when the fingers push with more than 1.2 N while
wider than 2 mm.

**Raises:**

RuntimeError: If no gripper is configured.

### `getEndEffectorIsMoving()`

```python Signature theme={null}
getEndEffectorIsMoving() -> bool
```

Report whether the gripper fingers are moving.

**Returns:**

True while the fingers are moving.

**Raises:**

RuntimeError: If no gripper is configured.

### `getEndEffectorPose()`

```python Signature theme={null}
getEndEffectorPose() -> Pose
```

```text theme={null}
[Deprecated]
Get the current end effector pose (position + orientation) w.r.t. the base frame.
```

### `getEndEffectorWidth()`

```python Signature theme={null}
getEndEffectorWidth() -> float
```

Get the current gripper width in meters.

**Returns:**

Distance between the fingers in meters.

**Raises:**

RuntimeError: If no gripper is configured.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> list[float]
```

Get current seven joint angles in radians.

**Returns:**

Current seven joint angles in radians, with base joint first

### `getJointVelocities()`

```python Signature theme={null}
getJointVelocities() -> list[float]
```

Get current seven joint velocities in radians/second.

**Returns:**

Current seven joint velocities in radians/second, with base joint first

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getNamedPose()`

```python Signature theme={null}
getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

<ParamField>
  Name of the pose to get (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose, or None if the named pose does not exist

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Orientation
```

Get the current end effector orientation with respect to the robot base.

**Returns:**

Current TCP orientation in the robot base frame.

### `getPose()`

```python Signature theme={null}
getPose() -> Pose
```

Get the current end effector pose (position and orientation) in the robot base frame.

**Returns:**

Current Tool-Center-Point (TCP) pose.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Position
```

Get the current end effector position with respect to the robot base (meters).

**Returns:**

Current TCP position in the robot base frame.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `grasp()`

```python Signature theme={null}
grasp() -> None
```

Close the gripper to grasp an object.

Closes at the gripper's maximum force and speed (`gripper.params()`) and
blocks until the fingers stop, either fully closed or on an object. Check
`getEndEffectorGraspDetected` to tell the two apart.

**Raises:**

RuntimeError: If no gripper is configured, or the fingers do not stop
before the deadline.

### `moveToDeltaPose()`

```python Signature theme={null}
moveToDeltaPose(delta_pose: Pose, blocking: bool = True) -> None
```

Offset the robot end effector by the specified delta pose from its current pose
(with respect to the base frame).

<ParamField>
  Pose offset to compose with the current pose. The position is added to the current position and the orientation is composed with the current orientation.
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `moveToHome()`

```python Signature theme={null}
moveToHome(
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
) -> None
```

Move the arm to its predefined home pose.

<ParamField>
  Wait for movement to complete.
</ParamField>

<ParamField>
  Total duration of the move (seconds).
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`.
</ParamField>

**Raises:**

RobotFault: If the controller reports a fault before or during the move.
RuntimeError: If a blocking move stops short of the target or does not
arrive before its deadline.

### `moveToNamedPose()`

```python Signature theme={null}
moveToNamedPose(
    pose_name: str,
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
) -> None
```

Move the arm to the joint angles of a named pose.

<ParamField>
  Name of the pose to move to (case-insensitive).
</ParamField>

<ParamField>
  Wait for movement to complete.
</ParamField>

<ParamField>
  Total duration of the move (seconds).
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`.
</ParamField>

**Raises:**

ValueError: If pose\_name is not in `named_poses`.
RobotFault: If the controller reports a fault before or during the move.
RuntimeError: If a blocking move stops short of the target or does not
arrive before its deadline.

### `moveToPose()`

```python Signature theme={null}
moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    high_frequency: bool = False,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    avoid_force: bool = False,
    force_threshold: float = 10.0,
) -> None
```

Move the robot end-effector to a specified pose.

If high\_frequency is False, a trapezoidal profile is planned from moving\_time and
accel\_time, capped by the linear and angular speed and acceleration limits. A
blocking move waits until the TCP is within 1 mm and
5 mrad of the target and at rest. If
high\_frequency is True, the target is sent at the speed caps without waiting,
for a caller streaming targets from a control loop.

<ParamField>
  Target pose (position in meters, orientation as a unit quaternion) in the robot's base frame.
</ParamField>

<ParamField>
  Wait for movement to complete. Ignored when high\_frequency is True; always waits when avoid\_force is True.
</ParamField>

<ParamField>
  If False, send one discrete move with a planned profile. Otherwise, send the target for streaming and return immediately.
</ParamField>

<ParamField>
  Seconds to complete the movement. Speed caps can make the move take longer; the move is then logged as clamped.
</ParamField>

<ParamField>
  Seconds to spend accelerating in a trapezoidal motion profile. Clamped to at most `moving_time / 2`.
</ParamField>

<ParamField>
  Monitor the TCP contact force during the move and stop the arm when it exceeds its pre-move baseline by more than force\_threshold. The arm holds where it stopped, which can leave it pressing on the contact; back off in the caller if that matters.
</ParamField>

<ParamField>
  Contact force increase, in Newtons, that stops an avoid\_force move.
</ParamField>

**Raises:**

ValueError: If moving\_time, accel\_time or force\_threshold are not positive,
or if avoid\_force is combined with high\_frequency.
TypeError: If moving\_time, accel\_time or force\_threshold are not numbers.
ForceThresholdExceeded: If an avoid\_force move stopped on contact.
RobotFault: If the controller reports a fault before or during the move;
`start()` clears it.
RuntimeError: If a blocking move stops short of the target (e.g. an
unreachable pose) or does not arrive before its deadline.

### `release()`

```python Signature theme={null}
release() -> None
```

Open the gripper to release an object.

Opens to the maximum width at the gripper's maximum force and speed and
blocks until the fingers stop.

**Raises:**

RuntimeError: If no gripper is configured, or the fingers stop short of
fully open or do not stop before the deadline.

### `removeNamedPose()`

```python Signature theme={null}
removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

<ParamField>
  Name of the pose to remove (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose that was removed, or None if the named
pose did not exist

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = True,
    *,
    high_frequency: bool = False,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    avoid_force: bool = False,
    force_threshold: float = 10.0,
) -> None
```

Set joint angles in radians.

Commands the arm to move its joints to the specified angles.
If high\_frequency is False:
a trapezoidal motion profile is generated (ending with zero velocity)
with the given moving\_time and accel\_time, capped by
`max_joint_speed` and `max_joint_acceleration`, and the robot's
internal motion generator smoothens and executes the motion. A
blocking move waits until the joints are within
2 mrad of the target and at rest.
If high\_frequency is True:
the target is sent without waiting, for a caller streaming targets from a
\~1-100 Hz control loop (e.g. a Vision-Language-Action model). The robot's
motion generator interpolates between targets at the configured speed caps,
so large jumps between consecutive targets move at those caps.

<ParamField>
  List of target joint angles in radians, starting with the base joint.
</ParamField>

<ParamField>
  Wait for movement to complete. Ignored when high\_frequency is True; always waits when avoid\_force is True.
</ParamField>

<ParamField>
  If False, send one discrete move with a planned profile. Otherwise, send the target for streaming and return immediately.
</ParamField>

<ParamField>
  Seconds to complete the movement. Speed caps can make the move take longer; the move is then logged as clamped.
</ParamField>

<ParamField>
  Seconds to accelerate from zero to full velocity (another accel\_time is needed to decelerate to zero). Clamped to at most `moving_time / 2`.
</ParamField>

<ParamField>
  Monitor the TCP contact force during the move and stop the arm when it exceeds its pre-move baseline by more than force\_threshold. The arm holds where it stopped, which can leave it pressing on the contact; back off in the caller if that matters.
</ParamField>

<ParamField>
  Contact force increase, in Newtons, that stops an avoid\_force move.
</ParamField>

**Raises:**

ValueError: If the angles do not match the joint count or the joint limits,
if moving\_time, accel\_time or force\_threshold are not positive, or if
avoid\_force is combined with high\_frequency.
TypeError: If moving\_time, accel\_time or force\_threshold are not numbers.
ForceThresholdExceeded: If an avoid\_force move stopped on contact.
RobotFault: If the controller reports a fault before or during the move;
`start()` clears it.
RuntimeError: If a blocking move stops short of the target or does not
arrive before its deadline.

### `startFreeDrive()`

```python Signature theme={null}
startFreeDrive() -> None
```

Enable free-drive (hand-guided) mode.

The arm becomes compliant and can be moved by hand while supporting
its own weight. Position-control commands such as
`moveToPose` and `setJointAngles` are not active in
this mode — call `endFreeDrive` to return to position
control.

All six Cartesian axes are unlocked, elbow motion is enabled, and
damping is set to a moderate level on every axis.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

### `validateGrasp()`

```python Signature theme={null}
validateGrasp() -> bool
```

Check whether the end effector is currently holding an object.

Thin wrapper that delegates to the configured end effector's
`EndEffector.getGripDetected`. Subclasses generally do not
need to override this.

**Returns:**

True if the end effector reports an object in its grip, False
otherwise.

**Raises:**

RuntimeError: If no end effector is configured on this arm.
NotImplementedError: If the configured end effector does not
support grip detection.

## Properties on the robot

Read as `robot.<property>`; each read runs the getter on the robot.

<ResponseField name="control_mode" type="Optional[str]">
  The controller's current control mode, e.g. `"NRT_JOINT_POSITION"` or `"IDLE"`.

  Read live from the controller, so a stop or fault shows as `"IDLE"`.
  Driver-owned: it changes only through the motion API. None before `start()`.
</ResponseField>

<ResponseField name="gripper_name" type="Optional[str]">
  Flexiv Elements name of the configured gripper, or None when there is none.
</ResponseField>

<ResponseField name="home_pose" type="list[float]">
  Joint angles (radians) with the arm over the workspace, joints at 90 degrees.
</ResponseField>

<ResponseField name="max_angular_acceleration" type="float">
  Cap applied to commanded TCP angular acceleration, in rad/s^2.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_angular_speed" type="float">
  Cap applied to commanded TCP angular speed, in rad/s.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_joint_acceleration" type="float">
  Cap applied to commanded joint acceleration, in rad/s^2.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_joint_speed" type="float">
  Cap applied to commanded joint speed, in rad/s. Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_linear_acceleration" type="float">
  Cap applied to commanded TCP linear acceleration, in m/s^2.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_linear_speed" type="float">
  Cap applied to commanded TCP linear speed, in m/s. Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="named_poses" type="Dict[str, List[float]]">
  Registered poses as `&#123;name: joint angles in radians&#125;` (a copy).

  Mutating the returned mapping does not change what the arm knows:
  register and remove entries with `addNamedPose` and
  `removeNamedPose`, or assign a whole mapping to replace them all.
</ResponseField>

## Configured children

* `robot.end_effector` — the gripper, chosen in the robot's configuration; when one is fitted, its methods are the [`EndEffector`](/v2.3/python-api/robot-interface/endeffector) interface's.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the children this class always ships with (customization point).
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()` — Config-args schema for this robot, derived from the constructor.
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# Unitree Go2 Quadruped
Source: https://docs.generalrobotics.dev/v2.3/python-api/go2/go2

The Unitree Go2 Quadruped as GRID drives it

The Unitree Go2 Quadruped as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `Go2`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<go2-name>")

# `front` is a built-in camera: reach it as an attribute.
frame = robot.front.getImage()
rgb = frame.decode()                    # -> H x W x 3 RGB ndarray
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `commandJointsPD()`

```python Signature theme={null}
commandJointsPD(
    joint_indices: np.ndarray,
    q: np.ndarray,
    kp: np.ndarray,
    kd: np.ndarray,
) -> None
```

Drive the given motors with per-joint PD gains; leave all others un-actuated.

Direct low-level position control for a fixed-rate policy loop:
non-blocking (no sleep) and gain-per-joint, unlike `setJointAngles`.
Motors named by `joint_indices` (SDK order) get the position PD
command; every other motor is parked at the firmware's position and
velocity stop values with zero gains, so it is not actuated.

<ParamField>
  SDK motor indices to drive.
</ParamField>

<ParamField>
  Target joint positions (rad), aligned to `joint_indices`.
</ParamField>

<ParamField>
  Per-joint position gains, aligned to `joint_indices`.
</ParamField>

<ParamField>
  Per-joint damping gains, aligned to `joint_indices`.
</ParamField>

### `getBatteryState()`

```python Signature theme={null}
getBatteryState()
```

Get the current battery state when low-level control enabled.

**Returns:**

Battery voltage and current

### `getControlState()`

```python Signature theme={null}
getControlState() -> ControlState
```

Return the latest control-loop state without consuming it.

Base angular velocity, orientation, and per-motor position/velocity in
Unitree SDK index order. Non-blocking; the RL control loop reads it each
tick. The Go2 runs no state estimator, so `base_lin_vel` is absent and
a policy consuming that term is rejected at driver construction.

**Returns:**

The latest control-loop state.

**Raises:**

RuntimeError: If no low-level state has been received yet.

### `getFootForce()`

```python Signature theme={null}
getFootForce()
```

Get the current foot force readings when low-level control enabled.

**Returns:**

Current foot force readings

### `getIMU()`

```python Signature theme={null}
getIMU()
```

Get the current IMU state when low-level control enabled.

**Returns:**

Current IMU state

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', image_type: str = '') -> Image | None
```

Get an image from the specified camera.

<ParamField type="str">
  name of the camera. May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField type="str">
  supported image types depend on camera, for the built-in `front` camera only "rgb" is supported
</ParamField>

**Returns:**

Image: requested image

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getLowLevelState()`

```python Signature theme={null}
getLowLevelState()
```

Get the complete low level state.

**Returns:**

Complete low level robot state
[https://github.com/unitreerobotics/unitree\_sdk2\_python/blob/3af1610228977f449e22c8fba868bb8516d41ec3/unitree\_sdk2py/idl/unitree\_go/msg/dds\_/\_LowState\_.py#L34](https://github.com/unitreerobotics/unitree_sdk2_python/blob/3af1610228977f449e22c8fba868bb8516d41ec3/unitree_sdk2py/idl/unitree_go/msg/dds_/_LowState_.py#L34)

### `getMotorState()`

```python Signature theme={null}
getMotorState()
```

Get the current state of all motors when low-level control enabled.

**Returns:**

Current state of all motors
[https://github.com/unitreerobotics/unitree\_sdk2\_python/blob/3af1610228977f449e22c8fba868bb8516d41ec3/unitree\_sdk2py/idl/unitree\_go/msg/dds\_/\_MotorState\_.py](https://github.com/unitreerobotics/unitree_sdk2_python/blob/3af1610228977f449e22c8fba868bb8516d41ec3/unitree_sdk2py/idl/unitree_go/msg/dds_/_MotorState_.py)

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Orientation | None
```

Get the current orientation of the unitree go2 agent in radians.

<ParamField type="optional, str">
  unused
</ParamField>

**Returns:**

Orientation: current orientation of the unitree go2 agent in radians

### `getPosition()`

```python Signature theme={null}
getPosition() -> Position | None
```

Get the current position of the unitree go2 agent with respect to the world coordinate.

<ParamField type="optional, str">
  unused
</ParamField>

**Returns:**

Position: unitree go2 agent's current position (x,y,z) with respect to the world
coordinate

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getWirelessRemoteState()`

```python Signature theme={null}
getWirelessRemoteState() -> Sequence[int]
```

Return the latest wireless-remote bytes (Unitree teleop), non-consuming.

Unitree-specific operator input, deliberately kept off the generic
low-level control contract.

**Returns:**

The raw `wireless_remote` byte buffer from the latest `LowState_`.

**Raises:**

RuntimeError: If no low-level state has been received yet.

### `lieDown()`

```python Signature theme={null}
lieDown(duration_s: float = 4.0) -> None
```

Ease the robot down to a folded resting pose.

Under high-level control this asks the built-in controller to stand
down. Under low-level control — where that controller has been released
and `self.client` does not exist — it interpolates every motor from
its measured position to `GO2_LIEDOWN_POSE` at the hold gains, so
the robot settles rather than collapsing.

<ParamField>
  Seconds to spend on the descent (low-level only). Slower is gentler.
</ParamField>

**Returns:**

None

**Raises:**

RuntimeError: If no low-level state has been received yet, or the
last one is stale (low-level only).

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Command a body-frame walking velocity.

Each command is honoured for roughly one second; without re-issue
the controller decays the command and the robot stops. The
controller also ramps each command up and down, so a single
command followed by a long wait covers significantly less ground
than `v × t` would predict (observed \~40–60% over a one-second
window). Re-issue at high rate (e.g. 10 Hz) for sustained motion
past about a second.

Body-frame z linear and x/y angular components are discarded —
the Go2 cannot translate vertically nor roll/pitch on demand.

<ParamField type="Velocity">
  Body-frame linear velocity. `x_vel` (forward, m/s), `y_vel` (left, m/s); `z_vel` is discarded.
</ParamField>

<ParamField type="Velocity">
  Body-frame angular velocity. `z_vel` (yaw rate, rad/s); `x_vel` and `y_vel` are discarded.
</ParamField>

<ParamField type="optional, str">
  Reference frame of the command. Defaults to `"body"`. `"world"` is not supported.
</ParamField>

**Returns:**

None

With `rl_locomotion` configured the command is latched for the
policy instead of sent to the built-in controller, so a caller — a
teleop script or the nav stack — drives a learned gait through this
same contract without knowing a policy is running. The policy tracks
the command continuously, so the decay and ramping described above do
not apply.

**Raises:**

NotImplementedError: If `low_level_control` was enabled on
construction without an RL policy (only the high-level
controller implements this), or if `frame="world"` is
requested.

### `setDamping()`

```python Signature theme={null}
setDamping(kd: float = 8.0) -> None
```

Publish a damping brake — zero position gain, given damping.

The Go2's braking safe state: the legs resist motion and the robot
settles onto them rather than collapsing.

<ParamField>
  Damping gain applied to every leg motor.
</ParamField>

### `setDefaultJointAngles()`

```python Signature theme={null}
setDefaultJointAngles(joint_pos: list) -> None
```

Set the default joint position for the robot.

<ParamField>
  Value of the joint position.
</ParamField>

### `setDefaultJointVelocities()`

```python Signature theme={null}
setDefaultJointVelocities(joint_vel: list) -> None
```

Set the default joint velocity for the robot.

<ParamField>
  Value of the joint velocity.
</ParamField>

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(joint_position: dict) -> None
```

Set the position of the robot's joints when low-level control enabled.

<ParamField type="dict">
  Dictionary mapping joint names to target positions
</ParamField>

**Returns:**

None

### `setJointTorques()`

```python Signature theme={null}
setJointTorques(joint_torque: dict) -> None
```

Set the torque of the robot's joints when low-level control enabled.

<ParamField type="dict">
  Dictionary mapping joint names to target torques
</ParamField>

**Returns:**

None

### `setJointVelocities()`

```python Signature theme={null}
setJointVelocities(joint_velocity: dict) -> None
```

Set the velocity of the robot's joints when low-level control enabled.

<ParamField type="dict">
  Dictionary mapping joint names to target velocities
</ParamField>

**Returns:**

None

### `setZeroTorque()`

```python Signature theme={null}
setZeroTorque() -> None
```

Publish a zero-torque command to all motors (non-blocking).

### `standUp()`

```python Signature theme={null}
standUp() -> None
```

Make the robot stand up from a lying position.

**Returns:**

None

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

## Properties on the robot

Read as `robot.<property>`; each read runs the getter on the robot.

<ResponseField name="policy_drivers" type="Dict[str, PolicyDriver]">
  The robot's registered policy drivers, keyed by name.

  Empty on a robot constructed without RL. Lazily created, so the mixin
  needs no cooperation from the host robot's `__init__`.
</ResponseField>

## robot.front — camera

Reached as `robot.front`; its methods are `Go2Camera`'s and run on the robot.

The Go2's front camera, read over the Unitree DDS video client.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `front.getCameraExtrinsics()`

```python Signature theme={null}
front.getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

### `front.getCameraIntrinsics()`

```python Signature theme={null}
front.getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

### `front.getCameraSettings()`

```python Signature theme={null}
front.getCameraSettings() -> CameraSettings
```

Get the camera settings.

### `front.getData()`

```python Signature theme={null}
front.getData() -> Image
```

Get the image from the camera.

### `front.getImage()`

```python Signature theme={null}
front.getImage(
    image_type: str | None = None,
    *,
    compressed: bool = True,
) -> Image | None
```

Get image from Go2 camera.

VideoClient natively returns JPEG (\~200 KB). By default we pass
those bytes through without decoding (\~30x bandwidth saving on
the wire). Pass `compressed=False` to get a decoded RGB ndarray
instead — pays a JPEG decode on every call, but matches the
legacy API for callers that expect ndarrays.

<ParamField type="str | None, optional">
  no effect for Go2Camera — only JPEG is supported. Kept for API compatibility.
</ParamField>

<ParamField type="bool, optional">
  when True (default) return the raw JPEG bytes via `Image(..., encoding_format="jpeg")`. When False, decode to an RGB ndarray and return `Image(rgb_ndarray)`.
</ParamField>

**Returns:**

Image | None: encoded JPEG or decoded RGB ndarray depending
on `compressed`. None if the SDK call fails.

### `front.getState()`

```python Signature theme={null}
front.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `front.recordCalibration()`

```python Signature theme={null}
front.recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

### `front.reloadCalibration()`

```python Signature theme={null}
front.reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

### `front.setCameraExtrinsics()`

```python Signature theme={null}
front.setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

### `front.setCameraIntrinsics()`

```python Signature theme={null}
front.setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

### `front.setCameraSettings()`

```python Signature theme={null}
front.setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

### `front.stop()`

```python Signature theme={null}
front.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

## robot.go2\_lidar — lidar

Reached as `robot.go2_lidar`; its methods are `Go2Lidar`'s and run on the robot.

Bridge the Go2's onboard LiDAR into the GRID `Lidar` interface.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `go2_lidar.getData()`

```python Signature theme={null}
go2_lidar.getData() -> PointCloud
```

### `go2_lidar.getPointCloud()`

```python Signature theme={null}
go2_lidar.getPointCloud(
    *,
    source: str = LIDAR_SOURCE_HEIGHT_MAP,
) -> Optional[PointCloud]
```

Return the latest point cloud from the selected source, or `None`.

<ParamField>
  Which LiDAR product to return. `"height_map"` (default) converts Unitree's fused elevation grid to one point per observed cell, robot-centred with `+x` forward. `"cloud"` returns the raw LiDAR returns of the most recent message, in the sensor's own frame. The class docstring sets out how the two differ in dimensionality, extent, freshness and frame.
</ParamField>

**Returns:**

The latest `PointCloud`, or `None` if the messages it
needs have not arrived yet or hold no usable points. The
`"height_map"` source needs both a height map and a robot
pose, each no older than `HEIGHT_MAP_MAX_AGE_S`, so it
returns `None` until each has arrived and again once either
stops — which is what the Go2 does with the height map the
moment it sits or lies down. Each distinct reason is logged
once rather than once per call.

**Raises:**

ValueError: If `source` is neither `"height_map"` nor
`"cloud"`.

### `go2_lidar.getState()`

```python Signature theme={null}
go2_lidar.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `go2_lidar.stop()`

```python Signature theme={null}
go2_lidar.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

## Not implemented on this robot

Declared by the interface, raises `NotImplementedError` here: `getJointAngles`.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addPolicy()` — Register a policy driver under a name.
* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the `front` camera every Go2 ships with.
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()`
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `isPolicyAlive()` — Return whether a policy control loop is currently running.
* `raiseForPolicyError()` — Re-raise the exception that killed a policy control loop, if any.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).
* `startPolicy()` — Run the policy startup handshake, then begin closed-loop control.
* `stopAllPolicies()` — Stop every registered policy control loop.
* `stopPolicy()` — Stop a policy control loop.

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# CortexClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-cortex-client/cortexclient

Client for interacting with Grid Cortex Ray Serve deployments

```python theme={null}
from grid_cortex_client import CortexClient
```

Client for interacting with Grid Cortex Ray Serve deployments.

## Constructor

```python Signature theme={null}
CortexClient(
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    timeout: float = 30.0,
    *,
    observer: Optional[RuntimeObserver] = None,
)
```

Initializes the CortexClient.

<ParamField>
  API key. Uses GRID\_CORTEX\_API\_KEY env var if None.
</ParamField>

<ParamField>
  Base URL of the Cortex API. If None, uses GRID\_CORTEX\_BASE\_URL env var or HTTPClient's default.
</ParamField>

<ParamField>
  Default timeout for HTTP requests in seconds.
</ParamField>

<ParamField>
  Optional caller-owned observer for run events. The client does not close it.
</ParamField>

## Methods

### `available_models()`

```python Signature theme={null}
available_models() -> list[str]
```

Return all registered model identifiers.

This method provides a complete list of all available models that can be
used with the CortexClient. Essential for LLM agents to discover what
models are available before attempting to use them.

**Returns:**

A sorted list of model identifiers (e.g., \["gsam2", "owlv2", "zoedepth"]).
These strings can be used directly with `run` and `help`.

```python theme={null}
client = CortexClient()
models = client.available_models()
print(models)  # ['gsam2', 'owlv2', 'zoedepth']
client.run(models[0], image_input=img)  # Use first available model
```

### `close()`

```python Signature theme={null}
close()
```

Closes the underlying HTTP client.

### `get_info()`

```python Signature theme={null}
get_info() -> Dict[str, Any]
```

Get Grid-Cortex server version and deployed models status.

Fetches real-time information about the Cortex deployment including
version and current model replica counts.

**Returns:**

Dictionary containing:

* version (str): Grid-Cortex version (e.g., "v0.2.49")
* models (list): List of deployed models with:
  * name (str): Model identifier
  * status (str): Deployment status ("RUNNING", etc.)
  * route (str): HTTP route prefix
  * replicas (int): Number of running replicas

**Raises:**

CortexAPIError: If the API returns an error.
CortexNetworkError: If network communication fails.

```python theme={null}
client = CortexClient()
info = client.get_info()
print(info["version"])
print(f"ZoeDepth has {info['models'][0]['replicas']} replicas")
```

### `help()`

```python Signature theme={null}
help(model_id: str) -> str
```

Return comprehensive documentation for a model.

This method provides complete API documentation for any registered model,
including usage examples, parameter descriptions, return types, and error
conditions. Essential for LLM agents to understand how to interact with
specific models before calling `run`.

<ParamField>
  Canonical model identifier (e.g., "zoedepth", "owlv2", "gsam2").
</ParamField>

**Returns:**

A formatted string containing:

* Class-level docstring with usage examples and parameter descriptions
* Preprocess method documentation (input parameters and validation)
* Postprocess method documentation (output format and data types)

**Raises:**

NotImplementedError: If model\_id is not registered or not found.

```python theme={null}
client = CortexClient()
docs = client.help("zoedepth")
print(docs)  # Shows complete zoedepth documentation
# For LLM agents: discover model capabilities
models = client.available_models()
for model in models:
    print(f"=== {model} ===")
    print(client.help(model))
```

### `run()`

```python Signature theme={null}
run(
    model_id: Union[str, ModelType],
    timeout: Optional[float] = None,
    debug: bool = False,
    raw_response: bool = False,
    **kwargs: Any,
) -> Any
```

Execute inference using a specified model with given inputs.

This is the primary method for running AI model inference. It automatically
handles model discovery, input preprocessing, API communication, and output
postprocessing. Essential for LLM agents to perform actual model inference
after discovering available models and understanding their requirements.

<ParamField>
  The identifier of the model to run (use `available_models` to see all available options). Examples: "zoedepth", "owlv2", "gsam2".
</ParamField>

<ParamField>
  Optional timeout in seconds for the HTTP request. If None, uses the client's default timeout.
</ParamField>

<ParamField>
  If True, enables detailed logging for this specific call to help troubleshoot issues.
</ParamField>

<ParamField>
  If True, returns the raw API response without postprocessing.
</ParamField>

<ParamField>
  Model-specific input parameters. Each model's page in the **Cortex Models** docs section and `help` document its exact inputs.
</ParamField>

**Returns:**

The model's postprocessed output; the concrete type is model-specific.
Per-model inputs, output types, and worked examples live on the model
pages in the **Cortex Models** docs section — generated from each
model wrapper's docstring, the canonical source — and via
`help`.

**Raises:**

NotImplementedError: If model\_id is not found in available models.
CortexAPIError: If the API returns an error response.
CortexNetworkError: If network communication fails.
ValueError: If input validation or processing fails.

```python theme={null}
client = CortexClient()
output = client.run(ModelType.ZOEDEPTH, image_input="scene.jpg")
```

### `run_with_detections()`

```python Signature theme={null}
run_with_detections(
    model_id: Union[str, ModelType],
    timeout: Optional[float] = None,
    **kwargs: Any,
) -> Dict[str, Any]
```

Like `run`, but returns per-instance detections (currently SAM3 text/box prompts).


# grid-cortex-client
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-cortex-client/overview

Python client for GRID Cortex

Python client for GRID Cortex — cloud model inference for robotics: depth, detection, segmentation, grasping, VLMs, and VLA policies behind one `run()` call.

## Install

```bash theme={null}
pip install grid-cortex-client
```

## Quickstart

```python theme={null}
from grid_cortex_client import CortexClient, ModelType

client = CortexClient()  # reads GRID_CORTEX_API_KEY from the environment
depth = client.run(ModelType.ZOEDEPTH, image_input="scene.jpg")
```

Every hosted model and its inputs/outputs is documented in the **Cortex Models** section of the sidebar.

## Classes

* [`CortexClient`](/v2.3/python-api/grid-cortex-client/cortexclient)
* [`AsyncCortexClient`](/v2.3/python-api/grid-cortex-client/asynccortexclient)
* [`CortexExecutionEvent`](/v2.3/python-api/grid-cortex-client/cortexexecutionevent)
* [`RuntimeObserver`](/v2.3/python-api/grid-cortex-client/runtimeobserver)
* [`CortexHubClient`](/v2.3/python-api/grid-cortex-client/cortexhubclient)
* [`CortexHubError`](/v2.3/python-api/grid-cortex-client/cortexhuberror)
* [`HubResult`](/v2.3/python-api/grid-cortex-client/hubresult)


# BlockStep
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/blockstep

Ordered operation metadata for one step inside a fused block

```python theme={null}
from grid_nexus_client import BlockStep
```

Ordered operation metadata for one step inside a fused block.

## Fields

<ResponseField name="node_id" type="str" />

<ResponseField name="node_kind" type="str" />

<ResponseField name="operation" type="str" />

<ResponseField name="source_line" type="int | None" />

<ResponseField name="source_end_line" type="int | None" />

<ResponseField name="subs" type="tuple[BlockStepSubscription, ...]" />

<ResponseField name="pub_topics" type="tuple[str, ...]" />

<ResponseField name="publish_intent" type="str" />

## Constructor

```python Signature theme={null}
BlockStep(
    node_id: str,
    node_kind: str = 'unknown',
    operation: str = 'unknown',
    source_line: int | None = None,
    source_end_line: int | None = None,
    subs: tuple[BlockStepSubscription, ...] = (),
    pub_topics: tuple[str, ...] = (),
    publish_intent: str = 'unknown',
)
```


# BlockStepSubscription
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/blockstepsubscription

Subscription metadata for one operation inside a fused block

```python theme={null}
from grid_nexus_client import BlockStepSubscription
```

Subscription metadata for one operation inside a fused block.

## Fields

<ResponseField name="topic" type="str" />

<ResponseField name="kind" type="str" />

<ResponseField name="name" type="str | None" />

<ResponseField name="once" type="bool" />

<ResponseField name="collect_n" type="int" />

<ResponseField name="gate_expect" type="bool | None" />

## Constructor

```python Signature theme={null}
BlockStepSubscription(
    topic: str,
    kind: str = 'data',
    name: str | None = None,
    once: bool = False,
    collect_n: int = 1,
    gate_expect: bool | None = None,
)
```


# create_execution_observer
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/create_execution_observer

Create a Cortex observer when ``GRID_EXECUTION_RECORDING_DIR`` is set

```python theme={null}
from grid_nexus_client import create_execution_observer
```

```python Signature theme={null}
create_execution_observer(*, robot_name: str | None = None) -> RuntimeObserver | None
```

Create a Cortex observer when `GRID_EXECUTION_RECORDING_DIR` is set.

Returns `None` when the variable is unset. Pass the result explicitly to
`CortexClient(observer=...)` for recorded skills; the environment variable
alone does not attach an observer to Cortex clients.
Events are summarized and queued synchronously; the process journal owns
background writes and shutdown, even when several clients share it.

<ParamField>
  Robot identity to attach to this client's recorded model calls.
</ParamField>


# FailedStep
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/failedstep

Operation metadata identifying the step that failed inside a fused block

```python theme={null}
from grid_nexus_client import FailedStep
```

Operation metadata identifying the step that failed inside a fused block.

## Fields

<ResponseField name="node_id" type="str" />

<ResponseField name="operation" type="str" />

<ResponseField name="source_line" type="int | None" />

## Constructor

```python Signature theme={null}
FailedStep(node_id: str, operation: str, source_line: int | None = None)
```


# GraphNodeStatus
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/graphnodestatus

GraphNodeStatus

```python theme={null}
from grid_nexus_client import GraphNodeStatus
```

## Fields

<ResponseField name="robot_name" type="str" />

<ResponseField name="node" type="str" />

<ResponseField name="node_id" type="str" />

<ResponseField name="method_name" type="str | None" />

<ResponseField name="operation" type="str | None" />

<ResponseField name="display_name" type="str | None" />

<ResponseField name="node_kind" type="str" />

<ResponseField name="placement" type="str" />

<ResponseField name="status" type="str" />

<ResponseField name="phase" type="str | None" />

<ResponseField name="phase_since_ms" type="int" />

<ResponseField name="trigger_count" type="int" />

<ResponseField name="error_count" type="int" />

<ResponseField name="last_trigger_ms" type="int" />

<ResponseField name="last_trace_id" type="str | None" />

<ResponseField name="last_started_ms" type="int" />

<ResponseField name="last_finished_ms" type="int" />

<ResponseField name="last_duration_ms" type="int" />

<ResponseField name="active_trace_id" type="str | None" />

<ResponseField name="iteration" type="int" />

<ResponseField name="active_iteration" type="int" />

<ResponseField name="last_completed_iteration" type="int" />

<ResponseField name="timestamp_ms" type="int" />

<ResponseField name="pub_topic" type="str" />

<ResponseField name="source_line" type="int | None" />

<ResponseField name="source_end_line" type="int | None" />

<ResponseField name="source_snippet" type="str | None" />

<ResponseField name="program_source" type="str | None" />

<ResponseField name="loop_id" type="str | None" />

<ResponseField name="loop_source_line" type="int | None" />

<ResponseField name="loop_mode" type="str | None" />

<ResponseField name="loop_role" type="str | None" />

<ResponseField name="slots" type="tuple[dict[str, Any], ...]" />

<ResponseField name="waiting_on" type="tuple[dict[str, Any], ...]" />

<ResponseField name="block_steps" type="tuple[BlockStep, ...] | None" />

<ResponseField name="scope_id" type="str | None" />

<ResponseField name="region_id" type="str | None" />

<ResponseField name="task_id" type="str | None" />

<ResponseField name="deployment_id" type="str | None" />

<ResponseField name="execution_key" type="str | None" />

## Constructor

```python Signature theme={null}
GraphNodeStatus(
    robot_name: str,
    node: str,
    node_id: str,
    method_name: str | None,
    operation: str | None,
    display_name: str | None,
    node_kind: str,
    placement: str,
    status: str,
    phase: str | None,
    phase_since_ms: int,
    trigger_count: int,
    error_count: int,
    last_trigger_ms: int,
    last_trace_id: str | None,
    last_started_ms: int,
    last_finished_ms: int,
    last_duration_ms: int,
    active_trace_id: str | None,
    iteration: int,
    active_iteration: int,
    last_completed_iteration: int,
    timestamp_ms: int,
    pub_topic: str,
    source_line: int | None = None,
    source_end_line: int | None = None,
    source_snippet: str | None = None,
    program_source: str | None = None,
    loop_id: str | None = None,
    loop_source_line: int | None = None,
    loop_mode: str | None = None,
    loop_role: str | None = None,
    slots: tuple[dict[str, Any], ...] = (),
    waiting_on: tuple[dict[str, Any], ...] = (),
    block_steps: tuple[BlockStep, ...] | None = None,
    scope_id: str | None = None,
    region_id: str | None = None,
    task_id: str | None = None,
    deployment_id: str | None = None,
    execution_key: str | None = None,
)
```


# GridEndpointProfile
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/gridendpointprofile

GridEndpointProfile

```python theme={null}
from grid_nexus_client import GridEndpointProfile
```

## Fields

<ResponseField name="target_env" type="str" />

<ResponseField name="cortex_base_url" type="str" />

<ResponseField name="user_signaling_url" type="str" />

<ResponseField name="robot_signaling_url" type="str" />

<ResponseField name="player_signaling_url" type="str" />

<ResponseField name="edge_setup_manifest_url" type="str" />

<ResponseField name="sources" type="Mapping[str, str]" />

## Constructor

```python Signature theme={null}
GridEndpointProfile(
    target_env: str,
    cortex_base_url: str,
    user_signaling_url: str,
    robot_signaling_url: str,
    player_signaling_url: str,
    edge_setup_manifest_url: str,
    sources: Mapping[str, str],
)
```

## Methods

### `redacted_dict()`

```python Signature theme={null}
redacted_dict() -> dict[str, object]
```


# HealthStatus
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/healthstatus

HealthStatus

```python theme={null}
from grid_nexus_client import HealthStatus
```

## Fields

<ResponseField name="robot_name" type="str" />

<ResponseField name="health_id" type="str" />

<ResponseField name="state" type="str" />

<ResponseField name="updated_at_ms" type="int" />

<ResponseField name="stream_id" type="str | None" />

<ResponseField name="source" type="str | None" />

<ResponseField name="readiness_state" type="str | None" />

<ResponseField name="evidence" type="dict[str, Any]" />

<ResponseField name="action" type="str | None" />

## Constructor

```python Signature theme={null}
HealthStatus(
    robot_name: str,
    health_id: str,
    state: str,
    updated_at_ms: int,
    stream_id: str | None = None,
    source: str | None = None,
    readiness_state: str | None = None,
    evidence: dict[str, Any] = dict(),
    action: str | None = None,
)
```


# make_robot
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/make_robot

Make a remote robot and connect to it via the signaling server

```python theme={null}
from grid_nexus_client import make_robot
```

```python Signature theme={null}
make_robot(
    robot_name: str,
    program=None,
    debug: bool | None = None,
    *,
    restart: bool = False,
    zenoh_config: str | os.PathLike[str] | Mapping[str, object] | None = None,
    enable_monitor_ws: bool | None = None,
    timeout: float | None = DEFAULT_CONNECT_TIMEOUT_SECS,
) -> RemoteRobot | RemoteDeployment
```

Make a remote robot and connect to it via the signaling server.

Returns a `RemoteRobot` for direct command dispatch, or a
`RemoteDeployment` if a `program` is provided (staged execution mode).
A remotely invoked program declares a `Robot` parameter and receives the
returned deployment in that slot; programs without a `Robot` parameter
use the standalone `grid_nexus_program.run_program` path.

In direct mode, the robot runtime builds the robot on the first
`make_robot()` of a robot session and reuses it for every later call in
that session, from any notebook or script. `restart=True` shuts that
robot and its navigation down and builds a fresh one without ending the
session. The robot is released when the session ends. When this call
joined an existing dev session (`zenoh_config` or a discovered one),
`RemoteRobot.shutdown()` closes only this client; when it opened the
session itself through signaling, `shutdown()` ends that session and
releases the robot. A staged deployment always builds its own robot, so
`restart` requires direct mode.

The signaling URL comes from `GRID_USER_SIGNALING_URL` when set — the GRID
CLI always exports it for the active cluster — and otherwise from the
`GRID_TARGET_ENV` profile defaults.

Streaming is inferred from the mode: off for direct/dev mode, on for
staged/deploy mode. Disconnects and re-raises on any connection failure.

`enable_monitor_ws` controls the in-process Rust websocket snapshot
broadcaster that serves the monitor on `127.0.0.1:8765`.

`zenoh_config` connects directly to an existing TUI-owned dev session
without opening a signaling websocket. It is supported only for direct/dev
mode, not when `program` is provided. Pass either a path to the TUI
session config file or the same combined `&#123;"player": ..., "edge": ...&#125;`
mapping. The former bare Player object is not accepted. When omitted, an
active dev session for `robot_name` (the config the GRID CLI writes on
`robot connect` / `session start robot`) is discovered automatically;
with no active dev session the signaling path is used.

When `debug` is omitted, it is enabled for staged/deploy connections
where `program` is provided and disabled for direct/dev connections.
It controls only cloud model debug-image streaming; pass `debug=False`
to disable those streams for a deployment. Native Rust/zenoh log verbosity
is controlled separately through `RUST_LOG` and defaults to warnings.

For `enable_monitor_ws`:

* `None` (default): best-effort. Start if possible, log and continue on
  failure (e.g. port already taken by another `make_robot()`).
* `True`: required. Propagate any failure so the caller knows.
* `False`: skip entirely.

Setting `GRID_NEXUS_CLIENT_DISABLE_MONITOR_WS=1` in the environment
behaves like `enable_monitor_ws=False` when the kwarg is left as
`None`.


# MonitorClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/monitorclient

High-level single-session monitor over the low-level Rust monitor feed

```python theme={null}
from grid_nexus_client import MonitorClient
```

High-level single-session monitor over the low-level Rust monitor feed.

## Constructor

```python Signature theme={null}
MonitorClient(
    handle,
    *,
    session_id: str | None = None,
    deployment_id: str | None = None,
    deployment_prefix: str | None = None,
    environment: str = 'unknown',
)
```

## Properties

<ResponseField name="scope" type="MonitorScope" />

<ResponseField name="ws_endpoint" type="tuple[str, int] | None" />

## Methods

### `close()`

```python Signature theme={null}
close() -> None
```

### `get_session()`

```python Signature theme={null}
get_session() -> SessionState
```

### `list_graph_nodes()`

```python Signature theme={null}
list_graph_nodes() -> list[GraphNodeStatus]
```

### `list_parties()`

```python Signature theme={null}
list_parties() -> list[PartyInstance]
```

### `recent_errors()`

```python Signature theme={null}
recent_errors(limit: int = 50) -> list[MonitorEvent]
```

### `recent_trace_refs()`

```python Signature theme={null}
recent_trace_refs(
    snapshot: MonitorSnapshot | None = None,
    *,
    limit: int = 20,
) -> list[TraceReference]
```

### `serve_ws()`

```python Signature theme={null}
serve_ws(
    *,
    host: str = '127.0.0.1',
    port: int = 0,
    interval_secs: float = 1.5,
    error_limit: int = 50,
    allow_remote: bool = False,
) -> int
```

Start a background websocket broadcaster for MonitorSnapshot JSON.

`port=0` asks the OS for a free port; the actual bound port is
returned so callers can tell viewers where to connect. Idempotent
in the sense that a second call while the server is running raises.

The snapshot includes full session/party/trace topology with no
authentication, so binding a non-loopback host requires the caller
to opt in with `allow_remote=True`.

### `session_parties()`

```python Signature theme={null}
session_parties(snapshot: MonitorSnapshot | None = None) -> list[PartyInstance]
```

### `snapshot()`

```python Signature theme={null}
snapshot(*, error_limit: int = 50) -> MonitorSnapshot
```

### `stop()`

```python Signature theme={null}
stop() -> None
```

### `stop_ws()`

```python Signature theme={null}
stop_ws() -> None
```


# MonitorEvent
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/monitorevent

MonitorEvent

```python theme={null}
from grid_nexus_client import MonitorEvent
```

## Fields

<ResponseField name="kind" type="str" />

<ResponseField name="robot_name" type="str" />

<ResponseField name="timestamp_ms" type="int" />

<ResponseField name="source" type="str" />

<ResponseField name="message" type="str" />

<ResponseField name="trace_id" type="str | None" />

<ResponseField name="payload" type="dict[str, Any]" />

<ResponseField name="failed_step" type="FailedStep | None" />

<ResponseField name="scope_id" type="str | None" />

<ResponseField name="region_id" type="str | None" />

<ResponseField name="task_id" type="str | None" />

<ResponseField name="deployment_id" type="str | None" />

<ResponseField name="execution_key" type="str | None" />

<ResponseField name="loop_id" type="str | None" />

<ResponseField name="iteration" type="int | None" />

<ResponseField name="source_line" type="int | None" />

<ResponseField name="source_end_line" type="int | None" />

<ResponseField name="source_snippet" type="str | None" />

## Constructor

```python Signature theme={null}
MonitorEvent(
    kind: str,
    robot_name: str,
    timestamp_ms: int,
    source: str,
    message: str,
    trace_id: str | None = None,
    payload: dict[str, Any] = dict(),
    failed_step: FailedStep | None = None,
    scope_id: str | None = None,
    region_id: str | None = None,
    task_id: str | None = None,
    deployment_id: str | None = None,
    execution_key: str | None = None,
    loop_id: str | None = None,
    iteration: int | None = None,
    source_line: int | None = None,
    source_end_line: int | None = None,
    source_snippet: str | None = None,
)
```


# MonitorScope
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/monitorscope

MonitorScope

```python theme={null}
from grid_nexus_client import MonitorScope
```

## Fields

<ResponseField name="robot_name" type="str" />

<ResponseField name="session_id" type="str | None" />

<ResponseField name="deployment_id" type="str | None" />

<ResponseField name="environment" type="str" />

## Constructor

```python Signature theme={null}
MonitorScope(
    robot_name: str,
    session_id: str | None = None,
    deployment_id: str | None = None,
    environment: str = 'unknown',
)
```


# MonitorSnapshot
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/monitorsnapshot

MonitorSnapshot

```python theme={null}
from grid_nexus_client import MonitorSnapshot
```

## Fields

<ResponseField name="scope" type="MonitorScope" />

<ResponseField name="session" type="SessionState" />

<ResponseField name="parties" type="tuple[PartyInstance, ...]" />

<ResponseField name="graph_nodes" type="tuple[GraphNodeStatus, ...]" />

<ResponseField name="health" type="tuple[HealthStatus, ...]" />

<ResponseField name="errors" type="tuple[MonitorEvent, ...]" />

<ResponseField name="collected_at_ms" type="int" />

## Constructor

```python Signature theme={null}
MonitorSnapshot(
    scope: MonitorScope,
    session: SessionState,
    parties: tuple[PartyInstance, ...],
    graph_nodes: tuple[GraphNodeStatus, ...],
    health: tuple[HealthStatus, ...],
    errors: tuple[MonitorEvent, ...],
    collected_at_ms: int,
)
```


# observe
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/observe

Create a monitor client from a connection object or low-level handle

```python theme={null}
from grid_nexus_client import observe
```

```python Signature theme={null}
observe(
    connection,
    *,
    session_id: str | None = None,
    environment: str = 'unknown',
) -> MonitorClient
```

Create a monitor client from a connection object or low-level handle.


# grid-nexus-client
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/overview

Python client for GRID Nexus

Python client for GRID Nexus — connect to a robot on the GRID network for direct command dispatch (`RemoteRobot`) or staged program deployment (`RemoteDeployment`), with live monitoring of the running graph.

## Install

```bash theme={null}
# Preinstalled in every GRID session workspace and in the Python environment the
# GRID CLI prepares when you run a program with `skill run`. Nothing to install.
```

## Quickstart

```python theme={null}
from grid_nexus_client import make_robot
from grid_types import Velocity

# Direct dispatch: a RemoteRobot whose methods are the robot's capabilities.
robot = make_robot("<robot-name>")
robot.getState()

# standUp/moveByVelocity are a quadruped's; what any given robot
# exposes is its own — see Robot interface.
robot.standUp()
robot.moveByVelocity(Velocity(0.1, 0.0, 0.0), Velocity(0.0, 0.0, 0.0))
```

The methods a `RemoteRobot` exposes are the robot's own — see **Robot interface** for the catalog. The end-to-end walkthrough is [Your first skill](/v2.3/get-started/first-skill).

## Classes

* [`RemoteRobot`](/v2.3/python-api/grid-nexus-client/remoterobot)
* [`RemoteDeployment`](/v2.3/python-api/grid-nexus-client/remotedeployment)
* [`MonitorClient`](/v2.3/python-api/grid-nexus-client/monitorclient)
* [`MonitorScope`](/v2.3/python-api/grid-nexus-client/monitorscope)
* [`MonitorSnapshot`](/v2.3/python-api/grid-nexus-client/monitorsnapshot)
* [`TraceReference`](/v2.3/python-api/grid-nexus-client/tracereference)
* [`BlockStepSubscription`](/v2.3/python-api/grid-nexus-client/blockstepsubscription)
* [`BlockStep`](/v2.3/python-api/grid-nexus-client/blockstep)
* [`FailedStep`](/v2.3/python-api/grid-nexus-client/failedstep)
* [`GraphNodeStatus`](/v2.3/python-api/grid-nexus-client/graphnodestatus)
* [`PartyInstance`](/v2.3/python-api/grid-nexus-client/partyinstance)
* [`MonitorEvent`](/v2.3/python-api/grid-nexus-client/monitorevent)
* [`SessionState`](/v2.3/python-api/grid-nexus-client/sessionstate)
* [`HealthStatus`](/v2.3/python-api/grid-nexus-client/healthstatus)
* [`GridEndpointProfile`](/v2.3/python-api/grid-nexus-client/gridendpointprofile)

## Functions

* [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot)
* [`create_execution_observer`](/v2.3/python-api/grid-nexus-client/create_execution_observer)
* [`observe`](/v2.3/python-api/grid-nexus-client/observe)
* [`resolve_grid_profile`](/v2.3/python-api/grid-nexus-client/resolve_grid_profile)


# PartyInstance
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/partyinstance

PartyInstance

```python theme={null}
from grid_nexus_client import PartyInstance
```

## Fields

<ResponseField name="robot_name" type="str" />

<ResponseField name="role" type="str" />

<ResponseField name="site" type="str" />

<ResponseField name="service_name" type="str" />

<ResponseField name="service_instance_id" type="str" />

<ResponseField name="state" type="str" />

<ResponseField name="last_seen_ms" type="int" />

<ResponseField name="started_at_ms" type="int" />

<ResponseField name="endpoint" type="str" />

<ResponseField name="metadata" type="dict[str, Any]" />

## Constructor

```python Signature theme={null}
PartyInstance(
    robot_name: str,
    role: str,
    site: str,
    service_name: str,
    service_instance_id: str,
    state: str,
    last_seen_ms: int,
    started_at_ms: int,
    endpoint: str = '',
    metadata: dict[str, Any] = dict(),
)
```


# RemoteDeployment
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/remotedeployment

Connection to a remote robot with a program deployed in staged execution mode

```python theme={null}
from grid_nexus_client import RemoteDeployment
```

Connection to a remote robot with a program deployed in staged execution mode.

Created by `make_robot()` when a program is provided. The program's
client-side nodes are materialized locally and wired to the robot via
Zenoh. Pass this object as the program's `Robot` argument; the remaining
arguments keep their ordinary Python positions and keywords. Calling the
program publishes its data inputs and fires one execution cycle.

Robot command validation is handled edge-side by `validate_robot_calls`
inside `prepare_program_nodes`, with errors propagated back through
signaling. The player skips introspection in deployment mode (no
`spawn_pubsub` on the edge), so `methods_info()` is not available.

## Constructor

```python Signature theme={null}
RemoteDeployment(
    handle: RobotHandle,
    client: SignalingClient | None,
    program,
    deployment_id: str,
    deployment_prefix: str,
    signaling_url: str | None = None,
)
```

## Properties

<ResponseField name="deployment_id" type="str" />

<ResponseField name="deployment_prefix" type="str" />

<ResponseField name="monitor" type="MonitorClient">
  Lazy-initialized monitor client for this deployment's Zenoh session.
</ResponseField>

<ResponseField name="robot_name" type="str" />

<ResponseField name="zenoh_session_config" type="str" />

## Methods

### `shutdown()`

```python Signature theme={null}
shutdown()
```

Stop the active program, local graph nodes, robot session, and signaling.


# RemoteRobot
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/remoterobot

Live connection to a remote robot, with its methods exposed as Python attributes

```python theme={null}
from grid_nexus_client import RemoteRobot
```

Live connection to a remote robot, with its methods exposed as Python attributes.

Created by `make_robot()` when no program is provided. The robot is the
root of a recursive component tree discovered at construction time:
robot methods are direct calls (`robot.set_velocity(0.5)`), and every
named subcomponent — sensors, end effector, arms, and their own
children — is a `RemoteComponent` reachable both via the
`subcomponents` mapping and as an attribute
(`robot.left_arm.wrist_cam.getImage()`).

The driver's `@property` values are advertised too, at every level:
reading one runs the getter on the robot, and assigning to one runs the
setter there. Assigning to any other public name raises
`AttributeError` instead of creating a local attribute. The names
below, plus `session`, `robot_name`, `zenoh_session_config`,
`monitor` and `shutdown`, belong to this class — a robot method or
property of the same spelling is not reachable by attribute access.

## Fields

<ResponseField name="type_name">
  Name of the Python driver class the robot runs as (`"UR5e"`, `"Go2"`), or `""` when it advertised none.
</ResponseField>

<ResponseField name="subcomponents">
  Dict of child name → RemoteComponent for every top-level child of the robot.
</ResponseField>

<ResponseField name="sensors">
  Derived dict of the children whose remote role is sensor.
</ResponseField>

<ResponseField name="end_effector">
  Derived RemoteComponent for the child end effector, or None.
</ResponseField>

<ResponseField name="identity">
  Hardware identity (serial number, model, controller version) of the root node alone — advertised per node, so every component in the tree carries its own and none aggregates its children's. A composite robot whose serial lives on a subcomponent reports `&#123;&#125;` here; walk `subcomponents` and apply your own policy to decide which serial identifies the robot. `&#123;&#125;` also means unknown.
</ResponseField>

## Constructor

```python Signature theme={null}
RemoteRobot(
    handle: RobotHandle,
    client: SignalingClient | None = None,
    signaling_url: str | None = None,
)
```

## Properties

<ResponseField name="end_effector" type="RemoteComponent | None">
  The child end effector, or `None` (derived view).

  Prefers the child named `"end_effector"`, else the first child
  whose remote role is end effector.
</ResponseField>

<ResponseField name="identity" type="dict[str, str]">
  Hardware identity of the physical unit behind this node.

  The manufacturer identity the robot reported when this connection
  introspected it — `serial_number`, `model`,
  `controller_version` — each key present only when the robot
  could read it, so an empty dict means *unknown*. Absence is never
  evidence of difference: two components that both report no serial
  are not thereby the same unit, nor thereby distinct ones.

  Read from the introspection payload at connect time, so it costs
  no round-trip and does not change for the life of the connection;
  call `getIdentity()` on the component for a live read.

  **Per-node, never aggregated.** It reports what this node itself
  advertised and nothing about its children: a composite robot
  whose serial lives on its arm reports `&#123;&#125;` at the root while
  `robot.subcomponents["arm"].identity` carries the serial. A
  caller that wants "the robot's serial" walks `subcomponents`
  and picks by its own policy — which node's serial counts as the
  robot's is a decision this client does not make.
</ResponseField>

<ResponseField name="instance" type="str | None">
  The ID of the robot instance `make_robot()` answered with.

  `make_robot(restart=True)` replaces the robot with a new instance,
  and the robot refuses requests that name the old one. `None` for a
  handle that made no robot.
</ResponseField>

<ResponseField name="monitor" type="MonitorClient" />

<ResponseField name="robot_name" type="str" />

<ResponseField name="sensors" type="dict[str, RemoteComponent]">
  Child components whose remote role is sensor (derived view).
</ResponseField>

<ResponseField name="session" type="RobotHandle">
  The underlying low-level robot handle (Zenoh session).
</ResponseField>

<ResponseField name="subcomponents" type="dict[str, RemoteComponent]">
  Named child components of this node (snapshot dict).
</ResponseField>

<ResponseField name="type_name" type="str">
  Name of the Python class this node runs as on the robot.

  The driver class the edge introspected (`"UR5e"`, `"Go2"`), read
  from the introspection payload at connect time, so it costs no
  round-trip and does not change for the life of the connection. It says
  what the component *is*, not which unit it is — see `identity` for
  that.
</ResponseField>

<ResponseField name="zenoh_session_config" type="str" />

## Methods

### `shutdown()`

```python Signature theme={null}
shutdown()
```

Close this Python handle's local resources and owned signaling session.


# resolve_grid_profile
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/resolve_grid_profile

resolve_grid_profile

```python theme={null}
from grid_nexus_client import resolve_grid_profile
```

```python Signature theme={null}
resolve_grid_profile(env: Mapping[str, str] | None = None) -> GridEndpointProfile
```


# SessionState
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/sessionstate

SessionState

```python theme={null}
from grid_nexus_client import SessionState
```

## Fields

<ResponseField name="robot_name" type="str" />

<ResponseField name="session_id" type="str | None" />

<ResponseField name="state" type="str" />

<ResponseField name="connected_roles" type="tuple[str, ...]" />

<ResponseField name="stale_nodes" type="int" />

<ResponseField name="error_count" type="int" />

<ResponseField name="last_update_ms" type="int" />

## Constructor

```python Signature theme={null}
SessionState(
    robot_name: str,
    session_id: str | None,
    state: str,
    connected_roles: tuple[str, ...],
    stale_nodes: int,
    error_count: int,
    last_update_ms: int,
)
```


# TraceReference
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-nexus-client/tracereference

TraceReference

```python theme={null}
from grid_nexus_client import TraceReference
```

## Fields

<ResponseField name="trace_id" type="str" />

<ResponseField name="source" type="str" />

<ResponseField name="timestamp_ms" type="int" />

<ResponseField name="kind" type="str" />

## Constructor

```python Signature theme={null}
TraceReference(trace_id: str, source: str, timestamp_ms: int, kind: str)
```


# CameraModel
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/cameramodel

Supported camera models

```python theme={null}
from grid_types import CameraModel
```

Supported camera models.

Defines the mathematical models used for camera projection and
distortion correction.

## Members

* `CameraModel.PINHOLE` = `'pinhole'`
* `CameraModel.FISHEYE` = `'fisheye'`


# CameraSettings
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/camerasettings

Camera configuration settings

```python theme={null}
from grid_types import CameraSettings
```

Camera configuration settings.

Contains intrinsic camera parameters, distortion coefficients,
extrinsic transformation matrix, and other camera-specific configuration.

## Fields

<ResponseField name="fx" type="Optional[float]">
  Focal length in x direction (pixels)
</ResponseField>

<ResponseField name="fy" type="Optional[float]">
  Focal length in y direction (pixels)
</ResponseField>

<ResponseField name="cx" type="Optional[float]">
  Principal point x coordinate (pixels)
</ResponseField>

<ResponseField name="cy" type="Optional[float]">
  Principal point y coordinate (pixels)
</ResponseField>

<ResponseField name="distortion_coeffs" type="Optional[list[float]]">
  Distortion coefficients
</ResponseField>

<ResponseField name="camera_model" type="Optional[CameraModel]">
  Camera projection model
</ResponseField>

<ResponseField name="image_type" type="Optional[ImageType]">
  Type of images captured
</ResponseField>

<ResponseField name="resolution" type="Optional[tuple[int, int]]">
  Image resolution (width, height)
</ResponseField>

<ResponseField name="extrinsics" type="Optional[np.ndarray]">
  4x4 transformation matrix representing the camera pose relative to a reference frame (e.g., robot base or end-effector). None if not configured.
</ResponseField>

## Constructor

```python Signature theme={null}
CameraSettings(
    fx: Optional[float] = None,
    fy: Optional[float] = None,
    cx: Optional[float] = None,
    cy: Optional[float] = None,
    distortion_coeffs: Optional[List[float]] = None,
    camera_model: Optional[CameraModel] = None,
    image_type: Optional[ImageType] = None,
    resolution: Optional[Tuple[int, int]] = None,
    extrinsics: Optional[np.ndarray] = None,
)
```

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> CameraSettings
```

Deserialize from dictionary.

<ParamField type="dict">
  Dictionary containing camera settings data
</ParamField>

**Returns:**

CameraSettings: Reconstructed camera settings object

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer.

**Returns:**

dict: Dictionary representation of the camera settings


# Force
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/force

A class to represent 3D force

```python theme={null}
from grid_types import Force
```

A class to represent 3D force.

Represents force in 3D space with x, y, and z components.
Supports mathematical operations and conversions to/from various formats.

## Fields

<ResponseField name="x" type="float">
  x-component of force (N)
</ResponseField>

<ResponseField name="y" type="float">
  y-component of force (N)
</ResponseField>

<ResponseField name="z" type="float">
  z-component of force (N)
</ResponseField>

## Constructor

```python Signature theme={null}
Force(x: float, y: float, z: float)
```

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> Force
```

Deserialize from dictionary.

<ParamField>
  Dictionary containing force data
</ParamField>

**Returns:**

Force: Reconstructed force object

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer.

**Returns:**

dict: Dictionary representation of the force


# ForceThresholdExceeded
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/forcethresholdexceeded

A force-aware move stopped because contact force crossed its threshold

```python theme={null}
from grid_types import ForceThresholdExceeded
```

A force-aware move stopped because contact force crossed its threshold.

Raised by drivers when a move issued with force avoidance (e.g.
`moveToPose(..., avoid_force=True)`) trips the configured force/torque
limit. Distinct from a timeout or a command failure so that callers for
whom contact is *expected* — a descent onto a surface — can catch exactly
this and let every other failure propagate.

Subclasses `RuntimeError`: existing broad handlers keep working.


# GeoPoint
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/geopoint

A class to represent a geographic point using latitude, longitude, and altitude

```python theme={null}
from grid_types import GeoPoint
```

A class to represent a geographic point using latitude, longitude, and altitude.

## Fields

<ResponseField name="latitude" type="float">
  Latitude in degrees.
</ResponseField>

<ResponseField name="longitude" type="float">
  Longitude in degrees.
</ResponseField>

<ResponseField name="altitude" type="float">
  Altitude in meters (e.g., above sea level).
</ResponseField>

## Constructor

```python Signature theme={null}
GeoPoint(latitude: float, longitude: float, altitude: float)
```

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> GeoPoint
```

Deserialize from dictionary

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer

## Example

```python theme={null}
pt1 = GeoPoint(latitude=45.0, longitude=-75.0, altitude=100.0)
pt2 = GeoPoint(45.0, -75.0, 100.0)
print(pt1)
print(np.array(pt1))
```


# GRIDType
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/gridtype

Abstract base class for all GRID Robot API types

```python theme={null}
from grid_types import GRIDType
```

Abstract base class for all GRID Robot API types.

All serializable types used as return values in the GRID Robot API
should inherit from this class and implement to\_dict() and from\_dict().

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> GRIDType
```

Deserialize from dictionary. Please ensure any nested types
are also deserialized correctly or are converted from a serializable format in this method.

<ParamField type="dict">
  Dictionary containing serialized object data
</ParamField>

**Returns:**

GRIDType: Reconstructed object

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer. Please ensure any nested types
are also JSON serializable or are converted to a serializable format in this method.

**Returns:**

dict: Dictionary representation of the object


# HeightMap
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/heightmap

A class to represent a height map, typically derived from LiDAR or depth data

```python theme={null}
from grid_types import HeightMap
```

A class to represent a height map, typically derived from LiDAR or depth data.

## Fields

<ResponseField name="data" type="np.ndarray">
  A 2D numpy array where each cell contains a height value. The shape is (height, width).
</ResponseField>

<ResponseField name="resolution" type="float">
  The size of each cell in meters. For example, a resolution of 0.1 means each cell is 0.1m x 0.1m.
</ResponseField>

<ResponseField name="origin" type="Position">
  The 3D world coordinates (x, y, z) of the corner of the cell (0,0) in the height map data.
</ResponseField>

## Constructor

```python Signature theme={null}
HeightMap(data: np.ndarray, resolution: float, origin: Position)
```

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> HeightMap
```

Deserialize from dictionary

### `get_world_coordinates()`

```python Signature theme={null}
get_world_coordinates() -> Tuple[np.ndarray, np.ndarray, np.ndarray]
```

Calculates the 3D world coordinates of each cell in the height map.

The (i, j)-th cell in the `data` array corresponds to a physical location.
This method computes the X, Y, and Z coordinates for all cells.
X and Y are grids representing the planar coordinates.
Z is the height data itself.

**Returns:**

Tuple\[np.ndarray, np.ndarray, np.ndarray]: A tuple containing three 2D arrays:

* X\_coords: World X coordinates of each cell center.
* Y\_coords: World Y coordinates of each cell center.
* Z\_coords: World Z coordinates (heights) of each cell (self.data).

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer

## Example

```python theme={null}
import numpy as np
# Assuming Position is in the same module context
from grid_types import Position
data = np.array([[1.0, 1.1, 1.2],
                 [1.3, 1.4, 1.5]], dtype=np.float32)
resolution = 0.5  # Each cell is 0.5m x 0.5m
origin = Position(x_val=10.0, y_val=20.0, z_val=0.0) # Map starts at (10, 20, 0)
height_map = HeightMap(data=data, resolution=resolution, origin=origin)
print(height_map.data.shape)
print(height_map.resolution)
print(height_map.origin)
```


# Image
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/image

A class to represent an image

```python theme={null}
from grid_types import Image
```

A class to represent an image.

`img_type` describes the **semantic content** of the image ("rgb",
"depth", "segmentation", ...). `encoding_format` describes the
**wire encoding** of `data` — empty string for a raw ndarray (or a
raw pixel-buffer reshaped into one), or one of \{"jpeg", "png",
"webp"} when `data` is the encoded bytes from a camera firmware /
image-transport plugin. The two are orthogonal: a JPEG is still
semantically an RGB image after decoding.

## Fields

<ResponseField name="data" type="Union[np.ndarray, bytes]">
  image data (H x W x C ndarray for raw, or the encoded byte blob when `encoding_format` is set).
</ResponseField>

<ResponseField name="capture_params" type="dict, optional">
  the parameters of image capture.
</ResponseField>

<ResponseField name="img_type" type="str">
  semantic image type ("rgb", "depth", "segmentation", ...).
</ResponseField>

<ResponseField name="encoding_format" type="str">
  "" for raw pixel data; "jpeg" / "png" / "webp" when `data` is encoded bytes. Use `Image.decode()` to lazily turn encoded bytes into an ndarray.
</ResponseField>

<ResponseField name="shape" type="tuple, optional">
  Shape for raw bytes data (height, width, channels).
</ResponseField>

<ResponseField name="dtype" type="np.dtype, optional">
  Data type for raw bytes data.
</ResponseField>

## Constructor

```python Signature theme={null}
Image(
    data: Union[np.ndarray, bytes],
    shape: Optional[tuple] = None,
    dtype: Optional[np.dtype] = None,
    capture_params: Optional[dict] = None,
    img_type: Optional[str] = None,
    encoding_format: str = '',
)
```

## Methods

### `decode()`

```python Signature theme={null}
decode() -> np.ndarray
```

Return an RGB ndarray, decoding from JPEG/PNG/WebP if needed.

No-op (returns `self.data`) when the image is already an ndarray.

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> Image
```

Deserialize from dictionary - handles encoded formats and the legacy
ndarray + image\_data variants.

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer.

For encoded formats (JPEG/PNG/WebP) the bytes are kept as-is and
flagged with `encoding_format`; the receiver reconstructs via
`from_dict` without reshaping. For ndarrays we fall back
to the legacy raw-bytes-with-shape/dtype path.

## Example

```python theme={null}
# Create from numpy array
image = Image(img_array)
# Create from raw pixel bytes
image = Image(raw_bytes, shape=(480, 640, 3), dtype=np.uint8)
# Create from JPEG bytes (e.g. from a camera that emits
# CompressedImage). No decode happens here.
image = Image(jpeg_bytes, encoding_format="jpeg")
```


# ImageType
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/imagetype

Supported image types

```python theme={null}
from grid_types import ImageType
```

Supported image types.

Defines the different types of images that cameras can capture.

## Members

* `ImageType.RGB` = `'rgb'`
* `ImageType.DEPTH` = `'depth'`
* `ImageType.IR` = `'ir'`


# Orientation
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/orientation

A class to represent the orientation as a quaternion

```python theme={null}
from grid_types import Orientation
```

A class to represent the orientation as a quaternion

## Fields

<ResponseField name="x" type="float">
  x component of quaternion
</ResponseField>

<ResponseField name="y" type="float">
  y component of quaternion
</ResponseField>

<ResponseField name="z" type="float">
  z component of quaternion
</ResponseField>

<ResponseField name="w" type="float">
  w component of quaternion (scalar) Can be initialized with either quaternion components or Euler angles
</ResponseField>

## Constructor

```python Signature theme={null}
Orientation(
    x: Union[float, int, np.ndarray, list],
    y: Union[float, int] = None,
    z: Union[float, int] = None,
    w: Optional[Union[float, int]] = None,
)
```

Initialize an Orientation object.

This constructor supports multiple initialization methods:

1. Using quaternion components (x, y, z, w)
2. Using Euler angles (roll, pitch, yaw) where the first three arguments
   are interpreted as roll, pitch, and yaw respectively
3. Using a rotation matrix (3x3 numpy array or list)
4. Using a quaternion array (4-element list or numpy array)

<ParamField>
  x component of quaternion, roll angle, rotation matrix, or quaternion array
</ParamField>

<ParamField>
  y component of quaternion or pitch angle. Ignored when x is an array.
</ParamField>

<ParamField>
  z component of quaternion or yaw angle. Ignored when x is an array.
</ParamField>

<ParamField>
  w component of quaternion. When None, x, y, z are interpreted as Euler angles.
</ParamField>

## Methods

### `conjugate()`

```python Signature theme={null}
conjugate() -> Orientation
```

Return the conjugate of the quaternion (-x, -y, -z, w).
For a unit quaternion, the conjugate is its inverse.

**Returns:**

Orientation: New orientation representing the conjugate.

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> Orientation
```

Deserialize from dictionary

### `normalize()`

```python Signature theme={null}
normalize() -> Orientation
```

Return a normalized version of this quaternion

**Returns:**

Orientation: New orientation with normalized quaternion components

### `to_axis_angle()`

```python Signature theme={null}
to_axis_angle(degrees: bool = False) -> np.ndarray
```

Convert quaternion to axis-angle representation.

<ParamField>
  If True, the angle is returned in degrees. Defaults to False.
</ParamField>

**Returns:**

np.ndarray: 3 dimensional vector which is co-directional to the axis of rotation and
whose norm gives the angle of rotation.

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer

### `to_euler()`

```python Signature theme={null}
to_euler(order: str = 'xyz') -> Tuple[float, float, float]
```

Convert quaternion to Euler angles.

<ParamField>
  Order of rotations. Defaults to "xyz". Supported orders include "xyz", "zyx", "yzx", etc.
</ParamField>

**Returns:**

tuple\[float, float, float]: Tuple of (roll, pitch, yaw) in radians.

### `to_matrix()`

```python Signature theme={null}
to_matrix() -> np.ndarray
```

Convert quaternion to a rotation matrix

**Returns:**

np.ndarray: 3x3 rotation matrix

## Example

```python theme={null}
orientation = Orientation(x, y, z, w)
orientation = Orientation(roll, pitch, yaw)
```


# grid-types
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/overview

The shared value types of the GRID platform

The shared value types of the GRID platform — poses, velocities, images, point clouds — accepted and returned by the robot, simulation, and model clients.

## Install

```bash theme={null}
# Preinstalled in every GRID session workspace. For local use, install
# from the GRID package index with your organization's read-only
# credentials (the same pair `robot add` provisions on robots):
export UV_INDEX_GRID_PYPI_USERNAME=<username>
export UV_INDEX_GRID_PYPI_PASSWORD=<token>
uv pip install grid-types --index grid-pypi=https://pypi.generalrobotics.dev/simple/
```

## Quickstart

```python theme={null}
from grid_types import Velocity

linear = Velocity(0.5, 0.0, 0.0)
angular = Velocity(0.0, 0.0, 0.4)
```

These types appear throughout **grid-nexus-client** robot commands and **grid-cortex-client** model inputs/outputs.

## Classes

* [`GRIDType`](/v2.3/python-api/grid-types/gridtype)
* [`Pose`](/v2.3/python-api/grid-types/pose)
* [`Position`](/v2.3/python-api/grid-types/position)
* [`Orientation`](/v2.3/python-api/grid-types/orientation)
* [`Velocity`](/v2.3/python-api/grid-types/velocity)
* [`Force`](/v2.3/python-api/grid-types/force)
* [`Torque`](/v2.3/python-api/grid-types/torque)
* [`Image`](/v2.3/python-api/grid-types/image)
* [`ImageType`](/v2.3/python-api/grid-types/imagetype)
* [`CameraModel`](/v2.3/python-api/grid-types/cameramodel)
* [`CameraSettings`](/v2.3/python-api/grid-types/camerasettings)
* [`PointCloud`](/v2.3/python-api/grid-types/pointcloud)
* [`HeightMap`](/v2.3/python-api/grid-types/heightmap)
* [`GeoPoint`](/v2.3/python-api/grid-types/geopoint)
* [`ForceThresholdExceeded`](/v2.3/python-api/grid-types/forcethresholdexceeded)
* [`RobotFault`](/v2.3/python-api/grid-types/robotfault)


# PointCloud
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/pointcloud

A class to represent a point cloud

```python theme={null}
from grid_types import PointCloud
```

A class to represent a point cloud.

## Fields

<ResponseField name="points" type="np.ndarray">
  Array of points with shape (N, D) where N is the number of points and D is the dimensionality of each point (e.g., D=3 for x,y,z). Each row is a point, and each column is a dimension/feature.
</ResponseField>

<ResponseField name="fields" type="List[str]">
  List of field names for the point cloud data. The order of field names must correspond to the columns in the points array. If not provided, defaults to \['x', 'y'] for 2D points (N,2) or \['x', 'y', 'z'] for 3D points (N,3). For other dimensions, fields must be explicitly provided.
</ResponseField>

## Constructor

```python Signature theme={null}
PointCloud(points: np.ndarray, fields: Optional[List[str]] = None)
```

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> PointCloud
```

Deserialize from dictionary

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer

## Example

```python theme={null}
import numpy as np
# 3D points with x, y, z
points_data_3d = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.float32)
pc1 = PointCloud(points=points_data_3d)
print(pc1.points)
print(pc1.fields)
# 2D points with x, y
points_data_2d = np.array([[1, 2], [3, 4]], dtype=np.float32)
pc2 = PointCloud(points=points_data_2d)
print(pc2.fields)
# 3D points with custom fields (e.g., x, y, intensity)
points_data_custom = np.array([[10, 20, 100], [30, 40, 150]], dtype=np.float32)
pc3 = PointCloud(points=points_data_custom, fields=['x', 'y', 'intensity'])
print(pc3.fields)
# Points with x, y, z, r, g, b
points_rgb = np.array([[1,2,3, 255,0,0], [4,5,6, 0,255,0]], dtype=np.float32)
fields_rgb = ['x', 'y', 'z', 'r', 'g', 'b']
pc4 = PointCloud(points=points_rgb, fields=fields_rgb)
print(pc4.points.shape)
print(pc4.fields)
```


# Pose
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/pose

A class to represent the pose (position and orientation) of the robot

```python theme={null}
from grid_types import Pose
```

A class to represent the pose (position and orientation) of the robot.

## Fields

<ResponseField name="position" type="Position">
  The position component of the pose.
</ResponseField>

<ResponseField name="orientation" type="Orientation">
  The orientation component of the pose.
</ResponseField>

## Constructor

```python Signature theme={null}
Pose(*args, **kwargs)
```

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> Pose
```

Deserialize from dictionary.

<ParamField>
  Dictionary containing pose data
</ParamField>

**Returns:**

Pose: Reconstructed pose object

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer.

**Returns:**

dict: Dictionary representation of the pose

### `to_matrix()`

```python Signature theme={null}
to_matrix() -> np.ndarray
```

Convert Pose to a 4x4 homogeneous transformation matrix.

**Returns:**

np.ndarray: 4x4 homogeneous transformation matrix


# Position
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/position

A class to represent 3D cartesian position

```python theme={null}
from grid_types import Position
```

A class to represent 3D cartesian position

## Fields

<ResponseField name="x" type="float">
  x-coordinate value (meters)
</ResponseField>

<ResponseField name="y" type="float">
  y-coordinate value (meters)
</ResponseField>

<ResponseField name="z" type="float">
  z-coordinate value (meters)
</ResponseField>

## Constructor

```python Signature theme={null}
Position(x: Union[float, List[float], np.ndarray], y: float = None, z: float = None)
```

Initialize a Position object.

<ParamField>
  x-coordinate value or 3-element array \[x, y, z]
</ParamField>

<ParamField>
  y-coordinate value. Defaults to None.
</ParamField>

<ParamField>
  z-coordinate value. Defaults to None.
</ParamField>

## Properties

<ResponseField name="x_val" type="float" />

<ResponseField name="y_val" type="float" />

<ResponseField name="z_val" type="float" />

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> Position
```

Deserialize from dictionary

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer


# RobotFault
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/robotfault

A robot controller reported a fault while executing a command

```python theme={null}
from grid_types import RobotFault
```

A robot controller reported a fault while executing a command.

The form-factor-agnostic controller-fault exception. Vendor drivers
subclass it (e.g. the FANUC drivers' `FanucFault`) and may attach vendor
attributes; callers that want fault-aware recovery catch `RobotFault` and
branch only on `recoverable`, never on vendor specifics::

try:
arm.followJointTrajectory(...)
except RobotFault as fault:
if fault.recoverable:
arm.reset()  # then retry
else:
raise  # fatal — needs human intervention

Severity is the universal contract: every robot can say whether a software
recovery attempt is worth making. Vendor alarm codes are optional metadata —
many controllers expose none, so no driver must populate them, and
robot-agnostic code must treat them as opaque display strings rather than
branching on their content.

Carries explicit typed fields rather than being a `@dataclass`: it has to
stay raisable and catchable by existing `except RuntimeError` handlers,
and a dataclass-generated `__init__` would not pass `message` through to
`RuntimeError` (so `str(fault)` would lose it).

## Fields

<ResponseField name="message">
  The fault description (see Args).
</ResponseField>

<ResponseField name="recoverable">
  The recovery hint (see Args).
</ResponseField>

<ResponseField name="codes">
  The vendor alarm codes, empty when none were available.
</ResponseField>

## Constructor

```python Signature theme={null}
RobotFault(message: str, *, recoverable: bool = True, codes: Optional[List[str]] = None)
```


# Torque
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/torque

A class to represent 3D torque

```python theme={null}
from grid_types import Torque
```

A class to represent 3D torque.

Represents torque in 3D space with x, y, and z components.
Supports mathematical operations and conversions to/from various formats.

## Fields

<ResponseField name="x" type="float">
  x-component of torque (N⋅m)
</ResponseField>

<ResponseField name="y" type="float">
  y-component of torque (N⋅m)
</ResponseField>

<ResponseField name="z" type="float">
  z-component of torque (N⋅m)
</ResponseField>

## Constructor

```python Signature theme={null}
Torque(x: float, y: float, z: float)
```

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> Torque
```

Deserialize from dictionary.

<ParamField>
  Dictionary containing torque data
</ParamField>

**Returns:**

Torque: Reconstructed torque object

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer.

**Returns:**

dict: Dictionary representation of the torque


# Velocity
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-types/velocity

A class to represent 3D velocity

```python theme={null}
from grid_types import Velocity
```

A class to represent 3D velocity.

Represents velocity in 3D space with x, y, and z components.
Supports mathematical operations and conversions to/from various formats.

## Fields

<ResponseField name="x" type="float">
  x-component of velocity (m/s or rad/s)
</ResponseField>

<ResponseField name="y" type="float">
  y-component of velocity (m/s or rad/s)
</ResponseField>

<ResponseField name="z" type="float">
  z-component of velocity (m/s or rad/s)
</ResponseField>

## Constructor

```python Signature theme={null}
Velocity(x: float, y: float, z: float)
```

## Properties

<ResponseField name="x_vel" type="float" />

<ResponseField name="y_vel" type="float" />

<ResponseField name="z_vel" type="float" />

## Methods

### `from_dict()`

```python Signature theme={null}
from_dict(data: dict) -> Velocity
```

Deserialize from dictionary.

<ParamField>
  Dictionary containing velocity data
</ParamField>

**Returns:**

Velocity: Reconstructed velocity object

### `to_dict()`

```python Signature theme={null}
to_dict() -> dict
```

Serialize to dictionary for JSON transfer.

**Returns:**

dict: Dictionary representation of the velocity


# Clearpath Jackal
Source: https://docs.generalrobotics.dev/v2.3/python-api/jackal/jackal

The Clearpath Jackal as GRID drives it

The Clearpath Jackal as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `Jackal`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<jackal-name>")
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `getBatteryState()`

```python Signature theme={null}
getBatteryState() -> Optional[dict]
```

Return the latest battery-management-system reading.

**Returns:**

A dict with `voltage` (volts), `current` (amps, negative when
discharging), `charge_percent` (0–100, or `None` if the BMS
does not report it) — or `None` if no battery message has
arrived yet.

### `getIMU()`

```python Signature theme={null}
getIMU() -> Optional[dict]
```

Return the latest IMU reading.

Same keys, units and semantics as `Vision60.getIMU`.

**Returns:**

A dict with `orientation` (quaternion), `angular_velocity`
(rad/s) and `linear_acceleration` (m/s²) — or `None` if no IMU
message has arrived yet.

**Raises:**

RuntimeError: If IMU data is arriving but does not decode as
`sensor_msgs/Imu`.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMagneticField()`

```python Signature theme={null}
getMagneticField() -> Optional[Velocity]
```

Return the latest magnetometer reading in tesla.

**Returns:**

Field vector in tesla as a `Velocity` triple (the shared
three-component type; these are not velocities), or `None` if no
magnetometer message has arrived yet.

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Return the base orientation as a quaternion, from fused odometry.

Yaw is dead-reckoned and drifts; roll and pitch are gravity-referenced
via the IMU and do not.

**Returns:**

Orientation quaternion, or `None` if no odometry has arrived yet.

**Raises:**

RuntimeError: If odometry is arriving but does not decode as
`nav_msgs/Odometry`.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Return the base position in metres, from fused odometry.

Dead-reckoned from wheel encoders and IMU by the platform's EKF, in
the odometry frame the stack started in. It drifts without bound and
is not an absolute world position.

**Returns:**

Position in metres, or `None` if no odometry has arrived yet.

**Raises:**

RuntimeError: If odometry is arriving but does not decode as
`nav_msgs/Odometry` — `None` means "nothing yet" only.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getVelocity()`

```python Signature theme={null}
getVelocity() -> Optional[Velocity]
```

Return the measured body-frame linear velocity in m/s.

Measured, not commanded — use it to close the loop on
`moveByVelocity`. Angular velocity is available from `getIMU()` or
`getState()`.

**Returns:**

Body-frame linear velocity in m/s, or `None` if no odometry has
arrived yet.

**Raises:**

RuntimeError: If odometry is arriving but does not decode as
`nav_msgs/Odometry`.

### `isEmergencyStopped()`

```python Signature theme={null}
isEmergencyStopped() -> bool
```

Report whether the platform emergency stop is currently engaged.

Raises rather than returning `None` when the state is unknown: a
caller writing `if robot.isEmergencyStopped()` would read an unknown
state as "clear to move", which is exactly backwards for a safety
interlock.

**Returns:**

True when the stop is engaged and motion is inhibited, False when
it is clear.

**Raises:**

RuntimeError: If the emergency-stop state is unknown — either
nothing has arrived on the topic, or what arrives does not
decode as `std_msgs/Bool`. The second case warns once on
first read, not at bring-up.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    *,
    duration: Optional[float] = 1.0,
) -> None
```

Command a body-frame twist.

Non-blocking: returns immediately, and the command is republished at
`_CMD_RATE_HZ` Hz until superseded by another call, until `stop()`,
or until *duration* seconds elapse — the platform MCU halts the wheels
when commands stop arriving, so continuous republish is what holds a
velocity.

The Jackal is a differential-drive base: it cannot translate
sideways. `linear_velocity.y` and `.z` are ignored, as are
`angular_velocity.x` and `.y`.

<ParamField>
  Body-frame linear velocity in m/s; only `x` (forward-positive) is actuated.
</ParamField>

<ParamField>
  Body-frame angular velocity in rad/s; only `z` (counter-clockwise-positive yaw) is actuated.
</ParamField>

<ParamField>
  Reference frame. Only `"body"` is supported.
</ParamField>

<ParamField>
  Seconds to hold the command. `None` republishes indefinitely until `stop()` or the next command.
</ParamField>

**Raises:**

NotImplementedError: If `frame == "world"`. The platform accepts
only body-frame twists; compose a world-frame move from
`getOrientation()` and repeated body-frame commands.
ValueError: If *frame* is neither `"body"` nor `"world"`, if
*duration* is negative, or if a commanded speed exceeds
`max_linear_speed` / `max_angular_speed`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

## Properties on the robot

Read as `robot.<property>`; each read runs the getter on the robot.

<ResponseField name="cmd_vel_topic" type="str">
  Velocity-command topic: the platform `twist_mux` input.
</ResponseField>

<ResponseField name="latest_battery" type="Optional[BatteryState]">
  The most recent battery-management-system message, or `None`.
</ResponseField>

<ResponseField name="latest_estop" type="Optional[bool]">
  Whether the emergency stop is engaged, or `None` if unknown.
</ResponseField>

<ResponseField name="latest_imu" type="Optional[Imu]">
  The most recent IMU message, or `None` if none has arrived.
</ResponseField>

<ResponseField name="latest_joint_state" type="Optional[JointState]">
  The most recent wheel joint-state message, or `None`.
</ResponseField>

<ResponseField name="latest_magnetometer" type="Optional[MagneticField]">
  The most recent magnetometer message, or `None`.
</ResponseField>

<ResponseField name="latest_odometry" type="Optional[Odometry]">
  The most recent fused-odometry message, or `None` if none has arrived.
</ResponseField>

<ResponseField name="odometry_topic" type="str">
  Fused (EKF) odometry topic.
</ResponseField>

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the children this class always ships with (customization point).
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()`
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# Python APIs
Source: https://docs.generalrobotics.dev/v2.3/python-api/overview

How a robot call travels, and which reference answers which question

## How a call travels

```python theme={null}
from grid_nexus_client import make_robot
from grid_cortex_client import CortexClient, ModelType

robot = make_robot("go2-lab")        # grid-nexus-client: a RemoteRobot, a proxy for one robot
frame = robot.front.getImage()    # `front` is a subcomponent; getImage runs ON the robot
rgb = frame.decode()              # grid-types: the Image came back over the network
                                  # (fit it to the model's size limit, stated on each model page)
answer = CortexClient().run(ModelType.MOONDREAM, image_input=rgb, task="vqa", prompt="What is here?")
robot.shutdown()                  # client side: closes your connection; the robot is untouched
```

Every attribute on the proxy is either a method or a named subcomponent, and both are the robot's own — apart from the few `RemoteRobot` defines on the client side (`shutdown`, `monitor`, `session`), which never reach the robot. What `robot.front.getImage` accepts is decided by the Go2 driver running on the robot, not by the client, which is why the reference is organised by robot. Connecting neither starts nor moves a robot. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message, never as the original type.

**Direct or staged?** `make_robot(name)` is direct dispatch: each call is one round trip, right for a program that reads sensors and issues commands in a loop from your machine. `make_robot(name, program=...)` stages a `@program` graph to run on the robot itself; reach for it when a loop must not round-trip. Start with direct dispatch.

## Which reference answers which question

| You want to… | Read | Start at |
| - | - | - |
| Connect to a robot and dispatch commands | **grid-nexus-client** | [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot) |
| What *your* robot accepts, method by method | **Robots** | [Fanuc CRX-30iA Arm](/v2.3/python-api/fanuccrx30/fanuccrx30) · [Fanuc LR Mate 200iD Arm](/v2.3/python-api/fanuclrmate200id/fanuclrmate200id) · [Flexiv Rizon Arm](/v2.3/python-api/flexiv-rizon/flexivrizon) · [Universal Robots UR3e Arm](/v2.3/python-api/ur3e/ur3e) · [Universal Robots UR5e Arm](/v2.3/python-api/ur5e/ur5e) · [Galaxea R1 Pro Mobile Manipulator](/v2.3/python-api/r1pro/galaxear1pro) · [Unitree Go2 Quadruped](/v2.3/python-api/go2/go2) · [Ghost Robotics Vision60](/v2.3/python-api/vision60/vision60) · [Ghost Robotics Vision60 + Ghost Arm](/v2.3/python-api/vision60-arm/vision60witharm) · [Composite Rig](/v2.3/python-api/rig/rig) · [Clearpath Jackal](/v2.3/python-api/jackal/jackal) |
| See what an attached camera can do (stereo pair, intrinsics, extrinsics) | **Cameras** | [`ZedUSBCamera`](/v2.3/python-api/cameras/zedusbcamera) |
| Look up what a robot can actually do (`standUp`, `getImage`, …) | **Robot interface** | [`Robot`](/v2.3/python-api/robot-interface/robot) |
| Pass poses, velocities, images between all of the above | **grid-types** | [`overview`](/v2.3/python-api/grid-types/overview) |
| Call hosted models (depth, detection, grasping, VLMs, VLAs) | **grid-cortex-client** | [`CortexClient`](/v2.3/python-api/grid-cortex-client/cortexclient) |
| Drive a robot in the AirGen (Unreal) simulator | **AirGen robots** | [`AirGenDrone`](/v2.3/python-api/airgen-robots/airgendrone) |
| Drive a robot in the Isaac Sim simulator | **Isaac robots** | [`IsaacArm`](/v2.3/python-api/isaac-robots/isaacarm) |
| Move objects and reset the scene in Isaac Sim | **Isaac scene** | [`IsaacClient`](/v2.3/python-api/isaac-scene/isaacclient) |

Every page in this section is generated from the package source — signatures,
parameters, and examples are the code's own docstrings, verified fresh in CI.


# Galaxea R1 Pro Mobile Manipulator
Source: https://docs.generalrobotics.dev/v2.3/python-api/r1pro/galaxear1pro

The Galaxea R1 Pro Mobile Manipulator as GRID drives it

The Galaxea R1 Pro Mobile Manipulator as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `GalaxeaR1Pro`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<r1pro-name>")

# `head_camera_left` is a built-in camera: reach it as an attribute.
frame = robot.head_camera_left.getImage()
rgb = frame.decode()                    # -> H x W x 3 RGB ndarray
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `addNamedPose()`

```python Signature theme={null}
addNamedPose(pose_name: str, joint_angles: Dict[str, List[float]]) -> None
```

Register a named pose, replacing any entry of the same name.

<ParamField>
  Case-insensitive name to register the pose under.
</ParamField>

<ParamField>
  Joint angles in radians per joint group (`"left_arm"`, `"right_arm"`, `"base"`); a group may be omitted to leave that group where it is.
</ParamField>

**Raises:**

ValueError: If `joint_angles` names a group this robot does not have.

### `getBatteryState()`

```python Signature theme={null}
getBatteryState() -> dict
```

Get battery state (voltage, current, capacity). Delegates to `GalaxeaR1ProBase`.

### `getIMU()`

```python Signature theme={null}
getIMU(sensor: str = 'chassis') -> dict
```

Get IMU data for `"chassis"` or `"torso"`. Delegates to `GalaxeaR1ProBase`.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles(
    group: Optional[str] = None,
) -> Union[Dict[str, List[float]], List[float]]
```

Get joint angles.

<ParamField>
  If provided, return joint angles for that subcomponent only (as a flat `list[float]`). If `None` (default), return a dict mapping every subcomponent name to its joint angles.
</ParamField>

**Returns:**

`list[float]` when *group* is given, otherwise
`dict[str, list[float]]`.

**Raises:**

KeyError: If *group* is not a known subcomponent.

````python theme={null}
```python
# All groups at once
all_joints = robot.getJointAngles()
# -> {"left_arm": [...], "right_arm": [...], "base": [...]}

# Single group (same return type as Arm.getJointAngles())
left_joints = robot.getJointAngles("left_arm")
# -> [0.0, 0.1, ...]
````

````

### `getLidarPointCloud()`

```python Signature
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
````

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Orientation
```

Get the chassis orientation in world frame.

Chassis orientation is calculated from accumulated LiDAR-IMU odometry,
with the origin at the robot's initial orientation on startup.
Delegates to `GalaxeaR1ProBase`.

**Raises:**

RuntimeError: If no odometry data has been received yet.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Position
```

Get the chassis position in world frame.

Chassis position is calculated from accumulated LiDAR-IMU odometry,
with the origin at the robot's initial position on startup.
Delegates to `GalaxeaR1ProBase`.

**Raises:**

RuntimeError: If no odometry data has been received yet.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    duration: Optional[float] = 1.0,
) -> None
```

Command chassis velocity.

Delegates to `GalaxeaR1ProBase.moveByVelocity`. The velocity is
republished at 50 Hz until `stop` is called, or until *duration*
seconds have elapsed.

<ParamField>
  Linear velocity in m/s (body frame).
</ParamField>

<ParamField>
  Angular velocity in rad/s.
</ParamField>

<ParamField>
  Reference frame for the velocity. Only `"body"` is supported; any other value (including `"world"`) raises.
</ParamField>

<ParamField>
  Maximum time in seconds to hold the velocity command. Pass `None` to republish indefinitely until `stop()`.
</ParamField>

**Raises:**

ValueError: If *frame* is not `"body"`.

### `moveToNamedPose()`

```python Signature theme={null}
moveToNamedPose(pose_name: str) -> None
```

Move arms and torso to a named pose.

Available poses are stored in `named_poses`. Built-in poses:

* `"home"` -- upright with elbows bent 90°.
* `"rest"` -- upright with arms straight (all joints zero).
* `"sleep"` -- torso folded down, elbows bent.

<ParamField>
  Case-insensitive pose name (e.g. `"home"`, `"sleep"`).
</ParamField>

**Raises:**

ValueError: If the pose name is not recognised.

### `moveToPose()`

```python Signature theme={null}
moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    frame: str = 'world',
    pos_threshold: float = 0.05,
    yaw_threshold: float = 0.05,
    max_linear_speed: float = 0.5,
    max_angular_speed: float = 1.0,
    kp_linear: float = 1.0,
    ki_linear: float = 0.1,
    kp_angular: float = 2.0,
    ki_angular: float = 0.2,
    integral_fraction: float = 0.2,
    timeout: float = 30.0,
) -> None
```

Drive the chassis to a target pose.

Delegates to `GalaxeaR1ProBase.moveToPose`. See that method for
full documentation of the PI controller and its parameters.

!!! note
The world frame origin is the robot's position and heading at
startup.  When *frame* is `"world"`, coordinates are absolute
in that odometry frame.  When *frame* is `"body"`, the target
pose is interpreted as a delta relative to the current pose at
the time of the call.

<ParamField>
  Target pose. Only `position.x`, `position.y`, and the yaw component (rotation about Z) of `orientation` are used; `z`, roll, and pitch are ignored. Interpretation depends on *frame*: absolute world-frame coordinates when `"world"`, or a body-frame delta (dx forward, dy left, dyaw) when `"body"`.
</ParamField>

<ParamField>
  This move always blocks until convergence or timeout; passing `blocking=False` logs a warning. Defaults to True.
</ParamField>

<ParamField>
  Reference frame for the target — `"world"` (default) for an absolute pose, or `"body"` for a delta relative to the current pose.
</ParamField>

<ParamField>
  Position convergence threshold in meters.
</ParamField>

<ParamField>
  Yaw convergence threshold in radians.
</ParamField>

<ParamField>
  Maximum linear velocity magnitude in m/s.
</ParamField>

<ParamField>
  Maximum angular velocity magnitude in rad/s.
</ParamField>

<ParamField>
  Proportional gain for XY position error.
</ParamField>

<ParamField>
  Integral gain for XY position error.
</ParamField>

<ParamField>
  Proportional gain for yaw error.
</ParamField>

<ParamField>
  Integral gain for yaw error.
</ParamField>

<ParamField>
  Maximum fraction of max speed that the integral term can contribute (0.0 to 1.0). Limits windup so the integral handles steady-state error without causing overshoot on longer drives.
</ParamField>

<ParamField>
  Maximum time in seconds before the controller gives up.
</ParamField>

**Raises:**

ValueError: If *frame* is not `"world"` or `"body"`.
RuntimeError: If no odometry data is available, or if *timeout*
is exceeded before convergence.

### `setBrakeMode()`

```python Signature theme={null}
setBrakeMode(engaged: bool) -> None
```

Engage or disengage the chassis brake. Delegates to `GalaxeaR1ProBase`.

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: Union[Dict[str, list], list],
    velocities: Union[Optional[Dict[str, list]], list] = None,
    group: Optional[str] = None,
) -> None
```

Set joint angles.

Can be called in two ways:

* **Multi-group** (default): pass a dict mapping group names to
  angle lists.  `velocities` may also be a dict.
* **Single-group**: pass a flat `list` of angles together with
  `group="&lt;name>"`.  `velocities` may also be a flat list.
  This matches the `Arm` / `Humanoid` / `Quadruped`
  signature.

<ParamField>
  Target joint angles in radians — a dict for multi-group or a list for single-group.
</ParamField>

<ParamField>
  Optional joint velocities. In single-group mode, a list or scalar. In multi-group mode, a dict mapping group names to velocity lists/scalars (partial dicts OK — omitted groups get no velocity), a single scalar (broadcast to every group being commanded), or `None`.
</ParamField>

<ParamField>
  Subcomponent name.  Required when *angles* is a list.
</ParamField>

**Raises:**

KeyError: If a group name is not a known subcomponent.
TypeError: If *angles* is a list but *group* is not provided,
or if *velocities* is a list in multi-group mode.

````python theme={null}
```python
# Multi-group
robot.setJointAngles({"left_arm": angles_l, "base": angles_b})

# Multi-group with per-group velocities
robot.setJointAngles(
    {"left_arm": angles_l, "right_arm": angles_r},
    velocities={"left_arm": 0.5},  # only left_arm; right_arm uses default
)

# Per-group velocities as a list
robot.setJointAngles(
    {"left_arm": angles_l, "right_arm": angles_r},
    velocities={"left_arm": [0.5] * 7, "right_arm": [0.1] * 7},
)

# Multi-group with a single velocity for all groups/joints
robot.setJointAngles(
    {"left_arm": angles_l, "base": angles_b},
    velocities=0.5,
)

# Single-group (same list signature as Arm, Humanoid, etc.)
robot.setJointAngles(angles_l, group="left_arm")
````

````

### `stop()`

```python Signature
stop() -> None
````

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

## Properties on the robot

Read as `robot.<property>`; each read runs the getter on the robot.

<ResponseField name="named_poses" type="Dict[str, Dict[str, List[float]]]">
  Registered poses as `&#123;name: &#123;joint group: angles in radians&#125;&#125;` (a copy).

  Mutating the returned mapping does not change what the robot knows:
  register entries with `addNamedPose`, or assign a whole mapping
  to replace them all.
</ResponseField>

## robot.head\_camera\_left and 10 more — camera

Reached as any of `robot.head_camera_left`, `robot.head_camera_right`, `robot.wrist_left`, `robot.wrist_right`, `robot.chassis_front_left`, `robot.chassis_front_right`, `robot.chassis_left`, `robot.chassis_right`, `robot.chassis_rear`, `robot.wrist_left_depth`, `robot.wrist_right_depth`; each is a `R1ProCamera` and its methods are `R1ProCamera`'s and run on the robot. Below, `<camera>` stands for any one of those names.

Camera sensor bridging a ROS 2 image topic to the GRID `Camera` interface.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `<camera>.getCameraExtrinsics()`

```python Signature theme={null}
<camera>.getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

### `<camera>.getCameraIntrinsics()`

```python Signature theme={null}
<camera>.getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

### `<camera>.getCameraSettings()`

```python Signature theme={null}
<camera>.getCameraSettings() -> CameraSettings
```

Get the camera settings.

### `<camera>.getData()`

```python Signature theme={null}
<camera>.getData() -> Image
```

Get the image from the camera.

### `<camera>.getImage()`

```python Signature theme={null}
<camera>.getImage(*, compressed: bool = True) -> Optional[Image]
```

Return the latest image, or `None` if no message has arrived yet.

ROS `CompressedImage` topics already carry JPEG/PNG bytes. By
default we pass those through unchanged (\~30x bandwidth saving
over decoding to an ndarray here); pass `compressed=False` to
get a decoded RGB ndarray instead. Unknown compressed formats
always fall back to the OpenCV decode path. Raw depth messages
(`32FC1`, `16UC1`) are converted to numpy arrays — the
`compressed` flag has no effect on depth.

<ParamField type="bool, optional">
  when True (default) and the ROS message is a JPEG/PNG CompressedImage, return the bytes via `Image(..., encoding_format=...)`. When False, always decode to an RGB ndarray.
</ParamField>

### `<camera>.getState()`

```python Signature theme={null}
<camera>.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `<camera>.recordCalibration()`

```python Signature theme={null}
<camera>.recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

### `<camera>.reloadCalibration()`

```python Signature theme={null}
<camera>.reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

### `<camera>.setCameraExtrinsics()`

```python Signature theme={null}
<camera>.setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

### `<camera>.setCameraIntrinsics()`

```python Signature theme={null}
<camera>.setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

### `<camera>.setCameraSettings()`

```python Signature theme={null}
<camera>.setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

### `<camera>.stop()`

```python Signature theme={null}
<camera>.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

## robot.left\_arm — arm

Reached as `robot.left_arm`; its methods are `GalaxeaR1ProArm`'s and run on the robot.

Control one 7-DOF arm of the Galaxea R1Pro via ROS 2.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `left_arm.addNamedPose()`

```python Signature theme={null}
left_arm.addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses

### `left_arm.getEndEffectorPose()`

```python Signature theme={null}
left_arm.getEndEffectorPose() -> Pose
```

```text theme={null}
[Deprecated]
```

### `left_arm.getGripperPosition()`

```python Signature theme={null}
left_arm.getGripperPosition() -> float
```

Get the current gripper position.

**Returns:**

Gripper position where `0` is fully closed and `100` is fully
open.

**Raises:**

RuntimeError: If no gripper feedback has been received yet.

### `left_arm.getImage()`

```python Signature theme={null}
left_arm.getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

### `left_arm.getJointAngles()`

```python Signature theme={null}
left_arm.getJointAngles() -> List[float]
```

Get current joint angles for all 7 arm joints.

**Returns:**

Joint angles in radians, ordered `joint1` through `joint7`.

**Raises:**

RuntimeError: If no arm joint state feedback has been received yet.

### `left_arm.getLidarPointCloud()`

```python Signature theme={null}
left_arm.getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

### `left_arm.getNamedPose()`

```python Signature theme={null}
left_arm.getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

### `left_arm.getOrientation()`

```python Signature theme={null}
left_arm.getOrientation() -> Orientation
```

Get the end-effector orientation (delegates to `getPose`).

### `left_arm.getPose()`

```python Signature theme={null}
left_arm.getPose() -> Pose
```

Get the current end-effector pose.

**Returns:**

The end-effector pose in the `torso_link4` frame (+X
forward, +Y left, +Z up). Returns an identity pose
(origin, no rotation) if no feedback has been received
yet.

.. note::
The orientation quaternion represents the rotation of the
`gripper_link` frame relative to `torso_link4`.  The
`gripper_link` axes are fixed to the gripper body:

* **+X** — up the wrist (toward the wrist camera)
* **+Y** — left across the gripper plane
* **+Z** — out through the back of the gripper (opposite the
  opening)

At identity `(0, 0, 0, 1)` the two frames are aligned, so
gripper +Z (out the back) coincides with torso +Z (up),
meaning the gripper opening faces **straight down**.  This
corresponds to the arms hanging relaxed at the robot's sides.

At the **home** pose the orientation is approximately
`(0, -0.71, 0, 0.71)` (-90° pitch about Y), which rotates
the gripper opening to face **forward** (+X in torso\_link4).

The feedback frame is decided by the vendor stack installed on
the unit: legacy stacks report in `torso_link4`, newer Galaxea
(MOCA-generation) stacks report in `base_link`. Feedback whose
`frame_id` is neither empty nor `torso_link4` is re-expressed
into `torso_link4` through a live tf2 lookup before being
returned, so the returned pose is always `torso_link4`
regardless of the unit's stack generation.

**Raises:**

RuntimeError: If feedback reports a frame other than
`torso_link4` and no transform into `torso_link4` is
available on `/tf` to re-express it — returning the raw
numbers would silently mis-place the end effector by the
(posture-dependent) offset between the two frames.

### `left_arm.getPosition()`

```python Signature theme={null}
left_arm.getPosition() -> Position
```

Get the end-effector position (delegates to `getPose`).

### `left_arm.getState()`

```python Signature theme={null}
left_arm.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `left_arm.grasp()`

```python Signature theme={null}
left_arm.grasp() -> None
```

Close the gripper to `closed_position`.

### `left_arm.moveToDeltaPose()`

```python Signature theme={null}
left_arm.moveToDeltaPose(delta_pose: Pose, blocking: bool = True) -> None
```

Offset the robot end effector by the specified delta pose from its current pose

### `left_arm.moveToHome()`

```python Signature theme={null}
left_arm.moveToHome(blocking: bool = True) -> None
```

Move the arm to its predefined home pose.

### `left_arm.moveToNamedPose()`

```python Signature theme={null}
left_arm.moveToNamedPose(pose_name: str, blocking: bool = True) -> None
```

Move the robot to the joint angles of a named pose.

### `left_arm.moveToPose()`

```python Signature theme={null}
left_arm.moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    max_pos_step: float = 0.02,
    max_ori_step_deg: float = 5.0,
    pos_threshold: float = 0.01,
    ori_threshold_deg: float = 3.0,
    step_timeout: float = 0.3,
    timeout: float = 10.0,
) -> None
```

Command the arm to a Cartesian pose via interpolated steps.

Breaks the movement into small steps (linear position interpolation,
spherical orientation interpolation) and waits for the IK solver to
converge at each step before advancing.  This compensates for the
relaxed IK solver's tendency to undershoot on large displacements.

The pose is an absolute transform of `gripper_link` expressed
in the `torso_link4` frame (the pelvis / top of the torso
linkage).

The `torso_link4` coordinate frame follows the convention:

* **+X** = forward (away from the robot's chest)
* **+Y** = left (from the robot's perspective)
* **+Z** = up

The orientation quaternion represents the rotation of the
`gripper_link` frame relative to `torso_link4`.  The
`gripper_link` axes are fixed to the gripper body:

* **+X** — up the wrist (toward the wrist camera)
* **+Y** — left across the gripper plane
* **+Z** — out through the back of the gripper (opposite the
  opening)

At identity `(0, 0, 0, 1)` the two frames are aligned, so
gripper +Z (out the back) coincides with torso +Z (up),
meaning the gripper opening faces **straight down**.  This
corresponds to the arms hanging relaxed at the robot's sides.

At the **home** pose the orientation is approximately
`(0, -0.71, 0, 0.71)` (-90° pitch about Y), which rotates
the gripper opening to face **forward** (+X in torso\_link4).

At rest the left gripper is at roughly
`(0.0, +0.25, -0.43)` and the right at `(0.0, -0.25, -0.43)`.
At home, roughly `(0.42, +0.25, -0.01)` and
`(0.42, -0.25, -0.01)`.

!!! note
Requires the relaxed IK nodes to be running
(`r1_pro_left_arm_relaxed_ik_launch.py` /
`r1_pro_right_arm_relaxed_ik_launch.py`). Without them
the command topic has no subscribers and nothing will happen.
See `r1pro-ik.service` for an auto-start systemd unit.

<ParamField>
  Absolute target pose (position in meters, orientation as a quaternion `(x, y, z, w)`) in the `torso_link4` frame.
</ParamField>

<ParamField>
  This move always blocks until convergence or timeout; passing `blocking=False` logs a warning. Defaults to True.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Maximum position displacement per interpolation step in meters.
</ParamField>

<ParamField>
  Maximum orientation displacement per step in degrees.
</ParamField>

<ParamField>
  Position convergence threshold in meters. The step is considered reached when the EE is within this distance of the target.
</ParamField>

<ParamField>
  Orientation convergence threshold in degrees (geodesic quaternion distance).
</ParamField>

<ParamField>
  Maximum seconds to wait for convergence at each interpolation step before advancing.  If an intermediate step times out, a warning is logged and the next step is attempted (the IK solver may still converge from the nearby pose).
</ParamField>

<ParamField>
  Maximum total seconds for the entire motion.
</ParamField>

**Raises:**

RuntimeError: If the overall `timeout` is exceeded, or if
the final interpolation step does not converge within
`step_timeout` — in either case the arm will be
somewhere along the interpolated path but not at the
requested target. Also raised before any motion if EE
feedback reports a frame other than `torso_link4` that
cannot be re-expressed via tf2 (no `/tf` transform
available): commanding interpolated targets computed
from a mis-framed current pose would move the arm to
unintended positions.

### `left_arm.release()`

```python Signature theme={null}
left_arm.release() -> None
```

Open the gripper to `open_position`.

### `left_arm.removeNamedPose()`

```python Signature theme={null}
left_arm.removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

### `left_arm.setGripperPosition()`

```python Signature theme={null}
left_arm.setGripperPosition(position: float) -> None
```

Set the gripper position.

<ParamField>
  Target position in the range `[0, 100]` where `0` is fully closed and `100` is fully open.
</ParamField>

### `left_arm.setJointAngles()`

```python Signature theme={null}
left_arm.setJointAngles(
    angles: list,
    blocking: bool = False,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    velocities: list = None,
) -> None
```

Publish target joint angles for the arm.

<ParamField>
  Target joint angles in radians. A scalar is broadcast to all 7 joints; a list or `np.ndarray` must have length 7.
</ParamField>

<ParamField>
  Not honored. This method publishes the target and returns immediately; passing `blocking=True` logs a warning. The Galaxea controller handles trajectory timing. Defaults to False.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Optional joint velocities in rad/s. A scalar is broadcast to all 7 joints. !!! note `blocking`, `moving_time`, and `accel_time` are accepted for compatibility with the base `Arm` interface but have no effect. The Galaxea motion controller handles trajectory timing internally.
</ParamField>

### `left_arm.stop()`

```python Signature theme={null}
left_arm.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

### `left_arm.validateGrasp()`

```python Signature theme={null}
left_arm.validateGrasp() -> bool
```

Check whether the end effector is currently holding an object.

## robot.right\_arm — arm

Reached as `robot.right_arm`; its methods are `GalaxeaR1ProArm`'s and run on the robot.

Control one 7-DOF arm of the Galaxea R1Pro via ROS 2.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `right_arm.addNamedPose()`

```python Signature theme={null}
right_arm.addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses

### `right_arm.getEndEffectorPose()`

```python Signature theme={null}
right_arm.getEndEffectorPose() -> Pose
```

```text theme={null}
[Deprecated]
```

### `right_arm.getGripperPosition()`

```python Signature theme={null}
right_arm.getGripperPosition() -> float
```

Get the current gripper position.

**Returns:**

Gripper position where `0` is fully closed and `100` is fully
open.

**Raises:**

RuntimeError: If no gripper feedback has been received yet.

### `right_arm.getImage()`

```python Signature theme={null}
right_arm.getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

### `right_arm.getJointAngles()`

```python Signature theme={null}
right_arm.getJointAngles() -> List[float]
```

Get current joint angles for all 7 arm joints.

**Returns:**

Joint angles in radians, ordered `joint1` through `joint7`.

**Raises:**

RuntimeError: If no arm joint state feedback has been received yet.

### `right_arm.getLidarPointCloud()`

```python Signature theme={null}
right_arm.getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

### `right_arm.getNamedPose()`

```python Signature theme={null}
right_arm.getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

### `right_arm.getOrientation()`

```python Signature theme={null}
right_arm.getOrientation() -> Orientation
```

Get the end-effector orientation (delegates to `getPose`).

### `right_arm.getPose()`

```python Signature theme={null}
right_arm.getPose() -> Pose
```

Get the current end-effector pose.

**Returns:**

The end-effector pose in the `torso_link4` frame (+X
forward, +Y left, +Z up). Returns an identity pose
(origin, no rotation) if no feedback has been received
yet.

.. note::
The orientation quaternion represents the rotation of the
`gripper_link` frame relative to `torso_link4`.  The
`gripper_link` axes are fixed to the gripper body:

* **+X** — up the wrist (toward the wrist camera)
* **+Y** — left across the gripper plane
* **+Z** — out through the back of the gripper (opposite the
  opening)

At identity `(0, 0, 0, 1)` the two frames are aligned, so
gripper +Z (out the back) coincides with torso +Z (up),
meaning the gripper opening faces **straight down**.  This
corresponds to the arms hanging relaxed at the robot's sides.

At the **home** pose the orientation is approximately
`(0, -0.71, 0, 0.71)` (-90° pitch about Y), which rotates
the gripper opening to face **forward** (+X in torso\_link4).

The feedback frame is decided by the vendor stack installed on
the unit: legacy stacks report in `torso_link4`, newer Galaxea
(MOCA-generation) stacks report in `base_link`. Feedback whose
`frame_id` is neither empty nor `torso_link4` is re-expressed
into `torso_link4` through a live tf2 lookup before being
returned, so the returned pose is always `torso_link4`
regardless of the unit's stack generation.

**Raises:**

RuntimeError: If feedback reports a frame other than
`torso_link4` and no transform into `torso_link4` is
available on `/tf` to re-express it — returning the raw
numbers would silently mis-place the end effector by the
(posture-dependent) offset between the two frames.

### `right_arm.getPosition()`

```python Signature theme={null}
right_arm.getPosition() -> Position
```

Get the end-effector position (delegates to `getPose`).

### `right_arm.getState()`

```python Signature theme={null}
right_arm.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `right_arm.grasp()`

```python Signature theme={null}
right_arm.grasp() -> None
```

Close the gripper to `closed_position`.

### `right_arm.moveToDeltaPose()`

```python Signature theme={null}
right_arm.moveToDeltaPose(delta_pose: Pose, blocking: bool = True) -> None
```

Offset the robot end effector by the specified delta pose from its current pose

### `right_arm.moveToHome()`

```python Signature theme={null}
right_arm.moveToHome(blocking: bool = True) -> None
```

Move the arm to its predefined home pose.

### `right_arm.moveToNamedPose()`

```python Signature theme={null}
right_arm.moveToNamedPose(pose_name: str, blocking: bool = True) -> None
```

Move the robot to the joint angles of a named pose.

### `right_arm.moveToPose()`

```python Signature theme={null}
right_arm.moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    max_pos_step: float = 0.02,
    max_ori_step_deg: float = 5.0,
    pos_threshold: float = 0.01,
    ori_threshold_deg: float = 3.0,
    step_timeout: float = 0.3,
    timeout: float = 10.0,
) -> None
```

Command the arm to a Cartesian pose via interpolated steps.

Breaks the movement into small steps (linear position interpolation,
spherical orientation interpolation) and waits for the IK solver to
converge at each step before advancing.  This compensates for the
relaxed IK solver's tendency to undershoot on large displacements.

The pose is an absolute transform of `gripper_link` expressed
in the `torso_link4` frame (the pelvis / top of the torso
linkage).

The `torso_link4` coordinate frame follows the convention:

* **+X** = forward (away from the robot's chest)
* **+Y** = left (from the robot's perspective)
* **+Z** = up

The orientation quaternion represents the rotation of the
`gripper_link` frame relative to `torso_link4`.  The
`gripper_link` axes are fixed to the gripper body:

* **+X** — up the wrist (toward the wrist camera)
* **+Y** — left across the gripper plane
* **+Z** — out through the back of the gripper (opposite the
  opening)

At identity `(0, 0, 0, 1)` the two frames are aligned, so
gripper +Z (out the back) coincides with torso +Z (up),
meaning the gripper opening faces **straight down**.  This
corresponds to the arms hanging relaxed at the robot's sides.

At the **home** pose the orientation is approximately
`(0, -0.71, 0, 0.71)` (-90° pitch about Y), which rotates
the gripper opening to face **forward** (+X in torso\_link4).

At rest the left gripper is at roughly
`(0.0, +0.25, -0.43)` and the right at `(0.0, -0.25, -0.43)`.
At home, roughly `(0.42, +0.25, -0.01)` and
`(0.42, -0.25, -0.01)`.

!!! note
Requires the relaxed IK nodes to be running
(`r1_pro_left_arm_relaxed_ik_launch.py` /
`r1_pro_right_arm_relaxed_ik_launch.py`). Without them
the command topic has no subscribers and nothing will happen.
See `r1pro-ik.service` for an auto-start systemd unit.

<ParamField>
  Absolute target pose (position in meters, orientation as a quaternion `(x, y, z, w)`) in the `torso_link4` frame.
</ParamField>

<ParamField>
  This move always blocks until convergence or timeout; passing `blocking=False` logs a warning. Defaults to True.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Maximum position displacement per interpolation step in meters.
</ParamField>

<ParamField>
  Maximum orientation displacement per step in degrees.
</ParamField>

<ParamField>
  Position convergence threshold in meters. The step is considered reached when the EE is within this distance of the target.
</ParamField>

<ParamField>
  Orientation convergence threshold in degrees (geodesic quaternion distance).
</ParamField>

<ParamField>
  Maximum seconds to wait for convergence at each interpolation step before advancing.  If an intermediate step times out, a warning is logged and the next step is attempted (the IK solver may still converge from the nearby pose).
</ParamField>

<ParamField>
  Maximum total seconds for the entire motion.
</ParamField>

**Raises:**

RuntimeError: If the overall `timeout` is exceeded, or if
the final interpolation step does not converge within
`step_timeout` — in either case the arm will be
somewhere along the interpolated path but not at the
requested target. Also raised before any motion if EE
feedback reports a frame other than `torso_link4` that
cannot be re-expressed via tf2 (no `/tf` transform
available): commanding interpolated targets computed
from a mis-framed current pose would move the arm to
unintended positions.

### `right_arm.release()`

```python Signature theme={null}
right_arm.release() -> None
```

Open the gripper to `open_position`.

### `right_arm.removeNamedPose()`

```python Signature theme={null}
right_arm.removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

### `right_arm.setGripperPosition()`

```python Signature theme={null}
right_arm.setGripperPosition(position: float) -> None
```

Set the gripper position.

<ParamField>
  Target position in the range `[0, 100]` where `0` is fully closed and `100` is fully open.
</ParamField>

### `right_arm.setJointAngles()`

```python Signature theme={null}
right_arm.setJointAngles(
    angles: list,
    blocking: bool = False,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    velocities: list = None,
) -> None
```

Publish target joint angles for the arm.

<ParamField>
  Target joint angles in radians. A scalar is broadcast to all 7 joints; a list or `np.ndarray` must have length 7.
</ParamField>

<ParamField>
  Not honored. This method publishes the target and returns immediately; passing `blocking=True` logs a warning. The Galaxea controller handles trajectory timing. Defaults to False.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Optional joint velocities in rad/s. A scalar is broadcast to all 7 joints. !!! note `blocking`, `moving_time`, and `accel_time` are accepted for compatibility with the base `Arm` interface but have no effect. The Galaxea motion controller handles trajectory timing internally.
</ParamField>

### `right_arm.stop()`

```python Signature theme={null}
right_arm.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

### `right_arm.validateGrasp()`

```python Signature theme={null}
right_arm.validateGrasp() -> bool
```

Check whether the end effector is currently holding an object.

## robot.base — mobile base

Reached as `robot.base`; its methods are `GalaxeaR1ProBase`'s and run on the robot.

Control the Galaxea R1Pro chassis and 4-DOF torso via ROS 2.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `base.getBatteryState()`

```python Signature theme={null}
base.getBatteryState() -> dict
```

Get battery state from the BMS.

**Returns:**

A dict with keys `"voltage"` (V), `"current"` (A), and
`"capacity"` (%). Returns zeros if the BMS topic is
unavailable or no message has been received yet.

### `base.getIMU()`

```python Signature theme={null}
base.getIMU(sensor: str = 'chassis') -> dict
```

Get IMU data from the chassis or torso IMU.

<ParamField>
  `"chassis"` or `"torso"`.
</ParamField>

**Returns:**

A dict with keys `"linear_acceleration"`, `"angular_velocity"`,
and `"orientation"`, each containing `x`, `y`, `z` (and `w` for
orientation) float values. Returns zeros / identity if no
feedback has been received yet.

**Raises:**

ValueError: If *sensor* is not `"chassis"` or `"torso"`.

### `base.getImage()`

```python Signature theme={null}
base.getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

### `base.getJointAngles()`

```python Signature theme={null}
base.getJointAngles() -> List[float]
```

Get current joint angles for the 4-DOF torso linkage.

**Returns:**

Joint angles in radians.

**Raises:**

RuntimeError: If no torso joint state feedback has been received yet.

### `base.getLidarPointCloud()`

```python Signature theme={null}
base.getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

### `base.getOrientation()`

```python Signature theme={null}
base.getOrientation() -> Orientation
```

Get the chassis orientation in world frame.

Orientation is calculated from accumulated LiDAR-IMU odometry, with
the origin at the robot's initial orientation on startup.

**Returns:**

Orientation as a quaternion `(x, y, z, w)`.

**Raises:**

RuntimeError: If no odometry data has been received yet.

### `base.getPosition()`

```python Signature theme={null}
base.getPosition() -> Position
```

Get the chassis position in world frame.

Position is calculated from accumulated LiDAR-IMU odometry, with
the origin at the robot's initial position on startup.

**Returns:**

Position in the world frame (meters).

**Raises:**

RuntimeError: If no odometry data has been received yet.

### `base.getState()`

```python Signature theme={null}
base.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `base.moveByVelocity()`

```python Signature theme={null}
base.moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    duration: Optional[float] = 1.0,
) -> None
```

Command chassis velocity.

The command is republished at 50 Hz until a new command (including
`stop`) is received, or until *duration* seconds have elapsed.

<ParamField>
  Body-frame linear velocity in m/s.
</ParamField>

<ParamField>
  Body-frame angular velocity in rad/s (only the `z` component is used for yaw).
</ParamField>

<ParamField>
  Reference frame for the velocity. Only `"body"` is supported; any other value (including `"world"`) raises.
</ParamField>

<ParamField>
  Maximum time in seconds to hold the velocity command. Pass `None` to republish indefinitely until `stop()`.
</ParamField>

**Raises:**

ValueError: If *frame* is not `"body"`.

### `base.moveToPose()`

```python Signature theme={null}
base.moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    frame: str = 'world',
    pos_threshold: float = 0.05,
    yaw_threshold: float = 0.05,
    max_linear_speed: float = 0.5,
    max_angular_speed: float = 1.0,
    kp_linear: float = 1.0,
    ki_linear: float = 0.1,
    kp_angular: float = 2.0,
    ki_angular: float = 0.2,
    integral_fraction: float = 0.2,
    timeout: float = 30.0,
) -> None
```

Drive the chassis to a target pose using a PI controller.

Commands body-frame velocities via `moveByVelocity` in a closed loop,
reading the current pose from the accumulated LiDAR-IMU odometry.
The controller runs at `_CMD_RATE_HZ` Hz and stops when the position
and yaw errors are both within their respective thresholds, or when
*timeout* is exceeded.

Only the yaw component of the pose's orientation is used — the chassis
cannot control roll or pitch.

!!! note
The world frame origin is the robot's position and heading at
startup.  When *frame* is `"world"`, coordinates are absolute
in that odometry frame.  When *frame* is `"body"`, the target
pose is interpreted as a delta relative to the current pose at
the time of the call.

!!! warning
Large yaw targets (more than roughly 10° from the current
heading) can exhibit hunting — limit-cycle oscillation around
the target yaw — under certain conditions, notably delayed or
stale odometry feedback. The move may then converge slowly or
hit *timeout*. A runtime warning is emitted when the initial
yaw error exceeds 10°. To mitigate, split the rotation into
smaller increments, lower `kp_angular`, or raise *timeout*.

<ParamField>
  Target pose. Only `position.x`, `position.y`, and the yaw component (rotation about Z) of `orientation` are used; `z`, roll, and pitch are ignored. Interpretation depends on *frame*: absolute world-frame coordinates when `"world"`, or a body-frame delta (dx forward, dy left, dyaw) when `"body"`.
</ParamField>

<ParamField>
  This move always blocks until convergence or timeout; passing `blocking=False` logs a warning. Defaults to True.
</ParamField>

<ParamField>
  Reference frame for the target — `"world"` (default) for an absolute pose, or `"body"` for a delta relative to the current pose.
</ParamField>

<ParamField>
  Position convergence threshold in meters.
</ParamField>

<ParamField>
  Yaw convergence threshold in radians.
</ParamField>

<ParamField>
  Maximum linear velocity magnitude in m/s.
</ParamField>

<ParamField>
  Maximum angular velocity magnitude in rad/s.
</ParamField>

<ParamField>
  Proportional gain for XY position error.
</ParamField>

<ParamField>
  Integral gain for XY position error.
</ParamField>

<ParamField>
  Proportional gain for yaw error.
</ParamField>

<ParamField>
  Integral gain for yaw error.
</ParamField>

<ParamField>
  Maximum fraction of max speed that the integral term can contribute (0.0 to 1.0). Limits windup so the integral handles steady-state error without causing overshoot on longer drives.
</ParamField>

<ParamField>
  Maximum time in seconds before the controller gives up.
</ParamField>

**Raises:**

ValueError: If *frame* is not `"world"` or `"body"`.
RuntimeError: If no odometry data is available (localization node
not running), or if *timeout* is exceeded before convergence.

### `base.setBrakeMode()`

```python Signature theme={null}
base.setBrakeMode(engaged: bool) -> None
```

Engage or disengage the chassis brake.

<ParamField>
  `True` to engage the brake, `False` to release.
</ParamField>

### `base.setJointAngles()`

```python Signature theme={null}
base.setJointAngles(
    angles: List[float],
    blocking: bool = False,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    *,
    velocities: List[float] = None,
) -> None
```

Set torso joint angles.

<ParamField>
  Target joint angles in radians. A scalar is broadcast to all 4 joints; a list or `np.ndarray` must have length 4.
</ParamField>

<ParamField>
  Not honored. This method publishes the target and returns immediately; passing `blocking=True` logs a warning. Defaults to False.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Unused -- accepted for interface compatibility.
</ParamField>

<ParamField>
  Optional joint velocities in rad/s. A scalar is broadcast to all 4 joints. !!! note `blocking`, `moving_time`, and `accel_time` are accepted for compatibility with the base `Wheeled` interface but have no effect. The Galaxea motion controller handles trajectory timing internally.
</ParamField>

### `base.stop()`

```python Signature theme={null}
base.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

## Not implemented on this robot

Declared by the interface, raises `NotImplementedError` here: `left_arm.endFreeDrive`, `left_arm.followJointTrajectory`, `left_arm.startFreeDrive`, `right_arm.endFreeDrive`, `right_arm.followJointTrajectory`, `right_arm.startFreeDrive`.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the eleven on-board cameras the R1Pro always ships with.
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()`
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# Composite Rig
Source: https://docs.generalrobotics.dev/v2.3/python-api/rig/rig

The Composite Rig as GRID drives it

The Composite Rig as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `Rig`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<rig-name>")
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

## Configured children

This robot owns no hardware of its own. Every robot, sensor and teleop device in it comes from the `subcomponents` block of its configuration and is reached as `robot.<name>`, keeping the methods of its own page in this reference.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the children this class always ships with (customization point).
* `configHash()` — Hash this component's serialized config subtree.
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# AerialDrone
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/aerialdrone

Abstract base class defining the interface for aerial drone robots

```python theme={null}
from grid_robot_api.base.robot import AerialDrone
```

Abstract base class defining the interface for aerial drone robots.

This class extends the base Robot class with additional methods specific to
aerial robot tasks and control.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the robot in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation of the robot in world coordinates,
or None if orientation is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the robot in the world frame, in meters.

**Returns:**

Optional\[Position]: Current position of the robot in world coordinates,
or None if position is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `land()`

```python Signature theme={null}
land() -> None
```

Command the drone to land.

Initiates controlled landing sequence and safely lands the drone
at the current position.

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Command the drone to move at the given linear and angular velocity.

Tracking accuracy is hardware-dependent — feed back position and
orientation if precise distance/heading control is required.

<ParamField>
  Linear velocity in m/s.
</ParamField>

<ParamField>
  Angular velocity in rad/s.
</ParamField>

<ParamField>
  Reference frame for the velocity command — `"body"` (drone-relative) or `"world"`. Defaults to `"body"`.
</ParamField>

**Raises:**

NotImplementedError: Must be implemented by subclasses.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

### `takeoff()`

```python Signature theme={null}
takeoff() -> None
```

Command the drone to takeoff.

Initiates takeoff sequence and transitions the drone to hover mode
at a safe altitude.

**Raises:**

NotImplementedError: Must be implemented by subclasses


# Arm
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/arm

Abstract base class defining the interface for robotic arms

```python theme={null}
from grid_robot_api.base.robot import Arm
```

Abstract base class defining the interface for robotic arms.

This class extends the base Robot class with additional methods specific to
robotic arm manipulation and control including joint control and gripper operations.

Class attributes:
NUM\_JOINTS: Number of joints (DOF) returned by `getJointAngles`,
or `None` when the joint count is not statically known and
must be resolved from the instance after configuration (e.g.
Isaac Sim arms whose DOF depends on the loaded URDF). Concrete
subclasses with a fixed joint count should override with an
`int`; software mocks with no joint model should set `0`.

## Constructor

```python Signature theme={null}
Arm()
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="home_pose" type="List[float]">
  Joint angles (radians) defining the home position. Must be implemented by subclasses.

  This property is accessed during `Arm.__init__`, so it must not depend on any
  instance state set by the subclass `__init__` — return a pure literal.
</ResponseField>

<ResponseField name="named_poses" type="Dict[str, List[float]]">
  Registered poses as `&#123;name: joint angles in radians&#125;` (a copy).

  Mutating the returned mapping does not change what the arm knows:
  register and remove entries with `addNamedPose` and
  `removeNamedPose`, or assign a whole mapping to replace them all.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addNamedPose()`

```python Signature theme={null}
addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses
(overriding any existing pair).

<ParamField>
  Name of the pose to define
</ParamField>

<ParamField>
  List of joint angles in radians
</ParamField>

**Raises:**

ValueError: If the length of joint\_angles list does match the length of other named
poses

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `endFreeDrive()`

```python Signature theme={null}
endFreeDrive() -> None
```

Exit free-drive mode and return to position control.

The arm is no longer movable by hand and again responds to
position-control commands such as `moveToPose` and
`setJointAngles`.

**Raises:**

NotImplementedError: If the arm does not support free-drive
mode.

### `followJointTrajectory()`

```python Signature theme={null}
followJointTrajectory(
    angles: List[List[float]],
    duration: Union[float, List[float]],
    blocking: bool = True,
) -> None
```

Move the arm through a sequence of joint configurations.

Each waypoint in `angles` is visited in order. The interpretation of
`duration` is uniform across implementations: a scalar is the *total*
trajectory time, split evenly across segments; a list specifies the
duration of each segment, where segment `i` is the move from the
previous pose (or the current arm pose, for `i=0`) to `angles[i]`,
so `len(duration)` must equal `len(angles)`.

Subclasses with a native trajectory-streaming API may blend between
waypoints; subclasses without one typically loop per-segment moves and
briefly stop at each waypoint. Either way the segment timings above
are honored.

<ParamField>
  Sequence of joint configurations (radians) to visit in order. Each inner list must have the same length as the arm's joint count.
</ParamField>

<ParamField>
  Either a single positive float giving the total trajectory time in seconds, or a list of positive floats with the same length as `angles` giving per-segment durations in seconds.
</ParamField>

<ParamField>
  Wait for the trajectory to complete before returning. Defaults to True.
</ParamField>

**Raises:**

NotImplementedError: If the arm does not implement trajectory
following.
ValueError: If `angles` is empty, `duration` is not positive,
or list-form `duration` length does not match `angles`.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getEndEffectorPose()`

```python Signature theme={null}
getEndEffectorPose() -> Pose
```

```text theme={null}
[Deprecated]
Get the current end effector pose (position + orientation) w.r.t. the base frame.
```

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> List[float]
```

Get current joint angles in radians.

**Returns:**

Current joint angles in radians, ordered by joint index

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getNamedPose()`

```python Signature theme={null}
getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

<ParamField>
  Name of the pose to get (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose, or None if the named pose does not exist

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the robot in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation of the robot in world coordinates,
or None if orientation is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getPose()`

```python Signature theme={null}
getPose() -> Pose
```

Get the current end effector pose (position + orientation) w\.r.t. the base frame.

**Returns:**

Current end effector pose with respect to the base frame.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the robot in the world frame, in meters.

**Returns:**

Optional\[Position]: Current position of the robot in world coordinates,
or None if position is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `grasp()`

```python Signature theme={null}
grasp() -> None
```

Close the gripper to grasp an object.

Closes the gripper to securely hold an object. The gripper will
apply appropriate force based on the object detected.

### `moveToDeltaPose()`

```python Signature theme={null}
moveToDeltaPose(delta_pose: Pose, blocking: bool = True) -> None
```

Offset the robot end effector by the specified delta pose from its current pose
(with respect to the base frame).

<ParamField>
  Pose offset to compose with the current pose. The position is added to the current position and the orientation is composed with the current orientation.
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `moveToHome()`

```python Signature theme={null}
moveToHome(blocking: bool = True) -> None
```

Move the arm to its predefined home pose.

Equivalent to `moveToNamedPose("home", blocking=blocking)`. The
`"home"` entry is registered in `named_poses` from the abstract
`home_pose` property during `Arm.__init__`, so every concrete
arm has it. Subclasses may add hardware-specific tuning parameters as
keyword-only arguments after `blocking`.

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `moveToNamedPose()`

```python Signature theme={null}
moveToNamedPose(pose_name: str, blocking: bool = True) -> None
```

Move the robot to the joint angles of a named pose.

Subclasses may add hardware-specific tuning parameters (timing,
force thresholds, etc.) as keyword-only arguments after
`blocking`.

<ParamField>
  Name of the pose to move to (case-insensitive).
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

**Raises:**

ValueError: If pose\_name is not found in the named poses
dictionary.

### `moveToPose()`

```python Signature theme={null}
moveToPose(pose: Pose, blocking: bool = True) -> None
```

Move the robot end effector to a specified pose with respect to the base frame.

Subclasses may add hardware-specific tuning parameters (timing, force
thresholds, etc.) as keyword-only arguments after `blocking`.

<ParamField>
  Target pose (position in meters, orientation as a unit quaternion). The pose is interpreted in the robot's base frame.
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `release()`

```python Signature theme={null}
release() -> None
```

Open the gripper to release an object.

Opens the gripper to release any held object. The gripper will
return to its fully open position.

### `removeNamedPose()`

```python Signature theme={null}
removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

<ParamField>
  Name of the pose to remove (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose that was removed, or None if the named
pose did not exist

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(angles: List[float], blocking: bool = True) -> None
```

Set joint angles in radians.

Commands the arm to move joints to the specified target angles.

Subclasses may add hardware-specific tuning parameters (timing,
force thresholds, high-frequency streaming, etc.) as keyword-only
arguments after `blocking`.

<ParamField>
  Target joint angles in radians, ordered by joint index. Length must match the number of joints on the arm.
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `startFreeDrive()`

```python Signature theme={null}
startFreeDrive() -> None
```

Enable free-drive (hand-guided) mode.

The arm becomes compliant and can be moved by hand while supporting
its own weight. Position-control commands such as
`moveToPose` and `setJointAngles` are not active in
this mode — call `endFreeDrive` to return to position
control.

**Raises:**

NotImplementedError: If the arm does not support free-drive
mode.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

### `validateGrasp()`

```python Signature theme={null}
validateGrasp() -> bool
```

Check whether the end effector is currently holding an object.

Thin wrapper that delegates to the configured end effector's
`EndEffector.getGripDetected`. Subclasses generally do not
need to override this.

**Returns:**

True if the end effector reports an object in its grip, False
otherwise.

**Raises:**

RuntimeError: If no end effector is configured on this arm.
NotImplementedError: If the configured end effector does not
support grip detection.


# Component
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/component

Base class for every composable robot part

```python theme={null}
from grid_robot_api.base.robot import Component
```

Base class for every composable robot part.

A component owns a mapping of named child components
(`subcomponents`) and can be attached to a parent component under a
name. The tree is recursive: a robot holds arms and sensors, an arm
holds an end effector and a wrist camera, and so on.

`subcomponents` is backed by a lazily created instance dict, so
subclasses that do not call `super().__init__()` (several sensor and
end-effector drivers predate this class) still get a working, empty
mapping on first access.

**Lifecycle.** Construction assembles the tree and acquires no
hardware: `__init__` records settings, and a parent constructs (or
receives) its children. Bring-up and teardown are recursive walks
owned by the base class — `start` (self before children,
root-to-leaf) and `stop` / `shutdown` (children first,
leaf-to-root) — and each class contributes only the protected local
hooks `_start_self`, `_provision_children`,
`_stop_self`, and `_shutdown_self`. Subclasses never
re-implement the recursion.
`from_config` joins the same template for construction: the
base classmethod walks the config tree and each class customizes only
its own construction, making `serialize` and
`from_config` a symmetric pair.

**Builtin children.** A class that always ships with certain children
declares them as data with `builtin_subcomponents`, in the same
config-schema shape an authored `subcomponents` entry uses. The base
class materializes that declaration for every construction path —
`from_config` and a direct constructor call alike — so a
hand-constructed robot has the same tree as a configured one. An
authored entry with the same name overlays the declaration (its
`args` merge over the builtin ones, `enabled: false` drops the
child) instead of colliding with it.

Root-to-leaf bring-up is what lets a parent hand runtime resources it
owns (an RTDE connection, a ROS node) to its children: the parent's
hooks have already run and provisioned them by the time a child's
hook runs, so no child ever reaches up — the tree keeps no parent
references.

`make_robot`/`make_sensor` start the tree they build, so a
configured robot is live when the factory returns. Components are
also context managers: `with make_robot(...) as robot:` starts the
tree on entry (a no-op when the factory already did) and shuts it
down deterministically on exit — never rely on garbage collection
for hardware teardown.

**Started-guard.** Because construction acquires nothing, calling a
driver method on a component that was never started would fail deep
inside the driver on a `None` handle. The base class removes that
failure mode automatically: at class-definition time every public
method a subclass defines is wrapped in a guard that raises
`ComponentNotStartedError` — naming the class, the method, and the
fix — when the component has never been brought up and is not inside
its own lifecycle hooks, and a distinct after-shutdown variant when
it has been shut down. Driver authors write no started-checks.

The guard tracks whether this component was ever brought up, not
whether it is currently armed: `stop` halts motion and re-arms
the tree for a later `start`, but leaves resources live, so a
stopped component stays fully callable — reading telemetry after a
soft e-stop is exactly when it matters most. Only `shutdown`
closes the surface.

The guard arms only for classes that participate in the lifecycle,
meaning some class in the MRO below this one implements
`_start_self`; a subclass that connects eagerly in `__init__` and
implements no bring-up hook is untouched. The lifecycle verbs
(`start`, `stop`, `shutdown`) and the structural/metadata
surface (`serialize`, `addSubcomponent`, `addSensor`) are never
gated, nor is anything defined on `Component` itself, nor properties
and `_`-prefixed methods. A method that must work on a merely
constructed component — a fixed kinematic offset, a metadata getter,
anything a parent calls on a not-yet-started child from
`_provision_children` — opts out with the
`available_before_start` decorator. Wrapping preserves the original
signature and docstring, so introspection sees the definition as
written.

## Constructor

```python Signature theme={null}
Component()
```

Construct a bare component that owns nothing.

Present so every component has a Python-level constructor the base
class can hook for builtin-subcomponent materialization; it records
no settings and acquires no hardware. Subclasses need not call it.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# ComponentIdentity
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/componentidentity

Hardware identity of one component, as a plain JSON-serializable dict

```python theme={null}
from grid_robot_api.base.robot import ComponentIdentity
```

Hardware identity of one component, as a plain JSON-serializable dict.

The manufacturer-assigned identity of the physical unit behind a
component: burned into the device, it survives IP changes, renames,
and re-imaging, so it — not the user-chosen name or the configured
address — is what says *which* robot or sensor this is.

**Every field is optional and a missing field means "unknown", never
"different".** A key is present only when it was actually read from
the device (or is knowledge the class holds about itself); drivers
with no hardware identifier produce an empty mapping, and so does a
device that is unreachable. Consumers de-duplicating or verifying
hardware must therefore treat absence as unknown: two components
that both report no serial are not thereby the same unit, and are
not thereby different ones either.

**The field set is closed.** These four fields are all a component
can report: a driver hook that returns any other key has it dropped
with a warning, so the mapping always matches the config envelope's
`identity` block (`ComponentIdentityConfig`, which rejects
unknown keys). Extending the set means adding the field here and
there in one change.

Read it with `Component.getIdentity`; it also appears as the
`identity` block of `Component.serialize`.


# ControlState
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/controlstate

A non-consuming snapshot of a robot's control-loop state, motor order

```python theme={null}
from grid_robot_api.base.robot import ControlState
```

A non-consuming snapshot of a robot's control-loop state, motor order.

Joint arrays are in the robot's motor index order (the order of the names
the robot passes as `robot_joint_names`) and are always present. The
floating-base fields are optional so a fixed-base robot (an arm, a
bolted-down manipulator) can implement this interface without fabricating
an IMU reading; a consumer that needs one raises a descriptive error when
it is absent rather than reading a placeholder.

## Fields

<ResponseField name="joint_pos">
  Motor positions (rad), motor order.
</ResponseField>

<ResponseField name="joint_vel">
  Motor velocities (rad/s), motor order.
</ResponseField>

<ResponseField name="base_ang_vel">
  Base angular velocity (rad/s), length 3; `None` on a robot with no floating base or no IMU.
</ResponseField>

<ResponseField name="quat_wxyz">
  Base orientation quaternion (w, x, y, z), length 4, mapping the base frame to a Z-up world frame — the robot driver owns any conversion from its sensor's native convention; `None` on a robot with no floating base or no IMU.
</ResponseField>

<ResponseField name="base_lin_vel">
  Base linear velocity (m/s), length 3; `None` unless the robot runs a state estimator that provides one.
</ResponseField>


# EndEffector
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/endeffector

Abstract base class for all end effectors

```python theme={null}
from grid_robot_api.base.robot import EndEffector
```

Abstract base class for all end effectors.

End effectors are devices attached to robotic arms for grasping
and manipulating objects. All end effector implementations should
inherit from this class.

**Bring-up contract.** One uniform handoff replaces the per-family
bring-up protocols: the attaching arm's `_start_self` hook runs
first (root-to-leaf ordering), creates the resources it owns, and
calls `_provision` on this end effector with them; the start walk
then runs this end effector's `_start_self`, which reads what it
needs with `_provisioned_resource` and connects/activates itself.
Resource names are defined by the attaching arm and documented on it
(the UR5e provides `robot_ip`, `rtde_c`, `rtde_r`, and
`rtde_i`); each end effector documents which names it consumes.
Nothing reaches back up the tree, and an arm needs no knowledge of
which end-effector family it is holding.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `from_choices()`

```python Signature theme={null}
from_choices(
    config: Any,
    choices: Mapping[str, EndEffectorFactory],
    context: str = 'end_effector',
) -> Optional[EndEffector]
```

Build the end effector named by a nested `end_effector` config arg.

End effectors are not in the robot/sensor registries: each arm
offers its own whitelist of compatible tools, so an arm's
construction hook resolves its `end_effector` arg through this
helper. Distinct from `Component.from_config`, which
constructs a registered component and its declared subtree.

<ParamField>
  The nested `end_effector` config value: a mapping with a `type` and optional `args`, `None`, or `&#123;"type": "none"&#125;` for no end effector.
</ParamField>

<ParamField>
  Mapping of accepted type name to the factory (normally the class) that builds it.
</ParamField>

<ParamField>
  Label for error messages, naming the owning arm's config field (e.g. `"UR5e end_effector"`).
</ParamField>

**Returns:**

The constructed end effector, or `None` when the config
selects no end effector. It is constructed only — the
attaching arm's `start` walk brings it online.

**Raises:**

TypeError: If the config, its `type`, or its `args` has
the wrong shape.
ValueError: If `type` is not one of `choices`.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getGripDetected()`

```python Signature theme={null}
getGripDetected() -> bool
```

Detect whether the end effector is currently holding an object.

**Returns:**

bool: True if an object is detected in the grip.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getPosition()`

```python Signature theme={null}
getPosition(normalized: bool = True) -> float
```

Get the current end-effector position.

Subclasses with a continuous position sensor (e.g. parallel-jaw
grippers) must override this. Subclasses without a meaningful
continuous position (e.g. binary suction valves) leave the
default, which raises.

<ParamField>
  If True (default), return the position normalized to \[0.0, 1.0] on a uniform scale across all end effectors: 0.0 is fully open/disengaged, 1.0 is fully closed/engaged, with linear interpolation between those endpoints. If False, return the raw hardware position; the units and range are implementation-specific (see the subclass docstring).
</ParamField>

**Returns:**

```text theme={null}
float: Current position. Normalized values are clamped to
[0.0, 1.0]; raw values pass through cast to ``float``.
```

**Raises:**

NotImplementedError: If the end effector does not expose a
continuous position.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getToolCenterWrtArm()`

```python Signature theme={null}
getToolCenterWrtArm() -> Pose
```

Get the tool center point offset relative to the arm flange.

**Returns:**

Pose: The TCP pose with respect to the arm flange.

### `grasp()`

```python Signature theme={null}
grasp() -> None
```

Close/engage the end effector to grasp an object.

### `release()`

```python Signature theme={null}
release() -> None
```

Open/disengage the end effector to release an object.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Hand
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/hand

Abstract base class defining the interface for hands

```python theme={null}
from grid_robot_api.base.robot import Hand
```

Abstract base class defining the interface for hands.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `from_choices()`

```python Signature theme={null}
from_choices(
    config: Any,
    choices: Mapping[str, EndEffectorFactory],
    context: str = 'end_effector',
) -> Optional[EndEffector]
```

Build the end effector named by a nested `end_effector` config arg.

End effectors are not in the robot/sensor registries: each arm
offers its own whitelist of compatible tools, so an arm's
construction hook resolves its `end_effector` arg through this
helper. Distinct from `Component.from_config`, which
constructs a registered component and its declared subtree.

<ParamField>
  The nested `end_effector` config value: a mapping with a `type` and optional `args`, `None`, or `&#123;"type": "none"&#125;` for no end effector.
</ParamField>

<ParamField>
  Mapping of accepted type name to the factory (normally the class) that builds it.
</ParamField>

<ParamField>
  Label for error messages, naming the owning arm's config field (e.g. `"UR5e end_effector"`).
</ParamField>

**Returns:**

The constructed end effector, or `None` when the config
selects no end effector. It is constructed only — the
attaching arm's `start` walk brings it online.

**Raises:**

TypeError: If the config, its `type`, or its `args` has
the wrong shape.
ValueError: If `type` is not one of `choices`.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getGripDetected()`

```python Signature theme={null}
getGripDetected() -> bool
```

Detect whether the end effector is currently holding an object.

**Returns:**

bool: True if an object is detected in the grip.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getPosition()`

```python Signature theme={null}
getPosition(normalized: bool = True) -> float
```

Get the current end-effector position.

Subclasses with a continuous position sensor (e.g. parallel-jaw
grippers) must override this. Subclasses without a meaningful
continuous position (e.g. binary suction valves) leave the
default, which raises.

<ParamField>
  If True (default), return the position normalized to \[0.0, 1.0] on a uniform scale across all end effectors: 0.0 is fully open/disengaged, 1.0 is fully closed/engaged, with linear interpolation between those endpoints. If False, return the raw hardware position; the units and range are implementation-specific (see the subclass docstring).
</ParamField>

**Returns:**

```text theme={null}
float: Current position. Normalized values are clamped to
[0.0, 1.0]; raw values pass through cast to ``float``.
```

**Raises:**

NotImplementedError: If the end effector does not expose a
continuous position.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getToolCenterWrtArm()`

```python Signature theme={null}
getToolCenterWrtArm() -> Pose
```

Get the tool center point offset relative to the arm flange.

**Returns:**

Pose: The TCP pose with respect to the arm flange.

### `grasp()`

```python Signature theme={null}
grasp() -> None
```

Close/engage the end effector to grasp an object.

### `release()`

```python Signature theme={null}
release() -> None
```

Open/disengage the end effector to release an object.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Humanoid
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/humanoid

Abstract base class defining the interface for humanoid robots

```python theme={null}
from grid_robot_api.base.robot import Humanoid
```

Abstract base class defining the interface for humanoid robots.

This class extends the base Robot class with additional methods specific to
humanoid locomotion and control.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> List[float]
```

Get current joint angles in radians.

**Returns:**

Current joint angles in radians, ordered by joint index.

**Raises:**

NotImplementedError: Must be implemented by subclasses.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the robot in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation of the robot in world coordinates,
or None if orientation is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the robot in the world frame, in meters.

**Returns:**

Optional\[Position]: Current position of the robot in world coordinates,
or None if position is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Command the robot to walk at the given linear and angular velocity.

Tracking accuracy is hardware-dependent — feed back position and
orientation if precise distance/heading control is required.

<ParamField>
  Linear velocity in m/s.
</ParamField>

<ParamField>
  Angular velocity in rad/s.
</ParamField>

<ParamField>
  Reference frame for the velocity command — `"body"` (robot-relative) or `"world"`. Defaults to `"body"`.
</ParamField>

**Raises:**

NotImplementedError: Must be implemented by subclasses.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setDefaultJointAngles()`

```python Signature theme={null}
setDefaultJointAngles(joint_pos: list) -> None
```

Set the default joint position for the robot.

<ParamField>
  Value of the joint position.
</ParamField>

### `setDefaultJointVelocities()`

```python Signature theme={null}
setDefaultJointVelocities(joint_vel: list) -> None
```

Set the default joint velocity for the robot.

<ParamField>
  Value of the joint velocity.
</ParamField>

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = True,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
) -> None
```

Set joint angles in radians.

Commands the humanoid to move joints to the specified target angles.
Can be blocking or non-blocking depending on the blocking parameter.

<ParamField>
  List of target joint angles in radians.
</ParamField>

<ParamField>
  Wait for movement to complete.
</ParamField>

<ParamField>
  Time to complete the movement in seconds.
</ParamField>

<ParamField>
  Time to accelerate/decelerate in seconds.
</ParamField>

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# LowLevelControllable
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/lowlevelcontrollable

Interface for robots controllable by direct low-level joint commands

```python theme={null}
from grid_robot_api.base.robot import LowLevelControllable
```

Interface for robots controllable by direct low-level joint commands.

## Methods

### `commandJointsPD()`

```python Signature theme={null}
commandJointsPD(
    joint_indices: np.ndarray,
    q: np.ndarray,
    kp: np.ndarray,
    kd: np.ndarray,
) -> None
```

Command a subset of joints to position targets with per-joint gains.

Deliberately **not** `setJointAngles`. The two look similar and are
not interchangeable, so per this package's "shared names mean shared
behavior" rule they carry different names:

* **Non-blocking.** `setJointAngles` may block — its base signature
  takes `blocking` / `moving_time`, and some implementations sleep
  for a control period. This is called every tick from a fixed-rate
  control thread that owns its own pacing, so it must return at once.
* **A subset, not the whole robot.** `setJointAngles` drives every
  joint and rejects a partial list. This drives exactly
  `joint_indices`, which is how a lower-body policy runs while a
  separate controller owns the arms.
* **Caller-supplied gains.** `setJointAngles` applies the robot's own
  stiffness. Here the gains arrive per call, because a policy's gains
  are part of its deployment contract and travel with its artifact.
  Driving at the robot's gains instead is a real failure and a quiet
  one — it shows up as a degraded gait, not an error.

Every joint NOT in `joint_indices` is left un-actuated per the robot's
own convention (zero gains, or the vendor's position/velocity-stop
sentinels), so a separate controller may own it. The four arrays are
positionally aligned (one entry per driven joint).

<ParamField>
  Motor indices to drive.
</ParamField>

<ParamField>
  Target joint positions (rad), aligned to `joint_indices`.
</ParamField>

<ParamField>
  Per-joint position gains, aligned to `joint_indices`.
</ParamField>

<ParamField>
  Per-joint damping gains, aligned to `joint_indices`.
</ParamField>

### `getControlState()`

```python Signature theme={null}
getControlState() -> ControlState
```

Return the latest control-loop state without consuming it.

Non-consuming and non-blocking: repeated calls return the most recent
snapshot, suitable for a fixed-rate control loop. Distinct from the
base `getState` registry
(a keyed dict for slow proprioception reads) — this is the fast,
fixed-shape accessor for closed-loop control.

**Returns:**

The latest control-loop state.

### `setDamping()`

```python Signature theme={null}
setDamping(kd: float = 8.0) -> None
```

Command a damping brake: zero position gain, the given damping gain.

<ParamField>
  Damping gain applied to every motor.
</ParamField>

### `setZeroTorque()`

```python Signature theme={null}
setZeroTorque() -> None
```

Command zero torque to all motors.


# MobileManipulator
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/mobilemanipulator

Abstract base class for mobile manipulator robots (mobile base + arm(s))

```python theme={null}
from grid_robot_api.base.robot import MobileManipulator
```

Abstract base class for mobile manipulator robots (mobile base + arm(s)).

A mobile manipulator combines a mobile base (wheeled, legged, etc.) with
one or more arms and other joint groups. Subclasses populate
`self.subcomponents` during `__init__` with a mapping of joint-group
name to the controller for that group (e.g. `"left_arm"` -> arm,
`"base"` -> mobile base). Sensors attached via `addSensor` share the
same `subcomponents` mapping; the joint accessors below operate on
the joint groups only (every subcomponent that is not a sensor or end
effector).

The base class provides `getJointAngles` / `setJointAngles` that
dispatch to joint groups by name. When called without a *group*
argument they operate on all joint groups via a dict; when called
with a *group* they operate on a single joint group and use the same
`list[float]` signature as `Arm`, `Humanoid`, etc.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles(
    group: Optional[str] = None,
) -> Union[Dict[str, List[float]], List[float]]
```

Get joint angles.

<ParamField>
  If provided, return joint angles for that subcomponent only (as a flat `list[float]`). If `None` (default), return a dict mapping every subcomponent name to its joint angles.
</ParamField>

**Returns:**

`list[float]` when *group* is given, otherwise
`dict[str, list[float]]`.

**Raises:**

KeyError: If *group* is not a known subcomponent.

````python theme={null}
```python
# All groups at once
all_joints = robot.getJointAngles()
# -> {"left_arm": [...], "right_arm": [...], "base": [...]}

# Single group (same return type as Arm.getJointAngles())
left_joints = robot.getJointAngles("left_arm")
# -> [0.0, 0.1, ...]
````

````

### `getLidarPointCloud()`

```python Signature
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
````

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the robot in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation of the robot in world coordinates,
or None if orientation is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the robot in the world frame, in meters.

**Returns:**

Optional\[Position]: Current position of the robot in world coordinates,
or None if position is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Command base velocity.

<ParamField>
  Linear velocity of the base.
</ParamField>

<ParamField>
  Angular velocity of the base.
</ParamField>

<ParamField>
  Reference frame for the velocity command.
</ParamField>

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: Union[Dict[str, list], list],
    velocities: Union[Optional[Dict[str, list]], list] = None,
    group: Optional[str] = None,
) -> None
```

Set joint angles.

Can be called in two ways:

* **Multi-group** (default): pass a dict mapping group names to
  angle lists.  `velocities` may also be a dict.
* **Single-group**: pass a flat `list` of angles together with
  `group="&lt;name>"`.  `velocities` may also be a flat list.
  This matches the `Arm` / `Humanoid` / `Quadruped`
  signature.

<ParamField>
  Target joint angles in radians — a dict for multi-group or a list for single-group.
</ParamField>

<ParamField>
  Optional joint velocities. In single-group mode, a list or scalar. In multi-group mode, a dict mapping group names to velocity lists/scalars (partial dicts OK — omitted groups get no velocity), a single scalar (broadcast to every group being commanded), or `None`.
</ParamField>

<ParamField>
  Subcomponent name.  Required when *angles* is a list.
</ParamField>

**Raises:**

KeyError: If a group name is not a known subcomponent.
TypeError: If *angles* is a list but *group* is not provided,
or if *velocities* is a list in multi-group mode.

````python theme={null}
```python
# Multi-group
robot.setJointAngles({"left_arm": angles_l, "base": angles_b})

# Multi-group with per-group velocities
robot.setJointAngles(
    {"left_arm": angles_l, "right_arm": angles_r},
    velocities={"left_arm": 0.5},  # only left_arm; right_arm uses default
)

# Per-group velocities as a list
robot.setJointAngles(
    {"left_arm": angles_l, "right_arm": angles_r},
    velocities={"left_arm": [0.5] * 7, "right_arm": [0.1] * 7},
)

# Multi-group with a single velocity for all groups/joints
robot.setJointAngles(
    {"left_arm": angles_l, "base": angles_b},
    velocities=0.5,
)

# Single-group (same list signature as Arm, Humanoid, etc.)
robot.setJointAngles(angles_l, group="left_arm")
````

````

### `setup_shutdown_handlers()`

```python Signature
setup_shutdown_handlers() -> None
````

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Robot interface
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/overview

The contract every GRID robot implements

The contract every GRID robot implements — the method names and signatures a driver must provide, whether the robot is physical or simulated. A method listed here is a promise the interface makes; what a specific robot actually accepts, and which of these it leaves unimplemented, is on that robot's own page under **Robots**.

## Install

```bash theme={null}
# Preinstalled in every GRID session workspace and in the Python environment the
# GRID CLI prepares when you run a program with `skill run`. Nothing to install.
```

## Quickstart

```python theme={null}
from grid_nexus_client import make_robot

# make_robot() returns a RemoteRobot whose attributes resolve to the
# methods below, for whichever of these interfaces your robot implements.
robot = make_robot("<robot-name>")
robot.standUp()             # Quadruped
image = robot.getImage("front")   # Robot

# Ask a live robot what it actually exposes:
print(robot.session.methods_info())

# Subcomponents — sensors, arms, end effectors — nest the same way:
robot.left_arm.wrist_cam.getImage()
```

You reach these methods through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot) in **grid-nexus-client**. The simulated implementations are **AirGen robots** and **Isaac robots**; values passed and returned are **grid-types**.

## Classes

* [`Robot`](/v2.3/python-api/robot-interface/robot)
* [`Component`](/v2.3/python-api/robot-interface/component)
* [`ComponentIdentity`](/v2.3/python-api/robot-interface/componentidentity)
* [`Arm`](/v2.3/python-api/robot-interface/arm)
* [`EndEffector`](/v2.3/python-api/robot-interface/endeffector)
* [`Hand`](/v2.3/python-api/robot-interface/hand)
* [`ParallelJawGripper`](/v2.3/python-api/robot-interface/paralleljawgripper)
* [`Quadruped`](/v2.3/python-api/robot-interface/quadruped)
* [`Humanoid`](/v2.3/python-api/robot-interface/humanoid)
* [`AerialDrone`](/v2.3/python-api/robot-interface/aerialdrone)
* [`Wheeled`](/v2.3/python-api/robot-interface/wheeled)
* [`MobileManipulator`](/v2.3/python-api/robot-interface/mobilemanipulator)
* [`LowLevelControllable`](/v2.3/python-api/robot-interface/lowlevelcontrollable)
* [`ControlState`](/v2.3/python-api/robot-interface/controlstate)


# ParallelJawGripper
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/paralleljawgripper

Base class for parallel-jaw grippers driven by their owner's interfaces

```python theme={null}
from grid_robot_api.base.robot import ParallelJawGripper
```

Base class for parallel-jaw grippers driven by their owner's interfaces.

Bring-up follows the uniform `EndEffector` contract: the attaching
robot provisions its interfaces, then this gripper's `_start_self`
hook connects the device; each driver documents whether bring-up moves the
jaws. The owner is whichever component
holds the gripper — an `Arm`
for a wrist-mounted tool, or the robot itself where there is no arm
component to hang it from.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `close()`

```python Signature theme={null}
close() -> None
```

Move the gripper to its narrowest position, with maximum speed and force (blocking).

.. deprecated::
Use `grasp` instead.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `from_choices()`

```python Signature theme={null}
from_choices(
    config: Any,
    choices: Mapping[str, EndEffectorFactory],
    context: str = 'end_effector',
) -> Optional[EndEffector]
```

Build the end effector named by a nested `end_effector` config arg.

End effectors are not in the robot/sensor registries: each arm
offers its own whitelist of compatible tools, so an arm's
construction hook resolves its `end_effector` arg through this
helper. Distinct from `Component.from_config`, which
constructs a registered component and its declared subtree.

<ParamField>
  The nested `end_effector` config value: a mapping with a `type` and optional `args`, `None`, or `&#123;"type": "none"&#125;` for no end effector.
</ParamField>

<ParamField>
  Mapping of accepted type name to the factory (normally the class) that builds it.
</ParamField>

<ParamField>
  Label for error messages, naming the owning arm's config field (e.g. `"UR5e end_effector"`).
</ParamField>

**Returns:**

The constructed end effector, or `None` when the config
selects no end effector. It is constructed only — the
attaching arm's `start` walk brings it online.

**Raises:**

TypeError: If the config, its `type`, or its `args` has
the wrong shape.
ValueError: If `type` is not one of `choices`.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getGripDetected()`

```python Signature theme={null}
getGripDetected() -> bool
```

Detect whether the end effector is currently holding an object.

**Returns:**

bool: True if an object is detected in the grip.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getPosition()`

```python Signature theme={null}
getPosition(normalized: bool = True) -> float
```

Get the current end-effector position.

Subclasses with a continuous position sensor (e.g. parallel-jaw
grippers) must override this. Subclasses without a meaningful
continuous position (e.g. binary suction valves) leave the
default, which raises.

<ParamField>
  If True (default), return the position normalized to \[0.0, 1.0] on a uniform scale across all end effectors: 0.0 is fully open/disengaged, 1.0 is fully closed/engaged, with linear interpolation between those endpoints. If False, return the raw hardware position; the units and range are implementation-specific (see the subclass docstring).
</ParamField>

**Returns:**

```text theme={null}
float: Current position. Normalized values are clamped to
[0.0, 1.0]; raw values pass through cast to ``float``.
```

**Raises:**

NotImplementedError: If the end effector does not expose a
continuous position.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getToolCenterWrtArm()`

```python Signature theme={null}
getToolCenterWrtArm() -> Pose
```

Get the tool center point offset relative to the gripper's mount.

Delegates to `get_tool_center_wrt_arm`.

**Returns:**

The tool-center pose in the mount frame.

### `get_tool_center_wrt_arm()`

```python Signature theme={null}
get_tool_center_wrt_arm() -> Pose
```

Get the Pose of the tool center relative to the gripper's mount.

The mount is whatever the gripper is attached to — an arm's tool
flange, or a humanoid's wrist.

**Returns:**

The tool-center pose in the mount frame.

### `grasp()`

```python Signature theme={null}
grasp() -> None
```

Close/engage the end effector to grasp an object.

### `open()`

```python Signature theme={null}
open() -> None
```

Move the gripper to its widest position, with maximum speed and force (blocking).

.. deprecated::
Use `release` instead.

### `release()`

```python Signature theme={null}
release() -> None
```

Open/disengage the end effector to release an object.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Quadruped
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/quadruped

Abstract base class defining the interface for quadruped robots

```python theme={null}
from grid_robot_api.base.robot import Quadruped
```

Abstract base class defining the interface for quadruped robots.

This class extends the base Robot class with additional methods specific to
quadruped locomotion and control.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> List[float]
```

Get current joint angles in radians.

**Returns:**

Current joint angles in radians, ordered by joint index.

**Raises:**

NotImplementedError: Must be implemented by subclasses.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the robot in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation of the robot in world coordinates,
or None if orientation is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the robot in the world frame, in meters.

**Returns:**

Optional\[Position]: Current position of the robot in world coordinates,
or None if position is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `lieDown()`

```python Signature theme={null}
lieDown() -> None
```

Command the robot to lie down.

Transitions the robot to a lying position where it can be safely
powered off. This is typically the lowest power consumption pose.

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Command the robot to walk at the given linear and angular velocity.

Tracking accuracy is hardware-dependent — feed back position and
orientation if precise distance/heading control is required.

<ParamField>
  Linear velocity in m/s.
</ParamField>

<ParamField>
  Angular velocity in rad/s.
</ParamField>

<ParamField>
  Reference frame for the velocity command — `"body"` (robot-relative) or `"world"`. Defaults to `"body"`.
</ParamField>

**Raises:**

NotImplementedError: Must be implemented by subclasses.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setDefaultJointAngles()`

```python Signature theme={null}
setDefaultJointAngles(joint_pos: list) -> None
```

Set the default joint position for the robot.

<ParamField>
  Value of the joint position.
</ParamField>

### `setDefaultJointVelocities()`

```python Signature theme={null}
setDefaultJointVelocities(joint_vel: list) -> None
```

Set the default joint velocity for the robot.

<ParamField>
  Value of the joint velocity.
</ParamField>

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = True,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
) -> None
```

Set joint angles in radians.

Commands the robot to move joints to the specified target angles.
Can be blocking or non-blocking depending on the blocking parameter.

<ParamField>
  List of target joint angles in radians.
</ParamField>

<ParamField>
  Wait for movement to complete.
</ParamField>

<ParamField>
  Time to complete the movement in seconds.
</ParamField>

<ParamField>
  Time to accelerate/decelerate in seconds.
</ParamField>

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `standUp()`

```python Signature theme={null}
standUp() -> None
```

Command the robot to stand up.

Transitions the robot from a lying or sitting position to a standing
position. The robot should be stable and ready for locomotion after
this command completes.

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Robot
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/robot

Abstract base class for all robot implementations

```python theme={null}
from grid_robot_api.base.robot import Robot
```

Abstract base class for all robot implementations.

Provides core functionality including sensor management, safety monitoring,
and automatic shutdown. All robot implementations should inherit from this
class and implement the abstract methods.

Every attached part — sensors, end effector, joint groups — lives in
the inherited `subcomponents` mapping; `sensors` and
`end_effector` are derived read-only views over it.

## Constructor

```python Signature theme={null}
Robot()
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the robot in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation of the robot in world coordinates,
or None if orientation is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the robot in the world frame, in meters.

**Returns:**

Optional\[Position]: Current position of the robot in world coordinates,
or None if position is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Wheeled
Source: https://docs.generalrobotics.dev/v2.3/python-api/robot-interface/wheeled

Abstract base class defining the interface for wheeled robots

```python theme={null}
from grid_robot_api.base.robot import Wheeled
```

Abstract base class defining the interface for wheeled robots.

This class extends the base Robot class with additional methods specific to
wheeled locomotion and control.

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the robot in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation of the robot in world coordinates,
or None if orientation is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the robot in the world frame, in meters.

**Returns:**

Optional\[Position]: Current position of the robot in world coordinates,
or None if position is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Command the base to move at the given linear and angular velocity.

Tracking accuracy is hardware-dependent — feed back position and
orientation if precise distance/heading control is required.

<ParamField>
  Linear velocity in m/s.
</ParamField>

<ParamField>
  Angular velocity in rad/s.
</ParamField>

<ParamField>
  Reference frame for the velocity command — `"body"` (robot-relative) or `"world"`. Defaults to `"body"`.
</ParamField>

**Raises:**

NotImplementedError: Must be implemented by subclasses.

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.


# Universal Robots UR3e Arm
Source: https://docs.generalrobotics.dev/v2.3/python-api/ur3e/ur3e

The Universal Robots UR3e Arm as GRID drives it

The Universal Robots UR3e Arm as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `UR3e`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<ur3e-name>")
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `addNamedPose()`

```python Signature theme={null}
addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses
(overriding any existing pair).

<ParamField>
  Name of the pose to define
</ParamField>

<ParamField>
  List of joint angles in radians
</ParamField>

**Raises:**

ValueError: If the length of joint\_angles list does match the length of other named
poses

### `endFreeDrive()`

```python Signature theme={null}
endFreeDrive() -> None
```

Exit free-drive mode and return to position control.

The arm is no longer movable by hand and again responds to
position-control commands such as `moveToPose` and
`setJointAngles`.

**Raises:**

RuntimeError: If the robot is in read only mode or the
controller rejects the end-teach-mode request.

### `followJointTrajectory()`

```python Signature theme={null}
followJointTrajectory(
    angles: List[List[float]],
    duration: Union[float, List[float]],
    blocking: bool = True,
) -> None
```

Move the arm through a sequence of joint configurations.

Each waypoint in `angles` is visited in order. The arm briefly
stops at every intermediate waypoint — this implementation is a
per-segment loop over `setJointAngles`, not a blended
trajectory.

<ParamField>
  Sequence of joint configurations (radians) to visit in order. Each inner list must have 6 elements (one per UR joint).
</ParamField>

<ParamField>
  Either a single positive float giving the total trajectory time in seconds (split evenly across segments), or a list of positive floats with the same length as `angles` giving the duration of each segment from the previous pose to `angles[i]`.
</ParamField>

<ParamField>
  Wait for the final segment to complete before returning. Intermediate segments are always blocking. Defaults to True.
</ParamField>

**Raises:**

ValueError: If `angles` is empty, `duration` is not
positive, or list-form `duration` length does not match
`angles`.
RuntimeError: If the robot is in read only mode or any
segment command is rejected.

### `getEndEffectorForce()`

```python Signature theme={null}
getEndEffectorForce() -> np.ndarray
```

Get the current end effector force (x, y, z, rx, ry, rz)

### `getEndEffectorPose()`

```python Signature theme={null}
getEndEffectorPose() -> Pose
```

```text theme={null}
[Deprecated]
Get the current end effector pose (position + orientation) w.r.t. the base frame.
```

### `getEndEffectorPosition()`

```python Signature theme={null}
getEndEffectorPosition(*, normalized: bool = True) -> float
```

Return the continuous end-effector position.

<ParamField>
  If True, return the position normalized against the auto-calibrated travel range. If False, return the raw Robotiq encoder value on its fixed 0-255 scale. Defaults to True.
</ParamField>

**Returns:**

```text theme={null}
Current position. With ``normalized=True``, the inclusive range is
[0.0, 1.0], where 0.0 is fully open and 1.0 is fully closed. With
``normalized=False``, the value is the raw encoder reading in
[0.0, 255.0].
```

**Raises:**

RuntimeError: If no end effector is configured or the configured
end effector is not a Robotiq gripper with continuous-position
feedback.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getInverseKinematics()`

```python Signature theme={null}
getInverseKinematics(
    position: Position,
    orientation: Orientation,
    qnear: Optional[List[float]] = None,
) -> List[float]
```

Solve inverse kinematics for a target end-effector pose (base frame).

Maps a Cartesian tool pose to the 6 joint angles that reach it. Used to
recover the joint-space command behind a Cartesian
`moveToPose(high_frequency=True)` stream (e.g. labelling a VR teleop
takeover for DAgger).

<ParamField>
  Target tool position in meters, in the robot base frame.
</ParamField>

<ParamField>
  Target tool orientation, in the robot base frame.
</ParamField>

<ParamField>
  Joint positions (radians) used to disambiguate the solution; the IK closest to `qnear` is returned (pass the current joints to avoid elbow/wrist flips). When None, the controller uses the current joint positions.
</ParamField>

**Returns:**

The 6 joint angles in radians that reach the pose.

**Raises:**

RuntimeError: If the robot is in read-only mode (the control
interface needed to solve IK is not connected).

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> list
```

Get a list of the 6 current joint angles in radians

**Returns:**

list: List of current joint angles in radians

### `getJointTorques()`

```python Signature theme={null}
getJointTorques() -> list
```

Get a list of the 6 current joint torques in Newtons meters

### `getJointVelocities()`

```python Signature theme={null}
getJointVelocities() -> list
```

Get a list of the 6 current joint velocities in radians/second

**Returns:**

list: List of current joint velocities in radians/second

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getNamedPose()`

```python Signature theme={null}
getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

<ParamField>
  Name of the pose to get (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose, or None if the named pose does not exist

### `getObs()`

```python Signature theme={null}
getObs(
    get_proprioception: bool = True,
    get_camera: bool = True,
    proprioception_items: Optional[List[str]] = None,
    normalize_gripper: bool = True,
) -> Dict
```

Get the current observation from the arm.

<ParamField type="bool">
  If True, include robot state (joint positions, velocities, end-effector pose, force, torques, gripper). Defaults to True.
</ParamField>

<ParamField type="bool">
  If True, include RGB images from all attached cameras. Defaults to True.
</ParamField>

<ParamField type="Optional[List[str]]">
  List of proprioception field names to include. If None, all available fields are returned.
</ParamField>

<ParamField type="bool">
  If True, normalize gripper position to \[0, 1]. Defaults to True.
</ParamField>

**Returns:**

```text theme={null}
Dict: Observation dictionary. Proprioception keys (when get_proprioception=True):
    - "joint_positions" (List[float]): Joint angles in radians.
    - "joint_velocities" (List[float]): Joint velocities in rad/s.
    - "end_effector_pose" (Pose): End-effector pose w.r.t. the base frame.
    - "end_effector_force" (List[float]): 6-element wrench
      [fx, fy, fz, tx, ty, tz] (N / N·m).
    - "joint_torques" (List[float]): Joint torques in N·m
      (only when read_only=False).
    - "gripper_pos" (float): Gripper position. Normalized to [0, 1] when
      normalize_gripper=True (0=open, 1=closed); raw hardware position otherwise. Only
      present when an end effector is attached.
    - "gripper_state": Gripper open/closed state. Only present when an end
      effector is attached.
    - "robot_mode" (int): UR robot mode (e.g. 7 = Running).
    Camera keys (when get_camera=True): "{camera_name}" for each camera.
```

**Raises:**

KeyError: If a requested proprioception key is not registered
on this robot.

### `getOrientation()`

```python Signature theme={null}
getOrientation(name: str = '') -> Orientation
```

Get the current end effector orientation with respect to the robot base

**Returns:**

Orientation: Current end effector orientation with respect to the robot base
name (str, optional): Unused

### `getPose()`

```python Signature theme={null}
getPose() -> Pose
```

Get the current end effector pose with respect to the base frame.

**Returns:**

Pose: Current end effector position and orientation

### `getPosition()`

```python Signature theme={null}
getPosition() -> Position
```

Get the current end effector position with respect to the robot base (meters)

**Returns:**

Position: Current end effector position with respect to the robot base

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `get_payload()`

```python Signature theme={null}
get_payload() -> Tuple[float, List[float]]
```

Get the payload currently configured on the controller.

**Returns:**

A `(mass, cog)` tuple — mass in kilograms and center of gravity
`[x, y, z]` in meters, displaced from the tool mount in the flange
frame. Reflects whatever was last set, whether from the pendant
installation screen or `set_payload`.

### `grasp()`

```python Signature theme={null}
grasp(
    suction: bool = False,
    *,
    approach_distance: float = 0.03,
    approach_time: float = 2.0,
) -> None
```

Close the gripper to grasp an object.

With `suction=False` (the default) the end effector is closed in
place. With `suction=True` the arm advances `approach_distance`
meters along the gripper's z-axis (the direction the gripper points),
engages the end effector, then retracts to the joint configuration it
was in before the call. Use `suction=True` for end effectors that
need light contact with a target before sealing.

Sets `ee_state` to `CLOSED` on success.

<ParamField>
  If True, perform a short approach-then-engage-then-retract motion instead of engaging in place. Defaults to False.
</ParamField>

<ParamField>
  Distance to advance along the gripper z-axis when `suction=True` (meters). Defaults to 0.03.
</ParamField>

<ParamField>
  Total duration of the approach move when `suction=True` (seconds). Defaults to 2.0.
</ParamField>

**Raises:**

RuntimeError: If the robot is in read only mode or no end
effector is configured.

### `moveToDeltaPose()`

```python Signature theme={null}
moveToDeltaPose(delta_pose: Pose, blocking: bool = True) -> None
```

Offset the robot end effector by the specified delta pose from its current pose
(with respect to the base frame).

<ParamField>
  Pose offset to compose with the current pose. The position is added to the current position and the orientation is composed with the current orientation.
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `moveToHome()`

```python Signature theme={null}
moveToHome(
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
) -> None
```

Move the robot to its predefined home pose.

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

<ParamField>
  Total duration of the move (seconds). Defaults to 2.0.
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`. Defaults to 0.75.
</ParamField>

**Raises:**

RuntimeError: If the robot is in read only mode.

### `moveToNamedPose()`

```python Signature theme={null}
moveToNamedPose(
    pose_name: str,
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
) -> None
```

Move the arm to the joint angles of a named pose.

<ParamField>
  Name of the pose to move to (case-insensitive).
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

<ParamField>
  Total duration of the move (seconds). Defaults to 2.0.
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`. Defaults to 0.75.
</ParamField>

**Raises:**

ValueError: If pose\_name is not in `named_poses`.

### `moveToPose()`

```python Signature theme={null}
moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    high_frequency: bool = False,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    avoid_force: bool = False,
    stop_acceleration: float = 5,
    force_threshold: float = 10,
    step_time: float = 0.1,
    lookahead_time: float = 0.03,
    gain: float = 300.0,
) -> None
```

Move the robot end effector to a specified pose with respect to the base frame.

Set `high_frequency=False` (the default) for a normal point-to-point
move that takes `moving_time` seconds end-to-end. Set
`high_frequency=True` to stream a single setpoint from a real-time
control loop (e.g. \~500 Hz) — each call commands one short step of
duration `step_time` and returns immediately, letting the arm follow
a stream of closely-spaced setpoints. Parameters that apply only to the
other mode are silently ignored (each is annotated below).

When `avoid_force=True` the arm stops and raises
`grid_types.ForceThresholdExceeded` if the end-effector force or
torque rises above the configured thresholds.

<ParamField>
  Target pose (position in meters, orientation as a unit quaternion) in the robot's base frame.
</ParamField>

<ParamField>
  Wait for the move to complete. Ignored when `high_frequency=True` (those calls always return immediately). Defaults to True.
</ParamField>

<ParamField>
  Select between a normal point-to-point move (False) and a single streaming control step (True). Defaults to False.
</ParamField>

<ParamField>
  Total duration of the move (seconds). Used only when `high_frequency=False`. Defaults to 2.0.
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`. Used only when `high_frequency=False`. Defaults to 0.5.
</ParamField>

<ParamField>
  If True, stop and raise `RuntimeError` when the end-effector force or torque rises above the configured thresholds. Requires `blocking=False`: force monitoring runs the move asynchronously, so it cannot also block. Defaults to False.
</ParamField>

<ParamField>
  Deceleration (m/s^2) used when stopping on a force/torque trigger. Used only when `high_frequency=False`. Defaults to 5.0.
</ParamField>

<ParamField>
  Force (N) above the pre-move baseline that triggers a stop. Used only when `high_frequency=False`. Defaults to 10.0.
</ParamField>

<ParamField>
  Duration of one high-frequency step (seconds). Used only when `high_frequency=True`. Defaults to 0.1.
</ParamField>

<ParamField>
  Smoothing horizon for the high-frequency tracking controller (seconds). Larger values smooth the trajectory at the cost of responsiveness. Clamped to \[0.03, 0.2]. Used only when `high_frequency=True`. Defaults to 0.03.
</ParamField>

<ParamField>
  Proportional gain of the high-frequency tracking controller. Lower values give faster reaction; higher values reduce overshoot but may cause jerkiness or oscillation. Clamped to \[100, 2000]. Used only when `high_frequency=True`. Defaults to 300.0.
</ParamField>

**Raises:**

ValueError: If `moving_time`, `accel_time`, or `step_time` are
not positive numbers, or if `avoid_force=True` is combined
with `blocking=True`.
RuntimeError: If the robot is in read only mode, the move command
is rejected, `avoid_force=True` and the end-effector
force/torque exceeds the configured thresholds, or a compliant
servo overlay is active — pose targets cannot be routed into
it (stop it with `stopCompliantServo()` first).

### `network_addresses()`

```python Signature theme={null}
network_addresses(args: dict) -> List[str]
```

Controller addresses a routing check should verify for these args.

<ParamField>
  Config `args` for this robot, as the wizard collected them.
</ParamField>

**Returns:**

The controller address, or none when no address is configured.

### `release()`

```python Signature theme={null}
release()
```

Open the gripper to release an object.

Only works if an end effector is configured. Changes ee\_state to OPEN.

**Raises:**

RuntimeError: If the robot is in read only mode or no end
effector is configured.

### `removeNamedPose()`

```python Signature theme={null}
removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

<ParamField>
  Name of the pose to remove (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose that was removed, or None if the named
pose did not exist

### `retract()`

```python Signature theme={null}
retract(linear_distance: float = 0.0, angular_distance: float = 0.0) -> None
```

Back the arm off along the current contact force/torque direction.

Intended for use after catching a `RuntimeError` from a force-aware
motion command. With both distances at 0.0 (default), retracts until
the contact wrench settles. With a positive distance, retracts that
far along the contact direction.

<ParamField>
  Cartesian back-off distance in meters. 0.0 retracts until force settles.
</ParamField>

<ParamField>
  Wrist back-off rotation in radians. 0.0 retracts until torque settles.
</ParamField>

### `setEndEffectorPosition()`

```python Signature theme={null}
setEndEffectorPosition(position: float, *, blocking: bool = False) -> None
```

Command a normalized continuous end-effector position.

On success, `ee_state` is updated immediately to the binary target
implied by `position`. For a nonblocking call this is optimistic
command state, not observed jaw feedback; use
`getEndEffectorPosition` to read the current hardware position.

<ParamField>
  Normalized target in the inclusive range \[0.0, 1.0], where 0.0 is fully open and 1.0 is fully closed.
</ParamField>

<ParamField>
  If True, wait until the gripper stops moving because it reached the target or stalled against an object. If False, return after the command is accepted. Defaults to False.
</ParamField>

**Raises:**

RuntimeError: If the robot is read-only, no end effector is
configured, or the configured end effector is not a Robotiq
gripper with continuous-position control.
ValueError: If `position` is not a finite number in \[0.0, 1.0].

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: List[float],
    blocking: bool = True,
    *,
    high_frequency: bool = False,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    avoid_force: bool = False,
    stop_acceleration: float = 5,
    force_threshold: float = 10,
    step_time: float = 0.1,
    lookahead_time: float = 0.03,
    gain: float = 300.0,
) -> None
```

Move the arm joints to the specified target angles.

Set `high_frequency=False` (the default) for a normal point-to-point
move that takes `moving_time` seconds end-to-end. Set
`high_frequency=True` to stream a single setpoint from a real-time
control loop (e.g. \~500 Hz) — each call commands one short step of
duration `step_time` and returns immediately, letting the arm follow
a stream of closely-spaced setpoints. Parameters that apply only to the
other mode are silently ignored (each is annotated below).

When `avoid_force=True` the arm stops and raises
`grid_types.ForceThresholdExceeded` if the end-effector force rises
above the configured threshold.

<ParamField>
  List of 6 target joint angles in radians (one per joint, base to wrist).
</ParamField>

<ParamField>
  Wait for the move to complete. Ignored when `high_frequency=True` (those calls always return immediately). Defaults to True.
</ParamField>

<ParamField>
  Select between a normal point-to-point move (False) and a single streaming control step (True). Defaults to False.
</ParamField>

<ParamField>
  Total duration of the move (seconds). Used only when `high_frequency=False`. Defaults to 2.0.
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`. Used only when `high_frequency=False`. Defaults to 0.5.
</ParamField>

<ParamField>
  If True, stop and raise `RuntimeError` when the end-effector force rises above the configured threshold. Requires `blocking=False`: force monitoring runs the move asynchronously, so it cannot also block. Defaults to False.
</ParamField>

<ParamField>
  Deceleration (rad/s^2) used when stopping on a force trigger. Used only when `high_frequency=False`. Defaults to 5.0.
</ParamField>

<ParamField>
  Force (N) above the pre-move baseline that triggers a stop. Used only when `high_frequency=False`. Defaults to 10.0.
</ParamField>

<ParamField>
  Duration of one high-frequency step (seconds). Used only when `high_frequency=True`. Defaults to 0.1.
</ParamField>

<ParamField>
  Smoothing horizon for the high-frequency tracking controller (seconds). Larger values smooth the trajectory at the cost of responsiveness. Clamped to \[0.03, 0.2]. Used only when `high_frequency=True`. Defaults to 0.03.
</ParamField>

<ParamField>
  Proportional gain of the high-frequency tracking controller. Lower values give faster reaction; higher values reduce overshoot but may cause jerkiness or oscillation. Clamped to \[100, 2000]. Used only when `high_frequency=True`. Defaults to 300.0.
</ParamField>

**Raises:**

ValueError: If `moving_time`, `accel_time`, or `step_time`
are not positive numbers, or if `avoid_force=True` is
combined with `blocking=True`.
RuntimeError: If the robot is in read only mode, the move
command is rejected, `avoid_force=True` and the
end-effector force exceeds the configured threshold, or a
blocking move is attempted while the compliant servo overlay
is active (stop it with `stopCompliantServo()` first).

### `set_payload()`

```python Signature theme={null}
set_payload(mass: float, cog: Optional[List[float]] = None) -> None
```

Set the mass and center of gravity of the payload on the flange.

Include the end-effector plus anything it holds. The controller uses this
for its dynamics model + protective-stop monitoring, and on the e-Series
to gravity-compensate the wrist F/T readings from `getEndEffectorForce`
— so a static payload's weight stops reading as an external push. One call
after grasping remains valid as the wrist rotates, as long as the payload
does not shift in the gripper.

<ParamField>
  Payload mass in kilograms.
</ParamField>

<ParamField>
  Center of gravity `[x, y, z]` in meters, displaced from the tool mount in the flange frame. None sets `[0.0, 0.0, 0.0]`.
</ParamField>

**Raises:**

RuntimeError: If the robot is in read-only mode, or the controller
rejects the payload (mass/CoG outside the robot's rated limits).

### `startCompliantServo()`

```python Signature theme={null}
startCompliantServo(
    *,
    waypoint_hz: float = 100.0,
    force_scale: float = 1.0,
    baseline_duration: float = 3.0,
) -> dict
```

Make the arm compliant to external contact while streaming waypoints.

Built for teleoperation and other force-aware, contact-rich tasks —
wiping a surface, insertion, collecting demonstrations where the arm
presses against fixtures, or policy rollouts near people. It starts an
admittance-control overlay on the arm: streamed high-frequency joint
waypoints are tracked as usual in free space, but on contact the arm
yields along the push and holds a bounded force instead of pushing
harder, then springs back once the push releases. Stop it with
`stopCompliantServo`. The gripper is never commanded by the
overlay.

Call with the arm stationary, contact-free, and at a repeatable pose
(e.g. after `moveToHome()`): the call blocks for
`baseline_duration` seconds measuring the resting force-sensor bias
that contact detection is referenced against.

Idempotent: if an overlay is already running, returns its status
without re-measuring the baseline.

<ParamField>
  Rate (Hz) at which the client streams waypoints; the overlay interpolates between them at the arm's servo rate.
</ParamField>

<ParamField>
  Multiplier in \[0, 1] on the sensed contact force. 1.0 = full tuned compliance; 0.0 = rigid waypoint tracking (contact has no effect, safety limits stay armed).
</ParamField>

<ParamField>
  Resting-force sampling window in seconds.
</ParamField>

**Returns:**

Dict with `started` (bool), `already_running` (bool),
`baseline` (list of 6 floats, N / N·m) and `waypoint_hz`.

**Raises:**

RuntimeError: If the arm is read-only.
ValueError: If `waypoint_hz` or `baseline_duration` is not
positive, or `force_scale` is outside \[0, 1].

### `startFreeDrive()`

```python Signature theme={null}
startFreeDrive() -> None
```

Enable free-drive (hand-guided) mode.

The arm becomes compliant and can be moved by hand while supporting
its own weight. Position-control commands such as
`moveToPose` and `setJointAngles` are not active in
this mode — call `endFreeDrive` to return to position
control.

**Raises:**

RuntimeError: If the robot is in read only mode, the controller
rejects the teach-mode request, or a compliant servo overlay
is active (stop it with `stopCompliantServo()` first —
teach mode and the overlay would be two competing writers).

### `stop()`

```python Signature theme={null}
stop(*, immediate: bool = False) -> None
```

Stop any movement of the robot (soft emergency-stop).

This override only *extends* the base component stop with the
`immediate` escape hatch; it never re-implements the recursion.
With `immediate=False` it delegates to `super().stop()` — the
standard recursive walk, which covers the attached end effector
and any other subcomponents, then performs a controlled stop of
the arm. `immediate=True` is a UR-specific hard stop that
halts the arm instantly without walking the tree (an attached
gripper holds its state on its own).

<ParamField>
  If True, stop motion instantly by killing the control script (no controlled deceleration), then reupload it so the arm stays usable for subsequent commands. Use this for an emergency stop. If False, perform a controlled stop and leave the script running. Defaults to False.
</ParamField>

**Raises:**

RuntimeError: If `immediate=True` on an arm that was never
started, so there is no control script to kill; or if
`immediate=True` stopped motion but the control script
could not be restarted (the controller is still in an
emergency or protective stop) — clear the stop on the
robot, then call `start()` to restore control.
ComponentStopError: If `immediate=False` and a stop hook in
the component tree raised; the walk still visits every
component.

### `stopCompliantServo()`

```python Signature theme={null}
stopCompliantServo() -> dict
```

Stop the compliant overlay and return to direct servo streaming.

The overlay's loop performs a controlled stop of the arm on exit.
Idempotent: a no-op when no overlay is running. This is also the
acknowledgment call after the overlay's emergency stop — motion
commands raise until it (or `startCompliantServo()`) is called.

**Returns:**

Dict with `stopped` (bool) and `was_running` (bool) — whether an
overlay existed and whether its loop was still alive.

**Raises:**

RuntimeError: If the overlay thread does not exit within 2 seconds.

### `validateGrasp()`

```python Signature theme={null}
validateGrasp() -> bool
```

Check whether the end effector is currently holding an object.

Thin wrapper that delegates to the configured end effector's
`EndEffector.getGripDetected`. Subclasses generally do not
need to override this.

**Returns:**

True if the end effector reports an object in its grip, False
otherwise.

**Raises:**

RuntimeError: If no end effector is configured on this arm.
NotImplementedError: If the configured end effector does not
support grip detection.

### `waitPeriod()`

```python Signature theme={null}
waitPeriod(t_start: float) -> None
```

Sleep until the end of a real-time control-loop iteration.

Used with `initPeriod` to pace a streaming control loop (see
`initPeriod` for example usage).

<ParamField>
  Loop-iteration start time returned by `initPeriod`.
</ParamField>

**Raises:**

RuntimeError: If the robot is in read only mode.

## Properties on the robot

Read as `robot.<property>`; each read runs the getter on the robot.

<ResponseField name="control_mode" type="ControlMode">
  The controller mode this driver last commanded.

  Driver-owned: it changes only through the motion API
  (`startFreeDrive`, `endFreeDrive`, the servo/speed/force
  paths and `stop`), never by assignment.
</ResponseField>

<ResponseField name="ee_state" type="int">
  Optimistic binary end-effector command state, `OPEN` (0) or `CLOSED` (1).

  Updated immediately after an accepted gripper command, so it reflects
  the last command issued rather than observed hardware feedback — read
  `getEndEffectorPosition` for the current jaw position.
</ResponseField>

<ResponseField name="force_ema_alpha" type="float">
  Force/torque baseline EMA smoothing factor, in \[0, 1]. Writable.

  Higher values make the baseline track more slowly, increasing
  sensitivity to sudden contacts.
</ResponseField>

<ResponseField name="force_threshold" type="float">
  Linear force delta above the EMA baseline that trips retraction, in N.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="home_pose" type="List[float]">
  Joint angles (radians) with the arm over the workspace, joints at 90 degrees.
</ResponseField>

<ResponseField name="max_joint_acceleration" type="float">
  Cap applied to commanded joint acceleration, in rad/s^2.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_joint_speed" type="float">
  Cap applied to commanded joint speed, in rad/s. Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_linear_acceleration" type="float">
  Cap applied to commanded tool acceleration, in m/s^2.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_linear_speed" type="float">
  Cap applied to commanded tool speed, in m/s. Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="named_poses" type="Dict[str, List[float]]">
  Registered poses as `&#123;name: joint angles in radians&#125;` (a copy).

  Mutating the returned mapping does not change what the arm knows:
  register and remove entries with `addNamedPose` and
  `removeNamedPose`, or assign a whole mapping to replace them all.
</ResponseField>

<ResponseField name="read_only" type="bool">
  Whether this arm was provisioned without a control interface (telemetry only).
</ResponseField>

<ResponseField name="torque_threshold" type="float">
  End-effector torque delta above the EMA baseline that trips retraction, in N·m.

  Writable; must be finite and > 0.
</ResponseField>

## Configured children

* `robot.end_effector` — the gripper, chosen in the robot's configuration; when one is fitted, its methods are the [`EndEffector`](/v2.3/python-api/robot-interface/endeffector) interface's.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the children this class always ships with (customization point).
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()`
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `initPeriod()` — Mark the start of a real-time control-loop iteration.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# Universal Robots UR5e Arm
Source: https://docs.generalrobotics.dev/v2.3/python-api/ur5e/ur5e

The Universal Robots UR5e Arm as GRID drives it

The Universal Robots UR5e Arm as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `UR5e`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<ur5e-name>")
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `addNamedPose()`

```python Signature theme={null}
addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses
(overriding any existing pair).

<ParamField>
  Name of the pose to define
</ParamField>

<ParamField>
  List of joint angles in radians
</ParamField>

**Raises:**

ValueError: If the length of joint\_angles list does match the length of other named
poses

### `endFreeDrive()`

```python Signature theme={null}
endFreeDrive() -> None
```

Exit free-drive mode and return to position control.

The arm is no longer movable by hand and again responds to
position-control commands such as `moveToPose` and
`setJointAngles`.

**Raises:**

RuntimeError: If the robot is in read only mode or the
controller rejects the end-teach-mode request.

### `followJointTrajectory()`

```python Signature theme={null}
followJointTrajectory(
    angles: List[List[float]],
    duration: Union[float, List[float]],
    blocking: bool = True,
) -> None
```

Move the arm through a sequence of joint configurations.

Each waypoint in `angles` is visited in order. The arm briefly
stops at every intermediate waypoint — this implementation is a
per-segment loop over `setJointAngles`, not a blended
trajectory.

<ParamField>
  Sequence of joint configurations (radians) to visit in order. Each inner list must have 6 elements (one per UR joint).
</ParamField>

<ParamField>
  Either a single positive float giving the total trajectory time in seconds (split evenly across segments), or a list of positive floats with the same length as `angles` giving the duration of each segment from the previous pose to `angles[i]`.
</ParamField>

<ParamField>
  Wait for the final segment to complete before returning. Intermediate segments are always blocking. Defaults to True.
</ParamField>

**Raises:**

ValueError: If `angles` is empty, `duration` is not
positive, or list-form `duration` length does not match
`angles`.
RuntimeError: If the robot is in read only mode or any
segment command is rejected.

### `getEndEffectorForce()`

```python Signature theme={null}
getEndEffectorForce() -> np.ndarray
```

Get the current end effector force (x, y, z, rx, ry, rz)

### `getEndEffectorPose()`

```python Signature theme={null}
getEndEffectorPose() -> Pose
```

```text theme={null}
[Deprecated]
Get the current end effector pose (position + orientation) w.r.t. the base frame.
```

### `getEndEffectorPosition()`

```python Signature theme={null}
getEndEffectorPosition(*, normalized: bool = True) -> float
```

Return the continuous end-effector position.

<ParamField>
  If True, return the position normalized against the auto-calibrated travel range. If False, return the raw Robotiq encoder value on its fixed 0-255 scale. Defaults to True.
</ParamField>

**Returns:**

```text theme={null}
Current position. With ``normalized=True``, the inclusive range is
[0.0, 1.0], where 0.0 is fully open and 1.0 is fully closed. With
``normalized=False``, the value is the raw encoder reading in
[0.0, 255.0].
```

**Raises:**

RuntimeError: If no end effector is configured or the configured
end effector is not a Robotiq gripper with continuous-position
feedback.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getInverseKinematics()`

```python Signature theme={null}
getInverseKinematics(
    position: Position,
    orientation: Orientation,
    qnear: Optional[List[float]] = None,
) -> List[float]
```

Solve inverse kinematics for a target end-effector pose (base frame).

Maps a Cartesian tool pose to the 6 joint angles that reach it. Used to
recover the joint-space command behind a Cartesian
`moveToPose(high_frequency=True)` stream (e.g. labelling a VR teleop
takeover for DAgger).

<ParamField>
  Target tool position in meters, in the robot base frame.
</ParamField>

<ParamField>
  Target tool orientation, in the robot base frame.
</ParamField>

<ParamField>
  Joint positions (radians) used to disambiguate the solution; the IK closest to `qnear` is returned (pass the current joints to avoid elbow/wrist flips). When None, the controller uses the current joint positions.
</ParamField>

**Returns:**

The 6 joint angles in radians that reach the pose.

**Raises:**

RuntimeError: If the robot is in read-only mode (the control
interface needed to solve IK is not connected).

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> list
```

Get a list of the 6 current joint angles in radians

**Returns:**

list: List of current joint angles in radians

### `getJointTorques()`

```python Signature theme={null}
getJointTorques() -> list
```

Get a list of the 6 current joint torques in Newtons meters

### `getJointVelocities()`

```python Signature theme={null}
getJointVelocities() -> list
```

Get a list of the 6 current joint velocities in radians/second

**Returns:**

list: List of current joint velocities in radians/second

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getNamedPose()`

```python Signature theme={null}
getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

<ParamField>
  Name of the pose to get (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose, or None if the named pose does not exist

### `getObs()`

```python Signature theme={null}
getObs(
    get_proprioception: bool = True,
    get_camera: bool = True,
    proprioception_items: Optional[List[str]] = None,
    normalize_gripper: bool = True,
) -> Dict
```

Get the current observation from the arm.

<ParamField type="bool">
  If True, include robot state (joint positions, velocities, end-effector pose, force, torques, gripper). Defaults to True.
</ParamField>

<ParamField type="bool">
  If True, include RGB images from all attached cameras. Defaults to True.
</ParamField>

<ParamField type="Optional[List[str]]">
  List of proprioception field names to include. If None, all available fields are returned.
</ParamField>

<ParamField type="bool">
  If True, normalize gripper position to \[0, 1]. Defaults to True.
</ParamField>

**Returns:**

```text theme={null}
Dict: Observation dictionary. Proprioception keys (when get_proprioception=True):
    - "joint_positions" (List[float]): Joint angles in radians.
    - "joint_velocities" (List[float]): Joint velocities in rad/s.
    - "end_effector_pose" (Pose): End-effector pose w.r.t. the base frame.
    - "end_effector_force" (List[float]): 6-element wrench
      [fx, fy, fz, tx, ty, tz] (N / N·m).
    - "joint_torques" (List[float]): Joint torques in N·m
      (only when read_only=False).
    - "gripper_pos" (float): Gripper position. Normalized to [0, 1] when
      normalize_gripper=True (0=open, 1=closed); raw hardware position otherwise. Only
      present when an end effector is attached.
    - "gripper_state": Gripper open/closed state. Only present when an end
      effector is attached.
    - "robot_mode" (int): UR robot mode (e.g. 7 = Running).
    Camera keys (when get_camera=True): "{camera_name}" for each camera.
```

**Raises:**

KeyError: If a requested proprioception key is not registered
on this robot.

### `getOrientation()`

```python Signature theme={null}
getOrientation(name: str = '') -> Orientation
```

Get the current end effector orientation with respect to the robot base

**Returns:**

Orientation: Current end effector orientation with respect to the robot base
name (str, optional): Unused

### `getPose()`

```python Signature theme={null}
getPose() -> Pose
```

Get the current end effector pose with respect to the base frame.

**Returns:**

Pose: Current end effector position and orientation

### `getPosition()`

```python Signature theme={null}
getPosition() -> Position
```

Get the current end effector position with respect to the robot base (meters)

**Returns:**

Position: Current end effector position with respect to the robot base

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `get_payload()`

```python Signature theme={null}
get_payload() -> Tuple[float, List[float]]
```

Get the payload currently configured on the controller.

**Returns:**

A `(mass, cog)` tuple — mass in kilograms and center of gravity
`[x, y, z]` in meters, displaced from the tool mount in the flange
frame. Reflects whatever was last set, whether from the pendant
installation screen or `set_payload`.

### `grasp()`

```python Signature theme={null}
grasp(
    suction: bool = False,
    *,
    approach_distance: float = 0.03,
    approach_time: float = 2.0,
) -> None
```

Close the gripper to grasp an object.

With `suction=False` (the default) the end effector is closed in
place. With `suction=True` the arm advances `approach_distance`
meters along the gripper's z-axis (the direction the gripper points),
engages the end effector, then retracts to the joint configuration it
was in before the call. Use `suction=True` for end effectors that
need light contact with a target before sealing.

Sets `ee_state` to `CLOSED` on success.

<ParamField>
  If True, perform a short approach-then-engage-then-retract motion instead of engaging in place. Defaults to False.
</ParamField>

<ParamField>
  Distance to advance along the gripper z-axis when `suction=True` (meters). Defaults to 0.03.
</ParamField>

<ParamField>
  Total duration of the approach move when `suction=True` (seconds). Defaults to 2.0.
</ParamField>

**Raises:**

RuntimeError: If the robot is in read only mode or no end
effector is configured.

### `moveToDeltaPose()`

```python Signature theme={null}
moveToDeltaPose(delta_pose: Pose, blocking: bool = True) -> None
```

Offset the robot end effector by the specified delta pose from its current pose
(with respect to the base frame).

<ParamField>
  Pose offset to compose with the current pose. The position is added to the current position and the orientation is composed with the current orientation.
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `moveToHome()`

```python Signature theme={null}
moveToHome(
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
) -> None
```

Move the robot to its predefined home pose.

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

<ParamField>
  Total duration of the move (seconds). Defaults to 2.0.
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`. Defaults to 0.75.
</ParamField>

**Raises:**

RuntimeError: If the robot is in read only mode.

### `moveToNamedPose()`

```python Signature theme={null}
moveToNamedPose(
    pose_name: str,
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
) -> None
```

Move the arm to the joint angles of a named pose.

<ParamField>
  Name of the pose to move to (case-insensitive).
</ParamField>

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

<ParamField>
  Total duration of the move (seconds). Defaults to 2.0.
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`. Defaults to 0.75.
</ParamField>

**Raises:**

ValueError: If pose\_name is not in `named_poses`.

### `moveToPose()`

```python Signature theme={null}
moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    high_frequency: bool = False,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    avoid_force: bool = False,
    stop_acceleration: float = 5,
    force_threshold: float = 10,
    step_time: float = 0.1,
    lookahead_time: float = 0.03,
    gain: float = 300.0,
) -> None
```

Move the robot end effector to a specified pose with respect to the base frame.

Set `high_frequency=False` (the default) for a normal point-to-point
move that takes `moving_time` seconds end-to-end. Set
`high_frequency=True` to stream a single setpoint from a real-time
control loop (e.g. \~500 Hz) — each call commands one short step of
duration `step_time` and returns immediately, letting the arm follow
a stream of closely-spaced setpoints. Parameters that apply only to the
other mode are silently ignored (each is annotated below).

When `avoid_force=True` the arm stops and raises
`grid_types.ForceThresholdExceeded` if the end-effector force or
torque rises above the configured thresholds.

<ParamField>
  Target pose (position in meters, orientation as a unit quaternion) in the robot's base frame.
</ParamField>

<ParamField>
  Wait for the move to complete. Ignored when `high_frequency=True` (those calls always return immediately). Defaults to True.
</ParamField>

<ParamField>
  Select between a normal point-to-point move (False) and a single streaming control step (True). Defaults to False.
</ParamField>

<ParamField>
  Total duration of the move (seconds). Used only when `high_frequency=False`. Defaults to 2.0.
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`. Used only when `high_frequency=False`. Defaults to 0.5.
</ParamField>

<ParamField>
  If True, stop and raise `RuntimeError` when the end-effector force or torque rises above the configured thresholds. Requires `blocking=False`: force monitoring runs the move asynchronously, so it cannot also block. Defaults to False.
</ParamField>

<ParamField>
  Deceleration (m/s^2) used when stopping on a force/torque trigger. Used only when `high_frequency=False`. Defaults to 5.0.
</ParamField>

<ParamField>
  Force (N) above the pre-move baseline that triggers a stop. Used only when `high_frequency=False`. Defaults to 10.0.
</ParamField>

<ParamField>
  Duration of one high-frequency step (seconds). Used only when `high_frequency=True`. Defaults to 0.1.
</ParamField>

<ParamField>
  Smoothing horizon for the high-frequency tracking controller (seconds). Larger values smooth the trajectory at the cost of responsiveness. Clamped to \[0.03, 0.2]. Used only when `high_frequency=True`. Defaults to 0.03.
</ParamField>

<ParamField>
  Proportional gain of the high-frequency tracking controller. Lower values give faster reaction; higher values reduce overshoot but may cause jerkiness or oscillation. Clamped to \[100, 2000]. Used only when `high_frequency=True`. Defaults to 300.0.
</ParamField>

**Raises:**

ValueError: If `moving_time`, `accel_time`, or `step_time` are
not positive numbers, or if `avoid_force=True` is combined
with `blocking=True`.
RuntimeError: If the robot is in read only mode, the move command
is rejected, `avoid_force=True` and the end-effector
force/torque exceeds the configured thresholds, or a compliant
servo overlay is active — pose targets cannot be routed into
it (stop it with `stopCompliantServo()` first).

### `network_addresses()`

```python Signature theme={null}
network_addresses(args: dict) -> List[str]
```

Controller addresses a routing check should verify for these args.

<ParamField>
  Config `args` for this robot, as the wizard collected them.
</ParamField>

**Returns:**

The controller address, or none when no address is configured.

### `release()`

```python Signature theme={null}
release()
```

Open the gripper to release an object.

Only works if an end effector is configured. Changes ee\_state to OPEN.

**Raises:**

RuntimeError: If the robot is in read only mode or no end
effector is configured.

### `removeNamedPose()`

```python Signature theme={null}
removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

<ParamField>
  Name of the pose to remove (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose that was removed, or None if the named
pose did not exist

### `retract()`

```python Signature theme={null}
retract(linear_distance: float = 0.0, angular_distance: float = 0.0) -> None
```

Back the arm off along the current contact force/torque direction.

Intended for use after catching a `RuntimeError` from a force-aware
motion command. With both distances at 0.0 (default), retracts until
the contact wrench settles. With a positive distance, retracts that
far along the contact direction.

<ParamField>
  Cartesian back-off distance in meters. 0.0 retracts until force settles.
</ParamField>

<ParamField>
  Wrist back-off rotation in radians. 0.0 retracts until torque settles.
</ParamField>

### `setEndEffectorPosition()`

```python Signature theme={null}
setEndEffectorPosition(position: float, *, blocking: bool = False) -> None
```

Command a normalized continuous end-effector position.

On success, `ee_state` is updated immediately to the binary target
implied by `position`. For a nonblocking call this is optimistic
command state, not observed jaw feedback; use
`getEndEffectorPosition` to read the current hardware position.

<ParamField>
  Normalized target in the inclusive range \[0.0, 1.0], where 0.0 is fully open and 1.0 is fully closed.
</ParamField>

<ParamField>
  If True, wait until the gripper stops moving because it reached the target or stalled against an object. If False, return after the command is accepted. Defaults to False.
</ParamField>

**Raises:**

RuntimeError: If the robot is read-only, no end effector is
configured, or the configured end effector is not a Robotiq
gripper with continuous-position control.
ValueError: If `position` is not a finite number in \[0.0, 1.0].

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: List[float],
    blocking: bool = True,
    *,
    high_frequency: bool = False,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    avoid_force: bool = False,
    stop_acceleration: float = 5,
    force_threshold: float = 10,
    step_time: float = 0.1,
    lookahead_time: float = 0.03,
    gain: float = 300.0,
) -> None
```

Move the arm joints to the specified target angles.

Set `high_frequency=False` (the default) for a normal point-to-point
move that takes `moving_time` seconds end-to-end. Set
`high_frequency=True` to stream a single setpoint from a real-time
control loop (e.g. \~500 Hz) — each call commands one short step of
duration `step_time` and returns immediately, letting the arm follow
a stream of closely-spaced setpoints. Parameters that apply only to the
other mode are silently ignored (each is annotated below).

When `avoid_force=True` the arm stops and raises
`grid_types.ForceThresholdExceeded` if the end-effector force rises
above the configured threshold.

<ParamField>
  List of 6 target joint angles in radians (one per joint, base to wrist).
</ParamField>

<ParamField>
  Wait for the move to complete. Ignored when `high_frequency=True` (those calls always return immediately). Defaults to True.
</ParamField>

<ParamField>
  Select between a normal point-to-point move (False) and a single streaming control step (True). Defaults to False.
</ParamField>

<ParamField>
  Total duration of the move (seconds). Used only when `high_frequency=False`. Defaults to 2.0.
</ParamField>

<ParamField>
  Time spent accelerating and decelerating (seconds). Clamped to at most `moving_time / 2`. Used only when `high_frequency=False`. Defaults to 0.5.
</ParamField>

<ParamField>
  If True, stop and raise `RuntimeError` when the end-effector force rises above the configured threshold. Requires `blocking=False`: force monitoring runs the move asynchronously, so it cannot also block. Defaults to False.
</ParamField>

<ParamField>
  Deceleration (rad/s^2) used when stopping on a force trigger. Used only when `high_frequency=False`. Defaults to 5.0.
</ParamField>

<ParamField>
  Force (N) above the pre-move baseline that triggers a stop. Used only when `high_frequency=False`. Defaults to 10.0.
</ParamField>

<ParamField>
  Duration of one high-frequency step (seconds). Used only when `high_frequency=True`. Defaults to 0.1.
</ParamField>

<ParamField>
  Smoothing horizon for the high-frequency tracking controller (seconds). Larger values smooth the trajectory at the cost of responsiveness. Clamped to \[0.03, 0.2]. Used only when `high_frequency=True`. Defaults to 0.03.
</ParamField>

<ParamField>
  Proportional gain of the high-frequency tracking controller. Lower values give faster reaction; higher values reduce overshoot but may cause jerkiness or oscillation. Clamped to \[100, 2000]. Used only when `high_frequency=True`. Defaults to 300.0.
</ParamField>

**Raises:**

ValueError: If `moving_time`, `accel_time`, or `step_time`
are not positive numbers, or if `avoid_force=True` is
combined with `blocking=True`.
RuntimeError: If the robot is in read only mode, the move
command is rejected, `avoid_force=True` and the
end-effector force exceeds the configured threshold, or a
blocking move is attempted while the compliant servo overlay
is active (stop it with `stopCompliantServo()` first).

### `set_payload()`

```python Signature theme={null}
set_payload(mass: float, cog: Optional[List[float]] = None) -> None
```

Set the mass and center of gravity of the payload on the flange.

Include the end-effector plus anything it holds. The controller uses this
for its dynamics model + protective-stop monitoring, and on the e-Series
to gravity-compensate the wrist F/T readings from `getEndEffectorForce`
— so a static payload's weight stops reading as an external push. One call
after grasping remains valid as the wrist rotates, as long as the payload
does not shift in the gripper.

<ParamField>
  Payload mass in kilograms.
</ParamField>

<ParamField>
  Center of gravity `[x, y, z]` in meters, displaced from the tool mount in the flange frame. None sets `[0.0, 0.0, 0.0]`.
</ParamField>

**Raises:**

RuntimeError: If the robot is in read-only mode, or the controller
rejects the payload (mass/CoG outside the robot's rated limits).

### `startCompliantServo()`

```python Signature theme={null}
startCompliantServo(
    *,
    waypoint_hz: float = 100.0,
    force_scale: float = 1.0,
    baseline_duration: float = 3.0,
) -> dict
```

Make the arm compliant to external contact while streaming waypoints.

Built for teleoperation and other force-aware, contact-rich tasks —
wiping a surface, insertion, collecting demonstrations where the arm
presses against fixtures, or policy rollouts near people. It starts an
admittance-control overlay on the arm: streamed high-frequency joint
waypoints are tracked as usual in free space, but on contact the arm
yields along the push and holds a bounded force instead of pushing
harder, then springs back once the push releases. Stop it with
`stopCompliantServo`. The gripper is never commanded by the
overlay.

Call with the arm stationary, contact-free, and at a repeatable pose
(e.g. after `moveToHome()`): the call blocks for
`baseline_duration` seconds measuring the resting force-sensor bias
that contact detection is referenced against.

Idempotent: if an overlay is already running, returns its status
without re-measuring the baseline.

<ParamField>
  Rate (Hz) at which the client streams waypoints; the overlay interpolates between them at the arm's servo rate.
</ParamField>

<ParamField>
  Multiplier in \[0, 1] on the sensed contact force. 1.0 = full tuned compliance; 0.0 = rigid waypoint tracking (contact has no effect, safety limits stay armed).
</ParamField>

<ParamField>
  Resting-force sampling window in seconds.
</ParamField>

**Returns:**

Dict with `started` (bool), `already_running` (bool),
`baseline` (list of 6 floats, N / N·m) and `waypoint_hz`.

**Raises:**

RuntimeError: If the arm is read-only.
ValueError: If `waypoint_hz` or `baseline_duration` is not
positive, or `force_scale` is outside \[0, 1].

### `startFreeDrive()`

```python Signature theme={null}
startFreeDrive() -> None
```

Enable free-drive (hand-guided) mode.

The arm becomes compliant and can be moved by hand while supporting
its own weight. Position-control commands such as
`moveToPose` and `setJointAngles` are not active in
this mode — call `endFreeDrive` to return to position
control.

**Raises:**

RuntimeError: If the robot is in read only mode, the controller
rejects the teach-mode request, or a compliant servo overlay
is active (stop it with `stopCompliantServo()` first —
teach mode and the overlay would be two competing writers).

### `stop()`

```python Signature theme={null}
stop(*, immediate: bool = False) -> None
```

Stop any movement of the robot (soft emergency-stop).

This override only *extends* the base component stop with the
`immediate` escape hatch; it never re-implements the recursion.
With `immediate=False` it delegates to `super().stop()` — the
standard recursive walk, which covers the attached end effector
and any other subcomponents, then performs a controlled stop of
the arm. `immediate=True` is a UR-specific hard stop that
halts the arm instantly without walking the tree (an attached
gripper holds its state on its own).

<ParamField>
  If True, stop motion instantly by killing the control script (no controlled deceleration), then reupload it so the arm stays usable for subsequent commands. Use this for an emergency stop. If False, perform a controlled stop and leave the script running. Defaults to False.
</ParamField>

**Raises:**

RuntimeError: If `immediate=True` on an arm that was never
started, so there is no control script to kill; or if
`immediate=True` stopped motion but the control script
could not be restarted (the controller is still in an
emergency or protective stop) — clear the stop on the
robot, then call `start()` to restore control.
ComponentStopError: If `immediate=False` and a stop hook in
the component tree raised; the walk still visits every
component.

### `stopCompliantServo()`

```python Signature theme={null}
stopCompliantServo() -> dict
```

Stop the compliant overlay and return to direct servo streaming.

The overlay's loop performs a controlled stop of the arm on exit.
Idempotent: a no-op when no overlay is running. This is also the
acknowledgment call after the overlay's emergency stop — motion
commands raise until it (or `startCompliantServo()`) is called.

**Returns:**

Dict with `stopped` (bool) and `was_running` (bool) — whether an
overlay existed and whether its loop was still alive.

**Raises:**

RuntimeError: If the overlay thread does not exit within 2 seconds.

### `validateGrasp()`

```python Signature theme={null}
validateGrasp() -> bool
```

Check whether the end effector is currently holding an object.

Thin wrapper that delegates to the configured end effector's
`EndEffector.getGripDetected`. Subclasses generally do not
need to override this.

**Returns:**

True if the end effector reports an object in its grip, False
otherwise.

**Raises:**

RuntimeError: If no end effector is configured on this arm.
NotImplementedError: If the configured end effector does not
support grip detection.

### `waitPeriod()`

```python Signature theme={null}
waitPeriod(t_start: float) -> None
```

Sleep until the end of a real-time control-loop iteration.

Used with `initPeriod` to pace a streaming control loop (see
`initPeriod` for example usage).

<ParamField>
  Loop-iteration start time returned by `initPeriod`.
</ParamField>

**Raises:**

RuntimeError: If the robot is in read only mode.

## Properties on the robot

Read as `robot.<property>`; each read runs the getter on the robot.

<ResponseField name="control_mode" type="ControlMode">
  The controller mode this driver last commanded.

  Driver-owned: it changes only through the motion API
  (`startFreeDrive`, `endFreeDrive`, the servo/speed/force
  paths and `stop`), never by assignment.
</ResponseField>

<ResponseField name="ee_state" type="int">
  Optimistic binary end-effector command state, `OPEN` (0) or `CLOSED` (1).

  Updated immediately after an accepted gripper command, so it reflects
  the last command issued rather than observed hardware feedback — read
  `getEndEffectorPosition` for the current jaw position.
</ResponseField>

<ResponseField name="force_ema_alpha" type="float">
  Force/torque baseline EMA smoothing factor, in \[0, 1]. Writable.

  Higher values make the baseline track more slowly, increasing
  sensitivity to sudden contacts.
</ResponseField>

<ResponseField name="force_threshold" type="float">
  Linear force delta above the EMA baseline that trips retraction, in N.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="home_pose" type="List[float]">
  Joint angles (radians) with the arm over the workspace, joints at 90 degrees.
</ResponseField>

<ResponseField name="max_joint_acceleration" type="float">
  Cap applied to commanded joint acceleration, in rad/s^2.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_joint_speed" type="float">
  Cap applied to commanded joint speed, in rad/s. Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_linear_acceleration" type="float">
  Cap applied to commanded tool acceleration, in m/s^2.

  Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="max_linear_speed" type="float">
  Cap applied to commanded tool speed, in m/s. Writable; must be finite and > 0.
</ResponseField>

<ResponseField name="named_poses" type="Dict[str, List[float]]">
  Registered poses as `&#123;name: joint angles in radians&#125;` (a copy).

  Mutating the returned mapping does not change what the arm knows:
  register and remove entries with `addNamedPose` and
  `removeNamedPose`, or assign a whole mapping to replace them all.
</ResponseField>

<ResponseField name="read_only" type="bool">
  Whether this arm was provisioned without a control interface (telemetry only).
</ResponseField>

<ResponseField name="torque_threshold" type="float">
  End-effector torque delta above the EMA baseline that trips retraction, in N·m.

  Writable; must be finite and > 0.
</ResponseField>

## Configured children

* `robot.end_effector` — the gripper, chosen in the robot's configuration; when one is fitted, its methods are the [`EndEffector`](/v2.3/python-api/robot-interface/endeffector) interface's.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the children this class always ships with (customization point).
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()`
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `initPeriod()` — Mark the start of a real-time control-loop iteration.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# Ghost Robotics Vision60 + Ghost Arm
Source: https://docs.generalrobotics.dev/v2.3/python-api/vision60-arm/vision60witharm

The Ghost Robotics Vision60 + Ghost Arm as GRID drives it

The Ghost Robotics Vision60 + Ghost Arm as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `Vision60WithArm`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<vision60_arm-name>")

# `front_left` is a built-in camera: reach it as an attribute.
frame = robot.front_left.getImage()
rgb = frame.decode()                    # -> H x W x 3 RGB ndarray
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `cleanup()`

```python Signature theme={null}
cleanup() -> None
```

Shut down the robot tree; alias kept for the historical Vision60 API.

Equivalent to `shutdown()`: recursive, idempotent, best-effort.

### `enableWalking()`

```python Signature theme={null}
enableWalking() -> None
```

Enable walking mode for the robot.

### `getGPS()`

```python Signature theme={null}
getGPS() -> Optional[dict]
```

Return latest GPS data: position, orientation, linear & angular velocity.

**Returns:**

A dict with `position`, `orientation`, `linear_velocity`,
and `angular_velocity` — or `None` if no GPS message has
been received yet.

### `getIMU()`

```python Signature theme={null}
getIMU() -> Optional[dict]
```

Get the latest IMU reading.

**Returns:**

A dict with `orientation`, `angular_velocity`, and
`linear_acceleration` — or `None` if no IMU message has
been received yet.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the robot orientation from odometry data.

**Returns:**

World-frame orientation, or `None` if no odometry message
has been received yet.

### `getPoseRel()`

```python Signature theme={null}
getPoseRel() -> Optional[Pose]
```

Return the body pose from the Vision60 `mcu/state/rel_pose` topic.

Ghost's firmware publishes this as a PoseStamped where the orientation
is the body's attitude relative to a gravity-aligned ground frame
(from the onboard IMU/EKF). The position field does not carry a
world-frame position — on the hardware sampled, x and y read zero and z
a small non-zero value — so use `getPosition()` / `getState()` when
world-frame position is what's wanted.

**Returns:**

Body pose whose orientation is the gravity-relative attitude and
whose position is not a world-frame position, or `None` if no
message has been received yet.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the robot position from odometry data.

**Returns:**

World-frame position, or `None` if no odometry message
has been received yet.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getVelocity()`

```python Signature theme={null}
getVelocity() -> Optional[Velocity]
```

Return the latest body-frame linear velocity (m/s).

Angular velocity is available via `getIMU()` or `getState()`.

**Returns:**

Body-frame linear velocity, or `None` if no base-velocity
message has been received yet.

### `lieDown()`

```python Signature theme={null}
lieDown() -> None
```

Make the robot lie down.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    *,
    duration: Optional[float] = 1.0,
) -> None
```

Command body-frame twist.

The command is republished at `_CMD_RATE_HZ` Hz until a new command
(including `stop`) is issued, or until *duration* seconds elapse —
Vision60's controller treats a gap as "stop", so continuous republish
is required to hold a velocity.

<ParamField>
  Body-frame linear velocity (m/s).
</ParamField>

<ParamField>
  Body-frame angular velocity (rad/s); only the z component is used for yaw.
</ParamField>

<ParamField>
  Reference frame. Only `"body"` is supported.
</ParamField>

<ParamField>
  Seconds to hold the command. Pass `None` to republish indefinitely until `stop()`.
</ParamField>

**Raises:**

NotImplementedError: If `frame == "world"` (matches Go2; world
frame is not supported on Vision60).
ValueError: If `frame` is any value other than `"body"` or
`"world"`.

### `setDefaultJointAngles()`

```python Signature theme={null}
setDefaultJointAngles(joint_pos: list) -> None
```

Set the default joint position for the robot.

<ParamField>
  Value of the joint position.
</ParamField>

### `setDefaultJointVelocities()`

```python Signature theme={null}
setDefaultJointVelocities(joint_vel: list) -> None
```

Set the default joint velocity for the robot.

<ParamField>
  Value of the joint velocity.
</ParamField>

### `standUp()`

```python Signature theme={null}
standUp() -> None
```

Make the robot stand up.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

## robot.front\_left and 4 more — camera

Reached as any of `robot.front_left`, `robot.front_right`, `robot.rear`, `robot.side_left`, `robot.side_right`; each is a `Vision60Camera` and its methods are `Vision60Camera`'s and run on the robot. Below, `<camera>` stands for any one of those names.

Camera sensor for the Vision60, bridging a ROS 2 `Image` topic to the

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `<camera>.cleanup()`

```python Signature theme={null}
<camera>.cleanup() -> None
```

Cleanup camera resources (no-op; shared node owned by caller).

### `<camera>.getCameraExtrinsics()`

```python Signature theme={null}
<camera>.getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

### `<camera>.getCameraIntrinsics()`

```python Signature theme={null}
<camera>.getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

### `<camera>.getCameraSettings()`

```python Signature theme={null}
<camera>.getCameraSettings() -> CameraSettings
```

Get the camera settings.

### `<camera>.getData()`

```python Signature theme={null}
<camera>.getData() -> Image
```

Get the image from the camera.

### `<camera>.getImage()`

```python Signature theme={null}
<camera>.getImage() -> Optional[Image]
```

Read image from shared memory file path.

**Returns:**

The latest image as an `Image` object, or `None` if no
image message has been received yet.

### `<camera>.getState()`

```python Signature theme={null}
<camera>.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `<camera>.recordCalibration()`

```python Signature theme={null}
<camera>.recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

### `<camera>.reloadCalibration()`

```python Signature theme={null}
<camera>.reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

### `<camera>.setCameraExtrinsics()`

```python Signature theme={null}
<camera>.setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

### `<camera>.setCameraIntrinsics()`

```python Signature theme={null}
<camera>.setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

### `<camera>.setCameraSettings()`

```python Signature theme={null}
<camera>.setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

### `<camera>.stop()`

```python Signature theme={null}
<camera>.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

## robot.arm — arm

Reached as `robot.arm`; its methods are `Vision60Arm`'s and run on the robot.

Control the Ghost Robotics arm mounted on a Vision60 via ROS 2.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `arm.addNamedPose()`

```python Signature theme={null}
arm.addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses

### `arm.ensureMode()`

```python Signature theme={null}
arm.ensureMode(
    field_name: str,
    value: int,
    *,
    n_tries: int = 50,
    wait_seconds: float = 0.1,
) -> None
```

Set a mode and confirm it via the `/state/heartbeat` echo.

Falls back to fire-and-forget when `ghost_manager_interfaces` is
not available or no heartbeat has been received yet.

<ParamField>
  Mode field name (see `setMode`).
</ParamField>

<ParamField>
  Desired value.
</ParamField>

<ParamField>
  Maximum publish-and-check attempts.
</ParamField>

<ParamField>
  Pause between attempts.
</ParamField>

**Raises:**

ValueError: If `field_name` is not a known Ghost mode field.
RuntimeError: If the heartbeat doesn't confirm the mode within
the retry budget.

### `arm.getEndEffectorPose()`

```python Signature theme={null}
arm.getEndEffectorPose() -> Pose
```

```text theme={null}
[Deprecated]
```

### `arm.getImage()`

```python Signature theme={null}
arm.getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

### `arm.getJointAngles()`

```python Signature theme={null}
arm.getJointAngles() -> List[float]
```

Get current arm joint angles, sliced from the body's `jointURDF`.

**Returns:**

Joint angles in radians (length `_NUM_JOINTS`).

**Raises:**

RuntimeError: If no `jointURDF` message has been received, or
the message doesn't contain enough joint values to slice.

### `arm.getJointVelocities()`

```python Signature theme={null}
arm.getJointVelocities() -> List[float]
```

Get current arm joint velocities, sliced from the body's `jointURDF`.

**Returns:**

Joint velocities in rad/s.

**Raises:**

RuntimeError: If no `jointURDF` message has been received, or
the velocity field is empty.

### `arm.getLidarPointCloud()`

```python Signature theme={null}
arm.getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

### `arm.getNamedPose()`

```python Signature theme={null}
arm.getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

### `arm.getOrientation()`

```python Signature theme={null}
arm.getOrientation() -> Orientation
```

Return the EE orientation. Delegates to `getPose`.

**Raises:**

NotImplementedError: See `getPose`.

### `arm.getPosition()`

```python Signature theme={null}
arm.getPosition() -> Position
```

Return the EE position. Delegates to `getPose`.

**Raises:**

NotImplementedError: See `getPose`.

### `arm.getState()`

```python Signature theme={null}
arm.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `arm.grasp()`

```python Signature theme={null}
arm.grasp() -> None
```

Close the gripper to `closed_position`.

### `arm.moveByVelocity()`

```python Signature theme={null}
arm.moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Publish a single EE twist to `/mcu/command/arm/ee_twist`.

Ghost arm EE twist is expected to be republished by the caller at
high rate for sustained motion — this method publishes once and
returns.

<ParamField>
  Linear velocity in m/s.
</ParamField>

<ParamField>
  Angular velocity in rad/s.
</ParamField>

<ParamField>
  Reference frame is determined by the `ARM_C_B_FRAME` parameter on the robot. The argument is accepted for interface compatibility but does not change the frame.
</ParamField>

### `arm.moveToDeltaPose()`

```python Signature theme={null}
arm.moveToDeltaPose(delta_pose: Pose, blocking: bool = True) -> None
```

Offset the robot end effector by the specified delta pose from its current pose

### `arm.moveToHome()`

```python Signature theme={null}
arm.moveToHome(blocking: bool = True) -> None
```

Move the arm to its predefined home pose.

### `arm.moveToNamedPose()`

```python Signature theme={null}
arm.moveToNamedPose(pose_name: str, blocking: bool = True) -> None
```

Move the robot to the joint angles of a named pose.

### `arm.moveToPose()`

```python Signature theme={null}
arm.moveToPose(
    pose: Pose,
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    publish_rate_hz: float = 100.0,
) -> None
```

Send an end-effector pose target to `/mcu/command/arm/ee_pose`.

The active EE frame (body vs. gripper) is determined by the
`ARM_C_B_FRAME` parameter on the robot. Set it via `setParam`
if you need to change frames.

<ParamField>
  Target EE pose (position in meters, orientation as a unit quaternion).
</ParamField>

<ParamField>
  If True, republish for `moving_time` seconds at `publish_rate_hz`.
</ParamField>

<ParamField>
  Hold duration in seconds when blocking.
</ParamField>

<ParamField>
  Republish rate (the Ghost docs recommend 100 Hz for sustained pose commands).
</ParamField>

### `arm.release()`

```python Signature theme={null}
arm.release() -> None
```

Open the gripper to `open_position`.

### `arm.removeNamedPose()`

```python Signature theme={null}
arm.removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

### `arm.setControlMode()`

```python Signature theme={null}
arm.setControlMode(value: int) -> None
```

Publish to `/command/setControlMode`.

Lower values have higher priority; the Ghost docs recommend
`140` for ROS 2 control and `180` for app/MAVLink.

### `arm.setGripperPosition()`

```python Signature theme={null}
arm.setGripperPosition(position: float) -> None
```

Publish a raw gripper position command (`Float32`).

### `arm.setGripperVelocity()`

```python Signature theme={null}
arm.setGripperVelocity(velocity: float) -> None
```

Publish a raw gripper velocity command (`Float32`).

### `arm.setJointAngles()`

```python Signature theme={null}
arm.setJointAngles(
    angles: List[float],
    blocking: bool = True,
    *,
    moving_time: Optional[float] = None,
    publish_rate_hz: float = 20.0,
) -> None
```

Publish target joint angles for the arm.

Joint position commands take precedence over joint velocity commands
on the Ghost arm, so only the `position` field of the `JointState`
message is set. Pass length `_NUM_JOINTS` to leave the gripper joint
held constant, or `_NUM_JOINTS + 1` to command the full arm.

<ParamField>
  Target joint angles in radians. Length must be `_NUM_JOINTS` or `_NUM_JOINTS + 1`.
</ParamField>

<ParamField>
  If True, republish the command for `moving_time` seconds at `publish_rate_hz`. If False, publish once.
</ParamField>

<ParamField>
  Hold duration in seconds when blocking. Defaults to 2.0 seconds when blocking and unset.
</ParamField>

<ParamField>
  Republish rate while blocking.
</ParamField>

**Raises:**

ValueError: If `angles` does not have length `_NUM_JOINTS` or
`_NUM_JOINTS + 1`.

### `arm.setJointVelocities()`

```python Signature theme={null}
arm.setJointVelocities(
    velocities: list,
    *,
    duration: float = 1.0,
    publish_rate_hz: float = 20.0,
) -> None
```

Publish target joint velocities for the arm.

<ParamField>
  Target joint velocities in rad/s. Length must be `_NUM_JOINTS` or `_NUM_JOINTS + 1`.
</ParamField>

<ParamField>
  Seconds to republish the command.
</ParamField>

<ParamField>
  Republish rate in Hz.
</ParamField>

**Raises:**

ValueError: If `velocities` does not have length `_NUM_JOINTS`
or `_NUM_JOINTS + 1`.

### `arm.setMode()`

```python Signature theme={null}
arm.setMode(field_name: str, value: int) -> None
```

Publish a `robotMode` command (fire-and-forget).

Use `ensureMode` for confirmed sets.

<ParamField>
  Mode field name (e.g. `"arm"`, `"action"`, `"vision_mode"`).
</ParamField>

<ParamField>
  Desired value for that field.
</ParamField>

**Raises:**

ValueError: If `field_name` is not a known Ghost mode field.

### `arm.setParam()`

```python Signature theme={null}
arm.setParam(
    name: str,
    val: list,
    *,
    planner: bool = False,
    n_tries: int = 10,
    wait_seconds: float = 0.05,
) -> None
```

Set a robot or planner parameter via `/mcu/command/param`.

Confirmed by the matching `/mcu/state/param` echo.

<ParamField>
  Parameter name (e.g. `"ARM_PREDEF_CFG"`, `"ARM_PAYLOAD"`).
</ParamField>

<ParamField>
  Parameter value as a list of floats.
</ParamField>

<ParamField>
  True for planner parameters, False for robot parameters.
</ParamField>

<ParamField>
  Maximum publish-and-check attempts.
</ParamField>

<ParamField>
  Pause between attempts.
</ParamField>

**Raises:**

RuntimeError: If `ghost_manager_interfaces` is not installed,
or the parameter set is not confirmed within the retry budget.

### `arm.setPredefinedConfig()`

```python Signature theme={null}
arm.setPredefinedConfig(config_id: int) -> None
```

Send the arm to a predefined configuration via `ARM_PREDEF_CFG`.

Valid values per the Ghost low-level parameters doc are `0` (None)
and `1..8` (predefined configs). The robot resets the parameter
automatically once the arm reaches or fails the requested config.

<ParamField>
  Predefined config id in `[0, 8]`.
</ParamField>

**Raises:**

ValueError: If `config_id` is outside the range `[0, 8]`.
RuntimeError: If `ghost_manager_interfaces` is not available
or the parameter set is not confirmed within the retry budget.

### `arm.stop()`

```python Signature theme={null}
arm.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

### `arm.stow()`

```python Signature theme={null}
arm.stow() -> None
```

Stow the arm to its rest configuration.

**Raises:**

RuntimeError: If the heartbeat doesn't confirm `arm_fsm == 0`
within the retry budget.

### `arm.unstow()`

```python Signature theme={null}
arm.unstow() -> None
```

Unstow the arm so it accepts motion commands.

**Raises:**

RuntimeError: If the heartbeat doesn't confirm `arm_fsm == 1`
within the retry budget (only checked when
`ghost_manager_interfaces` is available).

### `arm.validateGrasp()`

```python Signature theme={null}
arm.validateGrasp() -> bool
```

Check whether the end effector is currently holding an object.

## robot.vision60\_lidar — lidar

Reached as `robot.vision60_lidar`; its methods are `Vision60Lidar`'s and run on the robot.

LiDAR sensor for the Vision60, bridging a ROS 2 `PointCloud2` topic.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `vision60_lidar.cleanup()`

```python Signature theme={null}
vision60_lidar.cleanup() -> None
```

Cleanup lidar resources (no-op; shared node owned by caller).

### `vision60_lidar.getData()`

```python Signature theme={null}
vision60_lidar.getData() -> PointCloud
```

### `vision60_lidar.getPointCloud()`

```python Signature theme={null}
vision60_lidar.getPointCloud() -> Optional[PointCloud]
```

Return the most recently received point cloud, or `None`.

### `vision60_lidar.getState()`

```python Signature theme={null}
vision60_lidar.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `vision60_lidar.stop()`

```python Signature theme={null}
vision60_lidar.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

## Not implemented on this robot

Declared by the interface, raises `NotImplementedError` here: `getJointAngles`, `getJointStates`, `setJointAngles`, `arm.endFreeDrive`, `arm.followJointTrajectory`, `arm.getPose`, `arm.startFreeDrive`.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the five on-board cameras the Vision60 always ships with.
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()`
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# Ghost Robotics Vision60
Source: https://docs.generalrobotics.dev/v2.3/python-api/vision60/vision60

The Ghost Robotics Vision60 as GRID drives it

The Ghost Robotics Vision60 as GRID drives it — what this robot actually implements, with the signatures it actually accepts.

`make_robot("<name>")` returns a `RemoteRobot`. Its attributes are the methods and subcomponents below, and every call runs on the robot; the driver behind it is `Vision60`. Connecting neither starts nor moves the robot — it attaches to one that is already up. A method that fails on the robot arrives as `RuntimeError` naming the original error in its message. The client packages this page uses are preinstalled in every GRID session workspace and in the Python environment the GRID CLI prepares when you run a program with `skill run`; there is nothing to install.

```python theme={null}
from grid_nexus_client import make_robot

robot = make_robot("<vision60-name>")

# `front_left` is a built-in camera: reach it as an attribute.
frame = robot.front_left.getImage()
rgb = frame.decode()                    # -> H x W x 3 RGB ndarray
```

## Methods on the robot

Called as `robot.<method>(...)`.

### `cleanup()`

```python Signature theme={null}
cleanup() -> None
```

Shut down the robot tree; alias kept for the historical Vision60 API.

Equivalent to `shutdown()`: recursive, idempotent, best-effort.

### `enableWalking()`

```python Signature theme={null}
enableWalking() -> None
```

Enable walking mode for the robot.

### `getGPS()`

```python Signature theme={null}
getGPS() -> Optional[dict]
```

Return latest GPS data: position, orientation, linear & angular velocity.

**Returns:**

A dict with `position`, `orientation`, `linear_velocity`,
and `angular_velocity` — or `None` if no GPS message has
been received yet.

### `getIMU()`

```python Signature theme={null}
getIMU() -> Optional[dict]
```

Get the latest IMU reading.

**Returns:**

A dict with `orientation`, `angular_velocity`, and
`linear_acceleration` — or `None` if no IMU message has
been received yet.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the robot orientation from odometry data.

**Returns:**

World-frame orientation, or `None` if no odometry message
has been received yet.

### `getPoseRel()`

```python Signature theme={null}
getPoseRel() -> Optional[Pose]
```

Return the body pose from the Vision60 `mcu/state/rel_pose` topic.

Ghost's firmware publishes this as a PoseStamped where the orientation
is the body's attitude relative to a gravity-aligned ground frame
(from the onboard IMU/EKF). The position field does not carry a
world-frame position — on the hardware sampled, x and y read zero and z
a small non-zero value — so use `getPosition()` / `getState()` when
world-frame position is what's wanted.

**Returns:**

Body pose whose orientation is the gravity-relative attitude and
whose position is not a world-frame position, or `None` if no
message has been received yet.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the robot position from odometry data.

**Returns:**

World-frame position, or `None` if no odometry message
has been received yet.

### `getState()`

```python Signature theme={null}
getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

Recursive walk owned by the base class, following the lifecycle
template: each class contributes only the protected local hook
`_local_state`, and the walk composes the per-component
results into one nested mapping. Subclasses must not replace
this method — per-component state belongs in `_local_state`.

With no `keys`, returns this component's local state merged
with one nested node per subcomponent name — the tree structure
is the nesting itself, and the names mirror `subcomponents`
(and therefore `serialize()` and edge introspection): a
two-arm rig returns `&#123;"left_arm": &#123;"joint_positions": ...&#125;,
"right_arm": &#123;...&#125;&#125;`, and a leaf component returns its local
state alone. A component whose state could not be read (dead
telemetry, not yet started, already shut down) carries an
`"error"` entry — `&#123;"error": "&lt;ExceptionType>: &lt;message>"&#125;`,
with its children still nested alongside — instead of its state
keys. Errors are contained per node: one failing component never
loses the rest of the snapshot, and the walk still descends into
the failing component's children. `"error"` is reserved for
that purpose, and local state keys must not collide with
subcomponent names; a hook violating either is reported as that
node's error.

With `keys`, returns a flat mapping with one entry per match.
Each key is a `/`-separated path through the component tree:
every segment names a subcomponent, and the final segment may
instead name an entry in that component's local state. Because
structure is the nesting, a literal path is the same as plain
indexing — `getState(["left_arm/joint_positions"])` returns
the value of `getState()["left_arm"]["joint_positions"]` — and
a path ending on a subcomponent yields that component's full
nested node. Segments may use shell-style wildcards over
subcomponent names — `*` matches within one chunk and `**`
matches any chain of chunks — so `"*_arm/joint_positions"`
fans out to one entry per arm, keyed by the concrete matched
path. Wildcards never match state entries; only a literal final
segment does. A key that matches nothing raises, so a typo is
loud rather than silently absent. A matched component whose
state read failed yields `&#123;"error": "..."&#125;` at its path.

Keyed reads are lazy: a hook runs only where a key lands — a
literal path executes the final component's hook alone (not the
nodes traversed on the way), a glob executes only the matched
nodes, and each component's hook runs at most once per call
however many keys reach it. Components with a selective-read
hook (`_local_state_entries` — every `Robot` with
registered state getters) go further and execute only the getters a key names, so
a `**` glob probes their registries without touching
hardware. The caller pays only for the state actually
requested; `**` and the no-`keys` form visit the whole tree
because that is the request.

State is cheap by convention: local state carries kinematics,
status, and health — never bulk sensor payloads (camera frames,
point clouds, scans), which stay in their dedicated methods
(`getImage`, `getPointCloud`, ...). Callable on a stopped
tree — reading state after a soft e-stop is when it matters most
— and on a partially started one, where unstarted components
report a per-node error instead of failing the call.

<ParamField>
  State paths to read, or None for the full nested snapshot. A single string is shorthand for a one-element list.
</ParamField>

**Returns:**

The nested state snapshot when `keys` is None, otherwise a
flat mapping of matched path to state value or nested node.

**Raises:**

TypeError: If `keys` is neither None, a string, nor a
list/tuple of strings.
ValueError: If a key is empty, has an empty path segment, or
matches no subcomponent path or state entry.

### `getVelocity()`

```python Signature theme={null}
getVelocity() -> Optional[Velocity]
```

Return the latest body-frame linear velocity (m/s).

Angular velocity is available via `getIMU()` or `getState()`.

**Returns:**

Body-frame linear velocity, or `None` if no base-velocity
message has been received yet.

### `lieDown()`

```python Signature theme={null}
lieDown() -> None
```

Make the robot lie down.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    *,
    duration: Optional[float] = 1.0,
) -> None
```

Command body-frame twist.

The command is republished at `_CMD_RATE_HZ` Hz until a new command
(including `stop`) is issued, or until *duration* seconds elapse —
Vision60's controller treats a gap as "stop", so continuous republish
is required to hold a velocity.

<ParamField>
  Body-frame linear velocity (m/s).
</ParamField>

<ParamField>
  Body-frame angular velocity (rad/s); only the z component is used for yaw.
</ParamField>

<ParamField>
  Reference frame. Only `"body"` is supported.
</ParamField>

<ParamField>
  Seconds to hold the command. Pass `None` to republish indefinitely until `stop()`.
</ParamField>

**Raises:**

NotImplementedError: If `frame == "world"` (matches Go2; world
frame is not supported on Vision60).
ValueError: If `frame` is any value other than `"body"` or
`"world"`.

### `setDefaultJointAngles()`

```python Signature theme={null}
setDefaultJointAngles(joint_pos: list) -> None
```

Set the default joint position for the robot.

<ParamField>
  Value of the joint position.
</ParamField>

### `setDefaultJointVelocities()`

```python Signature theme={null}
setDefaultJointVelocities(joint_vel: list) -> None
```

Set the default joint velocity for the robot.

<ParamField>
  Value of the joint velocity.
</ParamField>

### `standUp()`

```python Signature theme={null}
standUp() -> None
```

Make the robot stand up.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

Recursive walk owned by the base class: every subcomponent is
stopped first (children before their parent, leaf-to-root;
siblings in `subcomponents` insertion order), then this
component's own `_stop_self` hook runs. The walk is
best-effort — a failing component never prevents the rest of the
tree from being stopped; failures are collected and raised
together after the walk completes. Components (and their
subtrees) that have already been shut down are skipped. Safe to
call repeatedly: stopping an already-stopped tree re-runs the
hooks, which must tolerate that. Blocks until every hook has
returned.

Stops motion only; resources stay live and the component remains
usable — telemetry and every other public method keep working on a
stopped tree. Use `shutdown` to release resources. Stopping
re-arms each visited component, so a later `start` re-runs
the bring-up hooks — that is the stop-then-start restart path —
but it does not revoke callability: only `shutdown` does
that.

Subclasses must not replace this method — per-component stop
behavior belongs in `_stop_self`. An override may only
*extend* the walk (adding a driver-specific mode, as `UR5e` does
with its `immediate` escape hatch) and must delegate to
`super().stop()` for the normal path; it must never
re-implement the recursion.

**Raises:**

ComponentStopError: If one or more stop hooks raised. The
walk still visited every component; the exception carries
every `(component_path, exception)` pair.

## robot.front\_left and 4 more — camera

Reached as any of `robot.front_left`, `robot.front_right`, `robot.rear`, `robot.side_left`, `robot.side_right`; each is a `Vision60Camera` and its methods are `Vision60Camera`'s and run on the robot. Below, `<camera>` stands for any one of those names.

Camera sensor for the Vision60, bridging a ROS 2 `Image` topic to the

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `<camera>.cleanup()`

```python Signature theme={null}
<camera>.cleanup() -> None
```

Cleanup camera resources (no-op; shared node owned by caller).

### `<camera>.getCameraExtrinsics()`

```python Signature theme={null}
<camera>.getCameraExtrinsics() -> Optional[np.ndarray]
```

Get the extrinsic parameters for the camera.

### `<camera>.getCameraIntrinsics()`

```python Signature theme={null}
<camera>.getCameraIntrinsics() -> Optional[Tuple[float, float, float, float]]
```

Get the intrinsic parameters for the camera.

### `<camera>.getCameraSettings()`

```python Signature theme={null}
<camera>.getCameraSettings() -> CameraSettings
```

Get the camera settings.

### `<camera>.getData()`

```python Signature theme={null}
<camera>.getData() -> Image
```

Get the image from the camera.

### `<camera>.getImage()`

```python Signature theme={null}
<camera>.getImage() -> Optional[Image]
```

Read image from shared memory file path.

**Returns:**

The latest image as an `Image` object, or `None` if no
image message has been received yet.

### `<camera>.getState()`

```python Signature theme={null}
<camera>.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `<camera>.recordCalibration()`

```python Signature theme={null}
<camera>.recordCalibration(calibration: dict) -> None
```

Install a recorded extrinsic calibration on this camera in place.

### `<camera>.reloadCalibration()`

```python Signature theme={null}
<camera>.reloadCalibration() -> dict
```

Re-read this camera's calibration from the robot's config and install it.

### `<camera>.setCameraExtrinsics()`

```python Signature theme={null}
<camera>.setCameraExtrinsics(transform: np.ndarray) -> None
```

Set the extrinsic parameters for the camera.

### `<camera>.setCameraIntrinsics()`

```python Signature theme={null}
<camera>.setCameraIntrinsics(fx: float, fy: float, cx: float, cy: float) -> None
```

Set the intrinsic parameters for the camera.

### `<camera>.setCameraSettings()`

```python Signature theme={null}
<camera>.setCameraSettings(settings: CameraSettings) -> None
```

Set the camera settings.

### `<camera>.stop()`

```python Signature theme={null}
<camera>.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

## robot.vision60\_lidar — lidar

Reached as `robot.vision60_lidar`; its methods are `Vision60Lidar`'s and run on the robot.

LiDAR sensor for the Vision60, bridging a ROS 2 `PointCloud2` topic.

Methods inherited from the component base are shown in brief here; their full descriptions are under *Methods on the robot* above.

### `vision60_lidar.cleanup()`

```python Signature theme={null}
vision60_lidar.cleanup() -> None
```

Cleanup lidar resources (no-op; shared node owned by caller).

### `vision60_lidar.getData()`

```python Signature theme={null}
vision60_lidar.getData() -> PointCloud
```

### `vision60_lidar.getPointCloud()`

```python Signature theme={null}
vision60_lidar.getPointCloud() -> Optional[PointCloud]
```

Return the most recently received point cloud, or `None`.

### `vision60_lidar.getState()`

```python Signature theme={null}
vision60_lidar.getState(keys: Optional[Union[str, List[str]]] = None) -> Dict[str, Any]
```

Get a live state snapshot of this component's tree.

### `vision60_lidar.stop()`

```python Signature theme={null}
vision60_lidar.stop() -> None
```

Halt all motion across this component's tree (soft e-stop).

## Not implemented on this robot

Declared by the interface, raises `NotImplementedError` here: `getJointAngles`, `getJointStates`, `setJointAngles`.

## Lifecycle and configuration

The driver's own bring-up and configuration hooks. The edge runs them when the robot comes up; do not call them from a program. Note that `robot.shutdown()` on the proxy is not the method below — it is `RemoteRobot.shutdown()`, which closes your connection and leaves the robot as it was.

* `addSensor()` — Add an external sensor to the robot.
* `addSubcomponent()` — Attach a child component under a name.
* `builtin_subcomponents()` — Declare the five on-board cameras the Vision60 always ships with.
* `configHash()` — Hash this component's serialized config subtree.
* `config_schema()`
* `from_config()` — Construct this component and its config-declared subtree.
* `getIdentity()` — Get this component's own hardware identity (serial, model, version, MAC).
* `getRobotId()` — Stable, readable identifier for a robot or rig, for a database key.
* `serialize()` — Serialize this component tree back to its config envelope.
* `setup_shutdown_handlers()` — Register the process-wide atexit and signal handlers for safe teardown.
* `shutdown()` — Shut down this component's tree, halting motion and releasing resources.
* `start()` — Bring this component's tree online (connect, enable, arm).

The contract these methods implement is **Robot interface**; values returned are **grid-types** (camera reads return `Image` — call [`decode()`](/v2.3/python-api/grid-types/image) for an ndarray). You reach the robot through [`make_robot`](/v2.3/python-api/grid-nexus-client/make_robot).


# AirGen Overview
Source: https://docs.generalrobotics.dev/v2.3/simulation/airgen/overview



AirGen is GRID's simulator on Unreal Engine. It targets robots that operate
outdoors and over distance — drones, ground vehicles, and legged platforms —
in large photorealistic environments with controllable weather, time of day,
and geographic anchoring.

It runs alongside [Isaac](/v2.3/simulation/isaac/overview) rather than instead of
it. Pick AirGen when the scene is an outdoor site and the question is
perception, navigation, or flight. Pick Isaac when the question is contact-rich
manipulation or large-scale parallel RL training.

## Key Features

* **Unreal Engine 5.7**: Photorealistic rendering for perception workloads
  where image fidelity is the point.

* **Aerial, ground, and legged robots**: 26 vehicles across multirotors,
  fixed-wing, wheeled and tracked platforms, and quadrupeds — see
  [Robots](/v2.3/simulation/airgen/robots).

* **Large outdoor environments**: Substations, oil rigs, forests, warehouses,
  and planetary surfaces — see [Scenes](/v2.3/simulation/airgen/scenes).

* **Geographically anchored**: Anchor the world origin to real latitude and
  longitude so GPS output matches a real site.

* **Controllable conditions**: Weather, wind, and a celestial clock that drives
  sun position from a wall-clock datetime.

* **One robot interface**: AirGen robots implement the same
  [Robot interface](/v2.3/python-api/robot-interface/overview) as physical machines,
  so `getImage()` and `moveByVelocity()` mean the same thing in simulation and
  on hardware.

## Start a sim

```text theme={null}
GRID # sim start
```

Pick **airgen**, then a scene and a robot. The CLI provisions a GPU-backed
session in the cloud and opens a VS Code workspace with a notebook whose first
cell already holds your robot:

```python theme={null}
from grid_sim_client.airgen.robot import AirGenDrone

drone = AirGenDrone()
drone.takeoff()
image = drone.getImage("front")
```

## Where next

* [Robots](/v2.3/simulation/airgen/robots) — the vehicle catalog and which class drives each
* [Scenes](/v2.3/simulation/airgen/scenes) — the environments you can launch into
* [Sensors](/v2.3/simulation/airgen/sensors) — cameras, lidar, IMU, GPS, and more
* [Session configuration](/v2.3/simulation/airgen/session_configuration) — weather, time of day, and camera setup
* [AirGen robots](/v2.3/python-api/airgen-robots/overview) — the Python API reference


# Robots
Source: https://docs.generalrobotics.dev/v2.3/simulation/airgen/robots



AirGen ships 26 vehicles. Each one is driven from Python by one of three
classes, chosen by the vehicle's physics model — you pick the robot by id when
you start the session, and the notebook instantiates the matching class for
you.

| Python class | Drives | Physics |
| - | - | - |
| [`AirGenDrone`](/v2.3/python-api/airgen-robots/airgendrone) | Multirotors and fixed-wing aircraft | `simpleflight`, `jsb` |
| [`AirGenCar`](/v2.3/python-api/airgen-robots/airgencar) | Wheeled and tracked ground vehicles | `chaos` |
| [`AirGenQuad`](/v2.3/python-api/airgen-robots/airgenquad) | Legged robots | `cvmover` |

## Aerial

Multirotors, flown through `AirGenDrone` on AirGen's `simpleflight` model.

| Robot id | Notes |
| - | - |
| `default_drone` | Generic quadrotor — the starting point if you have no specific airframe in mind |
| `astro` | Small survey quadrotor |
| `altax` | Heavy-lift platform |
| `holybro_s500` | Holybro S500 development quadrotor |
| `holybro_x500` | Holybro X500 development quadrotor |
| `matrice_300_rtk` | DJI Matrice 300 RTK — industrial inspection airframe |
| `starling2` | ModalAI Starling 2 |
| `starling2_max` | ModalAI Starling 2 Max |
| `evtol` | Electric vertical take-off and landing aircraft |

Fixed-wing runs on the JSBSim flight-dynamics model and is also driven through
`AirGenDrone`:

| Robot id | Notes |
| - | - |
| `f15e` | Fixed-wing aircraft on JSBSim |

## Ground

Wheeled and tracked vehicles, driven through `AirGenCar` on Unreal's Chaos
vehicle physics.

| Robot id | Notes |
| - | - |
| `husky` | Clearpath Husky UGV |
| `scout2` | AgileX Scout 2 |
| `hunter` | AgileX Hunter — Ackermann steering |
| `rover` | Generic exploration rover |
| `mcr` | Compact tracked robot |
| `jetbot` | NVIDIA JetBot — small differential-drive platform |
| `robomaster_s1` | DJI RoboMaster S1 |
| `farmng_amiga` | farm-ng Amiga agricultural platform |
| `tractor` | Agricultural tractor |
| `forklift` | Warehouse forklift |
| `sports_car` | Passenger car, for road and traffic scenes |

## Legged

Quadrupeds, driven through `AirGenQuad`.

| Robot id | Notes |
| - | - |
| `unitree_go2` | Unitree Go2 — the same platform GRID drives on real hardware |
| `unitree_go2_purple` | Unitree Go2, alternate livery |
| `ghost_v60` | Ghost Robotics Vision 60 |
| `cvmover_default` | Generic legged platform |

## Camera-only

| Robot id | Notes |
| - | - |
| `computer_vision` | A free-flying camera with no vehicle physics. Move it to a pose and capture — useful for building perception datasets without flying anything. |

<Note>
  `unitree_go2` and `ghost_v60` also exist as physical robots GRID drives through
  [grid-nexus-client](/v2.3/python-api/grid-nexus-client/overview). Because both the
  simulated and physical versions implement the same
  [Robot interface](/v2.3/python-api/robot-interface/overview), a skill you develop
  against the simulated Go2 runs against the real one.
</Note>


# Scenes
Source: https://docs.generalrobotics.dev/v2.3/simulation/airgen/scenes



A scene is the environment your robot spawns into. You pick one when you start
the sim:

```text theme={null}
GRID # sim start
```

## Industrial and infrastructure

| Scene | Description |
| - | - |
| `substation` | Electrical substation with transformers and power lines |
| `electric_central` | Power-generation site with wind turbines |
| `oil_rig` | Offshore oil rig with platforms, cranes, and walkways |
| `warehouse_big` | Large warehouse environment |
| `hangar` | Airplane hangar environment |

These are the inspection scenes — tight geometry, repeated structure, and the
kind of clutter that makes visual navigation hard.

## Outdoor and natural

| Scene | Description |
| - | - |
| `nordic_forest` | Nordic forest environment with trees, rocks, and terrain |
| `forest_fire` | Forest fire scenario with trees, smoke, and fire effects |
| `abandoned_building` | Abandoned building and surroundings with debris and narrow passages |

`forest_fire` carries live smoke and fire effects, which makes it the useful
one for testing perception under degraded visibility.

## Planetary

| Scene | Description |
| - | - |
| `moon` | Moon surface environment with craters and rocks |
| `mars` | Mars surface environment with rocks, dust, and terrain |

## Minimal

| Scene | Description |
| - | - |
| `blocks` | Simple Blocks environment |
| `empty` | Empty world |

`blocks` is the fastest scene to load and the right default when you are
testing control logic rather than perception. `empty` gives you a bare world to
place your own objects into.

<Note>
  Scene availability depends on your organization's asset access. If a scene you
  expect is missing from the CLI picker, reach out on our
  [Discord Community](https://discord.gg/yPtfUNDe5M) or by
  [email](mailto:info@generalrobotics.company).
</Note>


# Sensors
Source: https://docs.generalrobotics.dev/v2.3/simulation/airgen/sensors



Every AirGen robot carries a sensor suite you read through ordinary method
calls. Each sensor takes a name, so a robot can carry several of the same kind
— the defaults below are what a stock vehicle ships with.

## Cameras

Images come back through the shared
[`getImage()`](/v2.3/python-api/robot-interface/robot#getimage) method, which every
GRID robot has, simulated or physical:

```python theme={null}
image = drone.getImage("front")
```

Cameras are configured per session — resolution, field of view, and stream type
(RGB, depth, segmentation) are all set in the session configuration. See
[Session configuration](/v2.3/simulation/airgen/session_configuration) for the
camera block, including the noise overlay for testing perception against
degraded video.

## Lidar

```python theme={null}
points = drone.getLidarData("front_lidar")
```

Returns a point cloud from the named lidar. Default name: `front_lidar`.

## IMU

```python theme={null}
imu = drone.getImuData("imu")
```

Accelerometer and gyroscope readings. Default name: `imu`.

## GPS

```python theme={null}
fix = drone.getGpsData("gps")
```

Latitude, longitude, and altitude. GPS output is anchored to the world origin
you set in the session configuration, so you can place a scene at real
coordinates and get plausible fixes out of it. Default name: `gps`.

## Barometer

```python theme={null}
pressure = drone.getBarometerData("barometer")
```

Air pressure and derived altitude. Default name: `barometer`.

## Magnetometer

```python theme={null}
field = drone.getMagnetometerData("magnetometer")
```

Magnetic field vector, for heading estimation. Default name: `magnetometer`.

## Distance sensor

```python theme={null}
distance = drone.getDistanceSensorData("front_range")
```

Single-beam range reading. Default name: `front_range`.

## State

Pose and velocity come through the shared robot methods rather than a sensor:

```python theme={null}
drone.getState()
drone.getPosition()
drone.getOrientation()
```

<Note>
  Sensor availability varies by vehicle — a ground robot has no barometer worth
  reading. The full method list for each class is in the
  [AirGen robots](/v2.3/python-api/airgen-robots/overview) reference.
</Note>


# Session Configuration
Source: https://docs.generalrobotics.dev/v2.3/simulation/airgen/session_configuration



An AirGen session is described by one config file: which robot, which scene,
what the cameras look like, and what the world conditions are. The CLI writes a
working config when you start a session — you edit it when you need something
the picker doesn't offer.

## Robot and scene

```yaml theme={null}
scenario:
  id: substation
robots:
  - id: astro
    name: drone
    pose:
      position: [0.0, 0.0, -5.0]
      orientation_rpy_deg: [0.0, 0.0, 90.0]
```

`id` values come from the catalogs in [Robots](/v2.3/simulation/airgen/robots) and
[Scenes](/v2.3/simulation/airgen/scenes). `name` is what you address the vehicle by
from Python.

<Warning>
  Poses are in the **NED frame** — X north, Y east, Z **down**. A negative Z is
  above the ground. This is an aviation convention and it is a common source of
  confusion if you are coming from Isaac, which is Z-up.
</Warning>

Orientation is either `orientation_rpy_deg` (roll, pitch, yaw in degrees) or
`rotation_wxyz` (quaternion). Set one, not both.

## Cameras

```yaml theme={null}
cameras:
  - name: front
    streams:
      - type: rgb
        width: 1280
        height: 720
      - type: depth
        width: 640
        height: 480
```

Each camera can carry several streams, so one physical viewpoint yields RGB and
depth together.

### Noise overlay

Cameras support a noise overlay for testing perception against degraded video —
sensor grain, horizontal wave distortion, and scan-line artifacts:

```yaml theme={null}
cameras:
  - name: front
    noise:
      enabled: true
      rand_contrib: 0.2
      rand_size: 0.01
      horz_wave_contrib: 0.1
      horz_wave_strength: 0.05
```

Every field is optional; the ones you omit keep the engine default.

## World conditions

### Geographic origin

Anchor the world origin to real coordinates so GPS output matches a real site:

```yaml theme={null}
extensions:
  origin_geopoint:
    latitude: 47.641468
    longitude: -122.140165
    altitude: 122.0
```

### Time of day

Sun position is driven by a wall-clock datetime:

```yaml theme={null}
extensions:
  time_of_day:
    enabled: true
    start_datetime: "2026-06-21 06:30:00"
    utc_offset: -7.0
    celestial_clock_speed: 1.0
```

`celestial_clock_speed` multiplies how fast the sun moves — raise it to sweep a
whole day of lighting in a short run.

### Viewport

```yaml theme={null}
extensions:
  view_mode: SpringArmChase
```

Accepted values: `Fpv`, `GroundObserver`, `FlyWithMe`, `Manual`,
`SpringArmChase`, `Backup`, `NoDisplay`, `Front`. This controls only what the
streamed viewport shows — it has no effect on the robot or on
`getImage()` output.

<Note>
  The config is validated strictly: an unknown key is an error rather than a
  silently ignored line, so a typo fails `sim start` instead of quietly doing
  nothing.
</Note>


# ROS2 Communication
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/comms



In order to enable seamless integration of GRID into your current robotics stack, we provide ROS2 support with Isaac. This enables users to both publish data from the simulation as well as receive commands into the simulation to execute.

## Publishing Simulation Data

In order to publish simulation data, we provide support for a list of message types the details of which are provided below:

| Message Type | Configurable Parameters | Description |
| - | - | - |
| **RGBImage** | `msg_type: "sensor_msgs/Image"`, <br /> `target: "name_of_rgb_camera"`, <br /> `msg_name: "name_of_topic"` | RGB image frames |
| **DepthImage** | `msg_type: "sensor_msgs/Image"`, <br /> `target: "name_of_depth_camera"`, <br /> `msg_name: "name_of_topic"` | Depth image frames |
| **BasePose** | `msg_type: "geometry_msgs/Pose"`, <br /> `target: "name_of_robot"`, <br /> `body_name: "name_of_body"`, <br /> `msg_name: "name_of_topic"` | Pose of the robot’s base link |
| **EndEffectorPose** | `msg_type: "geometry_msgs/Pose"`, <br /> `target: "name_of_robot"`, <br /> `link_name: "name_of_link"`, <br /> `msg_name: "name_of_topic"` | Pose of the end-effector link (e.g. `panda_hand`) |
| **JointState** | `msg_type: "sensor_msgs/JointState"`, <br /> `target: "name_of_robot"`, <br /> `msg_name: "name_of_topic"` | Current joint states of the robot |
| **ContactForces** | `msg_type: "geometry_msgs/Wrench"`, <br /> `target: "name_of_contact_sensor"`, <br /> `msg_name: "name_of_topic"` | Contact force/torque readings |
| **LidarScan** | `msg_type: "sensor_msgs/PointCloud2"`, <br /> `target: "name_of_lidar"`, <br /> `msg_name: "name_of_topic"` | Point-cloud data from the LiDAR |
| **ImuData** | `msg_type: "sensor_msgs/msg/Imu"`, <br /> `target: "name_of_imu"`, <br /> `msg_name: "name_of_topic"` | IMU (accelerometer/gyroscope) measurements |
| **GPSOdometry** | `msg_type: "nav_msgs/msg/Odometry"`<br />`target: "name_of_robot"`<br />`body_name: "root"`<br />`msg_name: "name_of_topic"`<br />`info: {}` | Publishes full 6-DoF odometry (position, orientation, linear & angular velocity) of the robot’s root link, as from “GPS”. |
| **Quaternion\_Z\_Relative** | `msg_type: "geometry_msgs/msg/Quaternion"`<br />`target: "name_of_height_sensor"`<br />`msg_name: "name_of_topic"`<br />`body_name: "root"`<br />`info: { art_body: "robot" }` | Computes and publishes the Z-axis–only relative orientation quaternion between the robot and the ground plane under a raycaster sensor. |
| **CameraInfo** | `msg_type: "sensor_msgs/msg/CameraInfo"`<br />`target: "name_of_rgb_camera"`<br />`msg_name: "name_of_topic"`<br />`info: {}` | Publishes camera calibration data (image size, distortion coefficients D, intrinsic K, rectification R, projection P) flattened. |

An example of how to publish simulation data using `env.yaml` is as follows:

```yaml theme={null}
comms:
  - name_of_camera_msg:
      type: RGBImage
      config:
        target: camera_rgb_0 # name of the camera sensor
        msg_name: /robot/camera_rgb_0 # name of the topic to publish data
```

## Subscribing to Commands

We also allow users to send commands to the robot in the simulation session. Here is the list of commands we support.

| ROS2 Msg Type | Description |
| - | - |
| `sensor_msgs/JointState` | Command message to set robot joint positions |
| `geometry_msgs/Twist` | Command message to control base linear/angular velocity |
| `geometry_msgs/Pose` | Command message to set end-effector delta pose |

For each command, users need to specify the name of the topic to which they are publishing the specific message and the target command name from the `commands` entity specified in the `mdp.yaml`.
An example of how to use commands in `env.yaml` is as follows:

```yaml theme={null}
comms:
  - name_of_the_command_msg:
      type: Commands
      config:
        target: base_velocity # this is the name of the command 
        msg_name: /base_vel_cmd # this is the name of the topic to which the user is publishing
```

<Note>
  We are constantly updating our offering of supported message types, please let us know on our [Discord Community](https://discord.gg/yPtfUNDe5M) or reach out to us on our [email](mailto:info@generalrobotics.company).
</Note>


# Overview
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/overview



GRID provides users the access to Isaac Sim for large-scale data generation, evaluation, and training for robot learning.
It supports a wide range of robots including manipulators, quadrupeds, and humanoids—across diverse environments such as warehouses, hospitals, offices, and tabletop scenes.

![Isaac Overview](https://downloads.generalrobotics.dev/docs-assets/ecf2a88f5a5c/isaac_overview.png)

<br />

## Key Features

* **Isaac Sim 5.1 Ready**: GRID builds on top of NVIDIA Isaac Sim, enabling you to leverage the latest features in Isaac Sim.

* **Parallelized RL Training**: Support for training thousands of parallel agents in simulation for a number of diverse tasks.

* **Large-Scale Data Generation**: Generate high-quality simulation data at scale using teleoperation, motion planning, and reinforcement learning.

* **Advanced Locomotion and Manipulation Capabilities**: Access pre-trained policies for various robots, enabling complex movements and interactions across different environments.


# Customizing RL Training
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/reinforcement-learning/customizing-training



Users can customize the core MDP components — observations, commands, actions, rewards, events, and terminations — when training RL agents using GRID.
By configuring these elements, you can tailor environment feedback and control interfaces to fit specific robotics tasks and training objectives.

## Observations

Observations list each measurable quantity the environment can return, the configuration options for specifying which asset or sensor to observe, and a description of what the measurement represents.

| Observation Function | Configurable Options | Description |
| - | - | - |
| base\_pos\_z | asset\_cfg.name | Root height in the simulation world frame. |
| base\_lin\_vel | asset\_cfg.name | Root linear velocity in the asset’s root frame. |
| base\_ang\_vel | asset\_cfg.name | Root angular velocity in the asset’s root frame. |
| projected\_gravity | asset\_cfg.name | Gravity projection on the asset’s root frame. |
| root\_pos\_w | asset\_cfg.name | Asset root position in the environment frame. |
| root\_quat\_w | make\_quat\_unique (`bool`), asset\_cfg.name | Asset root orientation (w, x, y, z) in the environment frame. |
| root\_lin\_vel\_w | asset\_cfg.name | Asset root linear velocity in the environment frame. |
| root\_ang\_vel\_w | asset\_cfg.name | Asset root angular velocity in the environment frame. |
| body\_pose\_w | asset\_cfg.name, body\_ids (`list[int]`) | Flattened body poses of the asset w\.r.t. environment origin (x, y, z, qw, qx, qy, qz) for each configured body. |
| projected\_gravity | asset\_cfg.name, body\_ids (`list[int]`) | Direction of gravity projected onto each body frame (x, y, z) for configured bodies. |
| joint\_pos | asset\_cfg.name | Joint positions of the asset. |
| joint\_pos\_rel | asset\_cfg.name | Joint positions relative to default joint positions. |
| joint\_pos\_limit\_normalized | asset\_cfg.name | Joint positions normalized by the asset’s soft position limits. |
| joint\_vel | asset\_cfg.name | Joint velocities of the asset. |
| joint\_vel\_rel | asset\_cfg.name | Joint velocities relative to default joint velocities. |
| joint\_effort | asset\_cfg.name | Joint applied effort (torque) for configured joints. |
| height\_scan | sensor\_cfg.name, offset (float) | Height scan from the sensor’s frame minus the given offset. |
| body\_incoming\_wrench | asset\_cfg.name, body\_ids (`list[int]`) | 6-D spatial wrench (force, torque) applied to each configured body link by joint forces. |
| imu\_orientation | asset\_cfg.name | IMU sensor orientation in world frame as quaternion (w, x, y, z). |
| imu\_ang\_vel | asset\_cfg.name | IMU sensor angular velocity (rad/s) in sensor frame. |
| imu\_lin\_acc | asset\_cfg.name | IMU sensor linear acceleration (m/s²) in sensor frame. |
| image | sensor\_cfg.name, data\_type (`str`), convert\_perspective\_to\_orthogonal (`bool`), normalize (`bool`) | Images from a camera or ray-caster camera (e.g., “rgb”, “depth”). Optionally normalize and orthogonalize depth. |
| image\_features | sensor\_cfg.name, data\_type (`str`), model\_zoo\_cfg (`dict`), model\_name (`str`), model\_device (`str`) | Extracted image features via a pretrained encoder (e.g., ResNet, Theia). |
| last\_action | action\_name (`str` or None) | The last input action term (or full action tensor if None). |
| velocity\_commands | params.command\_name ("base\_velocity") | Generated command tensor for base‐velocity commands. |
| ee\_pose\_commands | params.command\_name ("ee\_pose") | Generated command tensor for end‐effector pose commands. |
| base\_pose\_commands | params.command\_name ("base\_pose") | Generated command tensor for base‐pose commands. |
| target\_object\_position\_in\_robot\_root\_frame | params.command\_name ("object\_pose") | Generated command tensor for the target object’s pose in the robot’s root frame. |

#### Robot-Specific Observation Terms

| Observation Term | Robot | Configurable Options | Description |
| - | - | - | - |
| joint\_pos\_rel\_digit | Agility Digit | noise.n\_min, noise.n\_max, params.asset\_cfg.name, params.asset\_cfg.joint\_names | Digit-group joint positions relative to defaults (regex match). |
| joint\_vel\_rel\_digit | Agility Digit | noise.n\_min, noise.n\_max, params.asset\_cfg.name, params.asset\_cfg.joint\_names | Digit-group joint velocities relative to defaults. |
| joint\_pos\_rel\_left\_arm | Unitree G1 (27 DOF) | noise.n\_min, noise.n\_max, params.asset\_cfg.name, params.asset\_cfg.joint\_names | Left-arm joint positions relative to defaults (explicit list). |
| joint\_vel\_rel\_left\_arm | Unitree G1 (27 DOF) | noise.n\_min, noise.n\_max, params.asset\_cfg.name, params.asset\_cfg.joint\_names | Left-arm joint velocities relative to defaults. |

## Commands

Commands define the functions available to sample or set asset poses or velocities, along with the configurable parameters that control how those commands are generated or applied.

| Command Function | Configurable Options | Description |
| - | - | - |
| UniformPose2dCommand | asset\_name, cfg.ranges.pos\_x (`tuple`), cfg.ranges.pos\_y (`tuple`), cfg.ranges.heading (`tuple`), cfg.simple\_heading (`bool`), cfg.resampling\_time\_range (`tuple`) | Sample a random 2D position around the environment origin and a heading (either toward target or uniform). |
| TerrainBasedPose2dCommand | asset\_name, cfg.ranges.heading (`tuple`), cfg.simple\_heading (`bool`), cfg.resampling\_time\_range (`tuple`) | Sample a random 2D position from valid terrain patches and a heading (either toward target or uniform). |
| UniformPoseCommand | asset\_name, body\_name, cfg.ranges.pos\_x (`tuple`), cfg.ranges.pos\_y (`tuple`), cfg.ranges.pos\_z (`tuple`), cfg.ranges.roll (`tuple`), cfg.ranges.pitch (`tuple`), cfg.ranges.yaw (`tuple`), cfg.make\_quat\_unique (`bool`), cfg.resampling\_time\_range (`tuple`) | Sample a random 3D pose (position + quaternion) in the robot’s base frame uniformly within specified ranges. |
| UniformVelocityCommand | asset\_name, cfg.ranges.lin\_vel\_x (`tuple`), cfg.ranges.lin\_vel\_y (`tuple`), cfg.ranges.ang\_vel\_z (`tuple`), cfg.heading\_command (`bool`), cfg.ranges.heading (`tuple`), cfg.rel\_heading\_envs (`float`), cfg.rel\_standing\_envs (`float`), cfg.resampling\_time\_range (`tuple`) | Sample a random base-frame linear (x,y) and yaw velocity (either uniform or based on heading error), with optional standing/no-motion environments. |
| NormalVelocityCommand | asset\_name, cfg.ranges.mean\_vel (`tuple` of 3), cfg.ranges.std\_vel (`tuple` of 3), cfg.ranges.zero\_prob (`tuple` of 3), cfg.rel\_standing\_envs (`float`), cfg.resampling\_time\_range (`tuple`) | Sample a base-frame velocity command from a normal distribution (with element-wise zeroing and optional standing). |

## Actions

Actions enumerate the terms that transform high-level input vectors into specific joint or base control targets — such as positions, velocities, or torques—along with their associated configuration options.

| Action Term | Configurable Options | One-line Meaning |
| - | - | - |
| BinaryJointPositionAction | cfg.joint\_names (list of joint names), cfg.open\_command\_expr (`string`), cfg.close\_command\_expr (`string`) | Map a binary (open/close) action to joint position targets for specified joints. |
| BinaryJointVelocityAction | cfg.joint\_names (list of joint names), cfg.open\_command\_expr (`string`), cfg.close\_command\_expr (`string`) | Map a binary (open/close) action to joint velocity targets for specified joints. |
| JointPositionToLimitsAction | cfg.joint\_names (`list`), cfg.scale (`float` or dict mapping joint→scale), cfg.rescale\_to\_limits (`bool`) | Scale raw inputs and (optionally) rescale to joint position limits before applying as position targets. |
| EMAJointPositionToLimitsAction | cfg.joint\_names (`list`), cfg.scale (`float` or `dict`), cfg.rescale\_to\_limits (`bool`), cfg.alpha (float or dict mapping joint→EMA weight) | Like JointPositionToLimitsAction, but applies exponential moving average (α) over processed position targets. |
| JointPositionAction | cfg.joint\_names (`list`), cfg.scale (`float` or `dict`), cfg.offset (`float` or `dict`), cfg.use\_default\_offset (`bool`) | Affinely transform input actions (scale + offset) and send as joint position targets. |
| RelativeJointPositionAction | cfg.joint\_names (`list`), cfg.scale (`float` or `dict`), cfg.offset (`float` or `dict`), cfg.use\_zero\_offset (`bool`) | Affinely transform input and add to current joint positions before sending as position commands. |
| JointVelocityAction | cfg.joint\_names (`list`), cfg.scale (`float` or `dict`), cfg.offset (`float` or `dict`), cfg.use\_default\_offset (`bool`) | Affinely transform input and send as joint velocity targets. |
| JointEffortAction | cfg.joint\_names (`list`), cfg.scale (`float` or `dict`), cfg.offset (`float` or `dict`) | Affinely transform input and send as joint effort targets. |
| NonHolonomicAction | cfg.x\_joint\_name (`str`), cfg.y\_joint\_name (`str`), cfg.yaw\_joint\_name (`str`), cfg.body\_name (`str`), cfg.scale (`tuple[2]`), cfg.offset (`tuple[2]`) | Map a 2D action (forward speed, yaw rate) to dummy joint velocities (x, y, yaw) for a skid-steer base. |
| DifferentialInverseKinematicsAction | cfg.joint\_names (`list`), cfg.body\_name (`str`), cfg.scale (`list` of `floats`), cfg.controller (DifferentialIK config), cfg.body\_offset (optional pos/rot tuples) | Apply scaled end-effector pose commands through a differential IK controller to produce joint position targets. |
| PretrainedPolicyAction | cfg.asset\_name (`str`), cfg.policy\_path (`str`), cfg.low\_level\_decimation (`int`), cfg.low\_level\_actions (ActionCfg), cfg.low\_level\_observations (`ObservationCfg`) | Use a pretrained low-level policy (e.g. locomotion) to decode actions in a hierarchical setup (e.g. navigation on top). |

## Rewards

Rewards describe the available functions for assigning scalar feedback to agent behaviors, detail any options required to configure them, and explain the physical or task-related criterion they encourage or penalize.

| Reward Function | Configurable Options | Description |
| - | - | - |
| is\_alive | none | +1 if the episode is still running (not terminated). |
| is\_terminated | none | +1 if the episode just terminated (penalizes any termination). |
| is\_terminated\_term | term\_keys (`string`, list of strings or regex) | Sum of specified non-timeout termination terms. |
| lin\_vel\_z\_l2 | asset\_cfg.name | Penalize squared z-axis base linear velocity. |
| ang\_vel\_xy\_l2 | asset\_cfg.name | Penalize squared x/y components of base angular velocity. |
| flat\_orientation\_l2 | asset\_cfg.name | Penalize deviation from a flat base orientation (projected gravity). |
| base\_height\_l2 | target\_height (`float`), asset\_cfg.name | Penalize squared deviation of base height from target. |
| body\_lin\_acc\_l2 | asset\_cfg.name | Penalize summed L2 norm of all body linear accelerations. |
| joint\_torques\_l2 | asset\_cfg.name | Penalize squared torques on configured joints. |
| joint\_vel\_l1 | asset\_cfg.name | Penalize absolute joint velocities (L1). |
| joint\_vel\_l2 | asset\_cfg.name | Penalize squared joint velocities. |
| joint\_acc\_l2 | asset\_cfg.name | Penalize squared joint accelerations. |
| joint\_deviation\_l1 | asset\_cfg.name | Penalize absolute deviation from default joint positions. |
| joint\_pos\_limits | asset\_cfg.name | Penalize violations of soft joint-position limits. |
| joint\_vel\_limits | soft\_ratio (`float`), asset\_cfg.name | Penalize violations of soft joint-velocity limits (clipped). |
| applied\_torque\_limits | asset\_cfg.name | Penalize mismatch between applied and computed torques. |
| action\_rate\_l2 | none | Penalize squared change in actions from one step to the next. |
| action\_l2 | none | Penalize squared magnitude of the actions themselves. |
| undesired\_contacts | threshold (`float`), sensor\_cfg.name | Penalize count of contact events whose force exceeds threshold. |
| contact\_forces | threshold (`float`), sensor\_cfg.name | Penalize amount by which contact forces exceed threshold. |
| track\_lin\_vel\_xy\_exp | std (`float`), command\_name (`str`), asset\_cfg.name | Reward (exp-kernel) how well base xy-velocity matches command. |
| track\_ang\_vel\_z\_exp | std (`float`), command\_name (`str`), asset\_cfg.name | Reward (exp-kernel) how well yaw velocity matches command. |
| air\_time | mode\_time (`float`), velocity\_threshold (`float`), asset\_cfg.name (`str`), sensor\_cfg.name (`str`), sensor\_cfg.body\_names (regex) | Reward for limbs airborne above the velocity threshold. |
| air\_time\_variance\_penalty | sensor\_cfg.name (`str`), sensor\_cfg.body\_names (regex) | Penalize uneven airborne time across limbs. |
| base\_angular\_velocity | std (`float`), asset\_cfg.name (`str`) | Reward (Gaussian) on the magnitude of base angular velocity. |
| base\_linear\_velocity | std (`float`), ramp\_rate (`float`), ramp\_at\_vel (`float`), asset\_cfg.name (`str`) | Reward (Gaussian with ramp) on base linear velocity. |
| foot\_clearance | std (`float`), tanh\_mult (`float`), target\_height (`float`), asset\_cfg.name (`str`) | Reward for foot clearance above a target height. |
| base\_motion | asset\_cfg.name (`str`) | Penalize any base movement (encourages stationarity). |
| base\_orientation | asset\_cfg.name (`str`) | Penalize deviation from upright base orientation. |
| foot\_slip | asset\_cfg.name (`str`), sensor\_cfg.name (`str`), sensor\_cfg.body\_names (regex), threshold (`float`) | Penalize foot-slip events when force exceeds the threshold. |
| joint\_pos | asset\_cfg.name (`str`), stand\_still\_scale (`float`), velocity\_threshold (`float`) | Penalize deviation from reference joint positions when stationary. |
| joint\_torques | asset\_cfg.name (`str`) | Penalize high joint-torque usage on configured joints. |
| termination\_penalty | none | Large penalty applied when the episode terminates. |

#### Task-Specific Reward Terms

| Reward Function | Configurable Options | Description | Task Name |
| - | - | - | - |
| position\_tracking\_error | std (`float`), command\_name (`str`) | Reward (tanh) on base position tracking accuracy. | Navigation |
| orientation\_tracking\_error | command\_name (`str`) | Penalize heading error relative to the commanded orientation. | Navigation |
| object\_ee\_distance | std (`float`) | Reward (Gaussian) on the distance between the end-effector and the object. | Manipulation Lift Object |
| object\_is\_lifted | minimal\_height (`float`) | Reward (binary) for the object being lifted above the minimal height threshold. | Manipulation Lift Object |
| object\_goal\_distance | std (`float`), minimal\_height (`float`), command\_name (`str`) | Reward (Gaussian) on the object's distance to the goal pose after lifting. | Manipulation Lift Object |
| track\_lin\_vel\_xy\_exp | std (`float`), command\_name (`str`), asset\_cfg.name | Reward (exp-kernel) how well base xy-velocity matches command. | Velocity Tracking |
| track\_ang\_vel\_z\_exp | std (`float`), command\_name (`str`), asset\_cfg.name | Reward (exp-kernel) how well yaw velocity matches command. | Velocity Tracking |
| track\_orientation\_inv\_l2 | `object_cfg` (`SceneEntityCfg("object")`), `rot_eps` (`float`), `command_name` (`str`) | Reward (inverse-L2) encouraging alignment of object orientation with the commanded pose. | Manipulation In-Hand |
| success\_bonus\_inhand | `object_cfg` (`SceneEntityCfg("object")`), `command_name` (`str`) | Bonus reward upon successful completion of the in-hand manipulation task. | Manipulation In-Hand |

#### Robot-Specific Reward Terms

| Reward Function | Robot | Configurable Options | Description |
| - | - | - | - |
| left\_wrist\_end\_effector\_position\_tracking | Unitree G1 (27 DOF) | asset\_cfg.name, body\_names, command\_name, shift | Penalize deviation of the left-wrist end-effector position from the commanded target. |
| left\_wrist\_end\_effector\_position\_tracking\_fine\_grained | Unitree G1 (27 DOF) | asset\_cfg.name, body\_names, std, command\_name, shift | Reward (tanh) on fine-grained left-wrist position tracking accuracy. |
| left\_wrist\_end\_effector\_orientation\_tracking | Unitree G1 (27 DOF) | asset\_cfg.name, body\_names, command\_name, tol | Penalize orientation error of the left-wrist end-effector relative to the command. |
| left\_hand\_joint\_range\_violation | Unitree G1 (27 DOF) | asset\_cfg.name, joint\_names, limits\_min, limits\_max | Penalize any left-hand joints outside the specified minimum/maximum limits. |

## Events

Events list environment-level operations that introduce randomized or deterministic changes — such as randomizing physical properties or applying external forces—along with the parameters needed to specify how those changes are applied.

| Event Function | Configurable Options | Description |
| - | - | - |
| randomize\_rigid\_body\_scale | env\_ids, scale\_range (`tuple[float, float]` or `dict{x, y, z → tuple[float, float]}`), asset\_cfg.name, relative\_child\_path (optional) | Randomize the USD-scale of a rigid‐body asset (or a specified child prim) before simulation starts. |
| randomize\_robot\_body\_material | env\_ids, static\_friction\_range (`tuple[float, float]`), dynamic\_friction\_range (`tuple[float, float]`), restitution\_range (`tuple[float, float]`), num\_buckets (int), asset\_cfg.name, make\_consistent (`bool`) | Sample a set of friction/restitution “buckets” and assign them to each geometry of the specified robot Articulation. |
| randomize\_object\_body\_material | env\_ids, static\_friction\_range (`tuple[float, float]`), dynamic\_friction\_range (`tuple[float, float]`), restitution\_range (`tuple[float, float]`), num\_buckets (int), asset\_cfg.name, make\_consistent (`bool`) | Sample a set of friction/restitution “buckets” and assign them to each geometry of the specified RigidObject. |
| randomize\_rigid\_body\_mass | env\_ids, asset\_cfg.name, mass\_distribution\_params (`tuple[float, float]`), operation (“add”/“scale”/“abs”), distribution (“uniform”/“log\_uniform”/“gaussian”), recompute\_inertia (`bool`) | Randomize per‐body mass values (add/scale/overwrite) and optionally recompute inertia tensors from default mass. |
| randomize\_rigid\_body\_com | env\_ids, com\_range (`dict{x, y, z → tuple[float, float]}`), asset\_cfg.name | Add a random offset to the center of mass of each body in the specified Articulation. |
| randomize\_rigid\_body\_collider\_offsets | env\_ids, rest\_offset\_distribution\_params (`tuple[float, float]`), contact\_offset\_distribution\_params (`tuple[float, float]`), asset\_cfg.name, distribution (“uniform”/“log\_uniform”/“gaussian”) | Randomize physics collider “rest” and/or “contact” offsets for each body shape of the specified asset. |
| randomize\_physics\_scene\_gravity | env\_ids, gravity\_distribution\_params (`tuple[list[float], list[float]]`), operation (“add”/“scale”/“abs”), distribution (“uniform”/“log\_uniform”/“gaussian”) | Randomize the global gravity vector (x, y, z) for the entire physics scene (same gravity for all envs). |
| randomize\_actuator\_gains | env\_ids, asset\_cfg.name, stiffness\_distribution\_params (`tuple[float, float]`), damping\_distribution\_params (`tuple[float, float]`), operation, distribution | Randomize stiffness and/or damping gains of actuators (implicit or explicit) on specified joint IDs. |
| randomize\_joint\_parameters | env\_ids, asset\_cfg.name, friction\_distribution\_params (`tuple[float, float]`), armature\_distribution\_params (`tuple[float, float]`), lower\_limit\_distribution\_params (`tuple[float, float]`), upper\_limit\_distribution\_params (`tuple[float, float]`), operation, distribution | Randomize joint physics properties: friction, armature, and position limits (lower/upper) by adding/scaling/overwriting. |
| randomize\_fixed\_tendon\_parameters | env\_ids, asset\_cfg.name, stiffness\_distribution\_params (`tuple[float, float]`), damping\_distribution\_params (`tuple[float, float]`), limit\_stiffness\_distribution\_params (`tuple[float, float]`), lower\_limit\_distribution\_params (`tuple[float, float]`), upper\_limit\_distribution\_params (`tuple[float, float]`), rest\_length\_distribution\_params (`tuple[float, float]`), offset\_distribution\_params (`tuple[float, float]`), operation, distribution | Randomize fixed‐tendon stiffness, damping, limit stiffness, lower/upper position limits, rest length, and/or offset. |
| apply\_external\_force\_torque | env\_ids, force\_range (`tuple[float, float]`), torque\_range (`tuple[float, float]`), asset\_cfg.name | Sample and buffer random forces and torques to apply to each body of the specified asset (effective on next write). |
| push\_by\_setting\_velocity | env\_ids, velocity\_range (`dict{x, y, z, roll, pitch, yaw → tuple[float, float]}`), asset\_cfg.name | Sample a random root‐velocity (linear + angular) and set it directly on the specified asset to simulate a push. |
| reset\_base | env\_ids, pose\_range (`dict{x, y, z, roll, pitch, yaw → tuple[float, float]}`), velocity\_range (`dict{x, y, z, roll, pitch, yaw → tuple[float, float]}`), asset\_cfg.name | Randomize root pose of the robot (translation + rotation) uniformly around default and root velocity, then write to simulation. |
| reset\_root\_state | env\_ids, pose\_range (`dict{x, y, z, roll, pitch, yaw → tuple[float, float]}`), velocity\_range (`dict{x, y, z, roll, pitch, yaw → tuple[float, float]}`), asset\_cfg.name | Randomize root pose (translation + rotation) of an object uniformly around default and root velocity, then write to simulation. |
| reset\_root\_state\_with\_random\_orientation | env\_ids, pose\_range (`dict{x, y, z → `tuple\[float, float]`}`), velocity\_range (`dict{x, y, z, roll, pitch, yaw → tuple[float, float]}`), asset\_cfg.name | Randomize root position uniformly, sample orientation uniformly from SO(3), and set velocity within given ranges. |
| reset\_root\_state\_from\_terrain | env\_ids, pose\_range (`dict{roll, pitch, yaw → `tuple\[float, float]`}`), velocity\_range (`dict{x, y, z, roll, pitch, yaw → tuple[float, float]}`), asset\_cfg.name | Sample a valid terrain patch (“init\_pos”), set root pose on terrain + random yaw/pitch/roll, then set velocity. |
| reset\_joints\_by\_scale | env\_ids, position\_range (`tuple[float, float]`), velocity\_range (`tuple[float, float]`), asset\_cfg.name | Scale default joint positions and velocities by random factors (within ranges) and clamp to soft limits before writing. |
| reset\_joints\_by\_offset | env\_ids, position\_range (`tuple[float, float]`), velocity\_range (`tuple[float, float]`), asset\_cfg.name | Offset default joint positions and velocities by random values (within ranges) and clamp to soft limits before writing. |
| reset\_nodal\_state\_uniform | env\_ids, position\_range (`dict{x, y, z → tuple[float, float]}`), velocity\_range (`dict{x, y, z → tuple[float, float]}`), asset\_cfg.name | Randomize default nodal (vertex) positions and velocities of a DeformableObject uniformly within given ranges. |
| reset\_scene\_to\_default | env\_ids | Restore all rigid objects, articulations (root pose + joint state), and deformables (nodal state) to their default values. |
| randomize\_visual\_texture\_material | env\_ids, event\_name (`str`), asset\_cfg.name, texture\_paths (`list[str]`), texture\_rotation (`tuple[float, float]`) | Trigger a Replicator‐based event that randomizes textures on each body’s “/visuals” prim under the specified asset. |
| randomize\_visual\_color | env\_ids, event\_name (`str`), asset\_cfg.name, colors (`list[tuple[float, float, float]]` or `dict{r, g, b → tuple[float, float]}`), mesh\_name (`str`) | Trigger a Replicator‐based event that randomizes color on the specified mesh prims under the asset. |

## Terminations

Terminations specify the conditions under which an episode ends, the configuration options that define threshold values or monitored signals, and a brief explanation of what triggers each termination.

| Termination Function | Configurable Options | Description |
| - | - | - |
| time\_out | none | Terminate when episode length ≥ max\_episode\_length. |
| command\_resample | command\_name (`str`), num\_resamples (`int`) | Terminate when a command has been resampled the specified number of times. |
| bad\_orientation | limit\_angle (float), asset\_cfg.name | Terminate if the asset’s orientation deviates from vertical by > limit\_angle. |
| root\_height\_below\_minimum | minimum\_height (`float`), asset\_cfg.name | Terminate if the asset’s root height drops below the minimum height. |
| joint\_pos\_out\_of\_limit | asset\_cfg.name | Terminate if any joint position exceeds the soft position limits. |
| joint\_pos\_out\_of\_manual\_limit | bounds (`tuple[min, max]`), asset\_cfg.name | Terminate if any joint position falls outside the user-specified bounds. |
| joint\_vel\_out\_of\_limit | asset\_cfg.name | Terminate if any joint velocity exceeds the soft velocity limits. |
| joint\_vel\_out\_of\_manual\_limit | max\_velocity (`float`), asset\_cfg.name | Terminate if any joint velocity exceeds the given max\_velocity. |
| joint\_effort\_out\_of\_limit | asset\_cfg.name | Terminate if any joint’s computed torque equals its applied torque (indicating effort clipping). |
| base\_contact | threshold (`float`), sensor\_cfg.name | Terminate if any contact force at the sensor exceeds the threshold. |

#### Robot-Specific Termination Terms

| Termination Function | Robot | Configurable Options | Description |
| - | - | - | - |
| base\_contact\_g1 | Unitree G1 (27 DOF) | sensor\_cfg.name (`str`), sensor\_cfg.body\_names (`list[str]`), threshold (`float`) | Terminate episode if any specified non-foot link (e.g. pelvis, torso, waist, shoulders) registers contact force above the threshold. |

#### Task-Specific Termination Terms

| Termination Function | Configurable Options | Description | Task Name |
| - | - | - | - |
| object\_out\_of\_reach | `asset_cfg` (`SceneEntityCfg("object")`), `threshold` (`float`) | Terminate when the object moves farther than the specified threshold distance from the robot. | Manipulation In-Hand |
| max\_consecutive\_success | `num_success` (`int`), `command_name` (`str`) | Terminate once the in-hand manipulation has succeeded the given number of times in a row. | Manipulation In-Hand |


# Policy Inference
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/reinforcement-learning/inference



Once the trained policy has been trained, it can be deployed in all the supported as well as custom environments.
Setting the `task` as `GRID-Isaac-CustomRL-v0` and specifying the environment in the `env.yaml` enables users to use the trained policy in diverse environments.
A sample `agent.yaml` file for inference is shown below:

```yaml theme={null}
- rsl_rl_agent:
    type: "rsl_rl"
    mode: "play"
    config: 
      resume: false
      video: false
      video_length: 200
      video_interval: 2000
      empirical_normalization: false
      experiment_name: "my_experiment_name"
      load_run: .*
      load_checkpoint: model.*
```


# Training Workflow
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/reinforcement-learning/training-workflow



GRID supports the training and evaluation of reinforcement learning agents in Isaac Sim for the supported quadruped, bipeds, arms, and humanoid robots.

![RL Training](https://downloads.generalrobotics.dev/docs-assets/3e3ab99c727f/rl-training.gif)

## Training

GRID supports training reinforcement learning agents using the [RSL-RL](https://github.com/leggedrobotics/rsl_rl) training methodology.
Agents can be trained by modifying the `agent.yaml` file as follows:

```yaml theme={null}
- rsl_rl_agent:
    type: "rsl_rl"
    mode: "play"
    config: 
      resume: false
      max_iterations: 1000
      num_steps_per_env: 24
      video: false
      video_length: 200
      video_interval: 2000
      empirical_normalization: false
      experiment_name: "my_experiment_name"
      load_run: .*
      load_checkpoint: model.*
      policy: 
        class_name: "ActorCritic"
        init_noise_std: 1.0
        actor_hidden_dims: [512, 256, 128]
        critic_hidden_dims: [512, 256, 128]
        activation: "elu"
      algorithm: 
        class_name: "PPO"
        value_loss_coef: 1.0
        use_clipped_value_loss: True
        clip_param: 0.2
        entropy_coef: 0.008
        num_learning_epochs: 5
        num_mini_batches: 4
        learning_rate: 1.0e-3
        schedule: "adaptive"
        gamma: 0.99
        lam: 0.95
        desired_kl: 0.01
        max_grad_norm: 1.0
```

<Note>
  To run the RL training headless, use the following configuration in `workflow.yaml`, change the variable `headless` to `True`.
</Note>

<Note>
  The `video` parameter in the `agent.yaml` can be used to save inference videos of the policy during training.
</Note>

<Note>
  The checkpoints are saved in the same directory as the configuration files with the appropriate date and time-stamp.
</Note>


# Sensors
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/sensors



GRID currently supports the following sensors with Isaac Sim.

## Camera

This is a camera sensor that can be of type RGB or Depth.

### Configuration

The configuration for the camera sensor can be set up in the configuration file. The following parameters are available:

| Parameter | Description |
| - | - |
| **Height** | The height of the captured image |
| **Width** | The width of the captured image |
| **Offset** | The offset of the camera with respect to the robot's frame of reference |
| **Focal Length** | The focal length of the camera |
| **Focal Distance** | The focal distance of the camera |
| **Horizontal Aperture** | The horizontal aperture of the camera |
| **Clipping Range** | The clipping range of the camera |

These parameters can be configured by adding the sensor in the scene entity inside `env.yaml` in the following manner:

```yaml theme={null}
- camera_sensor_name:
    type: Sensor
    name: CameraRGB
    config:
        prim_path: "/World/envs/env_.*/tabletop_rgb_camera"
        height: 256
        width: 256
        offset:
            pos: [1.5, 0.0, 0.7]
            rot: [0.0, -0.3, 0.0, 1.0]
            convention: "world"
        spawn:
            focal_length: 24.0
            focus_distance: 400.0
            horizontal_aperture: 20.955
            clipping_range: [0.1, 100000]
```

## Contact Sensor

This is a simple contact sensor that works as a ray caster simulating surface pressure by detecting contact points with precision.

### Configuration

The configuration for the height sensor can be set up in the configuration file. The following parameters are available:

| Parameter | Description |
| - | - |
| **History length** | The length of history to consider while computing sensor values |

These parameters can be configured by adding the sensor in the scene entity inside `env.yaml` in the following manner:

```yaml theme={null}
- contact_sensor_name:
    type: Sensor
    name: ContactSensor
    config:
        prim_path: "/World/envs/env_.*/robot/.*"
        history_length: 3
```

Note that you need to make sure `activate_contact_sensors` flag is set to true for your robot.

## Height Sensor

This is a simple height sensor that works as a ray caster to obtain the height values of points in a specified pattern.

### Configuration

The configuration for the height sensor can be set up in the configuration file. The following parameters are available:

| Parameter | Description |
| - | - |
| **Offset** | The offset of the height sensor with respect to robot's frame of reference |
| **Pattern Resolution** | The resolution of the grid pattern around the sensor |
| **Pattern Size** | The start and end of the grid pattern |

These parameters can be configured by adding the sensor in the scene entity inside `env.yaml` in the following manner:

```yaml theme={null}
- height_sensor_name:
    type: Sensor
    name: HeightSensor
    config:
        prim_path: "/World/envs/env_.*/robot/body"
        offset:
            pos: [0.3, 0.0, 0.22]
            rot: [0.0, 0.0, 0.0, 1.0]
        pattern_cfg:
            resolution: 0.1
            size: [1.6, 1.0]
```

## LiDAR

This is a LiDAR sensor that works as a ray caster to obtain a point cloud around the sensor.

### Configuration

The configuration for the height sensor can be set up in the configuration file. The following parameters are available:

| Parameter | Description |
| - | - |
| **Offset** | The offset of the height sensor with respect to the robot's frame of reference |
| **Pattern Size** | The start and end of the grid pattern |
| **Max Distance** | The maximum sensing distance of the height sensor |
| **Vertical FOV** | The vertical field of view of the sensor |
| **Horizontal FOV** | The horizontal field of view of the sensor |
| **Horizontal Resolution** | The horizontal resolution of the sensor |
| **Channels** | The number of channels used by the sensor |

These parameters can be configured by adding the sensor in the scene entity inside `env.yaml` in the following manner:

```yaml theme={null}
- lidar_sensor_name:
    type: Sensor
    name: LiDAR
    config:
            offset:
                pos: [0.0, 0.0, 0.0] # add init (x, y, z) position
                rot: [0.0, 0.0, 0.0, 0.0] # add init (x, y, z, w) quaternion
            pattern_cfg:
                channels: 16
                vertical_fov_range: [-15.0, 15.0]
                horizontal_fov_range: [-180.0, 180.0]
                horizontal_res: 0.2
            max_distance: 100
```

## IMU

The Inertial Measurement Unit (IMU) provides orientation and acceleration data by measuring the robot’s linear accelerations and angular velocities in its own body frame.

### Configuration

The configuration for the IMU sensor can be set up in the configuration file. The following parameters are available:

| Parameter | Description |
| - | - |
| **Offset** | Pose of the IMU relative to the robot’s frame of reference |
| **Gravity Bias** | The constant gravity vector to subtract from raw acceleration readings, as a 3-tuple `(x, y, z)` (m/s²) |

These parameters can be configured by adding the sensor in the scene entity inside `env.yaml` in the following manner:

```yaml theme={null}
- imu_sensor_name:
    type: Sensor
    name: IMU
    config:
            prim_path: "/World/envs/env_.*/robot/body"
            offset:
                pos: [0.0, 0.0, 0.0] # add init (x, y, z) position
                rot: [0.0, 0.0, 0.0, 0.0] # add init (x, y, z, w) quaternion
            gravity_bias: [0.0, 0.0, 9.81]
```

## Rectified Camera

This is a rectified camera sensor that applies intrinsic and extrinsic calibration to produce undistorted images (e.g., for stereo rigs or calibrated monocular setups).

### Configuration

The following parameters are available on the `RectifiedCameraCfg`:

| Parameter | Description |
| - | - |
| **Width** | The width of the captured image |
| **Height** | The height of the captured image |
| **Offset** | The offset of the camera with respect to the robot's frame of reference |
| **D** | Distortion coefficients `[k1, k2, p1, p2, (k3)]`. |
| **K** | Intrinsic matrix, flattened `[fx, 0, cx, 0, fy, cy, 0, 0, 1]`. |
| **R** | Rectification (rotation) matrix, flattened 3×3. |
| **P** | Projection matrix, flattened 3×4 `[fx′, 0, cx′, Tx, 0, fy′, cy′, Ty, 0, 0, 1, 0]`. |
| **Clipping Range** | The clipping range of the camera |
| **Focal Length** | The focal length of the camera |
| **Focal Distance** | The focal distance of the camera |
| **F Stop** | Aperture setting for spawn config (`0.0` means wide open). |
| **Projection Type** | Type of image projection -- one of "pinhole"`or`"fisheye". |
| **Lock Camera** | Whether to lock camera's transform or not. |

### Example

Add a rectified camera to your `env.yaml` like so:

```yaml theme={null}
- rectified_camera:
    type: Sensor
    name: RectifiedCamera
    config:
          prim_path: "/World/envs/env_*/stereo_camera"
          width: 640
          height: 480
          offset:
            pos: [0.0, 0.0, 1.2]
            rot: [0.0, 0.0, 0.0, 1.0]
          D: [0.1, -0.05, 0.001, 0.0005, 0.0]
          K: [600.0, 0.0, 320.0,
               0.0, 600.0, 240.0,
               0.0,   0.0,   1.0]
          R: [1.0, 0.0, 0.0,
              0.0, 1.0, 0.0,
              0.0, 0.0, 1.0]
          P: [600.0, 0.0, 320.0, 0.0,
              0.0, 600.0, 240.0, 0.0,
              0.0,   0.0,   1.0, 0.0]
          clipping_range: [0.1, 100000]
          focal_length: 24.0
          focus_distance: 500.0
          f_stop: 2.8
          projection_type: "pinhole"
          lock_camera: true
```


# Agent Config
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/session_configuration/agent



`agent.yaml` configures the agent type and its respective parameters. GRID supports a diverse set of agents types that include but are not limited to reinforcement learning agents, teleoperation agents (keyboard, VR devices, Gello devices), motion planning agents.

The below example provides a sample policy training configuration file. For more information on how to modify it for training RL policies, refer to this [section](/v2.3/simulation/isaac/reinforcement-learning/training-workflow).

```yaml theme={null}
- agent_name:
    type: "rsl_rl"
    mode: "train" # or "play"
    config: 
      resume: false
      max_iterations: 10000
      video: false
      video_length: 200
      video_interval: 2000
      experiment_name: "my_experiment_name"
      load_run: .*
      load_checkpoint: model.*
      policy: 
        class_name: "ActorCritic"
        init_noise_std: 1.0
        actor_hidden_dims: [512, 256, 128]
        critic_hidden_dims: [512, 256, 128]
        activation: "elu"
      algorithm: 
        class_name: "PPO"
        value_loss_coef: 1.0
        use_clipped_value_loss: True
        clip_param: 0.2
        entropy_coef: 0.008
        num_learning_epochs: 5
        num_mini_batches: 4
        learning_rate: 1.0e-3
        schedule: "adaptive"
        gamma: 0.99
        lam: 0.95
        desired_kl: 0.01
        max_grad_norm: 1.0
```

Similarly, you can add a teleoperation agent by adding this in the `agent.yaml`

```yaml theme={null}
- your_agent_name:
    type: "teleop"
    input: "" # "SE3", "SE2", "Gello", "DualArm" or "BaseWArm"
    device: "" # When input=="SE3"/"SE2", use "Keyboard", "Gamepad", "Handtracking" or "Spacemouse"
```


# Environment Config
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/session_configuration/env



`env.yaml` specifies the configuration settings for four essential components of the simulation scene: the environment, the robot, the sensors (on the robot or in the scene), and the assets (obstacles, interaction objects, etc.)

The below provided sample scene configuration file initializes a Unitree Go2 with a set of specified sensors in a standard warehouse environment.

```yaml theme={null}
scene:
  - scene_name:
      type: Asset
      name: Warehouse
      config:
        prim_path: "/World/ground"

  - robot_name:
      type: Robot
      name: Unitree_Go2
      config:
        init_state:
          pos: [0.0, 0.0, 0.0]
          rot: [0.0, 0.0, 0.0, 1.0]
  
  - sensor_name_1:
      type: Sensor
      name: HeightSensor
      config:
        prim_path: "/World/envs/env_.*/robot/base"

  - sensor_name_2:
      type: Sensor
      name: CameraRGB
      config:
        prim_path: "/World/envs/env_.*/robot/base/imu/cam_rgb"
        height: 256
        width: 256
```

You can also set scene specific variables like number of parallel environments, decimation, time step for simulation, episode length (in seconds), etc. using `env.yaml` by adding the following to it.

```yaml theme={null}
num_envs: 1
decimation: 4
episode_length_s: 5
env_spacing: 15

sim: 
  dt: 0.005
```

Finally, the `env.yaml` also configures the ROS2 communication layer. Please have a look at [this page](/v2.3/simulation/isaac/comms) to get more detailed information on how to publish simulation data or subscribe to commands.


# MDP Config
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/session_configuration/mdp



`mdp_cfg.yaml` is necessary for defining the MDP component settings. This includes parameters related to the high level commands given to the agent (like base velocity commands or end-effector commands), lower level actions provided to each of the DOFs (like relative change pose and binary gripper control), the set of observations fed to the policy network, termination conditions for each episode, reward design, and curriculum utilized in the training methodology.
The following example depicts the MDP settings for training a Unitree Go2 that receives velocities commands and executes them based on a locomotion policy.

```yaml theme={null}
actions:
    - joint_actions:
        type: JointPosition
        config:
            asset_name: robot
            joint_names: [".*"]
            scale: 0.5
            use_default_offset: True

commands: 
  - base_velocity:
      type: VelocityCommand
      config:
        asset_name: robot
        rel_standing_envs: 0.02
        rel_heading_envs: 1.0
        heading_control_stiffness: 0.5
        debug_vis: True
        heading_command: True
        resampling_time_range: [10.0, 10.0]
        ranges:
            lin_vel_x: [-1., 1.]
            lin_vel_y: [-1., 1.]
            ang_vel_z: [-1., 1.]
            heading: [-3.14, 3.14]

observations:
  - policy:
    - base_lin_vel: 
        type: base_lin_vel
    - base_ang_vel: 
        type: base_ang_vel
    - projected_gravity:
        type: projected_gravity
    - velocity_commands:
        type: velocity_commands
    - joint_pos_rel:
        type: joint_pos_rel
    - joint_vel_rel:
        type: joint_vel_rel
    - actions:
        type: actions
        config:
            params:
                action_name: joint_actions
    - height_scan:
        type: height_scan

terminations:
  - time_out:
      type: time_out
  - body_contact:
      type: body_contact
      config:
        params:
          threshold: 1.0
  - terrain_out_of_bounds:
      type: terrain_out_of_bounds
      config:
        params:
          distance_buffer: 3.0

events:
  - add_base_mass:
      type: add_base_mass
      config:
        params:
          mass_distribution_params: [-2.5, 2.5]
          operation: add
  - base_external_force_torque:
      type: base_external_force_torque
      config:
        params:
          force_range: [0.0, 0.0]
          torque_range: [-0.0, 0.0]
  - reset_base:
      type: reset_base
  - reset_robot_joints:
      type: reset_robot_joints
      
rewards:  
  - air_time:
      type: air_time
      config:
        weight: 5.0
        params:
          mode_time: 0.3
          velocity_threshold: 0.5
  - base_angular_velocity:
      type: base_angular_velocity
      config:
        weight: 5.0
        params:
          std: 2.0
  - base_linear_velocity:
      type: base_linear_velocity
      config:
        weight: 5.0
        params:
          std: 1.0
          ramp_rate: 0.5
          ramp_at_vel: 1.0
  - foot_clearance:
      type: foot_clearance
      config:
        weight: 0.5
        params:
          std: 0.05
          tanh_mult: 2.0
  - action_smoothness:
      type: action_smoothness
      config:
        weight: -1.0
  - air_time_variance:
      type: air_time_variance
      config:
        weight: -1.0
  - base_motion: 
      type: base_motion
      config:
        weight: -2.0
  - base_orientation:
      type: base_orientation
      config:
        weight: -3.0
  - foot_slip:
      type: foot_slip
      config:
        weight: -0.5
  - joint_pos:
      type: joint_pos
  - joint_torques:
      type: joint_torques
      config:
        weight: 1.0
```

<Note>
  If you want to take a look at the possible set of options for all MDP components available at your disposal, refer to [this page](/v2.3/simulation/isaac/reinforcement-learning/customizing-training).
</Note>


# Session Config Overview
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/session_configuration/overview



To configure a GRID session with Isaac, users have access to four configuration files which allows modification of any session parameter with ease.

The contents of the four different configuration files along with examples are provided in the following pages.


# Workflow Config
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/session_configuration/workflow



`workflow.yaml` defines the high level session parameters that include rendering settings and viewer settings.
In most scenarios, this file remains the same and users do not interact with it.

```yaml theme={null}
headless: False
livestream: 0
enable_cameras: False 
device: 'cuda:0'
cpu: False
disable_fabric: False

agent: !include agent.yaml
  
task: GRID-Isaac-CustomRL-v0 # or GRID-Isaac-Custom-v0

env: !include env.yaml

viewer:
  eye: [3.5, 3.5, 3.5]
  lookat: [0.0, 0.0, 0.0]
```


# Overview
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/teleoperation/overview



GRID provides support for multiple input devices and output commands, enabling teleoperation for a variety of robot form factors, as listed below:

| Input Device | Output Format | Command Specification |
| - | - | - |
| Keyboard | SE(2) | Linear x-y velocity, yaw rate |
| Keyboard | SE(3) | Change in 6D Pose (x, y, z, r, p, y) |
| VR Device: Apple Vision Pro | SE(3), 27 \* SE(3), 27 \* SE(3) | Head, Hand Poses |

GRID also supports the hybrid configurations of output formats and command specifications to control complex robot form factors, as listed below:

| Input Device | Output Format | Command Specification |
| - | - | - |
| Keyboard | SE(2) + SE(3) | Linear x-y velocity, yaw rate, Change in 6D pose (x, y, z, r, p, y) |
| Keyboard | SE(3) + SE(3) | Two vectors each with change in 6D pose (x, y, z, r, p, y) |

### Sample Configuration:

1. To use a keyboard device with SE(3) output format commanding change in 6D Pose (x, y, z, r, p, y), describe the agent in `agent_cfg.yaml` config as follows:

```yaml theme={null}
agent_cfg:
    - teleop:
        type: "SE3"
        device: "Keyboard"
        sensitivity: 1.0
```

2. To use a VR device, describe the agent as follows:

```yaml theme={null}
agent_cfg:
    - teleop:
        type: "VR"
        device: "AVP"
        ip: 192.168.254.206
```

3. To use a hybrid configuration, describe the agent as follows:

```yaml theme={null}
agent_cfg:
    - teleop:
        type: "SE3_SE3"
        device: "DualKeyboard"
        sensitivity: 1.0
```


# VR Teleop Guide
Source: https://docs.generalrobotics.dev/v2.3/simulation/isaac/teleoperation/vr-teleop-guide



This guide provides step-by-step instructions for setting up the GRID teleoperation interface using an Apple Vision Pro VR device to control a robot.

## Prerequisites

Before proceeding with the setup, ensure the following requirements are met:

* Install the GRID CLI and start an Isaac simulator session with the workflow configured to enable VR-based teleoperation.
* Download and install [TrackingStreamer](https://apps.apple.com/us/app/tracking-streamer/id6478969032) on Apple Vision Pro from the App Store. This app streams head, wrist, and hand tracking data to GRID.
* Ensure that both the system running GRID and the Apple Vision Pro are connected to the same wireless network for seamless data streaming.

## Configuring the IP Address for Streaming

To establish proper communication between the Apple Vision Pro and GRID, follow these steps:

1. Open the **TrackingStreamer** application on the Apple Vision Pro and note the displayed IP address.
2. Update the **IP address** in the agent configuration. Example configuration:

```yaml theme={null}
agent_cfg:
  - teleop:
      type: "SE3"
      device: "AVP"
      ip: 192.168.254.206
```

## Operator Calibration

Calibration is necessary to align the operator's wrist pose with the robot’s end effector, ensuring precise teleoperation. This process is performed once, with the robot stationary and visual aids in simulation guiding the alignment.

### Calibration Steps

1. Enable the calibration by setting `calibrate: True` in `agent_cfg.yaml` configuration.
2. Start a sim to visualize the scene, robot, and workspace:
   ```sh theme={null}
   sim start --name teleop_calib --config rbfranka_sbfarm_visionpro.json
   ```
   * This session displays two transforms in simulation, tracking wrist poses for both hands.
   * Workspace bounds are also visualized.
3. Observe the transformation needed to align the wrist with the robot’s end effector and note the workspace bounds.
4. Stop the sim:
   ```sh theme={null}
   sim stop teleop_calib
   ```
5. Update the `bounds` and `transform` parameters in the `agent_cfg.yaml` configuration in the following manner.

```yaml theme={null}
agent_cfg:
  - teleop:
      type: "SE3"
      device: "AVP"
      test: False
      ip: 192.168.254.206
      calibrate: True
      bounds:
        min: [-0.1, -0.6, -0.8]
        max: [0.6, 0.6, 1.2]
      transform:
        pos: [0.0, 0, -1.0]
        rot: [1, 0, 0, 0]
```

## Teleoperation Validation

Once calibration is complete, unfreeze the robot and test teleoperation.

### Validation Steps

1. Set `calibrate: False` in `agent_cfg.yaml` configuration.
2. Start the sim to validate teleoperation:
   ```sh theme={null}
   sim start --name teleop --config rbfranka_sbfarm_visionpro.json
   open teleop viz
   ```
3. Open the visualization interface in a browser and navigate to [this link](http://127.0.0.1:8211/streaming/webrtc-demo/?server=127.0.0.1).

The operator can now control the robot in simulation using arm and hand movements.


# GRID Navigator Support
Source: https://docs.generalrobotics.dev/v2.3/support/grid-navigator

Help, requirements, and contact for the GRID Navigator iOS app

GRID Navigator is the iOS capture app for the GRID platform. It records
synchronized color video, LiDAR depth, and device motion in a single walk-through
— the raw data used to build the maps and datasets robots navigate with.

## Get help

Email [gridnav@generalrobotics.company](mailto:gridnav@generalrobotics.company).
We aim to respond within two business days. Include your device model, iOS
version, and the app version from the profile screen.

## Requirements

* An iPhone with a LiDAR sensor (iPhone Pro models) for depth capture
* iOS 15.6 or later
* Camera and Motion permissions — both are required to record, and you can
  change them any time in **Settings → GRID Navigator**

## Getting started

**Try it without an account.** Tap **Continue in Demo Mode** on the login
screen. Capture runs entirely on your device; nothing is uploaded.

**Sign in to your organization.** Tap **Add GRID server** and enter the server
your GRID administrator gave you, then sign in. Accounts are provisioned by your
organization — there is no public sign-up.

## Troubleshooting

**Recording won't start**

* Confirm Camera and Motion access are allowed in **Settings → GRID Navigator**.
* Depth capture needs a LiDAR-capable device; non-LiDAR iPhones can't record
  depth.

**Scans look incomplete or drift**

* Move slowly and keep surfaces in view; fast turns lose tracking.
* Featureless walls and glass give the tracker little to lock onto — include
  more of the room.

**Upload is unavailable**

* Uploading requires signing in to a GRID server. In Demo Mode it stays
  disabled by design, and captures remain on your device.
* If you are signed in and uploads still fail, check that your device can reach
  your organization's GRID server, then contact support.

**Running out of space**

* Captures are written to the device. Delete sessions you've already uploaded
  from the session list to reclaim space.

## Accounts and data

Accounts are provisioned by your organization, so there is no in-app sign-up or
deletion. To request access to — or deletion of — your account and its captured
data, contact your organization administrator or email
[gridnav@generalrobotics.company](mailto:gridnav@generalrobotics.company).

What the app collects and how it's handled is described in the
[General Robotics Privacy Policy](https://www.generalrobotics.company/privacy-policy).


# GRID Cortex Client
Source: https://docs.generalrobotics.dev/v2.3/models/cortex



The **grid-cortex-client** Python package provides a unified interface to all AI models hosted on GRID Cortex.

<Steps>
  <Step title="Installation" icon="download">
    Inside a GRID session workspace the client is already installed — skip
    this step. On your own machine, install it with pip:

    ```bash theme={null}
    pip install grid-cortex-client
    ```

    It is recommended that you use Python 3.10+
  </Step>

  <Step title="Authentication & Endpoint" icon="key">
    Set up your API key (and endpoint, if needed):

    1. During onboarding **General Robotics** will give you a personal **CORTEX API key**.
    2. Export it so the client can pick it up automatically:
       ```bash theme={null}
       export GRID_CORTEX_API_KEY="<YOUR_KEY>"
       ```
    3. If you run Cortex on-prem or on a managed cloud deployment, point the client at the **Cortex API URL** supplied with your deployment — the dedicated `grid-…` API hostname, not the `admin-…` portal hostname:
       ```bash theme={null}
       export GRID_CORTEX_BASE_URL="https://<your-cortex-api-host>/cortex"
       ```
    4. You can also pass the key directly when constructing the client:
       ```python theme={null}
       from grid_cortex_client import CortexClient
       client = CortexClient(api_key="<YOUR_KEY>")
       ```
  </Step>

  <Step title="Quick Start (2 lines)" icon="rocket-launch">
    Get started with just two lines of code:

    ```python theme={null}
    from grid_cortex_client import CortexClient
    result = CortexClient().run(model_id="zoedepth", image_input="demo.jpg")
    ```

    The `result` type depends on the model — see the individual model pages for details.
  </Step>
</Steps>

***

## Unified API

Every model is called through the same function:

```python theme={null}
CortexClient.run(model_id: str, **kwargs) -> Any
```

* `model_id` — the model identifier (e.g. `"zoedepth"`, `"gsam2"`, `"pi05"`)
* `**kwargs` — model-specific inputs (`image_input`, `prompt`, `left_image`, etc.)

```python theme={null}
from grid_cortex_client import CortexClient

client = CortexClient()
depth = client.run(model_id="zoedepth", image_input="scene.jpg")
mask  = client.run(model_id="gsam2", image_input="scene.jpg", prompt="a robot arm")
```

***

## Discovery

List all available models and get per-model documentation at runtime:

```python theme={null}
from grid_cortex_client import CortexClient

client = CortexClient()

# List all deployed model IDs
print(client.available_models())
# ['da3metric', 'zoedepth', 'owlv2', 'gsam2', 'sam3', ...]

# Get detailed documentation for a specific model
print(client.help("sam3"))
```

You can also use the `ModelType` enum for IDE autocompletion:

```python theme={null}
from grid_cortex_client import CortexClient, ModelType

client = CortexClient()
depth = client.run(ModelType.ZOEDEPTH, image_input="demo.jpg")
```

***

## Async & WebSocket Clients

### AsyncCortexClient

For `asyncio`-based applications, use `AsyncCortexClient` — same API as `CortexClient` but with `await`:

```python theme={null}
from grid_cortex_client import AsyncCortexClient

async def main():
    client = AsyncCortexClient()
    depth = await client.run(model_id="zoedepth", image_input="demo.jpg")
    print(depth.shape)
    await client.close()
```

### CortexHubClient (WebSocket)

For high-throughput pipelines, `CortexHubClient` provides a persistent WebSocket connection. It supports two patterns:

**Request-response (simple)**

```python theme={null}
from grid_cortex_client import CortexHubClient, ModelType

async with CortexHubClient() as hub:
    depth = await hub.run(ModelType.ZOEDEPTH, image_input=img)
```

**Pub/Sub (concurrent, non-blocking)**

```python theme={null}
from grid_cortex_client import CortexHubClient, ModelType

async with CortexHubClient() as hub:
    await hub.publish(ModelType.ZOEDEPTH, request_id="depth1", image_input=img)
    await hub.publish(ModelType.GSAM2, request_id="mask1", image_input=img, prompt="cat")

    async for result in hub.subscribe():
        print(f"{result.request_id}: ok={result.ok}")
        process(result.data)
```

Each `HubResult` contains `request_id`, `model`, `data`, `ok`, and optional `error`.

***

## Troubleshooting

**401 Unauthorized** – Check that your shell actually has `GRID_CORTEX_API_KEY` exported and that the key is correct. A key only works on the cluster it was created in. Anything the GRID CLI starts for you — including a robot workspace's Python and notebooks — already has the active cluster's key; a `python` you start yourself needs it exported.
**Timeout / connection errors** – If you are on-prem/managed cloud, confirm `GRID_CORTEX_BASE_URL` points to your instance. You can also adjust the default 30 s timeout:

```python theme={null}
client = CortexClient(timeout=60)
```


# c-radio
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/c-radio

Compute an L2-normalized embedding for a single RGB image

Compute an L2-normalized embedding for a single RGB image.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

np.ndarray: Embedding as numpy array of shape `(D,)`, dtype `float32`,
L2-normalized so dot products give cosine similarity directly.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
emb = client.run(ModelType.C_RADIO, image_input=image)
print(emb.shape, float(np.linalg.norm(emb)))  # (D,) 1.0
```


# contact-graspnet
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/contact-graspnet

Generate grasps using ContactGraspNet

Generate grasps using ContactGraspNet.

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray, None]">
  Depth image (required).
</ParamField>

<ParamField type="Union[str, np.ndarray, None]">
  3×3 intrinsics matrix (required).
</ParamField>

<ParamField type="Union[str, Image.Image, np.ndarray, None]">
  Optional segmentation mask (uint8 H×W).
</ParamField>

<ParamField type="Dict[str, Any] | None">
  Optional dict. Keys: `top_k` (int, default 64), `z_range` (\[float, float], default \[0.2, 1.8]), `local_regions` (bool, default False), `filter_grasps` (bool, default False; requires `seg_image`), `forward_passes` (int, default 1).
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict with:

* `grasps`: (N, 4, 4) array of grasp poses in camera frame
* `confidence`: (N,) array of confidence scores in \[0, 1]
* `latency_ms`: server-reported latency

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
client = CortexClient()
depth = np.load("depth.npy")
K = np.array([[615,0,320],[0,615,240],[0,0,1]], dtype=np.float64)
out = client.run(ModelType.CONTACT_GRASPNET, depth_image=depth, camera_intrinsics=K, aux_args={"top_k": 32})
print(out["grasps"].shape)  # (<=32, 4, 4)
```


# da3metric
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/da3metric

Estimate metric depth from single RGB image

Estimate metric depth from single RGB image.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

np.ndarray: Depth map as numpy array (H, W) with dtype float32.
Values represent metric depth in meters.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
depth = client.run(ModelType.DA3METRIC, image_input=image)
print(depth.shape)  # (480, 640)
```

Uses Depth Anything 3.

## Example Output

<img alt="DA3Metric input and depth map output" />

```python theme={null}
from grid_cortex_client import CortexClient
from PIL import Image

client = CortexClient()
image = Image.open("scene.jpg")  # 640x480 RGB
depth = client.run(model_id="da3metric", image_input=image)

print(depth.shape, depth.dtype)
# (378, 504) float32 — note: output resolution differs from input

print(f"min={depth.min():.4f}, max={depth.max():.4f}, mean={depth.mean():.4f}")
# min=1.6177, max=53.1848, mean=12.9778  (meters)
```


# dinov2-base
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/dinov2-base

Extract DINOv2-base patch tokens and the [CLS] token for one RGB image

Extract DINOv2-base patch tokens and the \[CLS] token for one RGB image.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

Dict\[str, np.ndarray]: Dict with `patch_tokens` of shape `(16, 16, 768)` and `cls` of shape
`(768,)`, both `float32` and L2-normalized per vector. Pool
`patch_tokens` over a foreground mask and re-normalize to compare crops
by cosine similarity without their background.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
crop = np.array(Image.open("lock_crop_224.png"))
mask = np.array(Image.open("lock_mask_224.png")) > 0      # (224, 224) bool
out = client.run(ModelType.DINOV2_BASE, image_input=crop)
out["patch_tokens"].shape, out["cls"].shape               # (16, 16, 768), (768,)
fg = mask.reshape(16, 14, 16, 14).mean((1, 3)) > 0.5      # (16, 16) patch mask
v = out["patch_tokens"][fg].mean(0)
v /= np.linalg.norm(v)                                    # cosine == v @ w
```


# eomt
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/eomt

Segment an image using EoMT

Segment an image using EoMT.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  RGB input image.
</ParamField>

<ParamField type="str">
  "panoptic" ("instance" is temporarily disabled).
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict\[str, Any]: Backend-specific segmentation output.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
result = client.run(ModelType.EOMT, image_input=image, mode="panoptic")
```


# fast-foundationstereo
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/fast-foundationstereo

Estimate depth from stereo pair using Fast-FoundationStereo

Estimate depth from stereo pair using Fast-FoundationStereo.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  Left stereo image.
</ParamField>

<ParamField type="Union[str, Image.Image, np.ndarray]">
  Right stereo image.
</ParamField>

<ParamField type="Dict[str, Any]">
  Camera parameters: - "K": 3x3 camera intrinsics matrix - "baseline": Stereo baseline in meters - "hiera": Use hierarchical coarse-to-fine inference (bool) - "valid\_iters": Number of GRU refinement iterations (default 8)
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

np.ndarray: Depth map as numpy array (H, W) with dtype float32.
Values represent metric depth in meters.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
K = np.array([[525, 0, 320], [0, 525, 240], [0, 0, 1]], dtype=np.float32)
aux = {"K": K, "baseline": 0.1, "hiera": False, "valid_iters": 8}
left_image = np.array(Image.open("left.jpg"))
right_image = np.array(Image.open("right.jpg"))
depth = client.run(ModelType.FAST_FOUNDATIONSTEREO, left_image=left_image, right_image=right_image, aux_args=aux)
print(depth.shape)  # (480, 640)
```

Fast-FoundationStereo is \~10x faster than the original FoundationStereo while maintaining comparable accuracy (14.6M params, real-time capable).


# foundationstereo
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/foundationstereo

Estimate depth from stereo pair using FoundationStereo

Estimate depth from stereo pair using FoundationStereo.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  Left stereo image.
</ParamField>

<ParamField type="Union[str, Image.Image, np.ndarray]">
  Right stereo image.
</ParamField>

<ParamField type="ImageInput | None">
  Rectified \[left | right] frame, with equal-width views and at most 720x1280 pixels per eye. Supply this instead of left\_image and right\_image.
</ParamField>

<ParamField type="bool">
  If true, return a dictionary containing "depth" (float32 HxW) and "left\_image" (uint8 RGB HxWx3). The left image can be passed to any segmentation model.
</ParamField>

<ParamField type="Dict[str, Any]">
  Camera parameters: - "K": 3x3 intrinsics for the rectified left view at input resolution - "baseline": Stereo baseline in meters - "hiera": Hierarchy level (0-2) - "valid\_iters": Number of valid iterations
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

np.ndarray | dict\[str, np.ndarray]: Depends on return\_left\_image:

* False (default): The depth array.
* True: A dictionary with "depth" and "left\_image" arrays.

Depth is float32 with shape (H, W), in meters. The optional left
image is uint8 RGB with shape (H, W, 3), aligned with depth.
Both use the input per-eye resolution; the server performs no
resizing or rectification.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
K = np.array([[525, 0, 320], [0, 525, 240], [0, 0, 1]], dtype=np.float32)
aux = {"K": K, "baseline": 0.1, "hiera": 0, "valid_iters": 32}
left_image = np.array(Image.open("left.jpg"))
right_image = np.array(Image.open("right.jpg"))
depth = client.run(ModelType.FOUNDATIONSTEREO, left_image=left_image, right_image=right_image, aux_args=aux)
print(depth.shape)  # (480, 640)
```


# graspgen
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/graspgen

Generate grasps using GraspGen

Generate grasps using GraspGen.

## Parameters

<ParamField type="Dict[str, Any]">
  Auxiliary parameters (num\_grasps, gripper\_config, camera\_extrinsics).
</ParamField>

<ParamField type="Union[str, Image.Image, np.ndarray, None]">
  Depth image (required if point\_cloud is None).
</ParamField>

<ParamField type="Union[str, Image.Image, np.ndarray, None]">
  Segmentation mask (required if point\_cloud is None).
</ParamField>

<ParamField type="Union[str, np.ndarray, None]">
  3x3 intrinsics matrix (required if point\_cloud is None).
</ParamField>

<ParamField type="Union[str, np.ndarray, Sequence[Sequence[float]], None]">
  Optional (N,3) point cloud as array/list/path to .npy. When provided, depth/seg/intrinsics are ignored and sent directly.
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict with:

* grasps: Array of 4x4 grasp poses (N, 4, 4)
* confidence: Array of confidence scores (N,)
* latency\_ms: Optional server-reported latency in milliseconds

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
K = np.eye(3)
aux = {"num_grasps": 128, "gripper_config": "single_suction_cup_30mm", "camera_extrinsics": np.eye(4)}
depth_image = np.load("depth.npy")
seg_image = np.array(Image.open("seg.png"))
out = client.run(ModelType.GRASPGEN, depth_image=depth_image, seg_image=seg_image,
                 camera_intrinsics=K, aux_args=aux)
print(out["grasps"].shape)  # (N, 4, 4)
print(out["confidence"].shape)  # (N,)
```

## Supported grippers

`gripper_config` accepts `"robotiq_2f_140"` (default), `"single_suction_cup_30mm"`, or `"franka_panda"`.

## Reading the result

The call returns a dict — index it by key:

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
K = np.eye(3)
aux = {"num_grasps": 128, "gripper_config": "single_suction_cup_30mm", "camera_extrinsics": np.eye(4)}
depth_image = np.load("depth.npy")
seg_image = np.array(Image.open("seg.png"))

res = client.run(
    model_id="graspgen",
    depth_image=depth_image,
    seg_image=seg_image,
    camera_intrinsics=K,
    aux_args=aux,
)
print(res["grasps"].shape)  # (N, 4, 4)
```


# graspgenx
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/graspgenx

Generate 6-DoF grasps for a named gripper with GraspGenX

Generate 6-DoF grasps for a named gripper with GraspGenX.

## Parameters

<ParamField type="Dict[str, Any]">
  Must include "gripper\_name"; optional "num\_grasps", "planner" ("graspmoe"|"diffusion"), "grasp\_threshold", "camera\_extrinsics".
</ParamField>

<ParamField type="Union[str, np.ndarray, Sequence, None]">
  (N, 3) object point cloud.
</ParamField>

<ParamField type="Union[str, Image.Image, np.ndarray, None]">
  Depth image; together with seg\_image and camera\_intrinsics, the alternative input to point\_cloud, converted to a point cloud server-side.
</ParamField>

<ParamField type="Union[str, Image.Image, np.ndarray, None]">
  Segmentation mask selecting the object; part of the depth-based alternative to point\_cloud.
</ParamField>

<ParamField type="Union[str, np.ndarray, None]">
  3x3 camera intrinsics matrix; part of the depth-based alternative to point\_cloud.
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict\[str, Any]: Dict with:

* grasps: (N, 4, 4) array of grasp poses
* confidence: (N,) array of scores
* latency\_ms: server-reported latency

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
client = CortexClient()
pc = np.load("object_pc.npy")  # (N, 3)
out = client.run(ModelType.GRASPGENX, point_cloud=pc,
                  aux_args={"gripper_name": "robotiq_2f_85", "num_grasps": 64})
print(out["grasps"].shape)
```


# gsam2
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/gsam2

Segment objects in image using text prompt

Segment objects in image using text prompt.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="str">
  Text description of objects to segment.
</ParamField>

<ParamField type="float | None">
  Optional confidence threshold (0.0-1.0) for filtering detections.
</ParamField>

<ParamField type="float | None">
  Optional text confidence threshold (0.0-1.0).
</ParamField>

<ParamField type="float | None">
  Optional Non-Maximum-Suppression threshold (0.0-1.0).
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

np.ndarray: Binary segmentation mask as numpy array (H, W) with dtype uint8.
Foreground pixels are 255, background pixels are 0.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
mask = client.run(ModelType.GSAM2, image_input=image, prompt="a cat")
print(mask.shape)  # (480, 640)
```

Combines Grounding DINO with SAM 2.

## Example Output

<img alt="GSAM2 text-prompted segmentation output" />

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
img = Image.open("scene.jpg")  # 640x480 RGB
mask = client.run(model_id="gsam2", image_input=img, prompt="street")

print(mask.shape, mask.dtype)
# (480, 640) uint8

foreground = np.count_nonzero(mask)
print(f"foreground pixels: {foreground} ({foreground / mask.size * 100:.1f}%)")
# foreground pixels: 138737 (45.2%)
```


# lingbot-map
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/lingbot-map

Reconstruct camera-to-world poses + clip-relative depth from an ordered clip of frames

Reconstruct camera-to-world poses + clip-relative depth from an ordered clip of frames.

<Note>
  Input images up to **1920 x 1080** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Sequence[ImageInput]">
  Ordered clip of 1-32 RGB frames (path, URL, PIL Image, or numpy array). Each call is a self-contained window; chunk longer sequences into overlapping clips and align them client-side.
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

Dict\[str, np.ndarray]: Dict with `"extrinsic"` (N,3,4) camera-to-world in OpenCV axes,
`"intrinsic"` (N,3,3), `"depth"` (N,H,W), and `"depth_conf"`
(N,H,W), all float32. Depth and translation are in one
clip-relative scale (normalised by the clip's mean anchor
distance) — not metres; recover physical scale externally.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
client = CortexClient()
result = client.run(ModelType.LINGBOT_MAP, images=frames)
print(result["extrinsic"].shape, result["depth"].shape)  # (N, 3, 4) (N, H, W)
```


# locate_anything
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/locate_anything

Localize objects in an image with LocateAnything-3B

Localize objects in an image with LocateAnything-3B.

<Note>
  Input images up to **1280 x 1280** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  RGB image.
</ParamField>

<ParamField type="str">
  "detect" (open-vocabulary detection over comma-separated categories), "ground" (locate a referring phrase), or "point".
</ParamField>

<ParamField type="str">
  Categories (detect) or referring phrase (ground/point).
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict\[str, Any]: Backend response.

* detect/ground: \{"output": \{"boxes": \[\[x1,y1,x2,y2], ...],
  "labels": \[...], "scores": \[...]}}
* point: \{"output": \{"points": \[\[x, y], ...]}}

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
client = CortexClient()
result = client.run(ModelType.LOCATE_ANYTHING, image_input=image,
                    task="detect", prompt="person, car")
print(result["output"]["boxes"])
```


# metric3d
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/metric3d

Estimate metric depth and/or surface normals from a single RGB image

Estimate metric depth and/or surface normals from a single RGB image.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

<ParamField type="Optional[Union[str, Sequence[str]]]">
  Keyword-only. Optional selection of maps to return — `"depth"`, `"normals"`, or a non-empty subset of both. `None` (default) returns both. Requesting only what you need shrinks the response payload (normals are 3x the size of depth).
</ParamField>

## Returns

Dict with the requested subset of:

* `"depth"`: (H, W) float32 array, metric depth in metres.
* `"normals"`: (H, W, 3) float32 array, unit surface normals.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
client = CortexClient()
result = client.run(ModelType.METRIC3D, ...)
```

Uses Metric3D ViT-Large.

## Example Output

### Depth

<img alt="Metric3D input and depth map output" />

The depth map contains per-pixel metric distance in meters. Brighter regions (yellow/white) are farther from the camera; darker regions (purple/black) are closer. Values are absolute metric depth — larger values mean greater distance, and you can directly compare values across different images.

### Surface Normals

<img alt="Metric3D input and surface normals output" />

Surface normals represent the direction each surface faces as a unit vector `(x, y, z)`. In the RGB visualization, each channel maps to an axis: **red = +x** (right), **green = +y** (down), **blue = +z** (away from camera). Flat surfaces appear as uniform color; edges and curves show color transitions. Normals are mapped to RGB as `(normal + 1) / 2 * 255` for display.

### Working with the outputs

```python theme={null}
from grid_cortex_client import CortexClient
from PIL import Image

client = CortexClient()
image = Image.open("scene.jpg")  # 640x480 RGB
result = client.run(model_id="metric3d", image_input=image)

depth = result["depth"]
normals = result["normals"]

print(depth.shape, depth.dtype)
# (480, 640) float32

print(f"depth: min={depth.min():.3f}, max={depth.max():.3f}, mean={depth.mean():.3f} (meters)")
# depth: min=0.100, max=1.478, mean=0.621 (meters)

print(normals.shape, normals.dtype)
# (480, 640, 3) float32

# Visualize normals as RGB: map [-1, 1] to [0, 255]
normals_vis = ((normals + 1) / 2 * 255).clip(0, 255).astype("uint8")
Image.fromarray(normals_vis).save("normals_vis.png")
```


# moondream
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/moondream

Generate text response from image using Moondream

Generate text response from image using Moondream.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  RGB image.
</ParamField>

<ParamField type="str">
  Task type - "vqa" (Visual Question Answering), "caption" (Image Captioning), "detect" (Object Detection), or "point" (Pointing/Clickable points).
</ParamField>

<ParamField type="str">
  Text prompt/question about the image (required for vqa, detect, point tasks).
</ParamField>

<ParamField type="str">
  Caption length - "short" or "normal" (only for caption task).
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict\[str, Any]: Backend JSON response containing generated text or structured data.

* For vqa/caption: \{"output": "text response"}
* For detect: \{"output": \{"boxes": \[...], "scores": \[...], "labels": \[...]}}
* For point: \{"output": numpy array of (x,y) points}

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("path/to/kitchen.jpg"))
result = client.run(ModelType.MOONDREAM, image_input=image, task="vqa", prompt="How many cups are on the table?")
print(result["output"])  # Text answer
result = client.run(ModelType.MOONDREAM, image_input=image, task="caption", length="short")
print(result["output"])  # Text caption
result = client.run(ModelType.MOONDREAM, image_input=image, task="detect", prompt="cup, plate, bowl")
print(result["output"])  # Dict with boxes, scores, labels
result = client.run(ModelType.MOONDREAM, image_input=image, task="point", prompt="the red cup")
print(result["output"])  # Numpy array of (x,y) points
```

## Example Output

<img alt="Moondream VQA, caption, detect, and point task outputs" />

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
image = np.array(Image.open("scene.jpg"))  # 640x480 RGB

# Visual Question Answering
vqa = client.run(model_id="moondream", image_input=image, task="vqa",
                 prompt="What kind of scene is this?")
print(vqa["output"])
# "This is a city street scene, featuring a wide, empty road with
#  buildings on both sides."

# Image Captioning
caption = client.run(model_id="moondream", image_input=image, task="caption", length="short")
print(caption["output"])
# "A bustling city street at night features tall buildings, colorful
#  signs, and streetlights, with a train station and overpass in the
#  distance."

# Object Detection
dets = client.run(model_id="moondream", image_input=image, task="detect",
                  prompt="sign")
print(len(dets["output"]["boxes"]))
# 9
print(dets["output"]["boxes"][:3])
# [[86.25, 4.22, 142.5, 93.28],
#  [1.56, 33.05, 48.44, 109.45],
#  [176.25, 131.25, 203.75, 191.25]]

# Pointing
points = client.run(model_id="moondream", image_input=image, task="point",
                    prompt="street light")
print(points["output"]["points"][:3])
# [[584.375, 116.25], [589.375, 121.41], [531.875, 129.375]]
```


# oneformer
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/oneformer

Segment an image using OneFormer

Segment an image using OneFormer.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  RGB input image.
</ParamField>

<ParamField type="str">
  "panoptic", "semantic" or "instance".
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict\[str, Any]: Backend-specific segmentation output.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
result = client.run(ModelType.ONEFORMER, image_input=image, mode="semantic")
```

## Example Output

<img alt="OneFormer semantic segmentation output with label map" />

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
img = Image.open("scene.jpg")  # 640x480 RGB
result = client.run(
    model_id="oneformer",
    image_input=img,
    mode="semantic",
)

print(result.keys())
# dict_keys(['output', 'label_map', 'latency_ms'])

print(result["output"].shape)
# (480, 640)

print(np.unique(result["output"]))
# [ 1  2  4  6 11 17 32 36 38 43 69 86]

print(result["label_map"])
# {1: 'building', 2: 'sky', 4: 'tree', 6: 'road, route',
#  11: 'sidewalk, pavement', 17: 'plant', 32: 'fence',
#  36: 'lamp', 38: 'rail', 43: 'signboard, sign'}

print(f"latency: {result['latency_ms']:.1f} ms")
# latency: 249.6 ms
```


# owlv2
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/owlv2

Detect objects in image using text prompt

Detect objects in image using text prompt.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="str">
  Text description of objects to detect.
</ParamField>

<ParamField type="float | None">
  Optional confidence threshold (0.0-1.0) for filtering detections.
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

Dictionary with keys:

* "boxes": List of bounding boxes as \[x1, y1, x2, y2] coordinates
* "scores": List of confidence scores (0.0-1.0)
* "labels": List of label indices

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
dets = client.run(ModelType.OWLV2, image_input=image, prompt="a cat")
print(f"Found {len(dets['boxes'])} objects")
```

Uses Google's OWL-ViT v2.

## Tips

* Prompt with period-separated object phrases, e.g. `"car. person. traffic light"`.
* `box_threshold` defaults to `0.2`.

## Example Output

<img alt="OWLv2 object detection output with bounding boxes" />

```python theme={null}
from grid_cortex_client import CortexClient
from PIL import Image

client = CortexClient()
image = Image.open("scene.jpg")  # 640x480 RGB
dets = client.run(
    model_id="owlv2",
    image_input=image,
    prompt="building.",
    box_threshold=0.1,
)

print(len(dets["boxes"]))
# 10

# Top detections:
print(dets["scores"][0], dets["boxes"][0])
# 0.152  [122.0, 5.7, 187.9, 227.1]

print(dets["scores"][1], dets["boxes"][1])
# 0.271  [167.7, 26.6, 334.8, 242.4]

print(dets["scores"][2], dets["boxes"][2])
# 0.165  [-0.5, -0.9, 179.5, 242.3]
```


# pi05
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/pi05

Run PI05 policy inference on robot observations

Run PI05 policy inference on robot observations.

## Parameters

<ParamField type="ImageInput">
  Base camera RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="ImageInput">
  Wrist camera RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="Union[np.ndarray, list]">
  Joint positions as numpy array or list.
</ParamField>

<ParamField type="Union[np.ndarray, list]">
  Gripper position as numpy array or list.
</ParamField>

<ParamField type="Union[np.ndarray, list]">
  Robot state as numpy array or list (concatenation of joints and gripper).
</ParamField>

<ParamField type="Optional[str]">
  Optional task prompt string.
</ParamField>

<ParamField type="Optional[Dict[str, Any]]">
  Optional real-time-chunking params (see :py:meth:`preprocess`). When set, the server runs the RTC path and returns a `prev_chunk` field to feed back on the next call.
</ParamField>

<ParamField type="Optional[Union[np.ndarray, list]]">
  Previous predicted chunk fed back as RTC guidance (None on the first call).
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

Action dictionary containing:

* "actions": numpy array of shape (horizon, action\_dim) with predicted actions
* "prev\_chunk": (RTC only) chunk to feed back on the next call
* Other fields from policy.infer() (e.g., "state", "policy\_timing", etc.)

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
client = CortexClient()
base_img = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
wrist_img = np.random.randint(0, 255, (224, 224, 3), dtype=np.uint8)
joints = np.array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6])
gripper = np.array([0.5])
state = np.concatenate([joints, gripper])
action = client.run(
    ModelType.PI05,
    base_rgb=base_img,
    wrist_rgb=wrist_img,
    joints=joints,
    gripper=gripper,
    state=state,
    prompt="pick up the cup"
)
print(action["actions"].shape)
```


# qwen_vl
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/qwen_vl

Generate text response from image using Qwen3-VL

Generate text response from image using Qwen3-VL.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  RGB image.
</ParamField>

<ParamField type="str">
  Text prompt/question about the image.
</ParamField>

<ParamField type="int">
  Maximum number of tokens to generate.
</ParamField>

<ParamField type="float">
  Sampling temperature (0 = greedy).
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict\[str, Any]: Backend JSON response containing:

* "output": Generated text response string.
* "latency\_ms": Server-side processing time.
* "gpu\_stats": GPU memory usage statistics.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("path/to/image.jpg"))
result = client.run(ModelType.QWEN_VL, image_input=image, prompt="What do you see?")
print(result["output"])  # Text answer
```

Uses Qwen3-VL-4B.

## Example Output

<img alt="Qwen VL input image and text response" />

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
image = np.array(Image.open("scene.jpg"))  # 640x480 RGB
result = client.run(
    model_id="qwen_vl",
    image_input=image,
    prompt="What objects can you see in this scene? List them.",
    max_new_tokens=128,
    temperature=0.3,
)

print(result.keys())
# dict_keys(['output', 'latency_ms', 'gpu_stats'])

print(result["output"])
# "Based on the image provided, here is a list of objects that can be
#  seen in the scene:\n\n- **Street**: A wide, empty asphalt road...
#  \n- **Sidewalks**: Concrete sidewalks on both sides...
#  \n- **Buildings**: Multi-story buildings...
#  \n- **Signage**: Various signs on buildings..."

print(f"latency: {result['latency_ms']:.1f} ms")
# latency: 4323.4 ms
```


# rdt-1b
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/rdt-1b

Run RDT-1B policy inference on robot observations

Run RDT-1B policy inference on robot observations.

## Parameters

<ParamField type="ImageInput">
  Current camera frame as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="Union[np.ndarray, list]">
  Robot joint state as numpy array or list (7 arm joints + gripper).
</ParamField>

<ParamField type="str">
  Natural-language task instruction string.
</ParamField>

<ParamField type="Optional[ImageInput]">
  Previous camera frame, or None on the first call of an episode.
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

Action dictionary containing:

* "actions": numpy array of shape (64, 8) with predicted actions

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
client = CortexClient()
result = client.run(ModelType.RDT_1B, ...)
```


# roborefer
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/roborefer

Locate points in an image matching a spatial-referring query

Locate points in an image matching a spatial-referring query.

<Note>
  Input images up to **1280 x 1280** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  RGB image.
</ParamField>

<ParamField type="str">
  Spatial-referring query.
</ParamField>

<ParamField type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

Dict\[str, Any]: `&#123;"output": &#123;"points": [[x, y], ...]&#125;&#125;` in pixel coordinates.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
client = CortexClient()
result = client.run(ModelType.ROBOREFER, image_input=image,
                    prompt="the free area between the two boxes")
print(result["output"]["points"])
```


# sam2
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/sam2

Segment image with SAM-2 given point/box prompts

Segment image with SAM-2 given point/box prompts.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="Union[str, Image.Image, np.ndarray]">
  RGB image.
</ParamField>

<ParamField type="List[List[int]]">
  List of `[x, y]` pixel coordinates.
</ParamField>

<ParamField type="List[int]">
  1 = foreground, 0 = background per prompt.
</ParamField>

<ParamField type="bool">
  If *True* returns multiple masks.
</ParamField>

<ParamField type="str">
  Endpoint mode; only "image" currently supported.
</ParamField>

<ParamField type="float | None">
  HTTP timeout.
</ParamField>

## Returns

np.ndarray: Binary segmentation mask as numpy array (H, W) with dtype uint8.
Foreground pixels are 255, background pixels are 0.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
mask = client.run(
    ModelType.SAM2,
    image_input=image,
    prompts=[[320, 240]],
    labels=[1],
)
print(mask.shape)  # (480, 640)
```

## Example Output

<img alt="SAM2 point-prompted segmentation output" />

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
img = Image.open("scene.jpg")  # 640x480 RGB
mask = client.run(
    model_id="sam2",
    image_input=img,
    prompts=[[320, 350]],
    labels=[1],  # 1 = foreground
)

print(mask.shape, mask.dtype)
# (480, 640) uint8

print(np.unique(mask))
# [0, 255]

foreground = np.count_nonzero(mask)
print(f"foreground pixels: {foreground} ({foreground / mask.size * 100:.1f}%)")
# foreground pixels: 138532 (45.1%)
```


# sam3
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/sam3

Segment an image with SAM-3 using exactly one prompt type

Segment an image with SAM-3 using exactly one prompt type.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="Optional[str]">
  Text prompt describing objects to segment (exclusive with points/boxes).
</ParamField>

<ParamField type="Optional[Iterable[Iterable[float]]]">
  List of \[x, y] point coordinates (exclusive with text/boxes).
</ParamField>

<ParamField type="Optional[Iterable[Iterable[float]]]">
  List of \[x0, y0, x1, y1] box coordinates (exclusive with text/points).
</ParamField>

<ParamField type="Optional[Iterable[int]]">
  Required for points/boxes. 1=foreground, 0=background.
</ParamField>

<ParamField type="Optional[float]">
  Optional HTTP timeout in seconds.
</ParamField>

## Returns

np.ndarray: Binary segmentation mask as numpy array (H, W) with dtype uint8.
Foreground pixels are 255, background pixels are 0.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
# Text prompt
mask = client.run(ModelType.SAM3, image_input=image, text="cat")
# Point prompts
mask = client.run(
    ModelType.SAM3, image_input=image,
    points=[[320, 240]], labels=[1]
)
# Box prompts
mask = client.run(
    ModelType.SAM3, image_input=image,
    boxes=[[100, 120, 520, 480]], labels=[1]
)
```

SAM3 offers two client methods:

* **`run()`** — Returns a single union mask. Use when you only need the combined segmentation.
* **`run_with_detections()`** — Returns the union mask plus per-instance masks, bounding boxes, and confidence scores. Use when you need individual object information (e.g. counting objects, filtering by confidence, or processing instances separately). Only available for **text** and **box** prompts — point prompts have no detection semantics.

## `run_with_detections()`

Same call signature as `run()`. Returns a `dict` with keys:

* `union_mask` — Combined binary mask `(H, W)`, dtype `uint8` (same as `run()` output)
* `masks` — List of per-instance binary masks, each `(H, W)` dtype `uint8`
* `boxes` — List of `[x0, y0, x1, y1]` bounding boxes (text/box prompts only)
* `scores` — List of confidence scores (sorted descending)

For point prompts, `masks`, `boxes`, and `scores` will be empty lists.

## Example Output — `run()`

<img alt="SAM3 run() output — union mask overlay on input image" />

Use `run()` when you only need the combined mask — e.g. masking a region, computing area, or passing to a downstream model.

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
img = Image.open("cats.jpg")  # 640x480 RGB

# Text prompt — returns a single union mask
mask = client.run(model_id="sam3", image_input=img, text="cat")
print(mask.shape, mask.dtype)
# (480, 640) uint8
fg = np.count_nonzero(mask)
print(f"foreground: {fg} pixels ({fg / mask.size * 100:.1f}%)")
# foreground: 107198 pixels (34.9%)

# Points prompt — click on center of image
points_mask = client.run(
    model_id="sam3",
    image_input=img,
    points=[[320, 240]],
    labels=[1],
)
fg = np.count_nonzero(points_mask)
print(f"foreground: {fg} pixels ({fg / points_mask.size * 100:.1f}%)")
# foreground: 137017 pixels (44.6%)

# Boxes prompt — box around the right cat
boxes_mask = client.run(
    model_id="sam3",
    image_input=img,
    boxes=[[347, 26, 639, 369]],
    labels=[1],
)
fg = np.count_nonzero(boxes_mask)
print(f"foreground: {fg} pixels ({fg / boxes_mask.size * 100:.1f}%)")
# foreground: 107299 pixels (34.9%)
```

## Example Output — `run_with_detections()`

<img alt="SAM3 run_with_detections() output — per-instance masks, bounding boxes, and confidence scores" />

Use `run_with_detections()` when you need per-instance information — e.g. counting objects, filtering by confidence, or processing each instance separately. Works with **text** and **box** prompts only.

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
img = Image.open("cats.jpg")  # 640x480 RGB

# Text prompt with per-instance detections
result = client.run_with_detections(model_id="sam3", image_input=img, text="cat")

print(result.keys())
# dict_keys(['union_mask', 'boxes', 'scores', 'masks'])

print(result["union_mask"].shape, result["union_mask"].dtype)
# (480, 640) uint8

print(f"instances found: {len(result['masks'])}")
# instances found: 2

for i, (mask, box, score) in enumerate(zip(result["masks"], result["boxes"], result["scores"])):
    fg = np.count_nonzero(mask)
    print(f"  instance {i}: score={score:.4f}, box={box}, pixels={fg}")
# instance 0: score=0.9327, box=[14.58, 55.12, 315.22, 473.21], pixels=50090
# instance 1: score=0.9252, box=[347.68, 26.83, 638.91, 368.76], pixels=57108

# Filter by confidence
high_conf = [s for s in result["scores"] if s > 0.9]
print(f"high-confidence instances: {len(high_conf)}")
# high-confidence instances: 2

# Boxes prompt with per-instance detections
result = client.run_with_detections(
    model_id="sam3",
    image_input=img,
    boxes=[[14, 55, 315, 473], [347, 26, 639, 369]],
    labels=[1, 1],
)
print(f"instances: {len(result['masks'])}")
# instances: 2

for i, (mask, box, score) in enumerate(zip(result["masks"], result["boxes"], result["scores"])):
    fg = np.count_nonzero(mask)
    print(f"  instance {i}: score={score:.4f}, box={box}, pixels={fg}")
# instance 0: score=0.9905, box=[347.76, 26.36, 638.77, 370.08], pixels=57268
# instance 1: score=0.9903, box=[15.29, 55.16, 314.74, 472.38], pixels=49950
```


# sam3-1
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/sam3-1

Segment an image with SAM-3.1 using exactly one prompt type

Segment an image with SAM-3.1 using exactly one prompt type.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="Optional[str]">
  Text prompt describing objects to segment (exclusive with points/boxes).
</ParamField>

<ParamField type="Optional[Iterable[Iterable[float]]]">
  List of \[x, y] point coordinates (exclusive with text/boxes).
</ParamField>

<ParamField type="Optional[Iterable[Iterable[float]]]">
  List of \[x0, y0, x1, y1] box coordinates (exclusive with text/points).
</ParamField>

<ParamField type="Optional[Iterable[int]]">
  Required for points/boxes. 1=foreground, 0=background.
</ParamField>

<ParamField type="Optional[float]">
  Optional HTTP timeout in seconds.
</ParamField>

## Returns

np.ndarray: Binary segmentation mask as numpy array (H, W) with dtype uint8.
Foreground pixels are 255, background pixels are 0.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
# Text prompt
mask = client.run(ModelType.SAM3_1, image_input=image, text="cat")
# Point prompts
mask = client.run(
    ModelType.SAM3_1, image_input=image,
    points=[[320, 240]], labels=[1]
)
# Box prompts
mask = client.run(
    ModelType.SAM3_1, image_input=image,
    boxes=[[100, 120, 520, 480]], labels=[1]
)
```


# zoedepth
Source: https://docs.generalrobotics.dev/v2.3/models/cortex/zoedepth

Estimate depth from single RGB image

Estimate depth from single RGB image.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField type="ImageInput">
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField type="float | None">
  Optional timeout in seconds for the HTTP request.
</ParamField>

## Returns

np.ndarray: Depth map as numpy array (H, W) with dtype float32.
Values represent metric depth in meters.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
depth = client.run(ModelType.ZOEDEPTH, image_input=image)
print(depth.shape)  # (480, 640)
```

The server returns the depth map as `float16` on the wire; the client converts it to `float32`.

## Example Output

<img alt="ZoeDepth input and depth map output" />

```python theme={null}
from grid_cortex_client import CortexClient
from PIL import Image

client = CortexClient()
image = Image.open("scene.jpg")  # 640x480 RGB
depth = client.run(model_id="zoedepth", image_input=image)

print(depth.shape, depth.dtype)
# (480, 640) float32

print(f"min={depth.min():.4f}, max={depth.max():.4f}, mean={depth.mean():.4f}")
# min=1.5889, max=10.2891, mean=4.6381  (meters)
```


# Overview
Source: https://docs.generalrobotics.dev/v2.3/models/overview



GRID provides a comprehensive suite of AI models for robotics — covering depth estimation, object detection, segmentation, vision-language understanding, robot control, and more.

The fastest way to use these models is through **GRID Cortex**, our cloud-hosted inference service. Install the client, set your API key, and call any model in two lines of Python.

<CardGroup>
  <Card title="GRID Cortex Client" icon="bolt" href="/v2.3/models/cortex">
    Get started in 2 lines of code — unified API for all hosted models including depth, detection, segmentation, grasping, VLMs, and robot control.
  </Card>
</CardGroup>

Browse the hosted catalog in the **Cortex Models** section of the sidebar —
each model page covers inputs, outputs, and a runnable example.


# AirGenCar
Source: https://docs.generalrobotics.dev/v2.3/python-api/airgen-robots/airgencar

AirGen simulation car implementation

```python theme={null}
from grid_sim_client.airgen.robot import AirGenCar
```

AirGen simulation car implementation.

This class provides an interface to control simulated wheeled cars in AirGen
using the CarClient from the grid\_sim\_client.airgen client.

## Constructor

```python Signature theme={null}
AirGenCar(
    ip: str = '127.0.0.1',
    port: int = 41471,
    timeout_value: int = 3600,
    vehicle_name: str = '',
)
```

Initialize a simulated AirGen car client.

<ParamField type="str">
  IP address of the AirGen server. (default: "127.0.0.1")
</ParamField>

<ParamField type="int">
  Port number for the AirGen server. (default: 41471)
</ParamField>

<ParamField type="int">
  Timeout value for the connection in seconds. (default: 3600)
</ParamField>

<ParamField type="str">
  Name of the vehicle in the simulation. (default: "")
</ParamField>

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `cleanup()`

```python Signature theme={null}
cleanup() -> None
```

Release AirGen transport resources and unregister base cleanup.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getBarometerData()`

```python Signature theme={null}
getBarometerData(barometer_name: str = 'barometer')
```

### `getDistanceSensorData()`

```python Signature theme={null}
getDistanceSensorData(distance_sensor_name: str = 'front_range')
```

### `getGpsData()`

```python Signature theme={null}
getGpsData(gps_name: str = 'gps')
```

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', image_type: str = 'rgb', **kwargs) -> Image
```

Get an image from the specified camera.

<ParamField type="str">
  Name of the camera in the AirGen scene. (default: "front\_center")
</ParamField>

<ParamField type="str">
  Image type, one of ("rgb"|"depth"). (default: "rgb")
</ParamField>

**Returns:**

Image: Captured image wrapped in the project's Image type.

### `getImuData()`

```python Signature theme={null}
getImuData(imu_name: str = 'imu')
```

### `getLidarData()`

```python Signature theme={null}
getLidarData(lidar_name: str = 'front_lidar')
```

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMagnetometerData()`

```python Signature theme={null}
getMagnetometerData(magnetometer_name: str = 'magnetometer')
```

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the car in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation as a quaternion (x, y, z, w).

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the car in the world frame.

**Returns:**

Optional\[Position]: Current position of the car in world coordinates.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(proprioception_items: Optional[list[str]] = None) -> dict
```

Get the current state of the car.

**Returns:**

dict: Current state including position, orientation, and velocity.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Move the car with a velocity command.

For cars, velocity control is limited. The linear\_velocity.x\_vel controls
forward/backward speed, and angular\_velocity.z\_vel controls turning rate.

<ParamField type="Velocity">
  Linear velocity in m/s (x\_vel used for forward speed).
</ParamField>

<ParamField type="Velocity">
  Angular velocity in rad/s (z\_vel/yaw rate is used).
</ParamField>

<ParamField type="str">
  Reference frame for velocity ("body" only). (default: "body")
</ParamField>

**Returns:**

None

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Stop the car by zeroing target speed and controls.

**Returns:**

None


# AirGenDrone
Source: https://docs.generalrobotics.dev/v2.3/python-api/airgen-robots/airgendrone

AirGen simulation multirotor drone implementation

```python theme={null}
from grid_sim_client.airgen.robot import AirGenDrone
```

AirGen simulation multirotor drone implementation.

This class provides an interface to control simulated multirotor drones in AirGen
using the MultirotorClient from the grid\_sim\_client.airgen client.

## Constructor

```python Signature theme={null}
AirGenDrone(
    ip: str = '127.0.0.1',
    port: int = 41461,
    timeout_value: int = 3600,
    vehicle_name: str = '',
)
```

Initialize a simulated AirGen multirotor client.

<ParamField type="str">
  IP address of the AirGen server. (default: "127.0.0.1")
</ParamField>

<ParamField type="int">
  Port number for the AirGen server. (default: 41461)
</ParamField>

<ParamField type="int">
  Timeout value for the connection in seconds. (default: 3600)
</ParamField>

<ParamField type="str">
  Name of the vehicle in the simulation. (default: "")
</ParamField>

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `cleanup()`

```python Signature theme={null}
cleanup() -> None
```

Release AirGen transport resources and unregister base cleanup.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getBarometerData()`

```python Signature theme={null}
getBarometerData(barometer_name: str = 'barometer')
```

### `getDistanceSensorData()`

```python Signature theme={null}
getDistanceSensorData(distance_sensor_name: str = 'front_range')
```

### `getGpsData()`

```python Signature theme={null}
getGpsData(gps_name: str = 'gps')
```

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', image_type: str = 'rgb', **kwargs) -> Image
```

Get an image from the specified camera.

<ParamField type="str">
  Name of the camera in the AirGen scene. (default: "front\_center")
</ParamField>

<ParamField type="str">
  Image type, one of ("rgb"|"depth"). (default: "rgb")
</ParamField>

**Returns:**

Image: Captured image wrapped in the project's Image type.

### `getImuData()`

```python Signature theme={null}
getImuData(imu_name: str = 'imu')
```

### `getLidarData()`

```python Signature theme={null}
getLidarData(lidar_name: str = 'front_lidar')
```

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMagnetometerData()`

```python Signature theme={null}
getMagnetometerData(magnetometer_name: str = 'magnetometer')
```

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the drone in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation as a quaternion (x, y, z, w).

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the drone in the world frame.

**Returns:**

Optional\[Position]: Current position of the drone in world coordinates.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(proprioception_items: Optional[list[str]] = None) -> dict
```

Get the current state of the drone.

**Returns:**

dict: Current state including position, orientation, and velocity.

### `land()`

```python Signature theme={null}
land() -> None
```

Command the drone to land at its current position.

**Returns:**

None

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    *,
    duration: float = 1.0,
) -> None
```

Move the drone with a velocity command in m/s.

The command applies for the given duration. For the body frame, velocity is
relative to the drone's orientation. For the world frame, velocity is in the
global coordinate system.

<ParamField type="Velocity">
  Linear velocity in m/s (x, y, z).
</ParamField>

<ParamField type="Velocity">
  Angular velocity in rad/s (z\_vel/yaw rate is used).
</ParamField>

<ParamField type="str">
  Reference frame for velocity ("body" or "world"). (default: "body")
</ParamField>

<ParamField type="float">
  Duration in seconds for the command to apply. (default: 1.0)
</ParamField>

**Returns:**

None

### `moveToPosition()`

```python Signature theme={null}
moveToPosition(position: Position, velocity: float, timeout_sec: float = 60) -> None
```

Move the drone to a specified position in the world frame.

<ParamField type="Position">
  Target position in meters (x, y, z).
</ParamField>

<ParamField type="float">
  Velocity in m/s.
</ParamField>

<ParamField type="float">
  Timeout for the operation in seconds. (default: 60)
</ParamField>

**Returns:**

None

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Stop the drone by commanding zero velocity.

**Returns:**

None

### `takeoff()`

```python Signature theme={null}
takeoff() -> None
```

Command the drone to take off and hover.

**Returns:**

None


# AirGenQuad
Source: https://docs.generalrobotics.dev/v2.3/python-api/airgen-robots/airgenquad

AirGen simulation quadruped implementation

```python theme={null}
from grid_sim_client.airgen.robot import AirGenQuad
```

AirGen simulation quadruped implementation.

This class provides an interface to control simulated quadruped robots in AirGen
using the CVMoverClient from the grid\_sim\_client.airgen client.

## Constructor

```python Signature theme={null}
AirGenQuad(
    ip: str = '127.0.0.1',
    port: int = 41481,
    timeout_value: int = 3600,
    robot_name: str = '',
)
```

Initialize a simulated AirGen quadruped client.

<ParamField type="str">
  IP address of the AirGen server. (default: "127.0.0.1")
</ParamField>

<ParamField type="int">
  Port number for the AirGen server. (default: 41481)
</ParamField>

<ParamField type="int">
  Timeout value for the connection in seconds. (default: 3600)
</ParamField>

<ParamField type="str">
  Name of the robot in the simulation. (default: "")
</ParamField>

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `cleanup()`

```python Signature theme={null}
cleanup() -> None
```

Release AirGen transport resources and unregister base cleanup.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getBarometerData()`

```python Signature theme={null}
getBarometerData(barometer_name: str = 'barometer')
```

### `getDistanceSensorData()`

```python Signature theme={null}
getDistanceSensorData(distance_sensor_name: str = 'front_range')
```

### `getGpsData()`

```python Signature theme={null}
getGpsData(gps_name: str = 'gps')
```

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', image_type: str = 'rgb', **kwargs) -> Image
```

Get an image from the specified camera.

<ParamField type="str">
  Name of the camera in the AirGen scene. (default: "front\_center")
</ParamField>

<ParamField type="str">
  Image type, one of ("rgb"|"depth"). (default: "rgb")
</ParamField>

**Returns:**

Image: Captured image wrapped in the project's Image type.

### `getImuData()`

```python Signature theme={null}
getImuData(imu_name: str = 'imu')
```

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> list[float]
```

Get current joint angles in radians.

CVMoverClient doesn't provide direct joint angle access in the standard API.
This would require accessing lower-level state information.

**Returns:**

list\[float]: Current joint angles in radians.

### `getLidarData()`

```python Signature theme={null}
getLidarData(lidar_name: str = 'front_lidar')
```

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMagnetometerData()`

```python Signature theme={null}
getMagnetometerData(magnetometer_name: str = 'magnetometer')
```

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the quadruped in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation as a quaternion (x, y, z, w).

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the quadruped in the world frame.

**Returns:**

Optional\[Position]: Current position of the quadruped in world coordinates.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState(proprioception_items: Optional[list[str]] = None) -> dict
```

Get the current state of the quadruped.

**Returns:**

dict: Current state including position, orientation, and velocity.

### `lieDown()`

```python Signature theme={null}
lieDown() -> None
```

Command the robot to lie down.

CVMoverClient doesn't have an explicit lieDown command. Users can stop the
robot and it will settle into a stable pose.

**Returns:**

None

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Move the quadruped with a twist command (linear + angular velocity).

In body frame, the velocity is continuously re-applied in the robot's
instantaneous body frame, so a non-zero yaw rate produces curved motion.

<ParamField type="Velocity">
  Linear velocity in m/s (x, y, z).
</ParamField>

<ParamField type="Velocity">
  Angular velocity in rad/s; only the z component (yaw rate) is used.
</ParamField>

<ParamField type="str">
  Reference frame for the linear velocity ("body" or "world"). (default: "body")
</ParamField>

**Returns:**

None

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setDefaultJointAngles()`

```python Signature theme={null}
setDefaultJointAngles(joint_pos: list) -> None
```

Set the default joint position for the robot.

<ParamField>
  Value of the joint position.
</ParamField>

### `setDefaultJointVelocities()`

```python Signature theme={null}
setDefaultJointVelocities(joint_vel: list) -> None
```

Set the default joint velocity for the robot.

<ParamField>
  Value of the joint velocity.
</ParamField>

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = True,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
) -> None
```

Set joint angles in radians.

CVMoverClient doesn't provide direct joint angle control in the standard API.
The robot is controlled via velocity and position commands at a higher level.

<ParamField type="list">
  List of target joint angles in radians.
</ParamField>

<ParamField type="bool">
  Wait for movement to complete. (default: True)
</ParamField>

<ParamField type="Optional[float]">
  Time to complete the movement in seconds.
</ParamField>

<ParamField type="Optional[float]">
  Time to accelerate/decelerate in seconds.
</ParamField>

**Returns:**

None

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `standUp()`

```python Signature theme={null}
standUp() -> None
```

Command the robot to stand up.

This is typically handled automatically when the robot starts moving.
For explicit gait control, use the underlying CVMoverClient methods.

**Returns:**

None

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Soft e-stop for the robot.

Stops the robot from moving gracefully by sending zero velocity commands.
The API control is toggled off and on to reset the robot's internal
controller state and ensure all movement commands are cleared.

**Returns:**

None


# AirGen robots
Source: https://docs.generalrobotics.dev/v2.3/python-api/airgen-robots/overview

Robots in the AirGen simulator

Robots in the AirGen simulator — GRID's Unreal Engine backend. Each class implements the same neutral robot interface as a physical robot, so code written against a simulated drone runs against a real one.

## Install

```bash theme={null}
# Preinstalled in every GRID simulation session — the generated notebook
# already imports it. For local use, install from the GRID package index
# with your organization's read-only credentials:
export UV_INDEX_GRID_PYPI_USERNAME=<username>
export UV_INDEX_GRID_PYPI_PASSWORD=<token>
uv pip install grid-sim-client --index grid-pypi=https://pypi.generalrobotics.dev/simple/
```

## Quickstart

```python theme={null}
from grid_sim_client.airgen.robot import AirGenDrone

# In a GRID simulation session the notebook creates this for you.
drone = AirGenDrone()
drone.takeoff()
image = drone.getImage("front")
```

The methods these classes expose are defined by the **Robot interface**. The Isaac equivalents are **Isaac robots**.

## Classes

* [`AirGenDrone`](/v2.3/python-api/airgen-robots/airgendrone)
* [`AirGenQuad`](/v2.3/python-api/airgen-robots/airgenquad)
* [`AirGenCar`](/v2.3/python-api/airgen-robots/airgencar)


# AsyncCortexClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-cortex-client/asynccortexclient

Async client for interacting with Grid Cortex Ray Serve deployments

```python theme={null}
from grid_cortex_client import AsyncCortexClient
```

Async client for interacting with Grid Cortex Ray Serve deployments.

## Constructor

```python Signature theme={null}
AsyncCortexClient(
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    timeout: float = 30.0,
    *,
    observer: Optional[RuntimeObserver] = None,
)
```

Initialize the AsyncCortexClient.

<ParamField>
  API key. Uses GRID\_CORTEX\_API\_KEY env var if None.
</ParamField>

<ParamField>
  Base URL of the Cortex API. If None, uses GRID\_CORTEX\_BASE\_URL env var.
</ParamField>

<ParamField>
  Default timeout for HTTP requests in seconds.
</ParamField>

<ParamField>
  Optional caller-owned observer for run events. The client does not close it.
</ParamField>

## Methods

### `available_models()`

```python Signature theme={null}
available_models() -> list[str]
```

Return all registered model identifiers.

This method provides a complete list of all available models that can be
used with the CortexClient. Essential for LLM agents to discover what
models are available before attempting to use them.

**Returns:**

A sorted list of model identifiers (e.g., \["gsam2", "owlv2", "zoedepth"]).
These strings can be used directly with `run` and `help`.

```python theme={null}
client = CortexClient()
models = client.available_models()
print(models)  # ['gsam2', 'owlv2', 'zoedepth']
client.run(models[0], image_input=img)  # Use first available model
```

### `close()`

```python Signature theme={null}
close()
```

Closes the underlying async HTTP client.

### `get_info()`

```python Signature theme={null}
get_info() -> Dict[str, Any]
```

Get Grid-Cortex server version and deployed models status.

Fetches real-time information about the Cortex deployment including
version and current model replica counts.

**Returns:**

Dictionary containing version and models information.

**Raises:**

CortexAPIError: If the API returns an error.
CortexNetworkError: If network communication fails.

### `help()`

```python Signature theme={null}
help(model_id: str) -> str
```

Return comprehensive documentation for a model.

This method provides complete API documentation for any registered model,
including usage examples, parameter descriptions, return types, and error
conditions. Essential for LLM agents to understand how to interact with
specific models before calling `run`.

<ParamField>
  Canonical model identifier (e.g., "zoedepth", "owlv2", "gsam2").
</ParamField>

**Returns:**

A formatted string containing:

* Class-level docstring with usage examples and parameter descriptions
* Preprocess method documentation (input parameters and validation)
* Postprocess method documentation (output format and data types)

**Raises:**

NotImplementedError: If model\_id is not registered or not found.

```python theme={null}
client = CortexClient()
docs = client.help("zoedepth")
print(docs)  # Shows complete zoedepth documentation
# For LLM agents: discover model capabilities
models = client.available_models()
for model in models:
    print(f"=== {model} ===")
    print(client.help(model))
```

### `run()`

```python Signature theme={null}
run(
    model_id: Union[str, ModelType],
    timeout: Optional[float] = None,
    raw_response: bool = False,
    **kwargs: Any,
) -> Any
```

Execute inference using a specified model (async version).

<ParamField>
  The identifier of the model to run.
</ParamField>

<ParamField>
  Optional timeout in seconds for the HTTP request.
</ParamField>

<ParamField>
  If True, returns the raw API response without postprocessing.
</ParamField>

<ParamField>
  Model-specific input parameters. Each model's page in the **Cortex Models** docs section and `help` document its exact inputs.
</ParamField>

**Returns:**

The model's postprocessed output; the concrete type is model-specific.
Per-model inputs, output types, and worked examples live on the model
pages in the **Cortex Models** docs section — generated from each
model wrapper's docstring, the canonical source — and via
`help`.

**Raises:**

NotImplementedError: If model\_id is not found.
CortexAPIError: If the API returns an error.
CortexNetworkError: If network communication fails.
ValueError: If input validation or processing fails.


# CortexExecutionEvent
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-cortex-client/cortexexecutionevent

One phase of a client ``run`` call, correlated by ``call_id``

```python theme={null}
from grid_cortex_client import CortexExecutionEvent
```

One phase of a client `run` call, correlated by `call_id`.

`payload` contains the caller's inputs before model preprocessing;
`response` is the exact returned value, including when `raw_response` is
requested. Observers must not mutate these objects, and must snapshot anything
they retain. `route` is absent if model resolution failed before a request
could be prepared. `error_type` names the exception delivered to the caller.

## Fields

<ResponseField name="call_id" type="str" />

<ResponseField name="model" type="str" />

<ResponseField name="route" type="str | None" />

<ResponseField name="phase" type="Literal['request', 'response', 'error']" />

<ResponseField name="payload" type="dict[str, Any] | None" />

<ResponseField name="response" type="Any" />

<ResponseField name="error_type" type="str | None" />

## Constructor

```python Signature theme={null}
CortexExecutionEvent(
    call_id: str,
    model: str,
    route: str | None,
    phase: Literal['request', 'response', 'error'],
    payload: dict[str, Any] | None = None,
    response: Any = None,
    error_type: str | None = None,
)
```


# CortexHubClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-cortex-client/cortexhubclient

Asynchronous WebSocket client for CortexHub

```python theme={null}
from grid_cortex_client import CortexHubClient
```

Asynchronous WebSocket client for CortexHub.

Provides a persistent WebSocket connection for efficient model inference.
Supports both request-response and pub/sub patterns.

For synchronous usage, use CortexClient instead.

## Constructor

```python Signature theme={null}
CortexHubClient(
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    timeout: float = 60.0,
)
```

## Properties

<ResponseField name="is_connected" type="bool">
  Check if WebSocket connection is active.
</ResponseField>

<ResponseField name="pending_count" type="int">
  Number of published requests awaiting responses.
</ResponseField>

<ResponseField name="url" type="str">
  WebSocket URL this client connects to.
</ResponseField>

## Methods

### `available_models()`

```python Signature theme={null}
available_models() -> list[str]
```

Return registered model identifiers.

### `close()`

```python Signature theme={null}
close() -> None
```

Close WebSocket connection and cleanup pub/sub resources.

### `collect()`

```python Signature theme={null}
collect(count: Optional[int] = None) -> list[HubResult]
```

Collect all results into a list.

Convenience method that collects subscribe() results.

<ParamField>
  If provided, collect exactly this many results. If None, collect until no pending requests remain.
</ParamField>

**Returns:**

List of HubResult objects.

### `connect()`

```python Signature theme={null}
connect() -> None
```

Establish WebSocket connection.

### `help()`

```python Signature theme={null}
help(model_id: str) -> str
```

Return documentation for a model.

### `publish()`

```python Signature theme={null}
publish(
    model_id: Union[str, ModelType],
    request_id: Optional[str] = None,
    **kwargs: Any,
) -> str
```

Publish a model inference request (non-blocking).

Sends the request and returns immediately. Results arrive via subscribe().

<ParamField>
  Model to run (ModelType enum or string)
</ParamField>

<ParamField>
  Optional ID to track this request. Auto-generated if not provided.
</ParamField>

<ParamField>
  Model-specific parameters (e.g., image\_input, prompt)
</ParamField>

**Returns:**

The request\_id (useful when auto-generated)

**Raises:**

RuntimeError: If not connected

### `run()`

```python Signature theme={null}
run(model_id: Union[str, ModelType], **kwargs: Any) -> Any
```

Run model inference via CortexHub (blocking request-response).

<ParamField>
  Model to run (ModelType enum or string)
</ParamField>

<ParamField>
  Model-specific parameters (e.g., image\_input, prompt)
</ParamField>

**Returns:**

Model output (same format as CortexClient.run)

**Raises:**

RuntimeError: If not connected or if pub/sub mode is active
CortexHubError: If server returns an error

### `submit()`

```python Signature theme={null}
submit(
    model_id: Union[str, ModelType],
    request_id: Optional[str] = None,
    timeout_s: float | None = None,
    **kwargs: Any,
) -> 'asyncio.Task[HubResult]'
```

Submit a request and return a Task for its eventual result.

This is a convenience wrapper over the pub/sub API that lets you write:

> > > async with CortexHubClient() as hub:
> > > ...     depth\_t = hub.submit(ModelType.ZOEDEPTH, image\_input=img)
> > > ...     mask\_t = hub.submit(ModelType.GSAM2, image\_input=img, prompt="cat")
> > > ...     depth\_res, mask\_res = await asyncio.gather(depth\_t, mask\_t)

### `subscribe()`

```python Signature theme={null}
subscribe(count: Optional[int] = None) -> AsyncIterator[HubResult]
```

Subscribe to inference results.

Yields results as they arrive from published requests.

<ParamField>
  If provided, stop after receiving this many results. If None, yields indefinitely until no pending requests remain.
</ParamField>

**Yields:**

HubResult objects containing request\_id, model, data, ok, and error.

```python theme={null}
await hub.publish(ModelType.ZOEDEPTH, request_id="d1", image_input=img)
await hub.publish(ModelType.GSAM2, request_id="m1", image_input=img, prompt="cat")
async for result in hub.subscribe(count=2):
    if result.ok:
        print(f"{result.request_id}: shape={result.data.shape}")
    else:
        print(f"{result.request_id}: error={result.error}")
```


# CortexHubError
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-cortex-client/cortexhuberror

Exception for CortexHub errors

```python theme={null}
from grid_cortex_client import CortexHubError
```

Exception for CortexHub errors.

## Constructor

```python Signature theme={null}
CortexHubError(
    message: str,
    model: Optional[str] = None,
    request_id: Optional[str] = None,
)
```


# HubResult
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-cortex-client/hubresult

Result from a published inference request

```python theme={null}
from grid_cortex_client import HubResult
```

Result from a published inference request.

## Fields

<ResponseField name="request_id">
  The ID provided when publishing the request
</ResponseField>

<ResponseField name="model">
  The model that produced this result
</ResponseField>

<ResponseField name="data">
  The inference output (postprocessed)
</ResponseField>

<ResponseField name="ok">
  Whether the request succeeded
</ResponseField>

<ResponseField name="error">
  Error message if ok=False
</ResponseField>

## Constructor

```python Signature theme={null}
HubResult(
    request_id: str,
    model: str,
    data: Any,
    ok: bool = True,
    error: Optional[str] = None,
)
```


# RuntimeObserver
Source: https://docs.generalrobotics.dev/v2.3/python-api/grid-cortex-client/runtimeobserver

Caller-owned observer, invoked synchronously by observing clients

```python theme={null}
from grid_cortex_client import RuntimeObserver
```

Caller-owned observer, invoked synchronously by observing clients.

Methods should finish quickly, for example by queuing a snapshot for a
background writer. The SDK neither flushes nor closes the observer. An
observer shared across clients must support their calling threads/tasks.
Ordinary observer exceptions never replace inference results or exceptions.

## Methods

### `on_error()`

```python Signature theme={null}
on_error() -> None
```

Mark recording incomplete after event construction or delivery failed.

### `on_event()`

```python Signature theme={null}
on_event(event: CortexExecutionEvent) -> None
```

Receive a request, response, or error event.


# IsaacArm
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-robots/isaacarm

Isaac Sim arm implementation backed by Zenoh

```python theme={null}
from grid_sim_client.isaac.robot import IsaacArm
```

Isaac Sim arm implementation backed by Zenoh.

This class provides an interface to control a simulated arm in Isaac Sim
using Zenoh clients for poses, joints, and gripper control.

## Constructor

```python Signature theme={null}
IsaacArm(
    config=default_isaac_config,
    clients: Optional[dict] = None,
    client_bundle: Optional[IsaacClientBundle] = None,
    *,
    robot_name: str = 'ur5e',
    grace_robot_name: Optional[str] = None,
    grace_ee_frame: Optional[str] = None,
    arm_joints: Optional[int] = None,
    arm_joint_names: Optional[list[str]] = None,
    grid_zero_offset: Optional[list[float]] = None,
    gripper_client_name: Optional[str] = None,
    capture_startup_zero_offset: bool = True,
    startup_zero_offset_timeout: float = 10.0,
)
```

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="home_pose" type="list">
  Placeholder home pose — updated dynamically when moveToNamedPose('home') is called.
</ResponseField>

<ResponseField name="named_poses" type="Dict[str, List[float]]">
  Registered poses as `&#123;name: joint angles in radians&#125;` (a copy).

  Mutating the returned mapping does not change what the arm knows:
  register and remove entries with `addNamedPose` and
  `removeNamedPose`, or assign a whole mapping to replace them all.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addNamedPose()`

```python Signature theme={null}
addNamedPose(pose_name: str, joint_angles: List[float]) -> None
```

Define a pose\_name:joint\_angles pair in the dictionary of named poses
(overriding any existing pair).

<ParamField>
  Name of the pose to define
</ParamField>

<ParamField>
  List of joint angles in radians
</ParamField>

**Raises:**

ValueError: If the length of joint\_angles list does match the length of other named
poses

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `captureStartupZeroOffset()`

```python Signature theme={null}
captureStartupZeroOffset(
    *,
    timeout: float = 10.0,
    overwrite: bool = False,
) -> Optional[list[float]]
```

Capture the simulator's startup joint state as the Grid zero offset.

The offset follows the existing Grid convention: Grace joint configs are
converted to simulator commands by subtracting `grid_zero_offset`.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `create_clients()`

```python Signature theme={null}
create_clients(client_config: dict, agent_config: Optional[dict] = None) -> None
```

Create Zenoh clients based on configuration.

<ParamField>
  Dictionary of client configurations
</ParamField>

<ParamField>
  Optional dictionary of agent parameters
</ParamField>

### `endFreeDrive()`

```python Signature theme={null}
endFreeDrive() -> None
```

Exit free-drive mode and return to position control.

The arm is no longer movable by hand and again responds to
position-control commands such as `moveToPose` and
`setJointAngles`.

**Raises:**

NotImplementedError: If the arm does not support free-drive
mode.

### `followJointTrajectory()`

```python Signature theme={null}
followJointTrajectory(
    angles: List[List[float]],
    duration: Union[float, List[float]],
    blocking: bool = True,
) -> None
```

Move the arm through a sequence of joint configurations.

Each waypoint in `angles` is visited in order. The interpretation of
`duration` is uniform across implementations: a scalar is the *total*
trajectory time, split evenly across segments; a list specifies the
duration of each segment, where segment `i` is the move from the
previous pose (or the current arm pose, for `i=0`) to `angles[i]`,
so `len(duration)` must equal `len(angles)`.

Subclasses with a native trajectory-streaming API may blend between
waypoints; subclasses without one typically loop per-segment moves and
briefly stop at each waypoint. Either way the segment timings above
are honored.

<ParamField>
  Sequence of joint configurations (radians) to visit in order. Each inner list must have the same length as the arm's joint count.
</ParamField>

<ParamField>
  Either a single positive float giving the total trajectory time in seconds, or a list of positive floats with the same length as `angles` giving per-segment durations in seconds.
</ParamField>

<ParamField>
  Wait for the trajectory to complete before returning. Defaults to True.
</ParamField>

**Raises:**

NotImplementedError: If the arm does not implement trajectory
following.
ValueError: If `angles` is empty, `duration` is not positive,
or list-form `duration` length does not match `angles`.

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getEndEffectorPose()`

```python Signature theme={null}
getEndEffectorPose() -> Pose
```

```text theme={null}
[Deprecated]
Get the current end effector pose (position + orientation) w.r.t. the base frame.
```

### `getForce()`

```python Signature theme={null}
getForce(name: str = '') -> Force
```

Get force from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Force reading from the wrench client.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', image_type: Optional[str] = 'rgb') -> Image
```

Get an image from a camera client.

<ParamField>
  Name of the image client to read from. If empty, selects the default camera based on image\_type.
</ParamField>

<ParamField>
  Image type used to select the default camera. Accepts "rgb" or "depth".
</ParamField>

**Returns:**

Image: Captured image wrapped in the project's Image type.

**Raises:**

ValueError: If an invalid image\_type is provided.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles() -> Optional[list]
```

Get the current joint angles of the arm.

**Returns:**

Optional\[list]: List of current joint angles in radians.

### `getJointStates()`

```python Signature theme={null}
getJointStates(name: str = 'joint_states') -> Optional[dict]
```

Get complete joint states from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Returns:**

dict | None: Dictionary containing joint names, positions, velocities, and efforts, or
None if not available

**Raises:**

TypeError: If client is not a JointAngleClient

### `getJointVelocities()`

```python Signature theme={null}
getJointVelocities(name: str = 'joint_states') -> Optional[list]
```

Get joint velocities from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMsg()`

```python Signature theme={null}
getMsg(name: str) -> dict
```

Get a message from a named generic client.

<ParamField type="str, optional">
  Name of the generic client
</ParamField>

### `getNamedPose()`

```python Signature theme={null}
getNamedPose(pose_name: str) -> Optional[List[float]]
```

Get the list of joint angles corresponding to a named pose.

<ParamField>
  Name of the pose to get (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose, or None if the named pose does not exist

### `getObjectPose()`

```python Signature theme={null}
getObjectPose(name: str = 'get_object_pose') -> Optional[Tuple[Position, Orientation]]
```

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Orientation
```

Get the current orientation of the end effector.

**Returns:**

Orientation: Current orientation of the end effector as a quaternion (x, y, z, w).

### `getPose()`

```python Signature theme={null}
getPose() -> Pose
```

Get the current end effector pose w\.r.t. the base frame.

**Returns:**

Pose: Current end effector pose.

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the current position of the end effector.

**Returns:**

Optional\[Position]: Current position of the end effector.

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState() -> dict
```

Get the current state of the arm.

**Returns:**

dict: Current state including position, orientation, and joint positions.

### `getTorque()`

```python Signature theme={null}
getTorque(name: str = '') -> Torque
```

Get torque from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Torque reading from the wrench client.

### `grasp()`

```python Signature theme={null}
grasp()
```

Close the gripper.

**Returns:**

None

### `moveToDeltaPose()`

```python Signature theme={null}
moveToDeltaPose(
    delta_pose: Pose,
    blocking: bool = True,
    *,
    moving_time: float = 0.3,
    accel_time: float = 0.15,
)
```

Move the end effector to a relative pose.

<ParamField>
  Desired relative pose offset of the end effector.
</ParamField>

<ParamField>
  Whether to block until the move completes. (unused)
</ParamField>

<ParamField>
  Time allowed for movement in seconds. (unused)
</ParamField>

<ParamField>
  Acceleration time in seconds. (unused)
</ParamField>

**Returns:**

None

### `moveToHome()`

```python Signature theme={null}
moveToHome(blocking: bool = True) -> None
```

Move the arm to its predefined home pose.

Equivalent to `moveToNamedPose("home", blocking=blocking)`. The
`"home"` entry is registered in `named_poses` from the abstract
`home_pose` property during `Arm.__init__`, so every concrete
arm has it. Subclasses may add hardware-specific tuning parameters as
keyword-only arguments after `blocking`.

<ParamField>
  Wait for movement to complete. Defaults to True.
</ParamField>

### `moveToNamedPose()`

```python Signature theme={null}
moveToNamedPose(
    pose_name: str,
    blocking: bool = True,
    *,
    moving_time: float = 2.0,
    accel_time: float = 0.75,
) -> None
```

Move to a named pose. For 'home', resolves joint count at runtime.

<ParamField>
  Name of the pose (case-insensitive).
</ParamField>

<ParamField>
  Wait for movement to complete. (unused)
</ParamField>

<ParamField>
  Time to complete the movement in seconds. (unused)
</ParamField>

<ParamField>
  Time to accelerate/decelerate in seconds. (unused)
</ParamField>

**Raises:**

ValueError: If pose\_name is not found, or if getJointAngles() returns None for 'home'.

### `moveToPose()`

```python Signature theme={null}
moveToPose(
    pose: Optional[Pose | Position] = None,
    orientation: Optional[Orientation | list | np.ndarray] = None,
    blocking: bool = True,
    *,
    position: Optional[Position | list | np.ndarray] = None,
    moving_time: float = 0.3,
    accel_time: float = 0.15,
    relative: bool = False,
    ik_tolerance: float = 0.005,
    position_tolerance: float = 0.05,
) -> bool
```

Move the end effector to an absolute pose using Grace IK.

<ParamField>
  Target pose, or target position when `orientation` is supplied.
</ParamField>

<ParamField>
  Target orientation as an Orientation, quaternion, or RPY vector.
</ParamField>

<ParamField>
  Whether to wait for movement completion.
</ParamField>

<ParamField>
  Keyword-only target position used by ROS pose callbacks.
</ParamField>

<ParamField>
  Time allowed for movement in seconds.
</ParamField>

<ParamField>
  Acceleration time in seconds.
</ParamField>

<ParamField>
  Whether the supplied position is relative to the current EE position.
</ParamField>

<ParamField>
  Grace IK convergence tolerance.
</ParamField>

<ParamField>
  Maximum acceptable Cartesian IK error.
</ParamField>

**Returns:**

True if Grace found an IK solution and joint command publishing succeeded.

### `planToPose()`

```python Signature theme={null}
planToPose(
    pose: Optional[Pose | Position] = None,
    orientation: Optional[Orientation | list | np.ndarray] = None,
    blocking: bool = True,
    *,
    position: Optional[Position | list | np.ndarray] = None,
    pointcloud: Optional[list | np.ndarray] = None,
    goal_config: Optional[list | np.ndarray] = None,
    planner: str = 'aorrtc',
    max_iterations: int = 1000000,
    filter_robot: bool = True,
    path_step_s: float = 0.1,
    ik_tolerance: float = 0.005,
    position_tolerance: float = 0.05,
    wait_timeout: Optional[float] = None,
) -> bool
```

Plan a collision-free path to a pose with Grace/VAMP and execute it.

<ParamField>
  Target pose, or target position when `orientation` is supplied.
</ParamField>

<ParamField>
  Target orientation as an Orientation, quaternion, or RPY vector.
</ParamField>

<ParamField>
  Whether to wait for the final waypoint to be reached.
</ParamField>

<ParamField>
  Keyword-only target position.
</ParamField>

<ParamField>
  Obstacle points `[x, y, z]` in the robot base frame.
</ParamField>

<ParamField>
  Pre-validated Grace joint configuration to drive to instead of re-solving IK for the pose — a fresh solve can land on a different arm branch than the one that was validated.
</ParamField>

<ParamField>
  Grace/VAMP planner name (e.g. "aorrtc", "rrtc").
</ParamField>

<ParamField>
  Maximum planner iterations.
</ParamField>

<ParamField>
  Filter robot self-points out of the pointcloud.
</ParamField>

<ParamField>
  Delay between streamed path waypoints.
</ParamField>

<ParamField>
  Grace IK convergence tolerance (pose goals).
</ParamField>

<ParamField>
  Maximum acceptable Cartesian IK error (pose goals).
</ParamField>

<ParamField>
  Readback wait timeout for the final waypoint.
</ParamField>

**Returns:**

True if planning succeeded and the final waypoint command was
published (and, when blocking, reached).

### `prompt()`

```python Signature theme={null}
prompt() -> None
```

### `publishMsg()`

```python Signature theme={null}
publishMsg(msg: dict, name: str) -> None
```

Publish a message to a named generic client.

<ParamField>
  Message to publish
</ParamField>

<ParamField>
  Name of the generic client
</ParamField>

### `release()`

```python Signature theme={null}
release()
```

Open the gripper.

**Returns:**

None

### `removeNamedPose()`

```python Signature theme={null}
removeNamedPose(pose_name: str) -> Optional[List[float]]
```

Remove a named pose from the dictionary of pose\_name:joint\_angles pairs.

<ParamField>
  Name of the pose to remove (case-insensitive)
</ParamField>

**Returns:**

list: Joint angles (radians) of the named pose that was removed, or None if the named
pose did not exist

### `reset()`

```python Signature theme={null}
reset(name: str = 'reset') -> None
```

### `run()`

```python Signature theme={null}
run() -> None
```

Run all Zenoh clients

### `sendPose()`

```python Signature theme={null}
sendPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'cmd_delta_pose',
) -> None
```

Send pose command to named pose client.

<ParamField>
  Target position
</ParamField>

<ParamField>
  Target orientation (defaults to \[0,0,0,1] if None)
</ParamField>

<ParamField>
  Name of pose client
</ParamField>

**Raises:**

TypeError: If client is not a PoseClient
ValueError: If client is not in talker mode

### `sendVelocity()`

```python Signature theme={null}
sendVelocity(linear_vel: Velocity, angular_vel: Velocity, name: str = 'cmd_vel') -> None
```

Send velocity command to named velocity client.

<ParamField>
  Linear velocity components
</ParamField>

<ParamField>
  Angular velocity components
</ParamField>

<ParamField>
  Name of velocity client
</ParamField>

**Raises:**

TypeError: If client is not a VelocityClient
ValueError: If client is not in talker mode

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = True,
    *,
    velocities: Optional[list] = None,
    moving_time: float = 2.0,
    accel_time: float = 0.5,
    wait_timeout: Optional[float] = None,
    joint_tolerance: float = 0.25,
    settle_tolerance: float = 0.01,
    velocity_tolerance: float = 0.05,
    settle_samples: int = 3,
    poll_s: float = 0.05,
) -> bool
```

Set the joint angles of the arm.

<ParamField>
  List of joint angles for the robot in radians.
</ParamField>

<ParamField>
  Whether to wait for joint readback to reach the target.
</ParamField>

<ParamField>
  Time allowed for movement in seconds.
</ParamField>

<ParamField>
  Acceleration time in seconds.
</ParamField>

<ParamField>
  Optional readback wait timeout. Defaults to movement timing plus a small margin.
</ParamField>

<ParamField>
  Maximum per-joint target error in radians.
</ParamField>

<ParamField>
  Maximum per-poll joint delta when velocities are unavailable.
</ParamField>

<ParamField>
  Maximum per-joint velocity for settling.
</ParamField>

<ParamField>
  Number of consecutive settled polls required.
</ParamField>

<ParamField>
  Joint readback polling interval.
</ParamField>

### `setObjectPose()`

```python Signature theme={null}
setObjectPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'set_object_pose',
) -> None
```

### `setup()`

```python Signature theme={null}
setup(
    *,
    robot_name: Optional[str] = None,
    grace_robot_name: Optional[str] = None,
    grace_ee_frame: Optional[str] = None,
    arm_joints: Optional[int] = None,
    arm_joint_names: Optional[list[str]] = None,
    grid_zero_offset: Optional[list[float]] = None,
    gripper_client_name: Optional[str] = None,
) -> None
```

Configure Grace-backed pose planning for this simulated arm.

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `startFreeDrive()`

```python Signature theme={null}
startFreeDrive() -> None
```

Enable free-drive (hand-guided) mode.

The arm becomes compliant and can be moved by hand while supporting
its own weight. Position-control commands such as
`moveToPose` and `setJointAngles` are not active in
this mode — call `endFreeDrive` to return to position
control.

**Raises:**

NotImplementedError: If the arm does not support free-drive
mode.

### `stop()`

```python Signature theme={null}
stop(immediate: bool = False)
```

Stop the robot.

<ParamField>
  Whether to stop immediately. (unused)
</ParamField>

**Returns:**

None

### `validateGrasp()`

```python Signature theme={null}
validateGrasp() -> bool
```

Check whether the end effector is currently holding an object.

Thin wrapper that delegates to the configured end effector's
`EndEffector.getGripDetected`. Subclasses generally do not
need to override this.

**Returns:**

True if the end effector reports an object in its grip, False
otherwise.

**Raises:**

RuntimeError: If no end effector is configured on this arm.
NotImplementedError: If the configured end effector does not
support grip detection.


# IsaacBimanual
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-robots/isaacbimanual

Isaac Sim bimanual arm implementation backed by Zenoh

```python theme={null}
from grid_sim_client.isaac.robot import IsaacBimanual
```

Isaac Sim bimanual arm implementation backed by Zenoh.

This class provides an interface to control left and right arms in Isaac Sim
through Zenoh clients configured for side-specific topics.

## Constructor

```python Signature theme={null}
IsaacBimanual(
    config=default_isaac_config,
    *,
    robot_name: str | None = None,
    left_arm_kwargs: dict | None = None,
    right_arm_kwargs: dict | None = None,
    capture_startup_zero_offset: bool = True,
    client_bundle: IsaacClientBundle | None = None,
)
```

Initialize an IsaacBimanual robot instance.

This initializes a bimanual robot in Isaac Sim through zenoh.
For arm control, it sets up left and right arms with appropriate zenoh topics.

<ParamField type="dict">
  Configuration dictionary containing Zenoh topics and settings. (default: default\_isaac\_config)
</ParamField>

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="left_arm" type="IsaacArm" />

<ResponseField name="right_arm" type="IsaacArm" />

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `create_clients()`

```python Signature theme={null}
create_clients(client_config: dict, agent_config: Optional[dict] = None) -> None
```

Create Zenoh clients based on configuration.

<ParamField>
  Dictionary of client configurations
</ParamField>

<ParamField>
  Optional dictionary of agent parameters
</ParamField>

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getForce()`

```python Signature theme={null}
getForce(name: str = '') -> Force
```

Get force from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Force reading from the wrench client.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', image_type: Optional[str] = '') -> Image
```

Get image from named image client.

<ParamField>
  Name of image client
</ParamField>

<ParamField>
  Type of image ("rgb" or "depth"). Defaults to "rgb".
</ParamField>

**Returns:**

Image: Image object

**Raises:**

TypeError: If client is not an ImageClient

### `getJointAngles()`

```python Signature theme={null}
getJointAngles(name: str = 'joint_states') -> Optional[list]
```

Get joint angles from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Returns:**

list | None: List of joint angles or None if not available

**Raises:**

TypeError: If client is not a JointAngleClient

### `getJointStates()`

```python Signature theme={null}
getJointStates(name: str = 'joint_states') -> Optional[dict]
```

Get complete joint states from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Returns:**

dict | None: Dictionary containing joint names, positions, velocities, and efforts, or
None if not available

**Raises:**

TypeError: If client is not a JointAngleClient

### `getJointVelocities()`

```python Signature theme={null}
getJointVelocities(name: str = 'joint_states') -> Optional[list]
```

Get joint velocities from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMsg()`

```python Signature theme={null}
getMsg(name: str) -> dict
```

Get a message from a named generic client.

<ParamField type="str, optional">
  Name of the generic client
</ParamField>

### `getObjectPose()`

```python Signature theme={null}
getObjectPose(name: str = 'get_object_pose') -> Optional[Tuple[Position, Orientation]]
```

### `getOrientation()`

```python Signature theme={null}
getOrientation(name: str = 'robot_pose') -> Orientation
```

Get orientation from named pose client.

<ParamField>
  Name of pose client
</ParamField>

**Returns:**

Orientation: Orientation of agent as a quaternion

**Raises:**

TypeError: If client is not a PoseClient

### `getPosition()`

```python Signature theme={null}
getPosition(name: str = 'robot_pose') -> Optional[Position]
```

Get position from named pose client.

<ParamField>
  Name of pose client
</ParamField>

**Returns:**

Position | list: Position object or raw position data

**Raises:**

TypeError: If client is not a PoseClient

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState()
```

Get the current state of the bimanual arms.

**Returns:**

dict: Current state including left and right arm states.

### `getTorque()`

```python Signature theme={null}
getTorque(name: str = '') -> Torque
```

Get torque from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Torque reading from the wrench client.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
) -> None
```

Move the robot base by specifying linear and angular velocities.

<ParamField type="Velocity">
  Linear velocity components.
</ParamField>

<ParamField type="Velocity">
  Angular velocity components.
</ParamField>

<ParamField type="str">
  Reference frame for the velocity command. (default: "body")
</ParamField>

**Returns:**

None

**Raises:**

NotImplementedError: This robot does not support base velocity control.

### `prompt()`

```python Signature theme={null}
prompt() -> None
```

### `publishMsg()`

```python Signature theme={null}
publishMsg(msg: dict, name: str) -> None
```

Publish a message to a named generic client.

<ParamField>
  Message to publish
</ParamField>

<ParamField>
  Name of the generic client
</ParamField>

### `reset()`

```python Signature theme={null}
reset(name: str = 'reset') -> None
```

### `run()`

```python Signature theme={null}
run() -> None
```

Run all Zenoh clients

### `sendPose()`

```python Signature theme={null}
sendPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'cmd_delta_pose',
) -> None
```

Send pose command to named pose client.

<ParamField>
  Target position
</ParamField>

<ParamField>
  Target orientation (defaults to \[0,0,0,1] if None)
</ParamField>

<ParamField>
  Name of pose client
</ParamField>

**Raises:**

TypeError: If client is not a PoseClient
ValueError: If client is not in talker mode

### `sendVelocity()`

```python Signature theme={null}
sendVelocity(linear_vel: Velocity, angular_vel: Velocity, name: str = 'cmd_vel') -> None
```

Send velocity command to named velocity client.

<ParamField>
  Linear velocity components
</ParamField>

<ParamField>
  Angular velocity components
</ParamField>

<ParamField>
  Name of velocity client
</ParamField>

**Raises:**

TypeError: If client is not a VelocityClient
ValueError: If client is not in talker mode

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = False,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    name: str = 'joint_cmd',
) -> None
```

Send joint angle command to named joint angle client.

<ParamField type="list">
  List of target joint angles in radians
</ParamField>

<ParamField type="bool">
  Wait for movement to complete (default False)
</ParamField>

<ParamField type="Optional[float]">
  Time to complete the movement in seconds
</ParamField>

<ParamField type="Optional[float]">
  Time to accelerate/decelerate in seconds
</ParamField>

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Raises:**

TypeError: If client is not a JointAngleClient
ValueError: If client is not in talker mode

### `setObjectPose()`

```python Signature theme={null}
setObjectPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'set_object_pose',
) -> None
```

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Stop all clients and close Zenoh session


# IsaacHumanoid
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-robots/isaachumanoid

Isaac Sim humanoid implementation backed by Zenoh

```python theme={null}
from grid_sim_client.isaac.robot import IsaacHumanoid
```

Isaac Sim humanoid implementation backed by Zenoh.

This class provides an interface to control a humanoid robot in Isaac Sim
through Zenoh clients for locomotion and arm control.

## Constructor

```python Signature theme={null}
IsaacHumanoid(
    config=default_isaac_config,
    control: str = 'both',
    *,
    client_bundle: IsaacClientBundle | None = None,
)
```

Initialize an IsaacHumanoid robot instance.

This configures locomotion control, arm control, or both based on the
selected control mode, and sets up the required Zenoh topics.

<ParamField type="dict">
  Configuration dictionary containing Zenoh topics and settings. (default: default\_isaac\_config)
</ParamField>

<ParamField type="str">
  Control mode ("locomotion", "arm", or "both"). (default: "both")
</ParamField>

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `create_clients()`

```python Signature theme={null}
create_clients(client_config: dict, agent_config: Optional[dict] = None) -> None
```

Create Zenoh clients based on configuration.

<ParamField>
  Dictionary of client configurations
</ParamField>

<ParamField>
  Optional dictionary of agent parameters
</ParamField>

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getForce()`

```python Signature theme={null}
getForce(name: str = '') -> Force
```

Get force from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Force reading from the wrench client.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', image_type: Optional[str] = '') -> Image
```

Get image from named image client.

<ParamField>
  Name of image client
</ParamField>

<ParamField>
  Type of image ("rgb" or "depth"). Defaults to "rgb".
</ParamField>

**Returns:**

Image: Image object

**Raises:**

TypeError: If client is not an ImageClient

### `getJointAngles()`

```python Signature theme={null}
getJointAngles(name: str = 'joint_states') -> Optional[list]
```

Get joint angles from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Returns:**

list | None: List of joint angles or None if not available

**Raises:**

TypeError: If client is not a JointAngleClient

### `getJointStates()`

```python Signature theme={null}
getJointStates(name: str = 'joint_states') -> Optional[dict]
```

Get complete joint states from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Returns:**

dict | None: Dictionary containing joint names, positions, velocities, and efforts, or
None if not available

**Raises:**

TypeError: If client is not a JointAngleClient

### `getJointVelocities()`

```python Signature theme={null}
getJointVelocities(name: str = 'joint_states') -> Optional[list]
```

Get joint velocities from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMsg()`

```python Signature theme={null}
getMsg(name: str) -> dict
```

Get a message from a named generic client.

<ParamField type="str, optional">
  Name of the generic client
</ParamField>

### `getObjectPose()`

```python Signature theme={null}
getObjectPose(name: str = 'get_object_pose') -> Optional[Tuple[Position, Orientation]]
```

### `getOrientation()`

```python Signature theme={null}
getOrientation(name: str = 'robot_pose') -> Orientation
```

Get orientation from named pose client.

<ParamField>
  Name of pose client
</ParamField>

**Returns:**

Orientation: Orientation of agent as a quaternion

**Raises:**

TypeError: If client is not a PoseClient

### `getPosition()`

```python Signature theme={null}
getPosition(name: str = 'robot_pose') -> Optional[Position]
```

Get position from named pose client.

<ParamField>
  Name of pose client
</ParamField>

**Returns:**

Position | list: Position object or raw position data

**Raises:**

TypeError: If client is not a PoseClient

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState() -> dict
```

Get the current state of the humanoid.

**Returns:**

dict: Current state including base pose and arm states.

### `getTorque()`

```python Signature theme={null}
getTorque(name: str = '') -> Torque
```

Get torque from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Torque reading from the wrench client.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    name: str = 'cmd_vel',
)
```

Move the robot by specifying linear and angular velocities.

Due to the nature of Isaac Sim, the robot will move in the direction/rotation
of the velocity vectors, but exact movement may vary. Use odometry feedback
with getPosition and/or getOrientation when you need precise distance or
angle control.

<ParamField type="Velocity">
  Linear velocity components.
</ParamField>

<ParamField type="Velocity">
  Angular velocity components.
</ParamField>

<ParamField type="str">
  Reference frame for the velocity command. (default: "body")
</ParamField>

<ParamField type="str">
  Name of velocity command. (default: "cmd\_vel")
</ParamField>

**Returns:**

None

### `prompt()`

```python Signature theme={null}
prompt() -> None
```

### `publishMsg()`

```python Signature theme={null}
publishMsg(msg: dict, name: str) -> None
```

Publish a message to a named generic client.

<ParamField>
  Message to publish
</ParamField>

<ParamField>
  Name of the generic client
</ParamField>

### `reset()`

```python Signature theme={null}
reset(name: str = 'reset') -> None
```

### `run()`

```python Signature theme={null}
run() -> None
```

Run all Zenoh clients

### `sendPose()`

```python Signature theme={null}
sendPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'cmd_delta_pose',
) -> None
```

Send pose command to named pose client.

<ParamField>
  Target position
</ParamField>

<ParamField>
  Target orientation (defaults to \[0,0,0,1] if None)
</ParamField>

<ParamField>
  Name of pose client
</ParamField>

**Raises:**

TypeError: If client is not a PoseClient
ValueError: If client is not in talker mode

### `sendVelocity()`

```python Signature theme={null}
sendVelocity(linear_vel: Velocity, angular_vel: Velocity, name: str = 'cmd_vel') -> None
```

Send velocity command to named velocity client.

<ParamField>
  Linear velocity components
</ParamField>

<ParamField>
  Angular velocity components
</ParamField>

<ParamField>
  Name of velocity client
</ParamField>

**Raises:**

TypeError: If client is not a VelocityClient
ValueError: If client is not in talker mode

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setDefaultJointAngles()`

```python Signature theme={null}
setDefaultJointAngles(joint_pos: list) -> None
```

Set the default joint position for the robot.

<ParamField>
  Value of the joint position.
</ParamField>

### `setDefaultJointVelocities()`

```python Signature theme={null}
setDefaultJointVelocities(joint_vel: list) -> None
```

Set the default joint velocity for the robot.

<ParamField>
  Value of the joint velocity.
</ParamField>

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = False,
    moving_time: Optional[float] = None,
    accel_time: Optional[float] = None,
    name: str = 'joint_cmd',
) -> None
```

Send joint angle command to named joint angle client.

<ParamField type="list">
  List of target joint angles in radians
</ParamField>

<ParamField type="bool">
  Wait for movement to complete (default False)
</ParamField>

<ParamField type="Optional[float]">
  Time to complete the movement in seconds
</ParamField>

<ParamField type="Optional[float]">
  Time to accelerate/decelerate in seconds
</ParamField>

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Raises:**

TypeError: If client is not a JointAngleClient
ValueError: If client is not in talker mode

### `setObjectPose()`

```python Signature theme={null}
setObjectPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'set_object_pose',
) -> None
```

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop(name: str = 'cmd_vel')
```

Stop the robot.

<ParamField type="str">
  Name of velocity command. (default: "cmd\_vel")
</ParamField>

**Returns:**

None


# IsaacLocomotion
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-robots/isaaclocomotion

Isaac Sim locomotion implementation backed by Zenoh

```python theme={null}
from grid_sim_client.isaac.robot import IsaacLocomotion
```

Isaac Sim locomotion implementation backed by Zenoh.

This class provides a minimal base locomotion interface using Zenoh
velocity commands for Isaac Sim robots.

## Constructor

```python Signature theme={null}
IsaacLocomotion(
    config=default_isaac_config,
    clients: Union[dict, None] = None,
    client_bundle: IsaacClientBundle | None = None,
    *,
    joint_angle_passthrough: bool = True,
)
```

Initialize an Isaac Sim locomotion interface.

<ParamField type="dict">
  Configuration dictionary containing Zenoh topics and settings. (default: default\_isaac\_config)
</ParamField>

<ParamField type="Union[dict, None]">
  Pre-created Zenoh clients to reuse instead of creating new ones. (default: None)
</ParamField>

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `create_clients()`

```python Signature theme={null}
create_clients(client_config: dict, agent_config: Optional[dict] = None) -> None
```

Create Zenoh clients based on configuration.

<ParamField>
  Dictionary of client configurations
</ParamField>

<ParamField>
  Optional dictionary of agent parameters
</ParamField>

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getForce()`

```python Signature theme={null}
getForce(name: str = '') -> Force
```

Get force from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Force reading from the wrench client.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', image_type: Optional[str] = '') -> Image
```

Get image from named image client.

<ParamField>
  Name of image client
</ParamField>

<ParamField>
  Type of image ("rgb" or "depth"). Defaults to "rgb".
</ParamField>

**Returns:**

Image: Image object

**Raises:**

TypeError: If client is not an ImageClient

### `getJointAngles()`

```python Signature theme={null}
getJointAngles(name: str = 'joint_states') -> list | None
```

Return whole-robot joint angles unless this instance is a base component.

### `getJointStates()`

```python Signature theme={null}
getJointStates(name: str = 'joint_states') -> Optional[dict]
```

Get complete joint states from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Returns:**

dict | None: Dictionary containing joint names, positions, velocities, and efforts, or
None if not available

**Raises:**

TypeError: If client is not a JointAngleClient

### `getJointVelocities()`

```python Signature theme={null}
getJointVelocities(name: str = 'joint_states') -> Optional[list]
```

Get joint velocities from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMsg()`

```python Signature theme={null}
getMsg(name: str) -> dict
```

Get a message from a named generic client.

<ParamField type="str, optional">
  Name of the generic client
</ParamField>

### `getObjectPose()`

```python Signature theme={null}
getObjectPose(name: str = 'get_object_pose') -> Optional[Tuple[Position, Orientation]]
```

### `getOrientation()`

```python Signature theme={null}
getOrientation(name: str = 'robot_pose') -> Orientation
```

Get orientation from named pose client.

<ParamField>
  Name of pose client
</ParamField>

**Returns:**

Orientation: Orientation of agent as a quaternion

**Raises:**

TypeError: If client is not a PoseClient

### `getPosition()`

```python Signature theme={null}
getPosition(name: str = 'robot_pose') -> Optional[Position]
```

Get position from named pose client.

<ParamField>
  Name of pose client
</ParamField>

**Returns:**

Position | list: Position object or raw position data

**Raises:**

TypeError: If client is not a PoseClient

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState()
```

Get the current state of the robot.

**Returns:**

dict: A dictionary containing the position and orientation of the robot.

### `getTorque()`

```python Signature theme={null}
getTorque(name: str = '') -> Torque
```

Get torque from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Torque reading from the wrench client.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    name: str = 'cmd_vel',
)
```

Move the robot by specifying linear and angular velocities.

Due to the nature of Isaac Sim, the robot will move in the direction/rotation
of the velocity vectors, but exact movement may vary. Use odometry feedback
with getPosition and/or getOrientation when you need precise distance or
angle control.

<ParamField type="Velocity">
  Linear velocity components.
</ParamField>

<ParamField type="Velocity">
  Angular velocity components.
</ParamField>

<ParamField type="str">
  Reference frame for the velocity command. (default: "body")
</ParamField>

<ParamField type="str">
  Name of velocity command. (default: "cmd\_vel")
</ParamField>

**Returns:**

None

### `prompt()`

```python Signature theme={null}
prompt() -> None
```

### `publishMsg()`

```python Signature theme={null}
publishMsg(msg: dict, name: str) -> None
```

Publish a message to a named generic client.

<ParamField>
  Message to publish
</ParamField>

<ParamField>
  Name of the generic client
</ParamField>

### `reset()`

```python Signature theme={null}
reset(name: str = 'reset') -> None
```

### `run()`

```python Signature theme={null}
run() -> None
```

Run all Zenoh clients

### `sendPose()`

```python Signature theme={null}
sendPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'cmd_delta_pose',
) -> None
```

Send pose command to named pose client.

<ParamField>
  Target position
</ParamField>

<ParamField>
  Target orientation (defaults to \[0,0,0,1] if None)
</ParamField>

<ParamField>
  Name of pose client
</ParamField>

**Raises:**

TypeError: If client is not a PoseClient
ValueError: If client is not in talker mode

### `sendVelocity()`

```python Signature theme={null}
sendVelocity(linear_vel: Velocity, angular_vel: Velocity, name: str = 'cmd_vel') -> None
```

Send velocity command to named velocity client.

<ParamField>
  Linear velocity components
</ParamField>

<ParamField>
  Angular velocity components
</ParamField>

<ParamField>
  Name of velocity client
</ParamField>

**Raises:**

TypeError: If client is not a VelocityClient
ValueError: If client is not in talker mode

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: list,
    blocking: bool = False,
    *,
    velocities=None,
    moving_time: float | None = None,
    accel_time: float | None = None,
    name: str = 'joint_cmd',
) -> None
```

Send whole-robot joints, or accept empty base commands in component mode.

### `setObjectPose()`

```python Signature theme={null}
setObjectPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'set_object_pose',
) -> None
```

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop(name: str = 'cmd_vel')
```

Stop the robot.

<ParamField type="str">
  Name of velocity command. (default: "cmd\_vel")
</ParamField>

**Returns:**

None


# IsaacMobileBimanual
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-robots/isaacmobilebimanual

Isaac Sim mobile bimanual implementation backed by Zenoh

```python theme={null}
from grid_sim_client.isaac.robot import IsaacMobileBimanual
```

Isaac Sim mobile bimanual implementation backed by Zenoh.

This class extends IsaacBimanual to add locomotion capabilities, providing
an interface to control a mobile bimanual robot in Isaac Sim through Zenoh.
It combines bimanual arm control with base locomotion.

## Constructor

```python Signature theme={null}
IsaacMobileBimanual(
    config=default_isaac_config,
    *,
    robot_name: str | None = None,
    left_arm_kwargs: dict | None = None,
    right_arm_kwargs: dict | None = None,
    capture_startup_zero_offset: bool = True,
    client_bundle: IsaacClientBundle | None = None,
)
```

Initialize an IsaacMobileBimanual robot instance.

This initializes a mobile bimanual robot in Isaac Sim through Zenoh.
Sets up left and right arms with appropriate Zenoh topics, and adds
a locomotion base controller.

<ParamField type="dict">
  Configuration dictionary containing Zenoh topics and settings. (default: default\_isaac\_config)
</ParamField>

## Properties

<ResponseField name="arms" type="Dict[str, 'Component']">
  Child components that are arms (derived, read-only).

  Filtered from `subcomponents` by `Arm` role; the returned dict
  is a fresh snapshot.
</ResponseField>

<ResponseField name="end_effector" type="Optional['Component']">
  The attached end effector, or `None` (derived, read-only).

  Returns the child named `"end_effector"` when it is an
  `EndEffector`, otherwise the first `EndEffector` child in
  insertion order. Attach one via
  `addSubcomponent("end_effector", ...)`.
</ResponseField>

<ResponseField name="expected_identity" type="ComponentIdentity">
  Hardware identity this component's config declared it should have.

  Set from the `identity` block of the config envelope by
  `from_config`, and empty for a component built any other
  way. Recording it acquires no hardware, and what it *means*
  splits by transport. For network-addressed hardware (an arm at a
  configured IP) it is a declaration to verify against: whether a
  mismatch warns or fails belongs to the caller that owns that
  policy, not to the driver. For bus-enumerated hardware (USB
  cameras), whose enumeration order is not a stable address, the
  declared `serial_number` is instead a *selector*: bring-up
  opens exactly that unit and fails loudly when it is absent,
  never falling back to a different device.

  Compare it against `getIdentity`, which is what the
  hardware reports.
</ResponseField>

<ResponseField name="left_arm" type="IsaacArm" />

<ResponseField name="right_arm" type="IsaacArm" />

<ResponseField name="sensors" type="Dict[str, 'Component']">
  Child components that are sensors (derived, read-only).

  Filtered from `subcomponents` by `Sensor` role; attach sensors
  via `addSensor`/`addSubcomponent` rather than writing to the
  returned dict, which is a fresh snapshot.
</ResponseField>

<ResponseField name="subcomponents" type="Dict[str, 'Component']">
  Mapping of child-component name to child component.

  The returned dict is the live backing store: mutating it mutates
  the component tree. Prefer `addSubcomponent` for inserts.
</ResponseField>

## Methods

### `addSensor()`

```python Signature theme={null}
addSensor(name: str, sensor: Sensor) -> None
```

Add an external sensor to the robot.

<ParamField type="str">
  Unique identifier for the sensor
</ParamField>

<ParamField type="Sensor">
  Sensor object to add (e.g. Camera, IMU, Lidar)
</ParamField>

**Returns:**

None

### `addSubcomponent()`

```python Signature theme={null}
addSubcomponent(name: str, component: 'Component') -> None
```

Attach a child component under a name.

An existing child with the same name is replaced, matching dict
assignment semantics (`addSensor` has always overwritten).

<ParamField>
  Non-empty name for the child, unique within this component's `subcomponents`. Names are addressable as `getState` path chunks, so the path syntax characters `/ * ? [ ]` are not allowed.
</ParamField>

<ParamField>
  The child component to attach.
</ParamField>

**Raises:**

ValueError: If `name` is not a non-empty string, or contains
a path syntax character.

### `builtin_subcomponents()`

```python Signature theme={null}
builtin_subcomponents() -> Dict[str, Dict[str, Any]]
```

Declare the children this class always ships with (customization point).

Hardware that is part of the component itself — a humanoid's head
camera, an arm's wrist camera, a base built into a mobile
manipulator — is declared here rather than constructed in
`__init__`, so one description drives both the runtime tree and
the static config tooling. The declaration is **pure data** in the
same shape an authored `subcomponents` entry uses:
`&#123;"&lt;child name>": &#123;"type": "&lt;registry name>", "args": &#123;...&#125;,
"subcomponents": &#123;...&#125;, "enabled": True&#125;&#125;`, where `type` names a
robot- or sensor-registry key, `args` are that class's config
args, `subcomponents` declares grandchildren by the same rules,
and `enabled` (default `True`) can declare a child off by
default.

An override must be callable on the bare class, without
instantiation and without importing a driver or touching hardware:
the setup-time stream resolver reads it off the registry class to
resolve a robot's camera streams on a machine that has none of the
hardware attached.

The base class materializes the declaration on every construction
path — a direct constructor call attaches the children once the
constructor returns, and `from_config` attaches them merged
with the authored `subcomponents` block (authored keys win, so an
entry with the same name retunes `args` or drops the child with
`enabled: false` — and may omit `type`, inheriting the one
declared here — while an entry naming a different `type` is an
error). Attached builtin children are ordinary subcomponents:
they appear in `serialize`, in `getState`, and in the
lifecycle walks, and a builtin `Camera` child is skipped when the
tree is built with `enable_cameras=False`.

**Returns:**

Mapping of child name to its config declaration. The default is
empty — a class with no builtin children.

### `configHash()`

```python Signature theme={null}
configHash(
    *,
    include_types: Optional[Tuple[type, ...]] = None,
    include_identity: bool = False,
    exclude_fields: AbstractSet[str] = frozenset(),
    type_prefix: bool = False,
) -> str
```

Hash this component's serialized config subtree.

A SHA-256 hex digest over the `serialize` output — the
config topology and args, not object identity and not
`getState` telemetry. Deterministic: the same tree with
the same options always produces the same digest, regardless of
dict insertion order. Touches no hardware; with
`include_identity` it hashes whatever identity is already
recorded (declared or previously read), triggering no new read.

Two hashes are comparable only when computed with the same
options; equality across differently-parameterized calls is
meaningless. Note that with `include_identity` the digest
changes as identity fields become known — a component reports
fields monotonically (some only once started), so hash at a
consistent point in the lifecycle when comparing across runs.

<ParamField>
  When given, only tree nodes whose component is an instance of one of these classes are hashed; a non-matching node is pruned together with its entire subtree. `None` keeps every node.
</ParamField>

<ParamField>
  When True, each kept node's `identity` block (as `serialize` records it — hardware-read overlaid on declared) is included in the hash. When False the hash covers configuration only.
</ParamField>

<ParamField>
  Config `args` keys dropped from every kept node before hashing (e.g. an IP address that changes across networks).
</ParamField>

<ParamField>
  When True, prepend this component's registry type and an underscore to the digest (e.g. `"go2_&lt;digest>"`, `"rig_&lt;digest>"` for a composite root) for a human-readable, greppable label. The type is already part of the hashed payload, so this only labels the same digest — the suffix after `_` is identical to the unprefixed call with the same options.
</ParamField>

**Returns:**

A 64-character lowercase SHA-256 hex digest, or
`"&lt;type>_&lt;digest>"` when `type_prefix` is True.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component itself matches none of
`include_types` — the hash would cover an empty tree
and compare equal for unrelated components.

### `config_schema()`

```python Signature theme={null}
config_schema() -> dict[str, Any]
```

### `create_clients()`

```python Signature theme={null}
create_clients(client_config: dict, agent_config: Optional[dict] = None) -> None
```

Create Zenoh clients based on configuration.

<ParamField>
  Dictionary of client configurations
</ParamField>

<ParamField>
  Optional dictionary of agent parameters
</ParamField>

### `from_config()`

```python Signature theme={null}
from_config(config: Dict[str, Any], *, enable_cameras: bool = True) -> 'Component'
```

Construct this component and its config-declared subtree.

Recursive walk owned by the base class, the inverse of
`serialize`: the config envelope
(`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;...&#125;&#125;`) is
validated, this component is constructed from `args` via
`_from_config_args`, and each declared child is resolved
through the robot/sensor registries, constructed by its own
class's `from_config`, and attached. `type` may be omitted
when calling on a concrete class — it is then taken from the
class's registry entry.

The declared children are this class's
`builtin_subcomponents` overlaid by the config's
`subcomponents` block: builtin children first in declaration
order, then authored-only children. An authored entry whose name
matches a builtin one overlays it — its `args` merge over the
builtin `args` and `enabled: false` drops the child — rather
than colliding with it, and it may omit `type` entirely
(`&#123;"chassis_rear": &#123;"enabled": false&#125;&#125;` is a complete entry),
inheriting the builtin's; an entry naming a *different* `type`
than the builtin declaration is an error, as is an entry that
omits `type` while overlaying no builtin child. Any entry with
`enabled: false` is skipped, builtin or authored.

A node's optional `identity` block is recorded on the built
component as `expected_identity` — the hardware this entry
is *declared* to be. It is never checked against the device
here: construction acquires no hardware, and deciding what a
mismatch means belongs to the caller.

Component configs nested inside `args` (an arm's
`end_effector`, for example) are the constructor's business and
are built in `_from_config_args`; the recursion here covers
the `subcomponents` block only. The returned tree is
constructed but **not** started — use `make_robot`/
`make_sensor`, a `with` block, or an explicit
`start` call to bring it online.

<ParamField>
  Config envelope for this component. Extra keys are rejected; `args` and `subcomponents` may be omitted.
</ParamField>

<ParamField>
  When True, camera components declared in the config are constructed and attached for local `getImage` use. When False, config-declared cameras are skipped at every depth because deploy streaming owns those devices; the flag is also passed to `_from_config_args` so a driver can skip cameras it builds itself.
</ParamField>

**Returns:**

The constructed component with its declared subcomponents
attached and its config recorded — including, per builtin
child, whether the authored config moved it off its
declaration's `enabled` state — so
`type(c).from_config(c.serialize())` rebuilds an equivalent
tree.

**Raises:**

ValueError: If `config` is not a mapping, a declared
subcomponent type is in neither registry, or an authored
entry overlays a builtin child with a different `type`.
ConfigValidationError: If the config tree does not match the
envelope shape; the message carries full config-tree
paths.

### `getForce()`

```python Signature theme={null}
getForce(name: str = '') -> Force
```

Get force from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Force reading from the wrench client.

### `getIdentity()`

```python Signature theme={null}
getIdentity() -> ComponentIdentity
```

Get this component's own hardware identity (serial, model, version, MAC).

Local, not recursive: it answers for this component alone. The
tree-wide view is `serialize`, which carries each node's
identity alongside its topology; identity is deliberately absent
from `getState`, which is live telemetry rather than
constants burned into a device.

**Never raises and never blocks the caller's real work.** A
driver read that fails — controller unreachable, dashboard
refused, SDK error — is logged and degrades to whatever fields
are already known, down to an empty mapping. Absence means
*unknown*, never *different*: see `ComponentIdentity` for what
consumers may conclude from a missing field.

**Callable in every lifecycle state** — before `start()`,
while started, after `stop()`, and after `shutdown()`. Where
the transport allows it (the UR dashboard server needs only the
controller IP, ZED serials are enumerable from sysfs before the
device is opened) a constructed-but-unstarted component already
answers, which is what lets a caller de-duplicate a robot before
bringing it up. Drivers that can only read identity from a live
device handle return nothing until then, so a call after
`start()` may carry *more* fields than one before it.

**Monotonic per component.** Every field ever read successfully
is cached, so repeated calls only ever gain fields — a later
failure never drops one that was already known. A field whose
value is re-read is updated to the fresh value.

**The field set is closed.** Only the fields `ComponentIdentity`
declares are accepted; anything else a driver reports is logged
and dropped, exactly like a non-string value, so what a component
reports always round-trips through the config envelope.

**Returns:**

A fresh `ComponentIdentity` mapping holding only the fields
known for this component; `&#123;&#125;` when nothing is known.
Mutating the result does not affect the component.

### `getImage()`

```python Signature theme={null}
getImage(camera_name: str = '', **kwargs) -> Image
```

Return the image of camera.

Which camera a no-argument call reads is decided by cardinality
alone — no robot, config, or class declares a default. A robot with
exactly one camera needs no name; a robot with several requires one,
so adding a second camera never silently changes which one a bare
`getImage()` returns.

<ParamField type="str">
  Name of the camera to get image from — either a directly attached camera's name or a `/`-separated path through subcomponents to a nested one (`left_arm/wrist`). May be omitted when the robot has exactly one camera.
</ParamField>

<ParamField>
  Forwarded to the underlying sensor's `getImage`. Lets callers pass camera-specific options (e.g. `image_type="depth"`, `compressed=False`) without the base class having to enumerate them.
</ParamField>

**Returns:**

Image: The captured image.

**Raises:**

RuntimeError: If no cameras are configured, or the name is
omitted on a robot with more than one camera; the message
lists every configured camera path.
KeyError: If camera\_name is given but names no camera on this robot.

### `getJointAngles()`

```python Signature theme={null}
getJointAngles(
    group: Optional[str] = None,
) -> Union[Dict[str, List[float]], List[float]]
```

Get joint angles.

<ParamField>
  If provided, return joint angles for that subcomponent only (as a flat `list[float]`). If `None` (default), return a dict mapping every subcomponent name to its joint angles.
</ParamField>

**Returns:**

`list[float]` when *group* is given, otherwise
`dict[str, list[float]]`.

**Raises:**

KeyError: If *group* is not a known subcomponent.

````python theme={null}
```python
# All groups at once
all_joints = robot.getJointAngles()
# -> {"left_arm": [...], "right_arm": [...], "base": [...]}

# Single group (same return type as Arm.getJointAngles())
left_joints = robot.getJointAngles("left_arm")
# -> [0.0, 0.1, ...]
````

````

### `getJointStates()`

```python Signature
getJointStates(name: str = 'joint_states') -> Optional[dict]
````

Get complete joint states from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

**Returns:**

dict | None: Dictionary containing joint names, positions, velocities, and efforts, or
None if not available

**Raises:**

TypeError: If client is not a JointAngleClient

### `getJointVelocities()`

```python Signature theme={null}
getJointVelocities(name: str = 'joint_states') -> Optional[list]
```

Get joint velocities from named joint angle client.

<ParamField type="str, optional">
  Name of joint angle client
</ParamField>

### `getLidarPointCloud()`

```python Signature theme={null}
getLidarPointCloud(lidar_name: str = '') -> Optional[PointCloud]
```

Get a point cloud from the named LiDAR sensor.

<ParamField type="str">
  Name of the lidar. If empty, uses the first available lidar.
</ParamField>

**Returns:**

Optional\[PointCloud]: The point cloud, or None if lidar not found

### `getMsg()`

```python Signature theme={null}
getMsg(name: str) -> dict
```

Get a message from a named generic client.

<ParamField type="str, optional">
  Name of the generic client
</ParamField>

### `getObjectPose()`

```python Signature theme={null}
getObjectPose(name: str = 'get_object_pose') -> Optional[Tuple[Position, Orientation]]
```

### `getOrientation()`

```python Signature theme={null}
getOrientation() -> Optional[Orientation]
```

Get the orientation of the robot in the world frame.

**Returns:**

Optional\[Orientation]: Current orientation of the robot in world coordinates,
or None if orientation is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getPosition()`

```python Signature theme={null}
getPosition() -> Optional[Position]
```

Get the position of the robot in the world frame, in meters.

**Returns:**

Optional\[Position]: Current position of the robot in world coordinates,
or None if position is unavailable

**Raises:**

NotImplementedError: Must be implemented by subclasses

### `getRobotId()`

```python Signature theme={null}
getRobotId() -> str
```

Stable, readable identifier for a robot or rig, for a database key.

A fixed-options digest over `serialize`, so a caller storing
robots by ID does not have to choose them: `Robot`/`Rig` nodes
only, `args` dropped entirely, each node's
`serial_number`/`mac_address` folded in, and the root's registry
type as a prefix. The result is `"&lt;type>_&lt;digest>"` (e.g.
`"go2_1a2b3c…"`, `"rig_…"` on a composite root): the type prefix
makes it greppable, and folding in hardware identity distinguishes
two units built from the same config — so two physically different
robots get different IDs, which a config-only hash would not give.
Distinct from `getIdentity`, which reports the physical unit's
manufacturer identity and hashes nothing.

Four properties to hold when using it as a key:

* **Robots and rigs only.** Only `Robot` and `Rig` nodes are
  hashed; sensors (and any other non-robot subcomponents, e.g.
  teleop devices) are pruned, so swapping or adding a camera does
  not change a robot's ID. Called on a component that is neither a
  `Robot` nor a `Rig` — e.g. a bare sensor, an end effector, a
  teleop device — it raises, because such a component has no robot
  identity to key on.
* **Structure and identity, never parameters.** `args` are
  dropped at every node, so editing a parameter — an IP address, a
  force limit, a speed scale — leaves the ID unchanged: it
  identifies the unit, not its tuning. What survives is the tree
  shape (registry types and subcomponent names among the kept
  nodes) plus the identity fields. Anything configured as an
  `arg` rather than a subcomponent — an end effector, for
  instance — is invisible to the ID; use `configHash` when
  the configuration itself is what needs fingerprinting.
* **Distinctness needs identity.** Uniqueness per physical unit
  comes from the `serial_number`/`mac_address` a component
  reports; components that report no identity fall back to
  structure-only distinctness, so two units of the same type with
  no serial share an ID. It is derived, not registered — a hash,
  not a UUID. That fallback is not only a property of serial-less
  *models*: a unit whose identity read failed this run (an
  unreachable UR dashboard) reports nothing, so it silently takes
  the structure-only ID and does not match the ID it produces on a
  run where the read succeeded. Where the key must be unique, check
  `getIdentity` for a `serial_number`/`mac_address` first.
  A rig has no identity of its own, so a rig's ID is only as
  distinct as the robots inside it — a rig of nothing but sensors
  hashes to one shared constant.
* **Only identifying identity fields count.** `serial_number` and
  `mac_address` say *which* unit this is; `model` and
  `controller_version` describe it, and are left out so a firmware
  upgrade does not rekey the arm. An ID still moves when a component
  starts reporting a field it did not report before, so IDs
  persisted across a driver gaining a new identity source do not
  match the ones computed after it.

Touches no hardware and triggers no identity read; it hashes
whatever identity is already recorded, so call it at a consistent
lifecycle point when comparing across runs.

**Returns:**

`"&lt;type>_&lt;64-char lowercase SHA-256 hex digest>"`.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so it cannot be serialized.
ValueError: If this component is neither a `Robot` nor a
`Rig`, so it has no robot identity to key on.

### `getState()`

```python Signature theme={null}
getState() -> dict
```

Get the complete state of the mobile bimanual robot.

**Returns:**

dict: Dictionary containing base position, base orientation, left arm state,
and right arm state.

### `getTorque()`

```python Signature theme={null}
getTorque(name: str = '') -> Torque
```

Get torque from named wrench client.

<ParamField>
  Name of wrench client
</ParamField>

**Returns:**

Torque reading from the wrench client.

### `moveByVelocity()`

```python Signature theme={null}
moveByVelocity(
    linear_velocity: Velocity,
    angular_velocity: Velocity,
    frame: str = 'body',
    name: str = 'cmd_vel',
)
```

Move the robot base by specifying linear and angular velocities.

Due to the nature of Isaac Sim, the robot will move in the direction/rotation
of the velocity vectors, but exact movement may vary. Use odometry feedback
with getPosition and/or getOrientation when you need precise distance or
angle control.

<ParamField type="Velocity">
  Linear velocity components.
</ParamField>

<ParamField type="Velocity">
  Angular velocity components.
</ParamField>

<ParamField type="str">
  Reference frame for the velocity. (default: "body")
</ParamField>

<ParamField type="str">
  Name of velocity command. (default: "cmd\_vel")
</ParamField>

**Returns:**

None

### `prompt()`

```python Signature theme={null}
prompt() -> None
```

### `publishMsg()`

```python Signature theme={null}
publishMsg(msg: dict, name: str) -> None
```

Publish a message to a named generic client.

<ParamField>
  Message to publish
</ParamField>

<ParamField>
  Name of the generic client
</ParamField>

### `reset()`

```python Signature theme={null}
reset(name: str = 'reset') -> None
```

### `run()`

```python Signature theme={null}
run() -> None
```

Run all Zenoh clients

### `sendPose()`

```python Signature theme={null}
sendPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'cmd_delta_pose',
) -> None
```

Send pose command to named pose client.

<ParamField>
  Target position
</ParamField>

<ParamField>
  Target orientation (defaults to \[0,0,0,1] if None)
</ParamField>

<ParamField>
  Name of pose client
</ParamField>

**Raises:**

TypeError: If client is not a PoseClient
ValueError: If client is not in talker mode

### `sendVelocity()`

```python Signature theme={null}
sendVelocity(linear_vel: Velocity, angular_vel: Velocity, name: str = 'cmd_vel') -> None
```

Send velocity command to named velocity client.

<ParamField>
  Linear velocity components
</ParamField>

<ParamField>
  Angular velocity components
</ParamField>

<ParamField>
  Name of velocity client
</ParamField>

**Raises:**

TypeError: If client is not a VelocityClient
ValueError: If client is not in talker mode

### `serialize()`

```python Signature theme={null}
serialize() -> Dict[str, Any]
```

Serialize this component tree back to its config envelope.

The exact inverse of `from_config`, producing the recursive
config schema it consumes:
`&#123;"type": ..., "args": &#123;...&#125;, "subcomponents": &#123;name: &lt;node>&#125;&#125;`,
minimized via `model_dump(exclude_defaults=True)` so empty
`args`/`subcomponents` are omitted. Only config-declared
children (those constructed through `from_config`) are
emitted; parts a driver constructs internally are implied by the
parent's `args` and reappear on reconstruction.

A child a class ships with (`builtin_subcomponents`) is
normally implied by the parent's `type` and needs no
`enabled` key. It gets an explicit one exactly when its
attached state diverges from what the bare class declaration
would produce, because reconstruction would otherwise flip it:

* declared enabled but switched off by the config
  (`enabled: false`) — emitted as a bare
  `&#123;"enabled": false&#125;` stub under `subcomponents`, the
  type-omitted overlay form that inherits the declaration's
  `type`. The stub exists only in this output; it is never a
  phantom entry in `subcomponents`, `getState`, or
  introspection.
* declared `enabled: false` but switched on by the config
  (`enabled: true`) — its normal serialized entry additionally
  carries `"enabled": true`, which an omitted key would not
  preserve (an authored entry that omits `enabled` keeps the
  declaration's value).

A child whose state matches its declaration is emitted exactly as
before, with no `enabled` key and no stub.

The asymmetry to
know: children skipped because the tree was built with
`enable_cameras=False` get **no** stub. That flag is
factory-only camera-ownership semantics — deploy streaming owns
those devices for this process, the config never said to drop
them — so the serialized config keeps describing the robot's
cameras, and passing the flag again is what skips them again.

A node also carries an `identity` block —
`&#123;"serial_number": ..., "model": ..., "controller_version":
..., "mac_address": ...&#125;`, each key present only when known —
whenever this component has a hardware identity to record, so the serialized
tree says which physical units it was built from and not just
which types. It is what `getIdentity` reports overlaid on
the identity the config declared (`expected_identity`), so
hardware that has identified itself wins over the declaration
while an unread declaration survives the round-trip. Omitted
entirely when nothing is known — never an empty block.

**Returns:**

The minimal config mapping such that
`make_robot(component.serialize())` reconstructs an
equivalent component tree.

**Raises:**

RuntimeError: If this component was not constructed from a
config, so no config type is recorded.
ConfigValidationError: If the recorded config does not fit
the envelope (e.g. a recorded arg key is not a string).

### `setJointAngles()`

```python Signature theme={null}
setJointAngles(
    angles: Union[Dict[str, list], list],
    velocities: Union[Optional[Dict[str, list]], list] = None,
    group: Optional[str] = None,
) -> None
```

Set joint angles.

Can be called in two ways:

* **Multi-group** (default): pass a dict mapping group names to
  angle lists.  `velocities` may also be a dict.
* **Single-group**: pass a flat `list` of angles together with
  `group="&lt;name>"`.  `velocities` may also be a flat list.
  This matches the `Arm` / `Humanoid` / `Quadruped`
  signature.

<ParamField>
  Target joint angles in radians — a dict for multi-group or a list for single-group.
</ParamField>

<ParamField>
  Optional joint velocities. In single-group mode, a list or scalar. In multi-group mode, a dict mapping group names to velocity lists/scalars (partial dicts OK — omitted groups get no velocity), a single scalar (broadcast to every group being commanded), or `None`.
</ParamField>

<ParamField>
  Subcomponent name.  Required when *angles* is a list.
</ParamField>

**Raises:**

KeyError: If a group name is not a known subcomponent.
TypeError: If *angles* is a list but *group* is not provided,
or if *velocities* is a list in multi-group mode.

````python theme={null}
```python
# Multi-group
robot.setJointAngles({"left_arm": angles_l, "base": angles_b})

# Multi-group with per-group velocities
robot.setJointAngles(
    {"left_arm": angles_l, "right_arm": angles_r},
    velocities={"left_arm": 0.5},  # only left_arm; right_arm uses default
)

# Per-group velocities as a list
robot.setJointAngles(
    {"left_arm": angles_l, "right_arm": angles_r},
    velocities={"left_arm": [0.5] * 7, "right_arm": [0.1] * 7},
)

# Multi-group with a single velocity for all groups/joints
robot.setJointAngles(
    {"left_arm": angles_l, "base": angles_b},
    velocities=0.5,
)

# Single-group (same list signature as Arm, Humanoid, etc.)
robot.setJointAngles(angles_l, group="left_arm")
````

````

### `setObjectPose()`

```python Signature
setObjectPose(
    position: Position,
    orientation: Optional[Orientation] = None,
    name: str = 'set_object_pose',
) -> None
````

### `setup_shutdown_handlers()`

```python Signature theme={null}
setup_shutdown_handlers() -> None
```

Register the process-wide atexit and signal handlers for safe teardown.

Installs an `atexit` hook and SIGINT/SIGTERM (and SIGHUP where
available) handlers that shut down every enrolled bring-up entry
point, newest first, so hardware is released on normal
termination and on Ctrl+C. Registration normally happens
automatically the first time a component is enrolled from the
main thread; call this explicitly from the main thread when
components are only ever brought up from background threads,
where Python forbids installing signal handlers — enrollment
there defers the atexit hook together with the signal handlers.

### `shutdown()`

```python Signature theme={null}
shutdown() -> None
```

Shut down this component's tree, halting motion and releasing resources.

Two phases, both owned by the base class. First a tree-wide
`stop`: motion is halted everywhere before anything is torn
down, so no part of the robot is still commandable while another
part is being released. Then the teardown walk — every
subcomponent is shut down first (children before their parent,
leaf-to-root; siblings in `subcomponents` insertion order),
then this component's own `_shutdown_self` hook runs.
Children-first ordering is a contract for shared resources: a
parent that owns a resource its children borrow (e.g. one ROS
node shared by both arms) releases it in its own hook, after all
children have shut down — a child must never release a resource
it does not own.

Idempotent: the first call latches, and every later call is a
no-op; the tree-wide stop also runs once, so a nested
`shutdown()` reached by the walk does not re-stop its subtree.
Best-effort: the stop phase and every hook failure are logged and
the walk continues, so this method never raises — it can run
safely from `__exit__`, signal handlers, and interpreter-exit
hooks. Blocks until every hook has returned; the component is
unusable afterwards.

Shutting down also drops the component from process-wide exit
cleanup (the enrollment made by the public `start`), so
the atexit/signal handlers only ever touch components that are
still live.

Subclasses must not replace this method — per-component cleanup
belongs in `_shutdown_self`. An override may only *extend*
the walk and must delegate to `super().shutdown()`; it must
never re-implement the recursion.

### `start()`

```python Signature theme={null}
start() -> None
```

Bring this component's tree online (connect, enable, arm).

Recursive walk owned by the base class and the mirror of
`shutdown`. Per node the walk runs `_start_self`,
then `_provision_children`, then descends into every
subcomponent (parents before their children, root-to-leaf;
siblings in `subcomponents` insertion order). That ordering is
the resource-handoff contract: a parent creates the runtime
resources its children borrow (an RTDE connection, a ROS node) in
its own bring-up hook and hands them to its children in
`_provision_children`, before any child hook runs.

**Warning: bring-up hooks move hardware.** `start()` is not a
passive connect. Driver hooks power on, enable, home, calibrate,
or stand a robot up — a Robotiq gripper strokes its jaws to
auto-calibrate, a WidowX homes, a Flexiv enables and homes its
gripper, a Go2 stands up. Restarting a tree re-runs those hooks,
so `stop()` then `start()` repeats that motion. Clear the
workspace before starting or restarting a physical robot; each
driver's `_start_self` documents the motion it commands.

Idempotent: the walk always descends the whole tree, but a
component whose bring-up hook already ran — and whose
`_still_live` health hook still reports it live — is
skipped, so calling `start()` twice re-runs no bring-up and
calling it after attaching a new subcomponent brings up only the
newcomer. A started component whose health hook reports its
resources dead (a power-cycled controller, a dropped connection)
gets its bring-up re-run, so `start()` alone is the recovery
call after such a fault.
`_provision_children` runs on every descent through a node
regardless of that mark, so a newcomer is provisioned by its
parent before its own hook runs. `stop` re-arms every
component it visits, so `stop()` then `start()` re-runs the
bring-up hooks (reconnect-after-fault) — while leaving the stopped
tree callable throughout. Blocks until every hook has returned.

Fail-fast: the first failing hook aborts the walk and
`ComponentStartError` is raised — a half-started component is
never handed back to the caller. Cleanup is scoped to this call:
the components this walk brought up for the first time are shut
down (best-effort) and the failing subtree is released, while
components that were already live before the call keep running
and the tree is not latched. On an initial bring-up nothing was
live, so that scope is the whole tree. Components this walk was
*restarting* (started before, re-armed by `stop`) are only
stopped, never shut down — a failed reconnect (e.g. a robot still
in an emergency stop) stays retryable with another `start()`.
A subtree that was already shut down is skipped with a warning
rather than resurrected.

Calling this method also enrolls the component in process-wide
exit cleanup: the atexit/signal handlers shut down every
component whose public `start()` was called (a tree root, or a
subtree driven directly) and that has not been shut down yet, so
hardware is released on normal termination and Ctrl+C once the
handlers are installed — automatic on the first main-thread
enrollment; a process that only brings components up from
background threads must call `setup_shutdown_handlers`
from its main thread. `shutdown` unenrolls.

Subclasses must not replace this method — per-component bring-up
belongs in `_start_self`. An override may only *extend* the
walk by delegating to `super().start()`; it must never
re-implement the recursion.

**Raises:**

RuntimeError: If this component has already been shut down;
`shutdown()` is final, so a new object is required.
ComponentStartError: If a bring-up hook raised. Whatever this
call brought up has been released by the time it
propagates, and the original failure is the exception's
`__cause__`.

### `stop()`

```python Signature theme={null}
stop(name: str = 'cmd_vel')
```

Stop the robot base.

<ParamField type="str">
  Name of velocity command. (default: "cmd\_vel")
</ParamField>

**Returns:**

None


# Isaac robots
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-robots/overview

Robots in the Isaac Sim simulator

Robots in the Isaac Sim simulator — GRID's NVIDIA Isaac backend. Each class implements the same neutral robot interface as a physical robot, so code written against a simulated arm runs against a real one.

## Install

```bash theme={null}
# Preinstalled in every GRID simulation session — the generated notebook
# already imports it. For local use, install from the GRID package index
# with your organization's read-only credentials:
export UV_INDEX_GRID_PYPI_USERNAME=<username>
export UV_INDEX_GRID_PYPI_PASSWORD=<token>
uv pip install grid-sim-client --index grid-pypi=https://pypi.generalrobotics.dev/simple/
```

## Quickstart

```python theme={null}
from grid_sim_client.isaac.robot import IsaacArm

# In a GRID simulation session the notebook creates this for you.
arm = IsaacArm()
arm.setJointAngles([0.0, -1.2, 1.5, 0.0, 1.2, 0.0])
```

The methods these classes expose are defined by the **Robot interface**. The AirGen equivalents are **AirGen robots**. Simulation sessions are covered in the **Simulation** section of the sidebar.

## Classes

* [`IsaacArm`](/v2.3/python-api/isaac-robots/isaacarm)
* [`IsaacBimanual`](/v2.3/python-api/isaac-robots/isaacbimanual)
* [`IsaacMobileBimanual`](/v2.3/python-api/isaac-robots/isaacmobilebimanual)
* [`IsaacHumanoid`](/v2.3/python-api/isaac-robots/isaachumanoid)
* [`IsaacLocomotion`](/v2.3/python-api/isaac-robots/isaaclocomotion)


# GenericClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/genericclient

A generic Zenoh client that can handle arbitrary message types and processing functions

```python theme={null}
from grid_sim_client.isaac import GenericClient
```

A generic Zenoh client that can handle arbitrary message types and processing functions.

This class inherits from ZenohClient and provides functionality for publishing and
processing generic messages with optional custom processing functions.

## Fields

<ResponseField name="msg_type" type="str">
  The message type
</ResponseField>

<ResponseField name="fn" type="callable">
  Optional function for custom message processing
</ResponseField>

<ResponseField name="msg">
  The most recently published/received message
</ResponseField>

## Constructor

```python Signature theme={null}
GenericClient(
    *,
    client_dict: dict,
    agent_dict: Optional[dict] = None,
    shared_session: Any = None,
)
```

Initialize the generic client.

Note: \{
For generic client, you also need to include the following keys:

* "msg\_type": The message type (e.g., "Bool", "Twist", "Pose")
* "fn": The function to process the message
  }

<ParamField type="dict">
  Configuration dictionary for the client
</ParamField>

<ParamField type="dict, optional">
  Dictionary of agent parameters. Defaults to None.
</ParamField>

<ParamField>
  Optional shared Zenoh session. Defaults to None.
</ParamField>

## Methods

### `getLatestMessage()`

```python Signature theme={null}
getLatestMessage() -> Any
```

Return the most recent message from the subscription queue.

Blocks for up to one second waiting for a message.

**Returns:**

The raw payload bytes of the latest message, or `None` if no
message was received within the timeout.

### `get_msg()`

```python Signature theme={null}
get_msg() -> Any
```

Get the most recent message.

**Returns:**

The most recently published/received message

### `msg_cb()`

```python Signature theme={null}
msg_cb(sample: Any) -> None
```

Handle an incoming Zenoh sample by storing its payload in the queue.

<ParamField>
  The Zenoh sample received from the subscription.
</ParamField>

### `process_latest_msg()`

```python Signature theme={null}
process_latest_msg() -> None
```

Process the latest received message.

Gets the latest message, deserializes it using CDR or JSON fallback,
and processes it with the configured function if one exists.

**Returns:**

None

### `publish()`

```python Signature theme={null}
publish(data: bytes) -> None
```

Publish data to the topic.

<ParamField>
  Raw bytes to publish on the configured topic.
</ParamField>

### `publish_msg()`

```python Signature theme={null}
publish_msg(msg: Any) -> None
```

Publish a message to the configured topic.

If a processing function is defined, it will be called before publishing.

<ParamField>
  The message to publish (can be a pycdr2 IdlStruct, dict, or primitive)
</ParamField>

**Raises:**

Exception: If the message is None

### `run()`

```python Signature theme={null}
run() -> None
```

Start the client by declaring a subscriber or publisher on the session.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Undeclare the subscriber and close the owned Zenoh session if any.


# ImageClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/imageclient

ImageClient

```python theme={null}
from grid_sim_client.isaac import ImageClient
```

## Constructor

```python Signature theme={null}
ImageClient(
    *,
    client_dict: dict,
    agent_dict: Optional[dict] = None,
    shared_session: Any = None,
)
```

## Methods

### `getLatestMessage()`

```python Signature theme={null}
getLatestMessage() -> Any
```

Return the most recent message from the subscription queue.

Blocks for up to one second waiting for a message.

**Returns:**

The raw payload bytes of the latest message, or `None` if no
message was received within the timeout.

### `get_image()`

```python Signature theme={null}
get_image() -> Optional[np.ndarray]
```

### `msg_cb()`

```python Signature theme={null}
msg_cb(sample: Any) -> None
```

Handle an incoming Zenoh sample by storing its payload in the queue.

<ParamField>
  The Zenoh sample received from the subscription.
</ParamField>

### `process_latest_msg()`

```python Signature theme={null}
process_latest_msg() -> None
```

Process the latest message from the queue. Override in subclasses.

### `publish()`

```python Signature theme={null}
publish(data: bytes) -> None
```

Publish data to the topic.

<ParamField>
  Raw bytes to publish on the configured topic.
</ParamField>

### `publish_image()`

```python Signature theme={null}
publish_image(
    data: np.ndarray,
    encoding: str = 'rgb8',
    compressed: bool = True,
    format: str = 'jpeg',
    quality: int = 85,
) -> None
```

Publish an image to the topic.

<ParamField>
  Image data as numpy array
</ParamField>

<ParamField>
  Image encoding (e.g., "rgb8", "32FC1")
</ParamField>

<ParamField>
  Whether to use compressed image format (default: True)
</ParamField>

<ParamField>
  Compression format ("jpeg" or "png"), only used if compressed=True
</ParamField>

<ParamField>
  JPEG quality (0-100), only used for JPEG compression
</ParamField>

### `run()`

```python Signature theme={null}
run() -> None
```

Start the client by declaring a subscriber or publisher on the session.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Undeclare the subscriber and close the owned Zenoh session if any.


# IsaacClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/isaacclient

Generic Zenoh pub/sub client for simulation scene interactions

```python theme={null}
from grid_sim_client.isaac import IsaacClient
```

Generic Zenoh pub/sub client for simulation scene interactions.

Instead of dedicated methods like `setObjectPose`, this client exposes
generic `pub` / `sub` / `get` operations over a predefined topic
registry. Topics are looked up by key (e.g. `"set_object_pose"`), and
the client handles CDR serialization using the topic's declared ROS2
message type.

Usage::

client = SimClient()

# Publish a Pose to the "set\_object\_pose" topic

client.pub("set\_object\_pose", \{
"position": \{"x": 1.0, "y": 2.0, "z": 0.5},
"orientation": \{"x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0},
})

# Subscribe and poll

client.sub("get\_object\_pose")
pose = client.get("get\_object\_pose")

## Constructor

```python Signature theme={null}
IsaacClient(
    topics: Optional[Dict[str, dict]] = None,
    *,
    connect: Optional[List[str]] = None,
    listen: Optional[List[str]] = None,
    mode: Optional[str] = None,
    config_file: Optional[str] = None,
    verbose: bool = False,
)
```

## Methods

### `add_topic()`

```python Signature theme={null}
add_topic(key: str, zenoh_topic: str, msg_type: str, mode: str = 'both') -> None
```

Register a new topic at runtime.

<ParamField>
  Lookup key (e.g. `"my_custom_topic"`).
</ParamField>

<ParamField>
  Zenoh key expression (e.g. `"/my/topic"`).
</ParamField>

<ParamField>
  ROS2 message class name from `ros2_types` (e.g. `"Pose"`).
</ParamField>

<ParamField>
  `"pub"`, `"sub"`, or `"both"`.
</ParamField>

### `close()`

```python Signature theme={null}
close() -> None
```

Tear down all subscriptions and close the Zenoh session.

### `get()`

```python Signature theme={null}
get(topic_key: str, timeout: float = 1.0) -> Optional[Any]
```

Return the latest message on a subscribed topic.

Call `sub` first to start receiving messages.

<ParamField>
  Registered topic key.
</ParamField>

<ParamField>
  Seconds to wait for a message.
</ParamField>

**Returns:**

Deserialized message, or `None` if nothing received within *timeout*.

### `pub()`

```python Signature theme={null}
pub(topic_key: str, data: Any) -> None
```

Publish *data* to a predefined topic.

*data* can be:

* A dict matching the ROS2 message fields (auto-converted & CDR-serialized).
* A primitive (bool, int, float) for single-field messages like `Bool`.
* A pre-built `pycdr2.IdlStruct` instance (serialized directly).
* A raw `bytes` object (published as-is).

<ParamField>
  Registered topic key.
</ParamField>

<ParamField>
  Payload to publish.
</ParamField>

### `set_named_pose()`

```python Signature theme={null}
set_named_pose(
    name: str,
    position: Union[Sequence[float], Tuple[float, float, float]],
    orientation: Union[Sequence[float], Tuple[float, float, float, float]] = (1, 0, 0, 0),
) -> None
```

Teleport a named rigid body to a given pose.

<ParamField>
  Scene object name (e.g. `"box_pass_005"`).
</ParamField>

<ParamField>
  Target `(x, y, z)` world position.
</ParamField>

<ParamField>
  Target `(w, x, y, z)` quaternion. Defaults to identity.
</ParamField>

### `sub()`

```python Signature theme={null}
sub(topic_key: str, callback: Optional[Callable] = None) -> None
```

Subscribe to a predefined topic.

If *callback* is provided it is invoked with the deserialized message
each time a new sample arrives.  Regardless of callbacks, the latest
message is always available via `get`.

<ParamField>
  Registered topic key.
</ParamField>

<ParamField>
  Optional `fn(msg)` invoked on each message.
</ParamField>


# IsaacClientBundle
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/isaacclientbundle

Owns or views the Zenoh clients backing an Isaac robot

```python theme={null}
from grid_sim_client.isaac import IsaacClientBundle
```

Owns or views the Zenoh clients backing an Isaac robot.

## Fields

<ResponseField name="clients" type="dict[str, Any]" />

<ResponseField name="session_owner" type="Optional[ZenohSession]" />

<ResponseField name="shared_session" type="Any" />

<ResponseField name="velocity_clients" type="list[VelocityClient]" />

<ResponseField name="pose_clients" type="list[PoseClient]" />

<ResponseField name="image_clients" type="list[ImageClient]" />

<ResponseField name="joint_angle_clients" type="list[JointAngleClient]" />

<ResponseField name="wrench_clients" type="list[WrenchClient]" />

## Constructor

```python Signature theme={null}
IsaacClientBundle(
    clients: dict[str, Any],
    session_owner: Optional[ZenohSession] = None,
    shared_session: Any = None,
    velocity_clients: list[VelocityClient] = list(),
    pose_clients: list[PoseClient] = list(),
    image_clients: list[ImageClient] = list(),
    joint_angle_clients: list[JointAngleClient] = list(),
    wrench_clients: list[WrenchClient] = list(),
    _running: bool = False,
    _stopped: bool = False,
)
```

## Methods

### `from_config()`

```python Signature theme={null}
from_config(
    client_config: dict,
    agent_config: Optional[dict] = None,
) -> 'IsaacClientBundle'
```

### `from_existing()`

```python Signature theme={null}
from_existing(
    clients: dict[str, Any],
    *,
    shared_session: Any = None,
    session_owner: Optional[ZenohSession] = None,
) -> 'IsaacClientBundle'
```

### `run()`

```python Signature theme={null}
run() -> None
```

### `stop()`

```python Signature theme={null}
stop() -> None
```


# JointAngleClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/jointangleclient

A Zenoh client for handling joint state messages

```python theme={null}
from grid_sim_client.isaac import JointAngleClient
```

A Zenoh client for handling joint state messages.

This class inherits from ZenohClient and provides functionality for publishing and
receiving joint state messages over Zenoh topics using sensor\_msgs/JointState.

## Fields

<ResponseField name="joint_names" type="list">
  Names of the joints
</ResponseField>

<ResponseField name="joint_positions" type="numpy.ndarray">
  Current joint positions (angles)
</ResponseField>

<ResponseField name="joint_velocities" type="numpy.ndarray">
  Current joint velocities
</ResponseField>

<ResponseField name="joint_efforts" type="numpy.ndarray">
  Current joint efforts/torques
</ResponseField>

## Constructor

```python Signature theme={null}
JointAngleClient(
    *,
    client_dict: dict,
    agent_dict: Optional[dict] = None,
    shared_session: Any = None,
)
```

Initialize the joint angle client.

<ParamField type="dict">
  Configuration dictionary for the client
</ParamField>

<ParamField type="dict, optional">
  Dictionary of agent parameters. Defaults to None.
</ParamField>

<ParamField>
  Optional shared Zenoh session. Defaults to None.
</ParamField>

## Methods

### `getLatestMessage()`

```python Signature theme={null}
getLatestMessage() -> Any
```

Return the most recent message from the subscription queue.

Blocks for up to one second waiting for a message.

**Returns:**

The raw payload bytes of the latest message, or `None` if no
message was received within the timeout.

### `get_joint_efforts()`

```python Signature theme={null}
get_joint_efforts() -> Optional[np.ndarray]
```

Get the current joint efforts.

**Returns:**

numpy.ndarray: Current joint efforts/torques

### `get_joint_names()`

```python Signature theme={null}
get_joint_names() -> List[str]
```

Get the current joint names.

**Returns:**

list: Current joint names

### `get_joint_positions()`

```python Signature theme={null}
get_joint_positions() -> Optional[np.ndarray]
```

Get the current joint positions.

**Returns:**

numpy.ndarray: Current joint positions/angles

### `get_joint_state()`

```python Signature theme={null}
get_joint_state() -> Optional[tuple]
```

Get the latest joint state message.

**Returns:**

tuple: (joint\_names, joint\_positions, joint\_velocities, joint\_efforts) or None

### `get_joint_velocities()`

```python Signature theme={null}
get_joint_velocities() -> Optional[np.ndarray]
```

Get the current joint velocities.

**Returns:**

numpy.ndarray: Current joint velocities

### `msg_cb()`

```python Signature theme={null}
msg_cb(sample: Any) -> None
```

Handle an incoming Zenoh sample by storing its payload in the queue.

<ParamField>
  The Zenoh sample received from the subscription.
</ParamField>

### `process_latest_msg()`

```python Signature theme={null}
process_latest_msg() -> None
```

Process the latest received joint state message.

Gets the latest message and updates the stored joint states. If an agent is
connected, calls setJointAngles with the new positions.

**Returns:**

None

### `publish()`

```python Signature theme={null}
publish(data: bytes) -> None
```

Publish data to the topic.

<ParamField>
  Raw bytes to publish on the configured topic.
</ParamField>

### `publish_agent_joint_state()`

```python Signature theme={null}
publish_agent_joint_state() -> None
```

Publish the current joint state of the connected agent.

### `publish_joint_state()`

```python Signature theme={null}
publish_joint_state(
    joint_names: List[str],
    joint_positions: List[float],
    joint_velocities: Optional[List[float]] = None,
    joint_efforts: Optional[List[float]] = None,
) -> None
```

Publish a joint state message.

<ParamField type="list">
  Names of the joints
</ParamField>

<ParamField type="array-like">
  Joint positions/angles
</ParamField>

<ParamField type="array-like, optional">
  Joint velocities. Defaults to None.
</ParamField>

<ParamField type="array-like, optional">
  Joint efforts/torques. Defaults to None.
</ParamField>

### `run()`

```python Signature theme={null}
run() -> None
```

Start the client by declaring a subscriber or publisher on the session.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Undeclare the subscriber and close the owned Zenoh session if any.


# Isaac scene
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/overview

Drive the Isaac Sim *scene* rather than the robot in it

Drive the Isaac Sim *scene* rather than the robot in it — move props, read object poses, and reset between trials. Generic pub/sub over a topic registry, so one client covers every scene interaction.

## Install

```bash theme={null}
# Preinstalled in every GRID simulation session — the generated notebook
# already imports it. For local use, install from the GRID package index
# with your organization's read-only credentials:
export UV_INDEX_GRID_PYPI_USERNAME=<username>
export UV_INDEX_GRID_PYPI_PASSWORD=<token>
uv pip install grid-sim-client --index grid-pypi=https://pypi.generalrobotics.dev/simple/
```

## Quickstart

```python theme={null}
from grid_sim_client.isaac import IsaacClient

client = IsaacClient()

# Topics are addressed by key; the client handles CDR serialization.
client.pub("set_object_pose", {
    "position": {"x": 1.0, "y": 2.0, "z": 0.5},
    "orientation": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0},
})

# Subscribe, then poll for the latest value.
client.sub("get_object_pose")
pose = client.get("get_object_pose")
```

To drive the robot in the scene rather than the scene itself, see **Isaac robots**. The AirGen backend is documented under **AirGen robots**.

## Classes

* [`IsaacClient`](/v2.3/python-api/isaac-scene/isaacclient)
* [`IsaacClientBundle`](/v2.3/python-api/isaac-scene/isaacclientbundle)
* [`ZenohSession`](/v2.3/python-api/isaac-scene/zenohsession)
* [`ZenohClient`](/v2.3/python-api/isaac-scene/zenohclient)
* [`GenericClient`](/v2.3/python-api/isaac-scene/genericclient)
* [`ImageClient`](/v2.3/python-api/isaac-scene/imageclient)
* [`JointAngleClient`](/v2.3/python-api/isaac-scene/jointangleclient)
* [`PoseClient`](/v2.3/python-api/isaac-scene/poseclient)
* [`VelocityClient`](/v2.3/python-api/isaac-scene/velocityclient)
* [`WrenchClient`](/v2.3/python-api/isaac-scene/wrenchclient)


# PoseClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/poseclient

A Zenoh client for handling pose messages

```python theme={null}
from grid_sim_client.isaac import PoseClient
```

A Zenoh client for handling pose messages.

This class inherits from ZenohClient and provides functionality for publishing and
receiving pose messages over Zenoh topics.

## Fields

<ResponseField name="position" type="numpy.ndarray">
  Current position as \[x, y, z]
</ResponseField>

<ResponseField name="orientation" type="numpy.ndarray">
  Current orientation as quaternion \[x, y, z, w]
</ResponseField>

<ResponseField name="relative" type="bool">
  Whether poses are relative to current position
</ResponseField>

<ResponseField name="blocking" type="bool">
  Whether pose commands block until complete
</ResponseField>

## Constructor

```python Signature theme={null}
PoseClient(
    *,
    client_dict: dict,
    agent_dict: Optional[dict] = None,
    shared_session: Any = None,
)
```

Initialize the pose client.

<ParamField type="dict">
  Configuration dictionary for the client
</ParamField>

<ParamField type="dict, optional">
  Dictionary of agent parameters. Defaults to None.
</ParamField>

<ParamField>
  Optional shared Zenoh session. Defaults to None.
</ParamField>

## Methods

### `getLatestMessage()`

```python Signature theme={null}
getLatestMessage() -> Any
```

Return the most recent message from the subscription queue.

Blocks for up to one second waiting for a message.

**Returns:**

The raw payload bytes of the latest message, or `None` if no
message was received within the timeout.

### `get_orientation()`

```python Signature theme={null}
get_orientation() -> Optional[np.ndarray]
```

Get the current orientation.

**Returns:**

numpy.ndarray: Current orientation as quaternion \[x, y, z, w]

### `get_pose()`

```python Signature theme={null}
get_pose() -> Optional[tuple]
```

Get the latest pose message.

**Returns:**

tuple: (position, orientation) as numpy arrays or None

### `get_position()`

```python Signature theme={null}
get_position() -> Optional[np.ndarray]
```

Get the current position.

### `msg_cb()`

```python Signature theme={null}
msg_cb(sample: Any) -> None
```

Handle an incoming Zenoh sample by storing its payload in the queue.

<ParamField>
  The Zenoh sample received from the subscription.
</ParamField>

### `process_latest_msg()`

```python Signature theme={null}
process_latest_msg() -> None
```

Process the latest received pose message.

### `publish()`

```python Signature theme={null}
publish(data: bytes) -> None
```

Publish data to the topic.

<ParamField>
  Raw bytes to publish on the configured topic.
</ParamField>

### `publish_agent_pose()`

```python Signature theme={null}
publish_agent_pose() -> None
```

Publish the current pose of the connected agent.

### `publish_pose()`

```python Signature theme={null}
publish_pose(position: np.ndarray, orientation: np.ndarray) -> None
```

Publish a pose message.

<ParamField type="array-like">
  Position as \[x, y, z]
</ParamField>

<ParamField type="array-like">
  Orientation as quaternion \[x, y, z, w]
</ParamField>

### `run()`

```python Signature theme={null}
run() -> None
```

Start the client by declaring a subscriber or publisher on the session.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Undeclare the subscriber and close the owned Zenoh session if any.


# VelocityClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/velocityclient

VelocityClient

```python theme={null}
from grid_sim_client.isaac import VelocityClient
```

## Constructor

```python Signature theme={null}
VelocityClient(
    *,
    client_dict: dict,
    agent_dict: Optional[dict] = None,
    shared_session: Any = None,
)
```

## Methods

### `getLatestMessage()`

```python Signature theme={null}
getLatestMessage() -> Any
```

Return the most recent message from the subscription queue.

Blocks for up to one second waiting for a message.

**Returns:**

The raw payload bytes of the latest message, or `None` if no
message was received within the timeout.

### `msg_cb()`

```python Signature theme={null}
msg_cb(sample: Any) -> None
```

Handle an incoming Zenoh sample by storing its payload in the queue.

<ParamField>
  The Zenoh sample received from the subscription.
</ParamField>

### `process_latest_msg()`

```python Signature theme={null}
process_latest_msg() -> Optional[Tuple[np.ndarray, np.ndarray]]
```

### `publish()`

```python Signature theme={null}
publish(data: bytes) -> None
```

Publish data to the topic.

<ParamField>
  Raw bytes to publish on the configured topic.
</ParamField>

### `publish_velocity()`

```python Signature theme={null}
publish_velocity(
    linear_velocity: np.ndarray,
    angular_velocity: Optional[np.ndarray] = None,
) -> None
```

### `run()`

```python Signature theme={null}
run() -> None
```

Start the client by declaring a subscriber or publisher on the session.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Undeclare the subscriber and close the owned Zenoh session if any.


# WrenchClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/wrenchclient

A Zenoh client for publishing and receiving wrench messages over Zenoh topics

```python theme={null}
from grid_sim_client.isaac import WrenchClient
```

A Zenoh client for publishing and receiving wrench messages over Zenoh topics.
Wrenches are commonly received from contact sensors,
and published to end effectors that need to apply a force or torque.

## Fields

<ResponseField name="force" type="numpy.ndarray">
  Current force as \[x, y, z]
</ResponseField>

<ResponseField name="torque" type="numpy.ndarray">
  Current torque as \[x, y, z]
</ResponseField>

<ResponseField name="relative" type="bool">
  Whether wrenches are relative to current position
</ResponseField>

<ResponseField name="blocking" type="bool">
  Whether wrench commands block until complete
</ResponseField>

## Constructor

```python Signature theme={null}
WrenchClient(
    *,
    client_dict: dict,
    agent_dict: Optional[dict] = None,
    shared_session: Any = None,
)
```

Initialize the wrench client.

<ParamField type="dict">
  Configuration dictionary for the client
</ParamField>

<ParamField type="dict, optional">
  Dictionary of agent parameters. Defaults to None.
</ParamField>

<ParamField>
  Optional shared Zenoh session. Defaults to None.
</ParamField>

## Methods

### `getLatestMessage()`

```python Signature theme={null}
getLatestMessage() -> Any
```

Return the most recent message from the subscription queue.

Blocks for up to one second waiting for a message.

**Returns:**

The raw payload bytes of the latest message, or `None` if no
message was received within the timeout.

### `get_force()`

```python Signature theme={null}
get_force() -> Optional[np.ndarray]
```

Get the current force.

**Returns:**

numpy.ndarray: Current force as \[x, y, z]

### `get_torque()`

```python Signature theme={null}
get_torque() -> Optional[np.ndarray]
```

Get the current torque.

**Returns:**

numpy.ndarray: Current torque as \[x, y, z]

### `get_wrench()`

```python Signature theme={null}
get_wrench() -> Optional[tuple]
```

Get the latest wrench message.

**Returns:**

tuple: (force, torque) as numpy arrays or None

### `msg_cb()`

```python Signature theme={null}
msg_cb(sample: Any) -> None
```

Handle an incoming Zenoh sample by storing its payload in the queue.

<ParamField>
  The Zenoh sample received from the subscription.
</ParamField>

### `process_latest_msg()`

```python Signature theme={null}
process_latest_msg() -> None
```

Process the latest received wrench message.

### `publish()`

```python Signature theme={null}
publish(data: bytes) -> None
```

Publish data to the topic.

<ParamField>
  Raw bytes to publish on the configured topic.
</ParamField>

### `publish_wrench()`

```python Signature theme={null}
publish_wrench(force: np.ndarray, torque: np.ndarray) -> None
```

Publish a wrench message.

<ParamField type="array-like">
  Force as \[x, y, z]
</ParamField>

<ParamField type="array-like">
  Torque as \[x, y, z]
</ParamField>

### `run()`

```python Signature theme={null}
run() -> None
```

Start the client by declaring a subscriber or publisher on the session.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Undeclare the subscriber and close the owned Zenoh session if any.


# ZenohClient
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/zenohclient

Abstract base class for Zenoh pub/sub clients

```python theme={null}
from grid_sim_client.isaac import ZenohClient
```

Abstract base class for Zenoh pub/sub clients.

## Constructor

```python Signature theme={null}
ZenohClient(
    *,
    client_dict: Optional[dict] = None,
    agent_dict: Optional[dict] = None,
    shared_session: Any = None,
)
```

## Methods

### `getLatestMessage()`

```python Signature theme={null}
getLatestMessage() -> Any
```

Return the most recent message from the subscription queue.

Blocks for up to one second waiting for a message.

**Returns:**

The raw payload bytes of the latest message, or `None` if no
message was received within the timeout.

### `msg_cb()`

```python Signature theme={null}
msg_cb(sample: Any) -> None
```

Handle an incoming Zenoh sample by storing its payload in the queue.

<ParamField>
  The Zenoh sample received from the subscription.
</ParamField>

### `process_latest_msg()`

```python Signature theme={null}
process_latest_msg() -> None
```

Process the latest message from the queue. Override in subclasses.

### `publish()`

```python Signature theme={null}
publish(data: bytes) -> None
```

Publish data to the topic.

<ParamField>
  Raw bytes to publish on the configured topic.
</ParamField>

### `run()`

```python Signature theme={null}
run() -> None
```

Start the client by declaring a subscriber or publisher on the session.

### `stop()`

```python Signature theme={null}
stop() -> None
```

Undeclare the subscriber and close the owned Zenoh session if any.


# ZenohSession
Source: https://docs.generalrobotics.dev/v2.3/python-api/isaac-scene/zenohsession

Manages a Zenoh session with configurable connection parameters

```python theme={null}
from grid_sim_client.isaac import ZenohSession
```

Manages a Zenoh session with configurable connection parameters.

## Constructor

```python Signature theme={null}
ZenohSession(
    *,
    mode: Optional[str] = None,
    connect: Optional[List[str]] = None,
    listen: Optional[List[str]] = None,
    config_file: Optional[str] = None,
)
```

## Properties

<ResponseField name="session" />

## Methods

### `close()`

```python Signature theme={null}
close()
```