Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Repo-managed hooks are configured via `.githooks`:
- `pre-push`: Rust fmt/clippy/test + Python lint/typecheck subset/test
- Optional local main-push block: set `RFX_BLOCK_MAIN_PUSH=1`.

Enable hooks once per clone:
Hooks are automatically installed by `scripts/setup-from-source.sh`. To re-install hooks manually:

```bash
./scripts/setup-git-hooks.sh
Expand All @@ -57,7 +57,6 @@ Recommended first-time local setup:

```bash
bash scripts/setup-from-source.sh
./scripts/setup-git-hooks.sh
```

## Repo Layout
Expand Down
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,7 @@ loaded = rfx.load_policy("hf://rfx-community/go2-walk-v1")
| **SO-101** | 6-DOF arm | USB serial (Rust driver) | Ready |
| **Unitree Go2** | Quadruped | Ethernet (Zenoh transport) | Ready |
| **Unitree G1** | Humanoid | Ethernet (Zenoh transport) | In progress |
| **Innate** | Manipulation arm | Zenoh-native (no RobotNode) | Ready |

Custom robots: implement `observe()` / `act()` / `reset()` or write a YAML config.

Expand All @@ -198,6 +199,9 @@ Simulation is part of the framework contract. A policy should move across sim, m

- [Full documentation](https://deepwiki.com/quantbagel/rfx)
- [SO-101 quickstart](docs/so101.md)
- [Go2 quickstart](docs/go2.md)
- [Innate bot](docs/innate.md)
- [Teleoperation](docs/teleop.md)
- [Simulation guide](docs/sim.md)
- [Python SDK reference](docs/python-sdk.md)
- [CLI reference](docs/workflow-cli.md)
Expand All @@ -210,6 +214,16 @@ Adapters for specific robots exist to help integration when users already have h

Experimental workflow/runtime surfaces may exist in the repository, but the supported public path is the SDK plus the primary CLI above.

## Contributing

Prerequisites: Python 3.13+, Rust/cargo, uv.

```bash
bash scripts/setup-from-source.sh
```

This installs dependencies, builds the Rust extension, and sets up git hooks. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide and [docs/workflow.md](docs/workflow.md) for the development workflow.

## Community

- [Issues](https://github.com/quantbagel/rfx/issues)
Expand Down
64 changes: 43 additions & 21 deletions cli/README.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,45 @@
# CLI

Home for user-facing command-line tools.

Planned commands:

- `cli/rfx.sh doctor`: environment and dependency checks
- `cli/rfx.sh doctor-so101`: SO101-specific environment/port checks
- `cli/rfx.sh so101-demo`: run a minimal SO101 hardware quickstart
- `cli/rfx.sh so101-bimanual`: run bimanual SO101 teleop using `rfx/configs/so101_bimanual.yaml`
- `cli/rfx.sh bootstrap`: local project setup
- `cli/rfx.sh check`: run monorepo quality checks
- `cli/rfx.sh register --url <dashboard> --api-key <key>`: create or refresh the robot record in the platform
- `cli/rfx.sh probe`: measure candidate AWS region latency directly from the current machine
- `cli/rfx.sh probe --regions us-east-1,us-west-2`: probe a custom AWS region set locally
- `cli/rfx.sh probe --url <dashboard> --api-key <key> --robot-id <id> --submit`: upload probe results back to the platform
- `cli/rfx.sh connect --url <dashboard> --api-key <key>`: keep a registered robot online with periodic heartbeats
- `cli/rfx.sh pkg-create <name>`: create a runtime package scaffold
- `cli/rfx.sh pkg-list`: list runtime packages
- `cli/rfx.sh run <pkg> <node>`: run a node
- `cli/rfx.sh launch <file>`: run a launch graph
- `cli/rfx.sh graph`: inspect active launch graph
- `cli/rfx.sh topic-list`: inspect declared runtime topics
Shell helper for common rfx tasks. All commands run via `cli/rfx.sh <command>`.

## Environment & diagnostics

| Command | Description |
|---------|-------------|
| `doctor` | Environment and dependency checks |
| `doctor-teleop` | Teleop-specific environment checks |
| `doctor-so101` | SO101-specific environment and port checks |

## SO-101 hardware

| Command | Description |
|---------|-------------|
| `so101-demo [--port ...]` | Run a minimal SO101 hardware quickstart |
| `so101-bimanual` | Bimanual SO101 teleop using `rfx/configs/so101_bimanual.yaml` |
| `so101-setup` | Motor ID and baud rate setup wizard |

## Workflow (wraps `rfx` Python CLI)

| Command | Description |
|---------|-------------|
| `record [--robot ...] [--repo-id ...]` | Collect robot observations into a dataset |
| `train [...]` | Train a policy |
| `deploy <policy> [--robot ...]` | Deploy a trained policy to hardware |
| `runs [...]` | Browse saved training runs |

## Platform

| Command | Description |
|---------|-------------|
| `register --url <dashboard> --api-key <key>` | Register robot with the platform |
| `probe [--regions ...]` | Measure candidate AWS region latency |
| `connect --url <dashboard> --api-key <key>` | Keep a registered robot online with heartbeats |

## Setup

| Command | Description |
|---------|-------------|
| `bootstrap` | Local project setup |
| `bootstrap-teleop` | Teleop-specific bootstrap |
| `setup-source` | Run `scripts/setup-from-source.sh` |
| `check` | Run monorepo quality checks |
2 changes: 1 addition & 1 deletion cli/rfx.sh
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ so101_demo() {
}

so101_bimanual() {
uv run --python 3.13 python examples/teleop_record.py --config configs/so101_bimanual.yaml "$@"
uv run --python 3.13 python rfx/examples/teleop_record.py --config rfx/configs/so101_bimanual.yaml "$@"
}

so101_setup() {
Expand Down
28 changes: 22 additions & 6 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,30 @@
# Docs

New here? Start with the [Python SDK](python-sdk.md) to install and try a mock robot, then pick a robot quickstart below. When you're ready to collect data and deploy, see the [CLI reference](workflow-cli.md).

## Getting started

- Python SDK: `docs/python-sdk.md`
- SO101 quickstart: `docs/so101.md`
- Go2 quickstart: `docs/go2.md`
- Innate bot: `docs/innate.md`
- Simulation guide: `docs/sim.md`

## Core workflows

- Teleoperation: `docs/teleop.md`
- CLI reference: `docs/workflow-cli.md`
- Operator checklist: `docs/operator-checklist.md`

## Architecture

- Repository layout: `docs/structure.md`
- Architecture: `docs/architecture.md`
- OSS workflow: `docs/workflow.md`
- Simulation guide: `docs/sim.md`
- SO101 quickstart: `docs/so101.md`
- Python SDK: `docs/python-sdk.md`
- Core primitives (dev): `docs/core-primitives.md`
- Legacy runtime experiments: `docs/runtime.md`
- Workflow CLI: `docs/workflow-cli.md`
- Operator checklist: `docs/operator-checklist.md`

## Operations

- OSS workflow: `docs/workflow.md`
- PyPI release: `docs/release-pypi.md`
- Performance workflow: `docs/perf/README.md`
143 changes: 143 additions & 0 deletions docs/go2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
# Go2 Quickstart

If you have a Unitree Go2 quadruped, this is the fastest path.

## Prerequisites

- rfx installed from source (`bash scripts/setup-from-source.sh`)
- Go2 powered on and connected via Ethernet (default IP: `192.168.123.161`)
- Rust extension built (`maturin develop`)

## 1) Check environment

```bash
rfx doctor
```

Verify that the Rust extension (`rfx._rfx`) loads and core dependencies are available.

## 2) Connect and observe

```python
import rfx

