Metadata-Version: 2.4
Name: lerobot_robot_ugo_nova
Version: 0.1.0
Summary: LeRobot robot plugin for ugo Nova
Author: ugo
License: Apache-2.0
Project-URL: Homepage, https://github.com/ugo-plus/lerobot-robot-ugo-nova
Project-URL: Bug Tracker, https://github.com/ugo-plus/lerobot-robot-ugo-nova/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lerobot==0.6.1
Requires-Dist: numpy
Requires-Dist: opencv-python-headless
Dynamic: license-file

# LeRobot + ugo Nova

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

This package connects the ugo Nova humanoid to Hugging Face's [LeRobot](https://github.com/huggingface/lerobot). Once installed, the robot type `ugo_nova` is available to the LeRobot CLI tools. It reads Nova's joint states and cameras and sends joint position commands over ROS 2.

## Installation

```bash
pip install lerobot_robot_ugo_nova
```

Requires Python 3.12. This installs `lerobot==0.6.1`; add the [LeRobot extras](https://huggingface.co/docs/lerobot/installation) your policy needs.

On the robot, install into an environment that can see ROS 2 Jazzy's `rclpy`, e.g. a venv created with `python3 -m venv --system-site-packages` after `source /opt/ros/jazzy/setup.bash`.

### Check Installed Version

```bash
python -c "from importlib.metadata import version; print(version('lerobot_robot_ugo_nova'))"
```

---

## Quick Start

### Setup Variables

```bash
export REPO_ID="username/my_dataset"
export TASK_NAME="Pick up the cup"
```

### Inference

```bash
lerobot-rollout \
  --strategy.type=base \
  --robot.type=ugo_nova \
  --policy.path=<checkpoint> \
  --inference.type=rtc \
  --task="$TASK_NAME" \
  --duration=60
```

### Replay

```bash
lerobot-replay \
  --robot.type=ugo_nova \
  --dataset.repo_id=$REPO_ID \
  --dataset.episode=0
```

### Dataset Viewer

```bash
lerobot-dataset-viz \
  --repo-id $REPO_ID \
  --episode-index 0
```

### Policy Training

```bash
lerobot-train \
  --dataset.repo_id=$REPO_ID \
  --policy.type=act \
  --policy.device=cuda \
  --policy.push_to_hub=false \
  --output_dir=outputs/train/my_policy \
  --job_name=my_policy
```

---

## Configuration

Override any field with `--robot.<field>=...`, e.g. `--robot.exclude_joints='[waist_j1, waist_j2, waist_j3]'`.

| Field | Default | Description |
| --- | --- | --- |
| `joint_names` | 22 joints (waist, chest, neck, both arms and grippers) | Names and order of the joints in observations and actions |
| `exclude_joints` | `[]` | Joints that receive no command (they keep their current target) |
| `joint_states_topic` | `/joint_states` | Joint state topic |
| `camera_topics` | `hand_left`, `hand_right`, `head` (see below) | Camera name → JPEG topic |
| `camera_shapes` | hands `(1200, 1920)`, head `(720, 1280)` (the cameras' own size) | Camera name → `(height, width)` of the returned image. Smaller shapes are resized; exactly half is the fastest |
| `command_topic` | `/upper_body_position_controller/commands` | Command topic |
| `connect_timeout_s` | `10.0` | How long `connect()` waits for every topic |
| `joint_max_age_s` / `camera_max_age_s` | `0.2` / `0.5` | Older joint states / images raise an error instead of being used |

See [`config_ugo_nova.py`](https://github.com/ugo-plus/lerobot-robot-ugo-nova/blob/main/lerobot_robot_ugo_nova/config_ugo_nova.py) for the full joint list.

---

## ROS 2 Interface

| | Topic | Type |
| --- | --- | --- |
| Joint states | `/joint_states` | `sensor_msgs/JointState` |
| Cameras | `/camL/image_raw/compressed`, `/camR/image_raw/compressed`, `/head/image_raw/compressed` | `sensor_msgs/CompressedImage` |
| Commands | `/upper_body_position_controller/commands` | `std_msgs/Float64MultiArray` |

- **Observation:** joint positions (rad) keyed by `<joint>.pos` (e.g. `arm_r_j1.pos`), and one RGB image per camera.
- **Action:** target joint positions (rad) keyed by `<joint>.pos`, published as one array in `joint_names` order. Excluded joints are sent as `NaN`, which the controller treats as "keep the current target".

---

## Development

```bash
git clone https://github.com/ugo-plus/lerobot-robot-ugo-nova.git
cd lerobot-robot-ugo-nova
pip install -e .
```

## License

Apache-2.0. See [LICENSE](https://github.com/ugo-plus/lerobot-robot-ugo-nova/blob/main/LICENSE).
