Metadata-Version: 2.4
Name: lerobot_robot_galaxea_a1
Version: 0.3.0
Summary: LeRobot Robot plugin for the Galaxea A1 runtime
Author: PengYue
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/pengyue-polaron/lerobot-robot-galaxea-a1
Project-URL: Repository, https://github.com/pengyue-polaron/lerobot-robot-galaxea-a1
Project-URL: Issues, https://github.com/pengyue-polaron/lerobot-robot-galaxea-a1/issues
Keywords: lerobot,galaxea,a1,robotics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio<2.0.0,>=1.82.0
Requires-Dist: lerobot<0.7,>=0.6.0
Requires-Dist: protobuf<8.0.0,>=7.35.0
Dynamic: license-file

<h1 align="center">Galaxea A1 Robot for LeRobot</h1>

<p align="center">
  A third-party LeRobot Robot plugin for the Galaxea A1 Runtime.
</p>

<p align="center">
  <a href="https://huggingface.co/docs/lerobot/v0.6.0/en/integrate_hardware"><img alt="LeRobot 0.6" src="https://img.shields.io/badge/LeRobot-0.6-FFD21E"></a>
  <a href="LICENSE"><img alt="Apache-2.0 License" src="https://img.shields.io/badge/License-Apache--2.0-blue.svg"></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/pengyue-polaron/galaxea-a1-runtime/main/assets/images/a1-d405-wrist-camera.png" width="480" alt="Galaxea A1 follower with a RealSense D405 wrist camera">
</p>

This package registers the LeRobot Robot type `galaxea_a1`. It talks to the
separately supervised Galaxea A1 Runtime over a local Unix socket; ROS, vendor
drivers, cameras, process supervision, and motor publication remain in the
Runtime. The transport is an A1 implementation detail, not a generic robot API.

## Install

```bash
python -m pip install lerobot_robot_galaxea_a1
```

The [Galaxea A1 Runtime](https://github.com/pengyue-polaron/galaxea-a1-runtime)
must be installed and supervised separately.

## LeRobot integration

| Convention | Value |
| --- | --- |
| Distribution | `lerobot_robot_galaxea_a1` |
| Type | `galaxea_a1` |
| Config | `GalaxeaA1Config` |
| Robot | `GalaxeaA1` |
| Supported LeRobot | `>=0.6,<0.7` |

The distribution prefix, module layout, config registration, class names, and
package exports follow LeRobot's
[third-party hardware conventions](https://huggingface.co/docs/lerobot/v0.6.0/en/integrate_hardware).
LeRobot CLI entrypoints discover the plugin after installation.

`GalaxeaA1Config` requires an absolute `unix:///` Runtime endpoint. Creating
the config and Robot does not connect to the service, and both LeRobot feature
properties remain available while it is offline.

## Device contract

The plugin owns the fixed control feature names below. At connection time it
requires the Runtime manifest to match them exactly; the Runtime remains the
source of truth for configured joint limits.

```text
joint_1_rad ... joint_6_rad  absolute radians
gripper_normalized           continuous 0..1
```

`connect()` opens a Runtime session without moving the arm. `send_action()`
validates and submits six named joint targets plus the gripper target, then
returns the action accepted by the Runtime. `disconnect()` releases the command
lease; it does not home the arm or open the gripper.

Only one command session may hold the A1 control lease. Session heartbeats keep
the connection alive but do not extend the command-inactivity deadline; an idle
or failed command session loses control. If command-resource cleanup fails, the
service stops instead of admitting another owner. The endpoint directory and
socket are restricted to the Runtime user (`0700` and `0600` respectively), and
a pre-existing endpoint is never removed implicitly. Calibration and reset
remain explicit Runtime workflows and are not remote Robot operations.

## Pairing with the A1 SO-Leader

The modified leader reports degrees; the A1 accepts radians. Do not connect
them through the identity processors used by the generic LeRobot 0.6
`lerobot-teleoperate` and `lerobot-record` commands.

Use `make_galaxea_a1_processors()` with LeRobot's programmatic APIs, or use the
tracked A1 Runtime workflow. The supplied processor anchors leader deltas to
the A1 startup pose and applies explicit degree conversion, sign, scale, bias,
joint limits, and gripper normalization.

## Recording boundary

This plugin exposes control observations: six measured joints and normalized
gripper state. It does not reopen Runtime-owned cameras or make joint control
depend on EEF tracking.

The A1 Runtime combines this control path with EEF feedback and paired cameras,
then commits the canonical LeRobotDataset v3.0 dataset. Synchronization,
provenance, atomic episode commit, and safety lifecycle belong there.

## Development

```bash
uv venv --python 3.12
uv pip install -e . pytest ruff build
uv run --no-project pytest
uv run --no-project ruff check .
uv run --no-project ruff format --check .
uv build
```