robot = rfx.RealRobot(rfx.GO2_CONFIG)
obs = robot.observe()
print(obs["state"].shape) # torch.Size([1, 64])
robot.disconnect()
```

## 3) High-level commands

The Go2 backend exposes locomotion commands on top of the standard `observe`/`act`/`reset` interface:

```python
from rfx.real import RealRobot
from rfx.robot.config import GO2_CONFIG

robot = RealRobot(GO2_CONFIG)

robot._backend.stand() # recovery stand
robot._backend.sit() # sit down
robot._backend.walk(vx=0.3, vy=0.0, vyaw=0.0) # walk forward
robot._backend.stand() # stop and stand
robot.disconnect()
```

## 4) Deploy a policy

```bash
rfx deploy runs/go2-walk-v1 --robot go2
rfx deploy hf://rfx-community/go2-walk-v1 --robot go2 --duration 30
```

Or from Python:

```python
rfx.deploy("runs/go2-walk-v1", robot="go2", duration=30)
```

## Architecture

```mermaid
graph LR
A[Python: Go2Backend] --> B[Rust: RobotNode]
B --> C[Zenoh Transport]
C --> D[Go2 Hardware]
D --> C
C --> B
B --> A
```

The default backend uses the Rust `RobotNode` pipeline with Zenoh transport. This gives you real-time pub/sub between your Python policy and the robot.

Legacy backends (`unitree_sdk2py`, subprocess) are kept for backwards compatibility but are not recommended. Force the Rust backend with:

```bash
export RFX_GO2_BACKEND=rust
```

## Configuration

Default config (`rfx/configs/go2.yaml`):

```yaml
name: Unitree Go2
urdf_path: rfx/assets/robots/go2/urdf/go2.urdf
state_dim: 34 # 12 pos + 12 vel + 4 quat + 3 gyro + 3 acc
action_dim: 12 # 12 joint position commands
control_freq_hz: 200

