Metadata-Version: 2.4
Name: lerobot_robot_galaxea_a1
Version: 0.4.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: galaxea-a1-runtime-protocol<0.2,>=0.1.0
Requires-Dist: lerobot<0.7,>=0.6.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 adapter uses the lightweight `galaxea-a1-runtime-protocol`
distribution released from the Runtime repository. The protocol 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.

## Adapter 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. The first action uses the connection
timeout while the Runtime stages the current-joint hold and activates its relay;
later control calls use the shorter RPC timeout. `disconnect()` releases the
command lease; it does not home the arm or open the gripper.

The adapter does not host the service, own a lease/watchdog, secure the socket,
or import ROS. Those behaviors are implemented and tested in Galaxea A1
Runtime. 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 the tracked A1 Runtime workflow. The pair-specific processor is owned by
that composition root because it combines the SO-Leader units with tracked A1
mapping, limits, startup observation, gripper state, and safety policy. This
Robot package intentionally does not export pairing processors.

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