Metadata-Version: 2.5
Name: almond-axol
Version: 0.1.25
Summary: Almond Axol SDK
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: aiortc>=1.9
Requires-Dist: almond-pyroki>=0.1.0
Requires-Dist: draccus<0.12,>=0.11.6
Requires-Dist: fastapi>=0.135.2
Requires-Dist: jax>=0.9.2
Requires-Dist: jaxlie>=1.5.0
Requires-Dist: mujoco>=3.8.0
Requires-Dist: opencv-python-headless>=4.13.0.92
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-can>=4.6.1
Requires-Dist: scipy>=1.17.1
Requires-Dist: uvicorn[standard]>=0.42.0
Requires-Dist: yourdfpy>=0.0.60
Provides-Extra: gamepad
Requires-Dist: pygame>=2.6; extra == 'gamepad'
Provides-Extra: lerobot
Requires-Dist: lerobot[async,dataset,viz]>=0.6.1; extra == 'lerobot'
Provides-Extra: sim
Requires-Dist: viser>=1.0.24; extra == 'sim'
Description-Content-Type: text/markdown

# Almond Axol SDK

<img src="assets/axol.png" width="400" alt="Axol dual-arm robot" />

Command-line interface and Python SDK for the Almond Axol dual-arm robot. CLI invoked as `axol <command> [flags]`.