joints:
- {name: FR_hip, index: 0}
- {name: FR_thigh, index: 1}
- {name: FR_calf, index: 2}
- {name: FL_hip, index: 3}
- {name: FL_thigh, index: 4}
- {name: FL_calf, index: 5}
- {name: RR_hip, index: 6}
- {name: RR_thigh, index: 7}
- {name: RR_calf, index: 8}
- {name: RL_hip, index: 9}
- {name: RL_thigh, index: 10}
- {name: RL_calf, index: 11}

hardware:
ip_address: 192.168.123.161
edu_mode: false
```

Override at runtime:

```python
robot = rfx.RealRobot(rfx.GO2_CONFIG, ip_address="10.0.0.50")
```

## Simulation

Run the Go2 in Genesis without hardware:

```bash
uv run --python 3.13 rfx/examples/universal_go2.py --backend genesis --auto-install
```

Place URDF assets under `rfx/assets/robots/go2/urdf/` first. See [Simulation Guide](sim.md) for details.

## State vector layout

| Index | Field |
|-------|-------|
| 0-11 | Joint positions (FR hip/thigh/calf, FL, RR, RL) |
| 12-23 | Joint velocities |
| 24-27 | Body quaternion (w, x, y, z) |
| 28-30 | Gyroscope (rad/s) |
| 31-33 | Accelerometer |

Note: `GO2_CONFIG` in Python uses `state_dim=36` while the YAML and observe code produce 34 elements. The state is zero-padded to `max_state_dim=64` for the observation tensor regardless.

## Troubleshooting

- **Can't reach robot**: Verify Ethernet connection and `ping 192.168.123.161`.
- **Rust extension missing**: Run `maturin develop` from repo root.
- **Legacy backend warning**: Set `RFX_GO2_BACKEND=rust` or pass `hw_backend="rust"`.
- **Edu mode**: Pass `edu_mode=True` if your Go2 is in education mode (disables sport client).
Loading
Loading