Skip to content
Merged
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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Humanoid-Control-Website

Documentation site for [`humanoid_control`](https://github.com/Berkeley-Humanoids/humanoid_control) — the
Berkeley Humanoids (humanoid_control) humanoid low-level control stack.
Documentation site for [`Humanoid Control`](https://github.com/Berkeley-Humanoids/humanoid_control) — the
Berkeley Humanoids (Humanoid Control) humanoid low-level control stack.

Built with [Docusaurus 3](https://docusaurus.io/) + `@docusaurus/theme-mermaid`
for source-controlled diagrams of the control flow, FSM, and package
Expand Down
10 changes: 5 additions & 5 deletions docs/concepts/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ raw CycloneDDS, no `rclpy`); next it is VLA / manipulation. Such a client
does not hand-write the message types: [`humanoid_control_msgs_dds`](../reference/packages.md#humanoid_control_msgs_dds)
generates wire-compatible `cyclonedds` types from `humanoid_control_msgs/msg/*.msg`, and
the `lite_sdk2` SDK wraps them in a publisher/subscriber layer — see
[Talk to humanoid_control from Python](../how_to/talk_to_humanoid_control_from_python.md).
[Talk to Humanoid Control from Python](../how_to/talk_to_humanoid_control_from_python.md).
These are System 1/2: slower, deliberative, and tolerant of the latency the
DDS hop adds.

Expand Down Expand Up @@ -253,15 +253,15 @@ that belongs on its side. Single-machine sim/dev paths
`humanoid_bringup_lite/calibrate.launch.py`) are unaffected — they
collapse both sides into one process tree.

Launches come from two sibling repos: `humanoid_control` ships every
Launches come from two sibling repos: `Humanoid Control` ships every
Lite/Prime control-plane and tracking-policy launch; `pianist_ros2`
ships the piano-task-specific launches.

| Side | Machine | Launch | What lives here |
|---|---|---|---|
| **Robot** | Onboard computer (RT kernel, wired tether) | `humanoid_bringup_lite/launch/real.launch.py` (humanoid_control) | `ros2_control_node`, `humanoid_devices_robstride` / `humanoid_devices_sito` hardware plugins, `joint_state_broadcaster`, the five FSM controllers (`zero_torque` / `damping` / `standby` / `rl_policy` / `remote_policy`), `mode_manager`, `joy_node`, `robot_state_publisher`, IMU driver |
| **Host** | Operator workstation | `humanoid_bringup_lite/launch/viz.launch.py` (humanoid_control) | `viser_viz` *or* `rerun_viz` (selected by `viewer:=`) |
| **Robot** | Onboard computer | `humanoid_control_policy/launch/lite_policy.launch.py` (humanoid_control) / `pianist_policy/launch/piano_policy.launch.py` (pianist_ros2) | Runs `prepare` (resolve ONNX, convert motion → `.mcap` + overlay) then loads `rl_policy_controller` into the local CM. Inference is in-process, so the `.onnx` / `.mcap` artifacts **and** the W&B / HF Hub / `onnxruntime` *prepare-time* deps live here. The RT path itself pulls none of them. |
| **Robot** | Onboard computer (RT kernel, wired tether) | `humanoid_bringup_lite/launch/real.launch.py` (Humanoid Control) | `ros2_control_node`, `humanoid_devices_robstride` / `humanoid_devices_sito` hardware plugins, `joint_state_broadcaster`, the five FSM controllers (`zero_torque` / `damping` / `standby` / `rl_policy` / `remote_policy`), `mode_manager`, `joy_node`, `robot_state_publisher`, IMU driver |
| **Host** | Operator workstation | `humanoid_bringup_lite/launch/viz.launch.py` (Humanoid Control) | `viser_viz` *or* `rerun_viz` (selected by `viewer:=`) |
| **Robot** | Onboard computer | `humanoid_control_policy/launch/lite_policy.launch.py` (Humanoid Control) / `pianist_policy/launch/piano_policy.launch.py` (pianist_ros2) | Runs `prepare` (resolve ONNX, convert motion → `.mcap` + overlay) then loads `rl_policy_controller` into the local CM. Inference is in-process, so the `.onnx` / `.mcap` artifacts **and** the W&B / HF Hub / `onnxruntime` *prepare-time* deps live here. The RT path itself pulls none of them. |
| **Robot** | Onboard computer | `pianist_policy/launch/midi_keyboard_driver.launch.py` (pianist_ros2) | USB-MIDI keyboard driver → `/piano/key_state` (`std_msgs/Float32MultiArray`); feeds the on-robot controller's `key_pressed` extern term locally (loopback, does **not** cross the tether). |

:::tip[The deployment trade the in-process move makes]
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/frozen_schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Frozen schemas

# Frozen schemas

A few things in `humanoid_control` are described as **frozen**. This page
A few things in `Humanoid Control` are described as **frozen**. This page
explains which ones, why, and what to do when you want to change them.

![Frozen schemas and their consumers](/img/diagrams/concepts__frozen_schemas__01.svg)
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar_label: Overview

# Concepts

Background reading. These pages discuss the *design* of `humanoid_control` —
Background reading. These pages discuss the *design* of `Humanoid Control` —
the architecture, the conventions, the trade-offs that decided which
abstractions live where. Read these when you want to understand the
project well enough to extend it (or argue with it).
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/mit_command_surface.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: MIT command surface

# MIT command surface

Every joint in humanoid_control — Robstride, Sito, MujocoSystem, mock — exposes the
Every joint in Humanoid Control — Robstride, Sito, MujocoSystem, mock — exposes the
same **5 command interfaces** and **3 state interfaces**. This page
explains what those interfaces mean, how they combine into a single
torque, and why the same convention is used across silicon and
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/prime_hybrid_actuation.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Prime hybrid actuation

# Prime hybrid actuation

humanoid_control Prime is the bimanual humanoid. The **waist is dropped** this version
Humanoid Control Prime is the bimanual humanoid. The **waist is dropped** this version
(rigid torso, no waist drives), leaving **14 actuated DoF** — 7 per arm.
What makes Prime different from Lite is that those 14 joints live on **two
different buses, driven by two different actuator families**, yet present a
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/safety_pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Safety pipeline

# Safety pipeline

`humanoid_control`'s safety layer is **layered** rather than concentrated.
`Humanoid Control`'s safety layer is **layered** rather than concentrated.
Three subsystems each enforce one piece of the contract; together
they make sure that "the robot is in DAMPING within a tick of a
fault" is the worst case, never "the robot is doing something
Expand Down
12 changes: 6 additions & 6 deletions docs/concepts/workspace_and_environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ it into one environment and one repository creates dependency conflicts
(CUDA versions, PyTorch wheels vs. the ROS conda packages), build-system
mismatches (colcon vs. uv), and release-cadence mismatches.

`humanoid_control` separates code by **what it needs to talk to**, not by language
`Humanoid Control` separates code by **what it needs to talk to**, not by language
or topic:

| | **Tier 1 — ROS native** | **Tier 2 — workspace tooling** | **Tier 3 — separate project** |
Expand All @@ -39,7 +39,7 @@ follows: a process with no ROS deps participating in the robot's DDS
network.

The catch with "just speak DDS directly" is usually that you have to
hand-mirror the message types, and they drift. `humanoid_control` avoids that by
hand-mirror the message types, and they drift. `Humanoid Control` avoids that by
**generating** them:

- [`humanoid_control_msgs_dds`](../reference/packages.md) generates wire-compatible
Expand Down Expand Up @@ -121,7 +121,7 @@ The repository layout is a deliberate split:
environment and tooling — `pixi.toml`, `pixi.lock`, `.gitattributes`
(which marks `pixi.lock` as generated), `canup.sh`, and the task
definitions — and **gitignores all of `src/`** (keeping a `.gitkeep`).
- **First-party code lives in the `humanoid_control` monorepo.** All the `humanoid_control_*`
- **First-party code lives in the `Humanoid Control` monorepo.** All the `humanoid_control_*`
packages are co-developed and released together, so they share one repo
(its own git history) checked out under `src/humanoid_control/`, rather than the
strict `ros2/ros2` one-repo-per-package convention. The piano task is
Expand All @@ -132,7 +132,7 @@ The repository layout is a deliberate split:
`src/`. Pin to commit SHAs for releases.

This keeps the *environment* history (`humanoid_control_ws` / `pixi.lock`) on a separate
track from the *code* history (`humanoid_control`), while still letting `humanoid_control`
track from the *code* history (`Humanoid Control`), while still letting `Humanoid Control`
be tagged and reused on its own.

### The reproducibility chain
Expand All @@ -147,7 +147,7 @@ pixi run setup # vcs import third-party deps into src/
pixi run build # colcon build
```

`pixi.lock` pins the environment; the `humanoid_control` / `pianist_ros2`
`pixi.lock` pins the environment; the `Humanoid Control` / `pianist_ros2`
checkouts pin the first-party tree; `bar.repos` pins the third-party tree.
Together they reproduce the workspace bit-for-bit.

Expand All @@ -157,6 +157,6 @@ Together they reproduce the workspace bit-for-bit.
setup.
- [Workspace shortcuts with pixi](../how_to/use_pixi_tasks.md) — what each
`pixi run …` alias does.
- [Talk to humanoid_control from Python](../how_to/talk_to_humanoid_control_from_python.md)
- [Talk to Humanoid Control from Python](../how_to/talk_to_humanoid_control_from_python.md)
— building a Tier-3 client over DDS.
- [Packages reference](../reference/packages.md) — what each package ships.
16 changes: 8 additions & 8 deletions docs/getting_started/installation.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Installation

There are two ways to get humanoid_control onto your machine:
There are two ways to get Humanoid Control onto your machine:

- **Install the prebuilt packages (recommended)** — pull the `ros-jazzy-humanoid-control-*`
conda packages straight from the [`berkeley-humanoids`](https://prefix.dev/channels/berkeley-humanoids)
channel. No clone, no `colcon`, no compiler — ~2 minutes. Best for running the
control stack, deploying to a robot or Jetson, or building your own packages on
top of `humanoid_control_msgs` / `humanoid_controllers`.
- **Build from source** — clone the repos into a pixi workspace and `colcon
build`. For contributors who modify `humanoid_control`, and for the parts not yet in
build`. For contributors who modify `Humanoid Control`, and for the parts not yet in
the channel (MuJoCo sim, the piano task, EtherCAT / Prime).

Both use [pixi](https://pixi.sh); neither needs a system-wide `ros-jazzy-desktop`
Expand All @@ -19,7 +19,7 @@ every developer machine and on the Jetson.

| Item | Required | Reason |
|---|---|---|
| 64-bit Linux | yes | humanoid_control targets `linux-64` / `linux-aarch64`. macOS and Windows are not supported (SocketCAN + PREEMPT_RT are Linux-only). |
| 64-bit Linux | yes | Humanoid Control targets `linux-64` / `linux-aarch64`. macOS and Windows are not supported (SocketCAN + PREEMPT_RT are Linux-only). |
| pixi ≥ 0.30 | yes | manages every other dependency |
| Display server | for sim | `mujoco_sim` opens a GLFW window (source build only, today) |
| PREEMPT_RT kernel | recommended | hard real-time guarantees on real hardware |
Expand Down Expand Up @@ -51,7 +51,7 @@ shell rc. Restart your shell (or `source ~/.bashrc`) so `pixi` resolves.

## Install the prebuilt packages (recommended)

The humanoid_control packages are published as conda packages on the
The Humanoid Control packages are published as conda packages on the
[`berkeley-humanoids`](https://prefix.dev/channels/berkeley-humanoids) channel and rebuilt by
the buildfarm on every release. You consume them like any other dependency.

Expand Down Expand Up @@ -146,7 +146,7 @@ pixi add --pypi rerun-sdk viser yourdfpy "scipy>=1.13"

## Build from source

For contributors who modify `humanoid_control`, or to get the packages not yet in the
For contributors who modify `Humanoid Control`, or to get the packages not yet in the
channel (MuJoCo sim, piano task, EtherCAT / Prime). This builds everything with
`colcon` inside the same pixi-managed environment.

Expand Down Expand Up @@ -212,7 +212,7 @@ colcon build --symlink-install --packages-skip-regex 'ethercat.*|humanoid_bringu

`pixi shell` sources the conda env and `humanoid_control_ws/install/setup.bash` once it
exists, so `ros2`, `colcon`, and every console script land on `PATH`. The build
covers the Lite path (every humanoid_control + Pianist package plus the three `mujoco_*`
covers the Lite path (every Humanoid Control + Pianist package plus the three `mujoco_*`
deps). `--symlink-install` means edits to launch / config / Python files are
picked up without rebuilding. After the first successful build the install
overlay is on `AMENT_PREFIX_PATH` automatically — pixi's `[activation]` block
Expand All @@ -221,13 +221,13 @@ re-sources `install/setup.bash` whenever you enter `pixi shell`.
### 5. Sanity-check

```sh
ros2 pkg list | grep '^humanoid_control_' # 12 entries from humanoid_control
ros2 pkg list | grep '^humanoid_control_' # 12 entries from Humanoid Control
ros2 pkg list | grep '^pianist_' # 4 entries from pianist_ros2
ros2 control list_hardware_interfaces 2>/dev/null \
|| echo "(no controller_manager running yet — expected)"
```

The 11 `humanoid_control` packages (Lite's `lite_description` comes separately, via `bar.repos`):
The 11 `Humanoid Control` packages (Lite's `lite_description` comes separately, via `bar.repos`):

```
humanoid_bringup_lite
Expand Down
8 changes: 4 additions & 4 deletions docs/getting_started/intro.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Introduction

`humanoid_control` is the unified low-level control stack for the **Berkeley Architecture
Research (humanoid_control)** humanoid robots. It runs on **ROS 2 Jazzy under PREEMPT_RT**
`Humanoid Control` is the unified low-level control stack for the **Berkeley Architecture
Research (Humanoid Control)** humanoid robots. It runs on **ROS 2 Jazzy under PREEMPT_RT**
(shipped via the [RoboStack](https://robostack.github.io) conda channel and
pixi, no system-wide ROS install required) and targets two robots with **as
much shared code as possible**.

Task-specific packages (piano playing, etc.) ship from sibling repos
that depend on `humanoid_control` — see [Packages reference](../reference/packages.md)
that depend on `Humanoid Control` — see [Packages reference](../reference/packages.md)
for the split. Throughout the rest of the docs, runtime commands are
shown in canonical `ros2 launch …` / `ros2 run …` form; if you prefer
shorter aliases, the workspace also ships a `pixi run …` shortcut
Expand Down Expand Up @@ -35,7 +35,7 @@ hardware-by-hardware axis: separate plugins for each actuator family, separate
launch files per task, separate observation pipelines for sim vs. silicon. The
result is N × M code paths, where N is robots and M is tasks.

`humanoid_control` factors the axes orthogonally:
`Humanoid Control` factors the axes orthogonally:

| Axis | Where the variation lives |
|---|---|
Expand Down
2 changes: 1 addition & 1 deletion docs/how_to/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,5 +40,5 @@ and now have a concrete task in mind. How-tos skip the pedagogy that
| Guide | Use it when |
|---|---|
| [Run and extend an in-process policy](./promote_python_to_cpp.md) | You have a trained `.onnx` and want to ship it via the launch-time `prepare` step into the in-process C++ `RLPolicyController` (System 0) — or you need to add a new observation term or task. |
| [Talk to humanoid_control from Python](./talk_to_humanoid_control_from_python.md) | You want a host-side Python process (gravity-comp, VLA, data tool) to publish/subscribe `humanoid_control_msgs` over DDS with no `rclpy` — via `lite_sdk2` + the generated `humanoid_control_msgs_dds` types. |
| [Talk to Humanoid Control from Python](./talk_to_humanoid_control_from_python.md) | You want a host-side Python process (gravity-comp, VLA, data tool) to publish/subscribe `humanoid_control_msgs` over DDS with no `rclpy` — via `lite_sdk2` + the generated `humanoid_control_msgs_dds` types. |
| [Add a new joint to the URDF](./add_new_joint.md) | A new actuator goes on the robot. You need to wire it into the URDF, controllers YAML, and `calibration.yaml`. |
2 changes: 1 addition & 1 deletion docs/how_to/switch_controllers_manually.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ tests, or just verifying the underlying controller_manager service.
This how-to walks the mode FSM via direct `ros2 control` calls.

:::note[No gamepad? This is your mode-switch path.]
humanoid_control ships **no keyboard control** for the FSM — `mode_manager` reacts to a
Humanoid Control ships **no keyboard control** for the FSM — `mode_manager` reacts to a
gamepad (`/joy`) only. On a dev or headless host without one, the
`ros2 control` calls on this page **are** the supported way to drive modes
by hand. (There used to be a planned `termios` keyboard reader; it was
Expand Down
8 changes: 4 additions & 4 deletions docs/how_to/talk_to_humanoid_control_from_python.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: Talk to humanoid_control from Python
title: Talk to Humanoid Control from Python
---

# Talk to humanoid_control from Python
# Talk to Humanoid Control from Python

You have a host-side Python process — a gravity-comp runner, a VLA / manipulation
policy, a data tool — that needs to exchange messages with a running `humanoid_control`
policy, a data tool — that needs to exchange messages with a running `Humanoid Control`
bringup, but you **don't** want `rclpy`, a colcon overlay, or
`--system-site-packages` in that environment. This is the **Tier-3** path: a
pure-pip process that joins the same DDS network the ROS nodes use.
Expand Down Expand Up @@ -101,7 +101,7 @@ lite-sdk2-control enp2s0 disable # zero-torque burst, then exit

## Changing a message

Messages live in `humanoid_control`, not in the SDK. Edit `humanoid_control_msgs/msg/*.msg`, run
Messages live in `Humanoid Control`, not in the SDK. Edit `humanoid_control_msgs/msg/*.msg`, run
`pixi run gen-dds` to regenerate `humanoid_control_msgs_dds`, and the new/changed type flows
through `lite_sdk2` automatically — there is no schema to mirror by hand. This is
a [frozen-schema change](../concepts/frozen_schemas.md#how-to-change-a-frozen-schema);
Expand Down
Loading
Loading