From 758aa77980be83acd5c6dfaf06f425970305891a Mon Sep 17 00:00:00 2001 From: doctor Date: Thu, 5 Mar 2026 10:24:26 -0800 Subject: [PATCH 1/3] docs: add Go2, Innate, teleop guides; streamline existing docs --- README.md | 4 + docs/README.md | 26 ++++- docs/go2.md | 140 +++++++++++++++++++++++ docs/innate.md | 147 +++++++++++++++++++++++++ docs/operator-checklist.md | 54 +++++---- docs/python-sdk.md | 39 ++++++- docs/sim.md | 114 +++++-------------- docs/structure.md | 42 ++++--- docs/teleop.md | 201 ++++++++++++++++++++++++++++++++++ docs/workflow-cli.md | 5 +- rfx/python/rfx/real/README.md | 1 + 11 files changed, 634 insertions(+), 139 deletions(-) create mode 100644 docs/go2.md create mode 100644 docs/innate.md create mode 100644 docs/teleop.md diff --git a/README.md b/README.md index ee58cd9..bb67227 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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) diff --git a/docs/README.md b/docs/README.md index 2d47ea1..5bdf18a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,28 @@ # Docs +## 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` diff --git a/docs/go2.md b/docs/go2.md new file mode 100644 index 0000000..474b469 --- /dev/null +++ b/docs/go2.md @@ -0,0 +1,140 @@ +# 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 your network can reach the Go2. + +## 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 +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 | + +## 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). diff --git a/docs/innate.md b/docs/innate.md new file mode 100644 index 0000000..5264a4b --- /dev/null +++ b/docs/innate.md @@ -0,0 +1,147 @@ +# Innate Bot + +The Innate backend connects to bots that publish their own state over Zenoh. Unlike the Go2 or SO-101 backends, no Rust `RobotNode` is needed — the bot itself is the Zenoh publisher. + +## Prerequisites + +- rfx installed (`uv pip install rfx-sdk` or from source) +- `eclipse-zenoh` Python package: `pip install eclipse-zenoh` +- Innate bot powered on and reachable over the network + +## Quick start + +```python +from rfx.real import InnateRobot + +robot = InnateRobot() +obs = robot.observe() +robot.act(action_tensor) +robot.disconnect() +``` + +With a custom Zenoh endpoint (multi-machine setup): + +```python +robot = InnateRobot(zenoh_endpoint="tcp/10.0.0.1:7447") +``` + +## Architecture + +```mermaid +graph LR + Bot[Innate Bot] -- publishes state --> Z[Zenoh Bus] + Z -- subscribes --> B[InnateBackend] + B -- observe/act --> P[Python Policy] + P -- action --> B + B -- publishes cmd --> Z + Z -- receives cmd --> Bot +``` + +The bot publishes joint state to a Zenoh topic. `InnateBackend` subscribes, deserializes, and exposes it through the standard `observe()`/`act()`/`reset()` interface. Commands flow back the same way. + +## Configuration + +Default config (`INNATE_CONFIG`): + +```python +from rfx.robot.config import INNATE_CONFIG + +print(INNATE_CONFIG.action_dim) # 6 +print(INNATE_CONFIG.control_freq_hz) # 50 +``` + +Hardware settings are passed through to the backend: + +| Setting | Default | Description | +|---------|---------|-------------| +| `zenoh_state_topic` | `innate/joint_states` | Zenoh key for state subscription | +| `zenoh_cmd_topic` | `innate/joint_commands` | Zenoh key for command publishing | +| `msg_format` | `json` | Message format: `json` or `cdr` | +| `zenoh_endpoint` | none | Optional Zenoh router address | + +Override via hardware config dict or kwargs: + +```python +from rfx.real import RealRobot +from rfx.robot.config import INNATE_CONFIG + +robot = RealRobot( + INNATE_CONFIG, + zenoh_state_topic="my_bot/joints", + zenoh_cmd_topic="my_bot/commands", + msg_format="cdr", + zenoh_endpoint="tcp/10.0.0.1:7447", +) +``` + +## Message formats + +### JSON (default) + +State messages accepted in two formats: + +rfx-native: +```json +{ + "joint_positions": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6], + "joint_velocities": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0] +} +``` + +JointState-like: +```json +{ + "position": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6], + "velocity": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0] +} +``` + +Command messages: +```json +{"position": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6]} +``` + +### CDR (ROS 2 compatible) + +Set `msg_format: "cdr"` to receive `sensor_msgs/msg/JointState` messages encoded in CDR (Common Data Representation). The backend includes a minimal CDR deserializer that extracts position, velocity, and effort arrays. + +Commands in CDR mode are sent as raw little-endian `float64` arrays (not full CDR JointState). + +## Deploy a policy + +```bash +rfx deploy runs/my-policy --robot innate +``` + +```python +rfx.deploy("runs/my-policy", robot="innate") +``` + +## Custom joint count + +If your bot has more or fewer than 6 joints, create a custom config: + +```python +from rfx.robot.config import RobotConfig, JointConfig + +my_config = RobotConfig( + name="Innate", + state_dim=16, # 8 pos + 8 vel + action_dim=8, + joints=[JointConfig(name=f"joint_{i}", index=i) for i in range(8)], + hardware={ + "zenoh_state_topic": "my_bot/joints", + "zenoh_cmd_topic": "my_bot/commands", + "msg_format": "json", + }, +) + +robot = RealRobot(my_config, robot_type="innate") +``` + +## Troubleshooting + +- **`ImportError: zenoh`**: Install with `pip install eclipse-zenoh`. +- **No state received**: Verify the bot is publishing to the expected topic. Check with `zenoh` CLI tools or set `logging.basicConfig(level=logging.DEBUG)`. +- **CDR parse errors**: Ensure the bot sends standard ROS 2 CDR-encoded `sensor_msgs/JointState`. The deserializer expects little-endian encoding with a 4-byte RTPS header. +- **Multi-machine**: Pass `zenoh_endpoint="tcp/:7447"` to connect through a Zenoh router. diff --git a/docs/operator-checklist.md b/docs/operator-checklist.md index 7f3d1b7..af14190 100644 --- a/docs/operator-checklist.md +++ b/docs/operator-checklist.md @@ -1,42 +1,40 @@ # Operator Checklist -Use this checklist before every production deploy. +Checklist before deploying a policy to real hardware. ## Preconditions -- Zenoh control plane reachable for your deployment topology. -- Robot config selected and safety profile defined. -- Dataset collected with the same robot contract version. +- Robot powered on and reachable (serial port or network). +- Robot config selected and validated (`rfx doctor`). +- Policy trained and saved as a self-describing directory. -## Required Gates +## Pre-deploy checks -1. `collect` run exists and dataset inputs are stored. -2. `validate` report passed (`timestamp`, `alignment`, `schema`, `missing data` checks). -3. `train` produced a policy artifact manifest with compatibility metadata. -4. `eval` report passed for the same artifact. -5. Optional but recommended: `shadow` report passed. -6. `deploy` preflight allowed the release. +1. Policy loads without error: + ```python + loaded = rfx.load_policy("runs/my-policy") + print(loaded.policy_type, loaded.robot_config) + ``` -## Commands +2. Mock deploy succeeds: + ```bash + rfx deploy runs/my-policy --robot so101 --mock --duration 10 + ``` -```bash -rfx runs list -rfx runs show -rfx lineage -``` +3. Robot config matches the policy's training config (state_dim, action_dim, joint ordering). + +4. Control frequency is appropriate for the robot (`rate_hz` in config or `--rate-hz` flag). -## Blockers +## Deploy -Deploy must be blocked when any of the following occurs: +```bash +rfx deploy runs/my-policy --robot so101 --duration 30 +``` -- Artifact manifest missing or schema incompatible. -- No successful eval report for the artifact. -- Shadow is required but no passing shadow report exists. -- Robot config hash mismatch. -- Safety profile mismatch. +Monitor jitter stats in the output. High p95/p99 jitter indicates the control loop can't keep up at the requested rate. -## Incident Readiness +## Post-deploy -- Keep the `run_id` for rollback and audits. -- Verify `.rfx/runs/`, `.rfx/reports/`, and `.rfx/artifacts/` are persisted. -- Use `rfx reproduce ` to inspect exact replay prerequisites. +- Review `SessionStats` output (iterations, overruns, jitter percentiles). +- If overruns > 0, consider lowering `rate_hz` or profiling the policy. +- Keep the policy directory for reproducibility. diff --git a/docs/python-sdk.md b/docs/python-sdk.md index ba143a5..d8de381 100644 --- a/docs/python-sdk.md +++ b/docs/python-sdk.md @@ -33,6 +33,31 @@ obs = robot.observe() rfx.deploy("runs/my-policy", robot="so101") ``` +## No hardware? No problem + +You can explore the entire rfx workflow on your laptop — no robot required. + +```python +# Mock robot: zero deps, spring-damper physics +robot = rfx.MockRobot(state_dim=12, action_dim=6) +obs = robot.observe() +robot.act(torch.zeros(1, 64)) + +# Simulation: GPU-accelerated with viewer +robot = rfx.SimRobot.from_config("so101.yaml", backend="genesis", viewer=True) + +# Batched RL training: thousands of parallel envs +robot = rfx.SimRobot.from_config("go2.yaml", backend="mjx", num_envs=4096) +``` + +Test the full deploy pipeline without hardware: + +```bash +rfx deploy runs/my-policy --robot so101 --mock +``` + +Write a policy, save it, deploy with `--mock`, iterate. Switch to real hardware when you're ready. + ## The Robot Interface Every robot -- simulated or real -- implements three methods: @@ -48,7 +73,9 @@ Built-in robots: ```python robot = rfx.SimRobot.from_config("so101.yaml", backend="genesis", viewer=True) robot = rfx.MockRobot(state_dim=12, action_dim=6) # zero deps, for testing -robot = rfx.RealRobot(rfx.SO101_CONFIG) # real hardware +robot = rfx.RealRobot(rfx.SO101_CONFIG) # real hardware (SO-101) +robot = rfx.RealRobot(rfx.GO2_CONFIG) # real hardware (Go2) +robot = rfx.RealRobot(rfx.INNATE_CONFIG) # real hardware (Innate, Zenoh-native) ``` ## Collection @@ -196,9 +223,10 @@ Works with any robot config -- joint names are resolved from `config.joints`. ## Built-in Robot Configs ```python -rfx.SO101_CONFIG # 6 DOF arm, 50 Hz, joints: shoulder_pan, shoulder_lift, elbow, wrist_pitch, wrist_roll, gripper -rfx.GO2_CONFIG # 12 DOF quadruped, 200 Hz -rfx.G1_CONFIG # 29 DOF humanoid, 50 Hz +rfx.SO101_CONFIG # 6 DOF arm, 50 Hz, joints: shoulder_pan, shoulder_lift, elbow, wrist_pitch, wrist_roll, gripper +rfx.GO2_CONFIG # 12 DOF quadruped, 200 Hz +rfx.G1_CONFIG # 29 DOF humanoid, 50 Hz +rfx.INNATE_CONFIG # 6 DOF Innate bot, 50 Hz, Zenoh-native (no Rust RobotNode) ``` ## Package Layout @@ -207,8 +235,9 @@ rfx.G1_CONFIG # 29 DOF humanoid, 50 Hz rfx/python/rfx/ ├── robot/ # Robot protocol, config, URDF ├── collection/ # Collection and dataset contracts -├── real/ # Real hardware backends (SO-101, Go2, G1) +├── real/ # Real hardware backends (SO-101, Go2, G1, Innate) ├── sim/ # Simulation backends (MuJoCo, Genesis, mock) +├── teleop/ # Teleoperation sessions, transport, recording ├── runtime/ # Lifecycle, CLI, health, runtime helpers ├── hub.py # Model save/load/push (HuggingFace Hub) ├── session.py # Rate-controlled control loop diff --git a/docs/sim.md b/docs/sim.md index 2791687..7c76559 100644 --- a/docs/sim.md +++ b/docs/sim.md @@ -1,33 +1,36 @@ -# Simulation Guide +# Simulation -This document explains how to run rfx in simulation without robot hardware. - -Current status: - -- Genesis integration is available now. -- Isaac Lab and MuJoCo integration are planned and will be added in this same guide. +Three backends: Genesis (GPU), MJX (JAX-accelerated MuJoCo), and Mock (zero deps). ## Quickstart (Genesis) -Run this from the repo root: - ```bash uv pip install --python 3.13 torch uv run --python 3.13 rfx/examples/genesis_viewer.py --auto-install ``` -What this does: +This starts the Genesis backend, opens the viewer, and auto-installs `genesis-world` if missing. -- starts the Genesis backend -- opens the viewer -- auto-installs `genesis-world` if missing +## Python API -## Go2 URDF Integration +```python +from rfx.sim import SimRobot + +# Genesis with viewer +robot = SimRobot.from_config("rfx/configs/so101.yaml", backend="genesis", viewer=True, auto_install=True) +obs = robot.reset() + +# MJX with batched envs +robot = SimRobot.from_config("rfx/configs/go2.yaml", backend="mjx", num_envs=4096) + +# Mock (zero deps, for testing) +from rfx.sim import MockRobot +robot = MockRobot(state_dim=12, action_dim=6) +``` -Go2 assets are not bundled in this repository. -Place your own URDF + meshes under `rfx/assets/robots/go2/` before running Go2 examples. +## Go2 URDF Integration -Create this layout: +Go2 assets are not bundled. Place your own URDF + meshes under `rfx/assets/robots/go2/`: ```text rfx/assets/robots/go2/ @@ -38,53 +41,21 @@ rfx/assets/robots/go2/ └── go2.xml ``` -Then run: +Then: ```bash uv run --python 3.13 rfx/examples/universal_go2.py --backend genesis --auto-install ``` -`rfx/configs/go2.yaml` now defaults `urdf_path` to: - -- `rfx/assets/robots/go2/urdf/go2.urdf` - -For a Go2 command demo: +## Run modes -```bash -uv run --python 3.13 rfx/examples/universal_go2.py --backend genesis --auto-install -``` - -## Minimal Python API +Headless (no viewer): ```python -from rfx.sim import SimRobot - -robot = SimRobot.from_config( - "rfx/configs/so101.yaml", - backend="genesis", - viewer=True, - auto_install=True, -) - -obs = robot.reset() -``` - -## Common Run Modes - -Viewer mode: - -```bash -uv run --python 3.13 rfx/examples/genesis_viewer.py -``` - -Headless mode (no viewer): - -```python -from rfx.sim import SimRobot robot = SimRobot.from_config("rfx/configs/so101.yaml", backend="genesis", viewer=False) ``` -Control runtime knobs: +Runtime knobs: ```bash uv run --python 3.13 rfx/examples/genesis_viewer.py \ @@ -93,44 +64,19 @@ uv run --python 3.13 rfx/examples/genesis_viewer.py \ --substeps 4 ``` -## Auto-install Behavior - -If Genesis is not installed: +## Auto-install -- rfx first tries: `uv pip install --python genesis-world` -- if `uv` is unavailable, it falls back to: ` -m pip install genesis-world` +If Genesis is not installed, rfx tries `uv pip install genesis-world`, falling back to `pip install genesis-world`. -Current limitation: +Genesis requires CPython 3.13 (no 3.14 wheels yet). -- Genesis dependencies do not currently publish wheels for CPython 3.14. -- Use a CPython 3.13 environment for Genesis (`uv run --python 3.13 ...`). - -You can also opt in globally: +Opt in globally: ```bash export RFX_AUTO_INSTALL_GENESIS=1 ``` -Then any Genesis backend start will attempt install automatically. - ## Troubleshooting -If Genesis install fails, run: - -```bash -uv pip install genesis-world -``` - -If viewer does not appear: - -- check that your machine supports graphics for the active environment -- retry with `--device cpu` -- validate by running headless first - -## Roadmap - -This guide will gain sections for: - -- Isaac Lab integration -- MuJoCo integration -- backend switching patterns and shared config conventions +- Genesis install fails: `uv pip install genesis-world` manually. +- No viewer: check graphics support, retry with `--device cpu`, or run headless first. diff --git a/docs/structure.md b/docs/structure.md index db3c1ef..50fd391 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -1,21 +1,35 @@ # Repository Structure -Top-level layout: +``` +rfx/ # Core source tree +├── crates/ # Rust crates (rfx-core, rfx-python bindings) +├── python/rfx/ # Python SDK +│ ├── robot/ # Robot protocol, config, URDF +│ ├── real/ # Hardware backends (SO-101, Go2, G1, Innate) +│ ├── sim/ # Simulation backends (Genesis, MJX, Mock) +│ ├── teleop/ # Teleoperation sessions, transport, recording +│ ├── collection/ # Dataset recording, hub integration +│ ├── runtime/ # CLI, node lifecycle, health, otel +│ ├── workflow/ # Quality gates, stage registry +│ └── utils/ # Padding, transforms, normalizers +├── tests/ # Python test suite +├── configs/ # Robot YAML configs (so101, go2, so101_bimanual) +├── assets/ # Robot URDF/MJCF assets +└── examples/ # Runnable examples -- `rfx/`: production and test source code (includes `python/rfx/hub.py` for model management and `python/rfx/nn.py` for policy definitions) -- `packages/`: extension Python packages (`rfx-sdk-sim`, `rfx-sdk-go2`, `rfx-sdk-lerobot`) -- `docs/`: architecture, workflows, and contributor guides - includes perf baselines in `docs/perf/baselines/` -- `rfxJIT/`: ultra-performance kernel and compiler engine -- `cli/`: command-line interfaces and helpers -- `.claude/skills/`: Claude skills used by agents +packages/ # Extension Python packages +├── rfx-sim/ # rfx-sdk-sim (simulation extras) +├── rfx-go2/ # rfx-sdk-go2 (Go2-specific extras) +└── rfx-lerobot/ # rfx-sdk-lerobot (LeRobot integration) + +docs/ # Documentation +cli/ # Command-line tooling +``` Quality/tooling: -- Hook logic: `.githooks/` -- Hook installer/config: `scripts/setup-git-hooks.sh`, `.pre-commit-config.yaml` +- Git hooks: `.githooks/`, `scripts/setup-git-hooks.sh` - Moon workspace: `.moon/workspace.yml` -- Python check runner: `scripts/python-checks.sh` -- Source setup runner: `scripts/setup-from-source.sh` -- CI workflow: `.github/workflows/ci.yml` -- Workflow guide: `docs/workflow.md` +- Python checks: `scripts/python-checks.sh` +- Source setup: `scripts/setup-from-source.sh` +- CI: `.github/workflows/ci.yml` diff --git a/docs/teleop.md b/docs/teleop.md new file mode 100644 index 0000000..8edc117 --- /dev/null +++ b/docs/teleop.md @@ -0,0 +1,201 @@ +# Teleoperation + +Teleoperation is how you collect demonstrations for policy training. rfx provides a high-level `run()` function and a lower-level `BimanualSo101Session` for full control. + +## The workflow + +```mermaid +graph LR + T[Teleop Session] --> R[Record Episodes] + R --> E[Export Dataset] + E --> TR[Train Policy] + TR --> D[Deploy] +``` + +Leader arms drive follower arms. Joint positions are recorded at up to 350 Hz. Episodes are saved locally and can be exported to LeRobot or MCAP format for training. + +## Quick start + +```python +from rfx.teleop import run, so101 + +arm = so101( + leader_port="/dev/cu.usbmodemA", + follower_port="/dev/cu.usbmodemB", +) +run(arm) +``` + +That's it — teleop starts, Ctrl+C to stop. + +## Recording demos + +Pass `data_output` to enable recording: + +```python +from rfx.teleop import run, so101 + +arm = so101() +run( + arm, + data_output="demos", + duration_s=30.0, + rate_hz=200, +) +``` + +### Export formats + +Export during recording by setting `format`: + +```python +# Native (JSONL + NumPy) +run(arm, data_output="demos", format="native") + +# LeRobot dataset +run(arm, data_output="demos", format="lerobot", lineage="my-org/so101-demos") + +# MCAP timeline +run(arm, data_output="demos", format="mcap") +``` + +Or use the CLI: + +```bash +rfx record --robot so101 --repo-id my-org/demos --episodes 10 +``` + +## Bimanual setup + +For two-arm teleoperation, pass multiple arm pairs: + +```python +from rfx.teleop import run +from rfx.teleop.config import ArmPairConfig + +left = ArmPairConfig( + leader_port="/dev/cu.usbmodemA", + follower_port="/dev/cu.usbmodemB", + name="left", +) +right = ArmPairConfig( + leader_port="/dev/cu.usbmodemC", + follower_port="/dev/cu.usbmodemD", + name="right", +) +run([left, right], data_output="bimanual_demos") +``` + +Or use the config-driven approach: + +```bash +cli/rfx.sh so101-bimanual +``` + +Default bimanual config: `rfx/configs/so101_bimanual.yaml` + +## Camera integration + +Add camera streams to your session: + +```python +from rfx.teleop import run, so101 +from rfx.teleop.config import CameraStreamConfig + +arm = so101() +run( + arm, + cameras=[ + CameraStreamConfig(name="wrist", device_id=0, width=640, height=480, fps=30), + ], + data_output="demos_with_video", +) +``` + +Camera frames are captured in a background thread and synchronized with joint data. + +## Transport layer + +Teleop uses a pluggable transport for pub/sub messaging between components: + +```mermaid +graph TD + S[Session Control Loop] --> T{Transport} + T --> I[InprocTransport
Python queues] + T --> R[RustTransport
Rust channels] + T --> Z[ZenohTransport
Network pub/sub] + T --> H[HybridTransport
Local hot path +
Zenoh control plane] +``` + +| Transport | Use case | +|-----------|----------| +| `InprocTransport` | Single-process, no native deps | +| `RustTransport` | Single-process, low-latency via Rust channels | +| `ZenohTransport` | Multi-machine, network-transparent | +| `HybridTransport` | Local hot path + Zenoh for remote monitoring | + +The default is auto-selected based on available backends. Override with the `transport` parameter. + +## Session API (advanced) + +For full control, use `BimanualSo101Session` directly: + +```python +from rfx.teleop.session import BimanualSo101Session +from rfx.teleop.config import TeleopSessionConfig, ArmPairConfig + +config = TeleopSessionConfig( + arm_pairs=(ArmPairConfig(leader_port="auto", follower_port="auto"),), + rate_hz=200, +) + +with BimanualSo101Session(config=config) as session: + session.start_recording(label="episode-1") + # ... session runs in background thread + episode = session.stop_recording() + print(episode) +``` + +Key methods: + +| Method | Description | +|--------|-------------| +| `start()` / `stop()` | Start/stop the control loop | +| `start_recording()` / `stop_recording()` | Begin/end episode recording | +| `record_episode(duration_s=...)` | Record a fixed-length episode | +| `go_home()` | Send all arms to home position | +| `timing_stats()` | Get loop timing statistics | +| `check_health()` | Verify session health (raises on error) | + +## OpenTelemetry + +Enable tracing for debugging timing issues: + +```bash +export RFX_OTEL=1 +export RFX_OTEL_EXPORTER=console +export RFX_OTEL_SAMPLE_EVERY=100 +``` + +```python +run(arm, otel=True, otel_exporter="console") +``` + +## `run()` reference + +```python +run( + arm, # ArmPairConfig or list of them + logging=False, # live movement trace in terminal + rate_hz=None, # control loop frequency (default: from config) + duration_s=None, # run duration (None = until Ctrl+C) + cameras=None, # list of CameraStreamConfig + transport=None, # override transport backend + data_output=None, # directory to save recordings + lineage=None, # dataset lineage tag + scale=None, # run scale metadata + format="native", # export format: native, lerobot, mcap + metadata=None, # extra metadata dict + otel=False, # enable OpenTelemetry +) +``` diff --git a/docs/workflow-cli.md b/docs/workflow-cli.md index 9c4b399..1d4ebc3 100644 --- a/docs/workflow-cli.md +++ b/docs/workflow-cli.md @@ -39,7 +39,7 @@ rfx record --robot go2 --repo-id demos --duration 20 --push | Flag | Default | Description | |------|---------|-------------| -| `--robot` | required | Robot type (`so101`, `go2`, `g1`) | +| `--robot` | required | Robot type (`so101`, `go2`, `g1`, `innate`) | | `--repo-id` | required | Dataset name or HuggingFace repo ID | | `--episodes` | `1` | Number of episodes to record | | `--duration` | interactive | Episode duration in seconds. Omit to stop with Ctrl+C. | @@ -77,7 +77,7 @@ rfx deploy runs/my-policy --robot so101 --duration 60 --rate-hz 50 --port /dev/t | Flag | Default | Description | |------|---------|-------------| | `policy` | required | Path to policy dir, `hf://org/repo`, or `.py` file | -| `--robot` | auto | Robot type (`so101`, `go2`, `g1`). Auto-detected from policy config if saved. | +| `--robot` | auto | Robot type (`so101`, `go2`, `g1`, `innate`). Auto-detected from policy config if saved. | | `--config` | none | Path to robot YAML config (overrides `--robot`) | | `--port` | auto | Serial port or IP override | | `--rate-hz` | auto | Control loop frequency (defaults to robot config) | @@ -117,6 +117,7 @@ stats = rfx.deploy("hf://user/policy", robot="go2", duration=30) stats = rfx.deploy("my_policy.py", robot="so101") ``` + ## Secondary Commands `rfx train` and `rfx runs` remain available for lightweight workflow metadata and artifact lineage. diff --git a/rfx/python/rfx/real/README.md b/rfx/python/rfx/real/README.md index 275eb47..b2d567b 100644 --- a/rfx/python/rfx/real/README.md +++ b/rfx/python/rfx/real/README.md @@ -7,4 +7,5 @@ Real hardware backends for rfx. Each backend implements the Robot protocol for p - **`base.py`** -- RealRobot: auto-detects robot type from config and wraps the appropriate backend - **`so101.py`** -- So101Backend: 6-DOF arm via USB serial using the Rust driver at 1 Mbaud. Includes So101LeaderFollower for teleoperation pairing. - **`go2.py`** -- Go2Backend: 12-DOF Unitree Go2 quadruped via Zenoh transport (Rust RobotNode). Legacy unitree_sdk2py/subprocess backends kept for backwards compat. Provides stand/sit/walk commands. +- **`innate.py`** -- InnateBackend: Zenoh-native backend for Innate bots. The bot publishes its own state — no Rust RobotNode needed. Supports JSON and CDR (ROS 2 JointState) message formats. - **`camera.py`** -- Camera (OpenCV) and RealSenseCamera (Intel RealSense depth camera) From 4af1e79b8837a0d88cdd8288f69b401e7d276c6a Mon Sep 17 00:00:00 2001 From: doctor Date: Tue, 31 Mar 2026 12:31:45 -0700 Subject: [PATCH 2/3] docs: fix accuracy issues, broken paths, and onboarding gaps - Fix docs/so101.md: correct CLI command (rfx record), fix script path - Fix cli/rfx.sh: correct so101-bimanual paths - Fix docs/go2.md: revert state_dim to 34 (matches YAML and observe code), add urdf_path, fix doctor description - Rewrite cli/README.md to reflect actual cli/rfx.sh commands - Fix rfx/examples/README.md: correct so101_quickstart path, add g1_teleop - Update AGENTS.md: note hooks are auto-installed by setup script - Add SO101_CONFIG, GO2_CONFIG, G1_CONFIG, INNATE_CONFIG re-exports to rfx/__init__.py so rfx.SO101_CONFIG works as documented - Add Contributing section to root README.md - Add start-here guidance to docs/README.md - Fix docs/workflow-cli.md: remove phantom --device CLI flag, remove innate from rfx record (not supported), add missing --output and --task - Fix docs/python-sdk.md: complete deploy signature, add missing dirs to package layout, clarify MockRobot deps - Fix docs/teleop.md: complete run() reference with otel params - Fix docs/innate.md: correct CDR header terminology - Fix docs/sim.md: Genesis works on CPython <= 3.13, not only 3.13 --- AGENTS.md | 3 +- README.md | 10 ++++++ cli/README.md | 64 +++++++++++++++++++++++++------------- cli/rfx.sh | 2 +- docs/README.md | 2 ++ docs/go2.md | 5 ++- docs/innate.md | 2 +- docs/python-sdk.md | 10 ++++-- docs/sim.md | 2 +- docs/so101.md | 11 +++---- docs/teleop.md | 3 ++ docs/workflow-cli.md | 5 +-- rfx/examples/README.md | 4 ++- rfx/python/rfx/__init__.py | 11 +++++++ 14 files changed, 96 insertions(+), 38 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cb05f11..88c2e89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 @@ -57,7 +57,6 @@ Recommended first-time local setup: ```bash bash scripts/setup-from-source.sh -./scripts/setup-git-hooks.sh ``` ## Repo Layout diff --git a/README.md b/README.md index bb67227..95451dc 100644 --- a/README.md +++ b/README.md @@ -214,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) diff --git a/cli/README.md b/cli/README.md index 165f085..2e79d75 100644 --- a/cli/README.md +++ b/cli/README.md @@ -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 --api-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 --api-key --robot-id --submit`: upload probe results back to the platform -- `cli/rfx.sh connect --url --api-key `: keep a registered robot online with periodic heartbeats -- `cli/rfx.sh pkg-create `: create a runtime package scaffold -- `cli/rfx.sh pkg-list`: list runtime packages -- `cli/rfx.sh run `: run a node -- `cli/rfx.sh launch `: 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 `. + +## 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 [--robot ...]` | Deploy a trained policy to hardware | +| `runs [...]` | Browse saved training runs | + +## Platform + +| Command | Description | +|---------|-------------| +| `register --url --api-key ` | Register robot with the platform | +| `probe [--regions ...]` | Measure candidate AWS region latency | +| `connect --url --api-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 | diff --git a/cli/rfx.sh b/cli/rfx.sh index a208ced..34e1f49 100755 --- a/cli/rfx.sh +++ b/cli/rfx.sh @@ -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() { diff --git a/docs/README.md b/docs/README.md index 5bdf18a..fddacef 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,7 @@ # 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` diff --git a/docs/go2.md b/docs/go2.md index 474b469..92dff6f 100644 --- a/docs/go2.md +++ b/docs/go2.md @@ -14,7 +14,7 @@ If you have a Unitree Go2 quadruped, this is the fastest path. rfx doctor ``` -Verify that the Rust extension (`rfx._rfx`) loads and your network can reach the Go2. +Verify that the Rust extension (`rfx._rfx`) loads and core dependencies are available. ## 2) Connect and observe @@ -83,6 +83,7 @@ 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 @@ -132,6 +133,8 @@ Place URDF assets under `rfx/assets/robots/go2/urdf/` first. See [Simulation Gui | 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`. diff --git a/docs/innate.md b/docs/innate.md index 5264a4b..24a012d 100644 --- a/docs/innate.md +++ b/docs/innate.md @@ -143,5 +143,5 @@ robot = RealRobot(my_config, robot_type="innate") - **`ImportError: zenoh`**: Install with `pip install eclipse-zenoh`. - **No state received**: Verify the bot is publishing to the expected topic. Check with `zenoh` CLI tools or set `logging.basicConfig(level=logging.DEBUG)`. -- **CDR parse errors**: Ensure the bot sends standard ROS 2 CDR-encoded `sensor_msgs/JointState`. The deserializer expects little-endian encoding with a 4-byte RTPS header. +- **CDR parse errors**: Ensure the bot sends standard ROS 2 CDR-encoded `sensor_msgs/JointState`. The deserializer expects little-endian encoding with a 4-byte CDR encapsulation header. - **Multi-machine**: Pass `zenoh_endpoint="tcp/:7447"` to connect through a Zenoh router. diff --git a/docs/python-sdk.md b/docs/python-sdk.md index d8de381..6b01b73 100644 --- a/docs/python-sdk.md +++ b/docs/python-sdk.md @@ -38,7 +38,7 @@ rfx.deploy("runs/my-policy", robot="so101") You can explore the entire rfx workflow on your laptop — no robot required. ```python -# Mock robot: zero deps, spring-damper physics +# Mock robot: no sim engine deps, spring-damper physics robot = rfx.MockRobot(state_dim=12, action_dim=6) obs = robot.observe() robot.act(torch.zeros(1, 64)) @@ -72,7 +72,7 @@ Built-in robots: ```python robot = rfx.SimRobot.from_config("so101.yaml", backend="genesis", viewer=True) -robot = rfx.MockRobot(state_dim=12, action_dim=6) # zero deps, for testing +robot = rfx.MockRobot(state_dim=12, action_dim=6) # no sim engine deps, for testing robot = rfx.RealRobot(rfx.SO101_CONFIG) # real hardware (SO-101) robot = rfx.RealRobot(rfx.GO2_CONFIG) # real hardware (Go2) robot = rfx.RealRobot(rfx.INNATE_CONFIG) # real hardware (Innate, Zenoh-native) @@ -182,11 +182,14 @@ rfx.push_policy("runs/go2-walk-v1", "rfx-community/go2-walk-v1") stats = rfx.deploy( "runs/my-policy", # path, hf:// URL, or .py file robot="so101", # robot type or YAML path + config=None, # YAML config path (overrides robot) port="/dev/ttyACM0", # optional hardware override rate_hz=50, # control frequency duration=30, # seconds (None = infinite) mock=False, # use MockRobot instead device="cpu", # torch device + warmup_s=0.5, # seconds to sleep after reset + verbose=True, # print status during deployment ) # stats contains timing info @@ -239,6 +242,9 @@ rfx/python/rfx/ ├── sim/ # Simulation backends (MuJoCo, Genesis, mock) ├── teleop/ # Teleoperation sessions, transport, recording ├── runtime/ # Lifecycle, CLI, health, runtime helpers +├── workflow/ # Quality gates, stage registry +├── utils/ # Padding, transforms, normalizers +├── nn.py # Policy definitions (MLP, ActorCritic, save/load) ├── hub.py # Model save/load/push (HuggingFace Hub) ├── session.py # Rate-controlled control loop ├── deploy.py # rfx.deploy() implementation diff --git a/docs/sim.md b/docs/sim.md index 7c76559..dccdc3b 100644 --- a/docs/sim.md +++ b/docs/sim.md @@ -68,7 +68,7 @@ uv run --python 3.13 rfx/examples/genesis_viewer.py \ If Genesis is not installed, rfx tries `uv pip install genesis-world`, falling back to `pip install genesis-world`. -Genesis requires CPython 3.13 (no 3.14 wheels yet). +Genesis requires CPython <= 3.13 (no 3.14 wheels yet). Opt in globally: diff --git a/docs/so101.md b/docs/so101.md index 37eb2b7..9ecd238 100644 --- a/docs/so101.md +++ b/docs/so101.md @@ -53,14 +53,14 @@ cli/rfx.sh so101-demo --port /dev/ttyACM0 Direct script invocation: ```bash -uv run --python 3.13 python rfx/examples/so101_quickstart.py --port auto +uv run --python 3.13 examples/so101_quickstart.py --port auto ``` This will: - connect to SO101 through the core robot primitive - reset to home -- run a gentle sinusoidal motion +- run a gentle extend motion (use `--motion wiggle` for sinusoidal) - return home on exit ## Bimanual setup (2 arms) @@ -122,10 +122,9 @@ robot.disconnect() Collect directly into a LeRobot dataset: ```bash -rfx collect \ +rfx record \ --repo-id your-org/so101-demos \ - --robot-type so101 \ + --robot so101 \ --episodes 5 \ - --duration 30 \ - --collection-root datasets + --duration 30 ``` diff --git a/docs/teleop.md b/docs/teleop.md index 8edc117..37d93a0 100644 --- a/docs/teleop.md +++ b/docs/teleop.md @@ -197,5 +197,8 @@ run( format="native", # export format: native, lerobot, mcap metadata=None, # extra metadata dict otel=False, # enable OpenTelemetry + otel_exporter="console", # OTEL exporter: console or otlp + otel_sample_every=100, # trace every N iterations + otlp_endpoint=None, # OTLP collector endpoint ) ``` diff --git a/docs/workflow-cli.md b/docs/workflow-cli.md index 1d4ebc3..d30f9c5 100644 --- a/docs/workflow-cli.md +++ b/docs/workflow-cli.md @@ -39,10 +39,12 @@ rfx record --robot go2 --repo-id demos --duration 20 --push | Flag | Default | Description | |------|---------|-------------| -| `--robot` | required | Robot type (`so101`, `go2`, `g1`, `innate`) | +| `--robot` | required | Robot type (`so101`, `go2`, `g1`) | | `--repo-id` | required | Dataset name or HuggingFace repo ID | +| `--output` / `-o` | `datasets` | Output root directory | | `--episodes` | `1` | Number of episodes to record | | `--duration` | interactive | Episode duration in seconds. Omit to stop with Ctrl+C. | +| `--task` | `default` | Task label for episodes | | `--fps` | `30` | Recording frame rate | | `--rate-hz` | `fps` | Sampling rate override for `robot.observe()` | | `--config` | none | Robot YAML config override | @@ -83,7 +85,6 @@ rfx deploy runs/my-policy --robot so101 --duration 60 --rate-hz 50 --port /dev/t | `--rate-hz` | auto | Control loop frequency (defaults to robot config) | | `--duration` | infinite | Run time in seconds. Ctrl+C to stop if not set. | | `--mock` | `false` | Use MockRobot instead of real hardware | -| `--device` | `cpu` | Torch device for inference | | `--warmup` | `0.5` | Seconds to sleep after reset before starting | Deploy handles: load weights, resolve robot config, connect hardware, run control loop with rate control and jitter tracking, clean shutdown on Ctrl+C. diff --git a/rfx/examples/README.md b/rfx/examples/README.md index 352c1c2..9e03fa1 100644 --- a/rfx/examples/README.md +++ b/rfx/examples/README.md @@ -4,12 +4,14 @@ Canonical scripts demonstrating the core rfx user workflows. ## Scripts -- **`so101_quickstart.py`** -- Connect to a real SO-101 and run a gentle movement smoke test - **`deploy_real.py`** -- Deploy a policy to real SO-101 hardware (or mock mode) - **`universal_go2.py`** -- Command-level Go2 control across `mock`/`genesis`/`mjx`/`real` - **`genesis_viewer.py`** -- Visual inspection and debugging in Genesis with a live viewer - **`train_vla.py`** -- End-to-end training loop in simulation with parallel environments - **`teleop_record.py`** -- Teleoperation data collection with optional LeRobot/MCAP export +- **`g1_teleop.py`** -- G1 humanoid VR teleoperation (or mock/no-VR mode) + +Hardware quickstarts live in the top-level `examples/` directory (e.g. `examples/so101_quickstart.py`). ## Running diff --git a/rfx/python/rfx/__init__.py b/rfx/python/rfx/__init__.py index 97a1308..3b51e2b 100644 --- a/rfx/python/rfx/__init__.py +++ b/rfx/python/rfx/__init__.py @@ -73,6 +73,12 @@ from .hub import LoadedPolicy, inspect_policy, load_policy, push_policy # noqa: E402 from .observation import ObservationSpec, make_observation, unpad_action # noqa: E402 from .robot import URDF, Robot, RobotBase, RobotConfig, load_config # noqa: E402 +from .robot.config import ( # noqa: E402 + G1_CONFIG, + GO2_CONFIG, + INNATE_CONFIG, + SO101_CONFIG, +) from .session import Session, SessionStats, run # noqa: E402 from .skills import Skill, SkillRegistry, skill # noqa: E402 @@ -133,6 +139,11 @@ "Skill", "SkillRegistry", "URDF", + # Built-in robot configs + "SO101_CONFIG", + "GO2_CONFIG", + "G1_CONFIG", + "INNATE_CONFIG", "deploy", "inspect_policy", "jit", From c478184f7e5dc79d1e6814d3dfa3803f71080f7d Mon Sep 17 00:00:00 2001 From: doctor Date: Tue, 31 Mar 2026 12:32:44 -0700 Subject: [PATCH 3/3] fix: ruff format on collection and runtime CLI modules --- rfx/python/rfx/collection/__init__.py | 10 +-- rfx/python/rfx/runtime/cli.py | 91 ++++++++++++++++++++------- 2 files changed, 72 insertions(+), 29 deletions(-) diff --git a/rfx/python/rfx/collection/__init__.py b/rfx/python/rfx/collection/__init__.py index 3fcb136..394fecb 100644 --- a/rfx/python/rfx/collection/__init__.py +++ b/rfx/python/rfx/collection/__init__.py @@ -178,8 +178,7 @@ def _extract_images( if len(resolved_names) < images.shape[0]: resolved_names.extend(f"cam{i}" for i in range(len(resolved_names), images.shape[0])) return { - resolved_names[i]: np.asarray(images[i], dtype=np.uint8) - for i in range(images.shape[0]) + resolved_names[i]: np.asarray(images[i], dtype=np.uint8) for i in range(images.shape[0]) } @@ -224,8 +223,7 @@ def _mock_action(iteration: int, robot_config: RobotConfig) -> Any: phase = iteration / max(float(robot_config.control_freq_hz), 1.0) values = [ - 0.25 * math.sin(phase + joint_idx * 0.2) - for joint_idx in range(robot_config.action_dim) + 0.25 * math.sin(phase + joint_idx * 0.2) for joint_idx in range(robot_config.action_dim) ] tensor = torch.zeros((1, robot_config.max_action_dim), dtype=torch.float32) tensor[0, : robot_config.action_dim] = torch.tensor(values, dtype=torch.float32) @@ -308,9 +306,7 @@ def collect( robot.reset() recorder.start_episode(task=task) frame_count = 0 - deadline = ( - time.perf_counter() + float(duration_s) if duration_s is not None else None - ) + deadline = time.perf_counter() + float(duration_s) if duration_s is not None else None interrupted = False while True: diff --git a/rfx/python/rfx/runtime/cli.py b/rfx/python/rfx/runtime/cli.py index b11852b..858e98b 100644 --- a/rfx/python/rfx/runtime/cli.py +++ b/rfx/python/rfx/runtime/cli.py @@ -88,6 +88,7 @@ def _print_inference_profile(profile: dict[str, float]) -> None: print(f"[rfx] action: {profile['action_latency_ms']:.1f} ms") print(f"[rfx] e2e total: {profile['end_to_end_latency_ms']:.1f} ms") + # --------------------------------------------------------------------------- # deploy # --------------------------------------------------------------------------- @@ -458,7 +459,9 @@ def _local_region_candidates(regions: list[str]) -> list[dict[str, Any]]: ] -def _register_robot_from_args(args: argparse.Namespace) -> tuple[str, dict[str, str], dict[str, Any]]: +def _register_robot_from_args( + args: argparse.Namespace, +) -> tuple[str, dict[str, str], dict[str, Any]]: from rfx.platform_client import ( register_robot, ) @@ -491,7 +494,9 @@ def _run_region_probe(args: argparse.Namespace, *, robot_id: str) -> int: if not candidates: print("[rfx] No probe candidates returned by the platform.") return 1 - print(f"[rfx] Probing {len(candidates)} AWS region candidates directly from this machine...") + print( + f"[rfx] Probing {len(candidates)} AWS region candidates directly from this machine..." + ) probe_results = _probe_region_candidates( candidates, samples=args.probe_samples, @@ -542,13 +547,15 @@ def cmd_probe(args: argparse.Namespace) -> int: regions = [item.strip() for item in args.regions.split(",") if item.strip()] if not regions: - regions = list(_DEFAULT_AWS_PROBE_REGIONS) + regions = list(_DEFAULT_AWS_PROBE_REGIONS) try: if args.url: candidates = fetch_region_candidates(url=args.url, api_key=args.api_key) if not candidates: - print("[rfx] Platform returned no probe candidates; falling back to built-in AWS regions.") + print( + "[rfx] Platform returned no probe candidates; falling back to built-in AWS regions." + ) candidates = _local_region_candidates(regions) else: candidates = _local_region_candidates(regions) @@ -691,7 +698,9 @@ def _probe_region_candidates( continue avg_ms = statistics.fmean(sample_values) best_ms = min(sample_values) - print(f"[rfx] {region:12s} avg={avg_ms:6.1f} ms best={best_ms:6.1f} ms host={host}:{port}") + print( + f"[rfx] {region:12s} avg={avg_ms:6.1f} ms best={best_ms:6.1f} ms host={host}:{port}" + ) results.append( { "region": region, @@ -702,7 +711,9 @@ def _probe_region_candidates( "best_latency_ms": best_ms, } ) - return sorted(results, key=lambda item: (float(item["avg_latency_ms"]), float(item["best_latency_ms"]))) + return sorted( + results, key=lambda item: (float(item["avg_latency_ms"]), float(item["best_latency_ms"])) + ) # --------------------------------------------------------------------------- @@ -831,15 +842,25 @@ def build_parser() -> argparse.ArgumentParser: # --- shared robot args --- def add_robot_args(parser: argparse.ArgumentParser) -> None: - parser.add_argument("--url", default=None, help="public dashboard URL, e.g. https://dashboard.example.com") + parser.add_argument( + "--url", default=None, help="public dashboard URL, e.g. https://dashboard.example.com" + ) parser.add_argument("--api-key", default=None, help="platform API key") - parser.add_argument("--robot-id", default=None, help="robot identifier (default: local hostname)") - parser.add_argument("--robot-kind", default="so101", help="robot type label, e.g. so101 or go2") + parser.add_argument( + "--robot-id", default=None, help="robot identifier (default: local hostname)" + ) + parser.add_argument( + "--robot-kind", default="so101", help="robot type label, e.g. so101 or go2" + ) parser.add_argument("--display-name", default=None, help="human-readable robot name") - parser.add_argument("--transport", default="sdk", help="transport label shown in the dashboard") + parser.add_argument( + "--transport", default="sdk", help="transport label shown in the dashboard" + ) parser.add_argument("--hostname", default=None, help="override reported hostname") parser.add_argument("--org-id", default="", help="optional org identifier") - parser.add_argument("--metadata", action="append", default=[], help="extra metadata in key=value form") + parser.add_argument( + "--metadata", action="append", default=[], help="extra metadata in key=value form" + ) # --- register --- s = sp.add_parser( @@ -857,12 +878,28 @@ def add_robot_args(parser: argparse.ArgumentParser) -> None: description="Measure candidate AWS region latency directly from the current machine. Submission to the platform is optional.", ) add_robot_args(s) - s.add_argument("--regions", default=",".join(_DEFAULT_AWS_PROBE_REGIONS), help="comma-separated AWS regions to probe when not fetching candidates from the platform") - s.add_argument("--inference", action="store_true", help="print a full latency profile for the best region after probing") - s.add_argument("--submit", action="store_true", help="submit probe results back to the platform") - s.add_argument("--register-if-missing", action="store_true", help="register the robot before probing") - s.add_argument("--probe-samples", type=int, default=3, help="number of TCP latency samples per region") - s.add_argument("--probe-timeout", type=float, default=2.5, help="per-sample TCP connect timeout in seconds") + s.add_argument( + "--regions", + default=",".join(_DEFAULT_AWS_PROBE_REGIONS), + help="comma-separated AWS regions to probe when not fetching candidates from the platform", + ) + s.add_argument( + "--inference", + action="store_true", + help="print a full latency profile for the best region after probing", + ) + s.add_argument( + "--submit", action="store_true", help="submit probe results back to the platform" + ) + s.add_argument( + "--register-if-missing", action="store_true", help="register the robot before probing" + ) + s.add_argument( + "--probe-samples", type=int, default=3, help="number of TCP latency samples per region" + ) + s.add_argument( + "--probe-timeout", type=float, default=2.5, help="per-sample TCP connect timeout in seconds" + ) s.set_defaults(fn=cmd_probe) # --- connect --- @@ -872,11 +909,21 @@ def add_robot_args(parser: argparse.ArgumentParser) -> None: description="Register a robot, refresh its region probe automatically, and send periodic heartbeats.", ) add_robot_args(s) - s.add_argument("--probe", action="store_true", help="deprecated; probing already runs by default") - s.add_argument("--skip-probe", action="store_true", help="skip the automatic region probe during connect") - s.add_argument("--probe-samples", type=int, default=3, help="number of TCP latency samples per region") - s.add_argument("--probe-timeout", type=float, default=2.5, help="per-sample TCP connect timeout in seconds") - s.add_argument("--heartbeat-interval", type=float, default=15.0, help="heartbeat interval in seconds") + s.add_argument( + "--probe", action="store_true", help="deprecated; probing already runs by default" + ) + s.add_argument( + "--skip-probe", action="store_true", help="skip the automatic region probe during connect" + ) + s.add_argument( + "--probe-samples", type=int, default=3, help="number of TCP latency samples per region" + ) + s.add_argument( + "--probe-timeout", type=float, default=2.5, help="per-sample TCP connect timeout in seconds" + ) + s.add_argument( + "--heartbeat-interval", type=float, default=15.0, help="heartbeat interval in seconds" + ) s.add_argument("--once", action="store_true", help="register once and exit without heartbeats") s.set_defaults(fn=cmd_connect)