The browser front-ends live under [`web/`](web/): a **VR teleoperation interface** (WebXR, hosted at [axol.almond.bot](https://axol.almond.bot)), a **web control panel** that drives the robot from a browser via `axol serve`, and a **diagnostics dashboard** for live motor telemetry and health. See [`web/README.md`](web/README.md) for the front-end details.

The full documentation is hosted at [docs.almond.bot](https://docs.almond.bot). The sources live under [`docs/`](docs/), and the pages below link to them.

**New here?** See [Teleoperation](https://docs.almond.bot/operations/teleop) to go from installation to a live session, or the [Web Control Panel guide](https://docs.almond.bot/guides/control-panel) to drive Axol from a browser.

## Requirements

- **Linux**
- **Python 3.13+**
- **(Optional) NVIDIA Jetson** (e.g. a ZED Box) — required for the GMSL-attached ZED cameras (data collection / policy inference).

## Installation

### One-command install (recommended)

One command installs `uv`, the `axol` CLI (from PyPI, with every extra), and a root systemd service that keeps `axol serve` running at boot:

```bash
curl https://axol.almond.bot/install -fsS | bash
```

Then open [axol.almond.bot](https://axol.almond.bot) and connect to the machine. The install tracks [releases](https://github.com/almond-bot/axol/releases): when a newer release exists, the control panel shows an update banner, and pressing **Update** reinstalls at the new release and restarts the server once idle.

### Development install

Install the package from a clone using [`uv`](https://docs.astral.sh/uv/) — every dependency resolves from PyPI (kinematics comes through our published forks, `almond-pyroki` and `almond-jaxls`):

```bash
uv sync
```

Then activate the virtual environment so the `axol` CLI is on your path (or prefix every command with `uv run`):

```bash
source .venv/bin/activate
```

Install optional dependency groups as needed:

| Extra | Contents | When to use |
|---|---|---|
| `lerobot` | LeRobot (from PyPI, >= 0.6.1) | `collect-data`, `run-policy` |
| `sim` | viser | `teleop --sim` |

```bash
uv sync --extra lerobot --extra sim   # everything
```

The ZED Python bindings (`pyzed`) are not on PyPI and must be installed separately after the ZED SDK is installed:

```bash
axol zed.install
```

Streaming the ZED cameras to the headset (`teleop --cameras`, `collect-data`) encodes on the Jetson's NVENC via GStreamer and sends over WebRTC with aiortc. The encode path needs the system GStreamer NVENC tools plus the patched ZED source plugins, so it isn't a dependency extra. Install it once (and, on a Jetson, pin the NVENC/VIC clocks for low-latency encode):

```bash
axol gst.install
axol gst.build-zed   # build the patched ZED source plugins (needs the ZED SDK)
axol jetson.setup    # Jetson only; no-op elsewhere
```

Before using any motor or robot commands, initialize the CAN hardware:

```bash
axol can.setup
```

To drive Axol from a browser instead of the terminal, build the web UI once (it's served by `axol serve`):

```bash
cd web
npm install
npm run build --workspace=packages/axol-vr-client   # client package first
npm run build --workspace=app                        # → web/app/dist
```

See the [installation guide](https://docs.almond.bot/installation) for the full walkthrough.

## Sitemap

### Get Started

- [Overview](https://docs.almond.bot)
- [Installation](https://docs.almond.bot/installation)

### Operations

Each operation can be driven from the web control panel or the CLI:

- [Teleoperation](https://docs.almond.bot/operations/teleop) — drive the robot live from a VR headset (or in sim)
- [Gravity Compensation](https://docs.almond.bot/operations/gravity-comp) — hold the arms weightless for hand-guiding
- [Data Collection](https://docs.almond.bot/operations/data-collection) — record teleop episodes to a LeRobot dataset
- [Replay Dataset](https://docs.almond.bot/cli/replay-dataset) — replay a recorded dataset episode on the robot, once or on a loop
- [Run Policy](https://docs.almond.bot/operations/run-policy) — run a trained policy, local or remote inference

### Remote Teleop

- [Remote Teleop](https://docs.almond.bot/guides/remote-teleop) — drive over the internet by sideloading Tailscale on a Meta Quest

### Web Interfaces

- [Web Control Panel](https://docs.almond.bot/guides/control-panel) — drive the robot from a browser via `axol serve`
- [Diagnostics Dashboard](https://docs.almond.bot/guides/diagnostics-dashboard) — live motor telemetry, health tiles, and diagnostics scripts, served by `axol serve`
- [VR Interface](https://docs.almond.bot/guides/vr-interface) — the in-repo WebXR teleop app (`web/`)
- [Quest over USB](https://docs.almond.bot/guides/quest-over-usb) — low-latency wired controller transport (poses over a USB `adb` tunnel; camera stays on the LAN)

### Advanced

- [Development install](https://docs.almond.bot/advanced/development-install) — clone + `uv sync`, optional extras, building the web UI

### CLI Reference

- [Command configuration](https://docs.almond.bot/cli/configuration) — draccus config model for `teleop`, `gravity-comp`, `waypoints`, `collect-data`, `replay-dataset`, `run-policy`, `inference-server`
- [`serve`](https://docs.almond.bot/cli/serve) — web control panel + API server
- [`can.setup`](https://docs.almond.bot/cli/can-setup)
- [`can.enable`](https://docs.almond.bot/cli/can-enable)
- [`can.driver`](https://docs.almond.bot/cli/can-driver)
- [`motor.info`](https://docs.almond.bot/cli/motor-info)
- [`motor.health`](https://docs.almond.bot/cli/motor-health)
- [`diag.rom-enable`](https://docs.almond.bot/cli/diag-rom-enable)
- [`diag.rom-disable`](https://docs.almond.bot/cli/diag-rom-disable)
- [`diag.zed-cable`](https://docs.almond.bot/cli/diag-zed-cable)
- [`motor.set-can-id`](https://docs.almond.bot/cli/motor-set-can-id)
- [`motor.set-zero-pos`](https://docs.almond.bot/cli/motor-set-zero-pos)
- [`motor.dump-config`](https://docs.almond.bot/cli/motor-dump-config)
- [`motor.set-config`](https://docs.almond.bot/cli/motor-set-config)
- [`motor.restore-config`](https://docs.almond.bot/cli/motor-restore-config)
- [`motor.flash`](https://docs.almond.bot/cli/motor-flash)
- [`teleop`](https://docs.almond.bot/cli/teleop)
- [`collect-data`](https://docs.almond.bot/cli/collect-data)
- [`replay-dataset`](https://docs.almond.bot/cli/replay-dataset)
- [`run-policy`](https://docs.almond.bot/cli/run-policy)
- [`inference-server`](https://docs.almond.bot/cli/inference-server)
- [`provision`](https://docs.almond.bot/cli/provision)
- [`zed.driver`](https://docs.almond.bot/cli/zed-driver)
- [`zed.install`](https://docs.almond.bot/cli/zed-install)
- [`gst.install`](https://docs.almond.bot/cli/gst-install)
- [`gst.build-zed`](https://docs.almond.bot/cli/gst-build-zed)
- [`jetson.setup`](https://docs.almond.bot/cli/jetson-setup)
- [`tune.pid`](https://docs.almond.bot/cli/tune-pid)
- [`tune.friction`](https://docs.almond.bot/cli/tune-friction)
- [`tune.repeatability`](https://docs.almond.bot/cli/tune-repeatability)
- [`gravity-comp`](https://docs.almond.bot/cli/gravity-comp)
- [`waypoints`](https://docs.almond.bot/cli/waypoints)

### Python API

- [Core Concepts](https://docs.almond.bot/api/concepts)
- [`almond_axol.robot`](https://docs.almond.bot/api/robot) — `Axol`, `Sim`, configuration, gravity compensation
- [`almond_axol.kinematics`](https://docs.almond.bot/api/kinematics)
- [`almond_axol.teleop`](https://docs.almond.bot/api/teleop)
- [`almond_axol.vr`](https://docs.almond.bot/api/vr)
- [`almond_axol.zed`](https://docs.almond.bot/api/zed)
- [`almond_axol.motor`](https://docs.almond.bot/api/motor)
- [`almond_axol.lerobot`](https://docs.almond.bot/api/lerobot)
