From e64a5e8f6fc710bf1d2eb26dcab7a7cc16c63111 Mon Sep 17 00:00:00 2001 From: "-T.K.-" Date: Mon, 29 Jun 2026 18:46:39 -0700 Subject: [PATCH] docs: use the readable brand "Humanoid Control" in prose Brand noun humanoid_control -> "Humanoid Control" in narrative prose + the site title. Code identifiers (package names, humanoid_control:: namespace in examples, URLs) untouched: namespace 4->4, identifier refs 450->450. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 4 ++-- docs/concepts/architecture.md | 10 +++++----- docs/concepts/frozen_schemas.md | 2 +- docs/concepts/index.md | 2 +- docs/concepts/mit_command_surface.md | 2 +- docs/concepts/prime_hybrid_actuation.md | 2 +- docs/concepts/safety_pipeline.md | 2 +- docs/concepts/workspace_and_environment.md | 12 +++++------ docs/getting_started/installation.md | 16 +++++++-------- docs/getting_started/intro.md | 8 ++++---- docs/how_to/index.md | 2 +- docs/how_to/switch_controllers_manually.md | 2 +- .../talk_to_humanoid_control_from_python.md | 8 ++++---- docs/how_to/use_pixi_tasks.md | 10 +++++----- docs/reference/cli_tools.md | 20 +++++++++---------- docs/reference/controllers.md | 2 +- docs/reference/hardware_specs.md | 4 ++-- docs/reference/launch_args.md | 4 ++-- docs/reference/messages.md | 2 +- docs/reference/packages.md | 12 +++++------ docs/reference/quick_reference.md | 6 +++--- docs/reference/reference_map.md | 10 +++++----- docs/reference/topics_services.md | 4 ++-- docs/tutorials/run_gravity_compensation.md | 8 ++++---- docusaurus.config.ts | 10 +++++----- package.json | 2 +- src/pages/index.tsx | 2 +- 27 files changed, 84 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 74faea0..a200f6a 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md index 17bfa52..35d2745 100644 --- a/docs/concepts/architecture.md +++ b/docs/concepts/architecture.md @@ -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. @@ -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] diff --git a/docs/concepts/frozen_schemas.md b/docs/concepts/frozen_schemas.md index c1fa194..ab45eb4 100644 --- a/docs/concepts/frozen_schemas.md +++ b/docs/concepts/frozen_schemas.md @@ -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) diff --git a/docs/concepts/index.md b/docs/concepts/index.md index d747c61..178385a 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -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). diff --git a/docs/concepts/mit_command_surface.md b/docs/concepts/mit_command_surface.md index 4d808aa..f85822e 100644 --- a/docs/concepts/mit_command_surface.md +++ b/docs/concepts/mit_command_surface.md @@ -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 diff --git a/docs/concepts/prime_hybrid_actuation.md b/docs/concepts/prime_hybrid_actuation.md index 9fb5371..d35bea0 100644 --- a/docs/concepts/prime_hybrid_actuation.md +++ b/docs/concepts/prime_hybrid_actuation.md @@ -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 diff --git a/docs/concepts/safety_pipeline.md b/docs/concepts/safety_pipeline.md index 80c4495..a8bd564 100644 --- a/docs/concepts/safety_pipeline.md +++ b/docs/concepts/safety_pipeline.md @@ -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 diff --git a/docs/concepts/workspace_and_environment.md b/docs/concepts/workspace_and_environment.md index c7006da..e49699c 100644 --- a/docs/concepts/workspace_and_environment.md +++ b/docs/concepts/workspace_and_environment.md @@ -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** | @@ -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 @@ -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 @@ -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 @@ -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. @@ -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. diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md index 0f3ee3a..3e8cb02 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -1,6 +1,6 @@ # 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) @@ -8,7 +8,7 @@ There are two ways to get humanoid_control onto your machine: 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` @@ -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 | @@ -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. @@ -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. @@ -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 @@ -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 diff --git a/docs/getting_started/intro.md b/docs/getting_started/intro.md index 599d854..ca6b438 100644 --- a/docs/getting_started/intro.md +++ b/docs/getting_started/intro.md @@ -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 @@ -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 | |---|---| diff --git a/docs/how_to/index.md b/docs/how_to/index.md index f2a2a9e..7c8250a 100644 --- a/docs/how_to/index.md +++ b/docs/how_to/index.md @@ -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`. | diff --git a/docs/how_to/switch_controllers_manually.md b/docs/how_to/switch_controllers_manually.md index 3de9012..e01b86d 100644 --- a/docs/how_to/switch_controllers_manually.md +++ b/docs/how_to/switch_controllers_manually.md @@ -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 diff --git a/docs/how_to/talk_to_humanoid_control_from_python.md b/docs/how_to/talk_to_humanoid_control_from_python.md index a136ad0..9821884 100755 --- a/docs/how_to/talk_to_humanoid_control_from_python.md +++ b/docs/how_to/talk_to_humanoid_control_from_python.md @@ -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. @@ -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); diff --git a/docs/how_to/use_pixi_tasks.md b/docs/how_to/use_pixi_tasks.md index da738a2..12d67b3 100644 --- a/docs/how_to/use_pixi_tasks.md +++ b/docs/how_to/use_pixi_tasks.md @@ -16,10 +16,10 @@ what each alias maps to, when to reach for it, and how to add your own. `pixi.toml` lives at the **workspace level** (`humanoid_control_ws/pixi.toml`), -*not* inside `humanoid_control` or `pianist_ros2`. That's intentional — the +*not* inside `Humanoid Control` or `pianist_ros2`. That's intentional — the file pins ROS 2 Jazzy, the colcon toolchain, every Python dep, and the activation script that auto-sources `install/setup.bash`. Those -are workspace concerns; both `humanoid_control` and `pianist_ros2` consume them. +are workspace concerns; both `Humanoid Control` and `pianist_ros2` consume them. :::tip[Why have aliases at all] A single `pixi run launch-mujoco` is shorter than @@ -41,12 +41,12 @@ explicit `pixi shell` first. | `pixi run build` | `colcon build --symlink-install --packages-skip-regex 'ethercat.*\|humanoid_bringup_prime'` | Build the Lite path (skips the EtherCAT-linked Prime lane that has no conda recipe). | | `pixi run build-all` | `colcon build --symlink-install` | Same, but includes `humanoid_bringup_prime` and `ethercat_driver_ros2`. Requires `libethercat` installed on the host. | | `pixi run build-pkg ` | `colcon build --symlink-install --packages-select ` | Targeted rebuild of one package — fastest edit-loop while iterating. | -| `pixi run test` | `colcon test --packages-skip-regex 'ethercat.*\|humanoid_bringup_prime\|mujoco_.*' --ctest-args -LE linter --event-handlers console_cohesion-` | Run humanoid_control-owned tests; skips the vendored `mujoco_*` packages and the CMake-registered linters (which RoboStack ships at newer versions than apt-jazzy, so they'd diverge from the industrial_ci-on-humanoid_control source of truth). | +| `pixi run test` | `colcon test --packages-skip-regex 'ethercat.*\|humanoid_bringup_prime\|mujoco_.*' --ctest-args -LE linter --event-handlers console_cohesion-` | Run humanoid_control-owned tests; skips the vendored `mujoco_*` packages and the CMake-registered linters (which RoboStack ships at newer versions than apt-jazzy, so they'd diverge from the industrial_ci-on-Humanoid Control source of truth). | | `pixi run test-lint` | Same as `test`, but keeps the linters. | Use when you specifically want to see uncrustify / cpplint output locally. | | `pixi run test-results` | `colcon test-result --verbose` | Print the per-package test summary after `pixi run test`. | | `pixi run clean` | `rm -rf build install log` | Wipe the colcon overlay (leaves the source tree and `.pixi/` env alone). Handy after a package rename. | -## Launch aliases — humanoid_control +## Launch aliases — Humanoid Control Each alias just wraps a `ros2 launch ` invocation; any extra arguments after the alias are forwarded unchanged. @@ -115,7 +115,7 @@ Then `pixi run my-thing` works immediately; no rebuild needed. If the alias should live next to the launch file conceptually (e.g. it's a piano-specific helper), the convention today is to -still register it at the workspace level — `humanoid_control` and +still register it at the workspace level — `Humanoid Control` and `pianist_ros2` are pure ROS 2 source trees and don't try to expose a workspace-shell-shortcut layer of their own. diff --git a/docs/reference/cli_tools.md b/docs/reference/cli_tools.md index a45e978..01d2d89 100644 --- a/docs/reference/cli_tools.md +++ b/docs/reference/cli_tools.md @@ -4,7 +4,7 @@ title: CLI tools # CLI tools -Standalone executables shipped by `humanoid_control`. The primary entry +Standalone executables shipped by `Humanoid Control`. The primary entry point is the unified `hc` CLI from `humanoid_control_cli` — `hc bus ping`, `hc bus discover`, `hc motor slider`, `hc viz rerun`, `hc viz viser`, `hc calibrate`. Every underlying executable is also @@ -22,15 +22,15 @@ These are normally driven by their launch files, but are reachable via | Executable | Package | Repo | What it does | |---|---|---|---| -| `hc` (unified CLI) | `humanoid_control_cli` | humanoid_control | Verb/noun entry point (`hc bus ping`, `hc bus discover`, `hc motor slider`, `hc viz rerun`, …). | -| `robstride_ping` | `humanoid_devices_robstride` | humanoid_control | Single-actuator probe (GetDeviceId / OperationStatus). Read-only. | -| `robstride_discover` | `humanoid_devices_robstride` | humanoid_control | Scan a CAN ID range, print every device that replies. Read-only. | -| `mit_slider_gui` | `humanoid_devices_robstride` | humanoid_control | Qt slider window publishing Float64MultiArray to a forward_command_controller. | -| `mode_manager` | `humanoid_controllers` | humanoid_control | The FSM orchestrator. Normally launched by bringup; sometimes useful to start manually. | -| `calibrate_robot` | `humanoid_bringup_lite` | humanoid_control | Sample (min, max) per joint; write `calibration.yaml` on Ctrl+C. | -| `rerun_viz` | `humanoid_bringup_lite` | humanoid_control | Native rerun viewer subscribed to `/robot_description` + `/lite/joint_states`. | -| `viser_viz` | `humanoid_bringup_lite` | humanoid_control | Browser viewer (default port 8080). Same subscriptions. | -| `prepare` | `humanoid_control_policy` | humanoid_control | Launch-time prep: resolve the ONNX (local / W&B), convert the LeRobot motion → `.mcap` bag, emit the `rl_policy_controller` overlay (used by `lite_policy.launch.py`). | +| `hc` (unified CLI) | `humanoid_control_cli` | Humanoid Control | Verb/noun entry point (`hc bus ping`, `hc bus discover`, `hc motor slider`, `hc viz rerun`, …). | +| `robstride_ping` | `humanoid_devices_robstride` | Humanoid Control | Single-actuator probe (GetDeviceId / OperationStatus). Read-only. | +| `robstride_discover` | `humanoid_devices_robstride` | Humanoid Control | Scan a CAN ID range, print every device that replies. Read-only. | +| `mit_slider_gui` | `humanoid_devices_robstride` | Humanoid Control | Qt slider window publishing Float64MultiArray to a forward_command_controller. | +| `mode_manager` | `humanoid_controllers` | Humanoid Control | The FSM orchestrator. Normally launched by bringup; sometimes useful to start manually. | +| `calibrate_robot` | `humanoid_bringup_lite` | Humanoid Control | Sample (min, max) per joint; write `calibration.yaml` on Ctrl+C. | +| `rerun_viz` | `humanoid_bringup_lite` | Humanoid Control | Native rerun viewer subscribed to `/robot_description` + `/lite/joint_states`. | +| `viser_viz` | `humanoid_bringup_lite` | Humanoid Control | Browser viewer (default port 8080). Same subscriptions. | +| `prepare` | `humanoid_control_policy` | Humanoid Control | Launch-time prep: resolve the ONNX (local / W&B), convert the LeRobot motion → `.mcap` bag, emit the `rl_policy_controller` overlay (used by `lite_policy.launch.py`). | | `prepare` | `pianist_policy` | pianist_ros2 | Piano counterpart of `humanoid_control_policy prepare` (song → key-state `.mcap`; used by `piano_policy.launch.py`). | | `piano_state_bridge` | `pianist_policy` | pianist_ros2 | Sim-side bridge — JointState piano keys → `std_msgs/Float32MultiArray` on `/piano/key_state`. | | `midi_keyboard_driver` | `pianist_policy` | pianist_ros2 | USB-MIDI input → `/piano/key_state` (`std_msgs/Float32MultiArray`, real-piano counterpart of the sim bridge). | diff --git a/docs/reference/controllers.md b/docs/reference/controllers.md index 0dc3b9d..b0cc118 100644 --- a/docs/reference/controllers.md +++ b/docs/reference/controllers.md @@ -150,7 +150,7 @@ deliberative, and tolerant of the DDS-hop latency. A producer depends on `lite_sdk2` (the `humanoid_control_msgs` types generated by [`humanoid_control_msgs_dds`](packages.md#humanoid_control_msgs_dds) plus the DDS channel layer) rather than hand-writing message mirrors — see -[Talk to humanoid_control from Python](../how_to/talk_to_humanoid_control_from_python.md). See +[Talk to Humanoid Control from Python](../how_to/talk_to_humanoid_control_from_python.md). See [Policy runner](policy_runner.md) for how the in-process learned-policy path relates. diff --git a/docs/reference/hardware_specs.md b/docs/reference/hardware_specs.md index 540d338..10d6077 100644 --- a/docs/reference/hardware_specs.md +++ b/docs/reference/hardware_specs.md @@ -85,7 +85,7 @@ the `lite_description` repo and flows back through `bar.repos`: 1. In the `lite_description` repo, edit the joint's `torque_limit` (N·m, float) and / or `current_limit` (A, float) in `robots/lite_dummy/cad/ros2_control.json`. 2. Regenerate the xacro: `uv run robot-assets-generate lite_dummy --only xacro`. -3. Commit + push; bump the `lite_description` pin in `humanoid_control`'s `bar.repos` +3. Commit + push; bump the `lite_description` pin in `Humanoid Control`'s `bar.repos` (keep the buildfarm's in sync). 4. Re-import, rebuild, and re-launch: @@ -117,7 +117,7 @@ lives in `humanoid_bringup_lite/config/calibration.yaml`), torque and current caps are per-robot-tuning — same value on every Lite physical instance, versioned alongside the URDF. If you want to A/B-test caps across deployments without editing source, set up two checked-out branches of -`humanoid_control` and switch between them rather than splitting the source of +`Humanoid Control` and switch between them rather than splitting the source of truth. **Setting to 0 disables the firmware write.** The plugin treats diff --git a/docs/reference/launch_args.md b/docs/reference/launch_args.md index efc47f1..c7f324e 100644 --- a/docs/reference/launch_args.md +++ b/docs/reference/launch_args.md @@ -1,6 +1,6 @@ # Launch args -Every humanoid_control bringup follows the same vocabulary. Each robot ships **two +Every Humanoid Control bringup follows the same vocabulary. Each robot ships **two parallel launches** — `real.launch.py` for silicon, `mujoco.launch.py` for MuJoCo physics. Operators pick the *launch file* rather than flipping a `use_fake_hardware` flag on a single one. The xacro still accepts @@ -9,7 +9,7 @@ bundled launch enables that path. Launches live in two repos: -- `humanoid_control` ships the Lite + Prime control-plane bringups (`humanoid_bringup_lite`, +- `Humanoid Control` ships the Lite + Prime control-plane bringups (`humanoid_bringup_lite`, `humanoid_bringup_prime`), the URDF inspector (`humanoid_bringup_lite`), and the policy prepare-and-load launches (`humanoid_control_policy`). - `pianist_ros2` ships piano-task-specific launches: scene composition diff --git a/docs/reference/messages.md b/docs/reference/messages.md index b96f914..f8f369f 100644 --- a/docs/reference/messages.md +++ b/docs/reference/messages.md @@ -10,7 +10,7 @@ which keeps `humanoid_controllers` free of any `pianist_msgs` dependency. Tier-3 (non-`rclpy`) clients get these types from [`humanoid_control_msgs_dds`](packages.md#humanoid_control_msgs_dds) — generated from the same `.msg` and wire-compatible — usually via the `lite_sdk2` SDK. 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). ::: ## Topology diff --git a/docs/reference/packages.md b/docs/reference/packages.md index 2ee929c..e8a5a98 100644 --- a/docs/reference/packages.md +++ b/docs/reference/packages.md @@ -11,11 +11,11 @@ cloned side-by-side under `humanoid_control_ws/src/`: task-specific code. - **[`T-K-233/pianist_ros2`](https://github.com/T-K-233/pianist_ros2)** — 4 packages implementing the **piano playing** task on top of - `humanoid_control`: piano MJCF assets, a scene-composition launch, the + `Humanoid Control`: piano MJCF assets, a scene-composition launch, the piano-specific messages, and a `pianist_policy` package shipping the piano `prepare` tool + live key-state nodes. -The split is deliberate. `humanoid_control` is robot/control infrastructure +The split is deliberate. `Humanoid Control` is robot/control infrastructure that every task reuses; `pianist_ros2` is the first concrete task following the pattern. New task families (locomotion-task, dexterous grasping, etc.) follow the same shape — a sibling repo depending on @@ -28,7 +28,7 @@ The rest of this page walks each package in turn. The [`pianist_ros2` packages](#task-specific-packages-live-in-sibling-repos) get their own section near the bottom. -## Per-package details (humanoid_control) +## Per-package details (Humanoid Control) ### `humanoid_control_common` @@ -73,12 +73,12 @@ wire conventions only** — no participant/transport. | Generated types | `MITCommand`, `ControlMode`, `SafetyStatus`, `StandbyState` + borrowed `std_msgs/Header`, `builtin_interfaces/Time`, `sensor_msgs/JointState` | The `lite_sdk2` SDK builds its publisher/subscriber layer on top. 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). ### `lite_description` / `prime_description` (external) URDF / xacro / meshes / `` blocks. **Lite's description is no longer -in `humanoid_control`** — it lives in the external, CAD-generated +in `Humanoid Control`** — it lives in the external, CAD-generated [`lite_description`](https://github.com/Berkeley-Humanoids/Lite-Description) repo (bar deploys the `lite_dummy` variant), pulled in via `bar.repos`. It is **asset-only**: the RViz inspector (`view_lite.launch.py` + `view_lite.rviz`) now @@ -232,7 +232,7 @@ the `prepare` CLI args, and the dataset-resolution order. ### Task-specific packages live in sibling repos -`humanoid_control` deliberately does not carry task-specific code. The piano +`Humanoid Control` deliberately does not carry task-specific code. The piano playing task lives in [**`T-K-233/pianist_ros2`**](https://github.com/T-K-233/pianist_ros2), cloned side-by-side under `humanoid_control_ws/src/`: diff --git a/docs/reference/quick_reference.md b/docs/reference/quick_reference.md index 2ee04d8..27a6bbb 100644 --- a/docs/reference/quick_reference.md +++ b/docs/reference/quick_reference.md @@ -11,7 +11,7 @@ parameters. The cheat sheet you print or pin to a second monitor. Every link points at the page with the full details. All commands below assume you've entered the workspace env (e.g. -`cd humanoid_control_ws && pixi shell`) so `ros2`, `colcon`, and the humanoid_control console +`cd humanoid_control_ws && pixi shell`) so `ros2`, `colcon`, and the Humanoid Control console scripts are on `PATH`. Looking for one-line aliases (`pixi run launch-mujoco`, `pixi run build`, …)? See [How-to → Workspace shortcuts with pixi](../how_to/use_pixi_tasks.md). @@ -22,7 +22,7 @@ Grouped by which machine they run on. See [Concepts → Architecture → Deployment topology](../concepts/architecture.md#deployment-topology) for the split rationale. Launches come from two repos: -- `humanoid_control` ships the Lite + Prime bringups (`humanoid_bringup_lite`, +- `Humanoid Control` ships the Lite + Prime bringups (`humanoid_bringup_lite`, `humanoid_bringup_prime`), the description viewer (`humanoid_bringup_lite`), and the policy prepare-and-load launch (`humanoid_control_policy`). - `pianist_ros2` ships the piano-task launches (`pianist_bringup` @@ -68,7 +68,7 @@ loaded on the robot below. ### Robot onboard computer (prepare + load a policy) ```bash -# Prepare + load the in-process tracking policy (humanoid_control → humanoid_control_policy): +# Prepare + load the in-process tracking policy (Humanoid Control → humanoid_control_policy): # runs `prepare` (ONNX → .mcap + overlay), then loads rl_policy_controller # inactive. START_LOCOMOTION (R1+A) activates it. ros2 launch humanoid_control_policy lite_policy.launch.py \ diff --git a/docs/reference/reference_map.md b/docs/reference/reference_map.md index 5722428..0e3b4be 100644 --- a/docs/reference/reference_map.md +++ b/docs/reference/reference_map.md @@ -1,9 +1,9 @@ # Reference map A survey of the open robot low-level control ecosystem we studied while -designing `humanoid_control`. It is **descriptive**, not prescriptive: each entry +designing `Humanoid Control`. It is **descriptive**, not prescriptive: each entry records *what the reference is* and *the role it played in our study*, so a -contributor can go read the primary source. Where `humanoid_control` made a +contributor can go read the primary source. Where `Humanoid Control` made a specific design choice, the rationale lives in the [Concepts](../concepts/index.md) pages — this page is the map, not the decision log. @@ -22,7 +22,7 @@ layering is remarkably consistent (see [Common layering](#common-layering-patter | ROS 2 — Quality of Service | [https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html) | History/depth/reliability/durability/deadline/liveliness — why control vs. logging traffic want different profiles. | | ROS 2 — Executors | [https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Executors.html](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Executors.html) | Callback scheduling and its interaction with control-loop timing and data freshness. | | ROS 2 — Real-time programming demo | [https://docs.ros.org/en/jazzy/Tutorials/Demos/Real-Time-Programming.html](https://docs.ros.org/en/jazzy/Tutorials/Demos/Real-Time-Programming.html) | The "what not to do in the RT path" list: page faults, dynamic allocation, blocking sync; `mlockall`, latency measurement. | -| ros2_control — Getting started | [https://control.ros.org/jazzy/doc/getting_started/getting_started.html](https://control.ros.org/jazzy/doc/getting_started/getting_started.html) | The core architecture `humanoid_control` is built on: controller manager, resource manager, controllers, hardware components. | +| ros2_control — Getting started | [https://control.ros.org/jazzy/doc/getting_started/getting_started.html](https://control.ros.org/jazzy/doc/getting_started/getting_started.html) | The core architecture `Humanoid Control` is built on: controller manager, resource manager, controllers, hardware components. | | ROS 2 code style | [https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html) · [REP-8](https://ros.org/reps/rep-0008.html) | The style floor for our C++ / Python packages. | ### ros2_control in one paragraph @@ -66,7 +66,7 @@ This is exactly the spine described in | instinct_onboard | [https://github.com/project-instinct/instinct_onboard](https://github.com/project-instinct/instinct_onboard) | Onboard inference (Unitree G1, Jetson Orin NX) with **ONNX Runtime CPU/GPU auto-dispatch** and MCAP logging — reference for our in-process ONNX path. | | legged_control template controller | [https://github.com/qiayuanl/legged_template_controller](https://github.com/qiayuanl/legged_template_controller) | Minimal legged-RL controller skeleton. | -These map onto `humanoid_control` as: the **training side** (BeyondMimic, +These map onto `Humanoid Control` as: the **training side** (BeyondMimic, `pianist-tracking-mj`) produces a self-describing ONNX; the **deployment side** runs it in-process in `RLPolicyController` (see [Tracking policy](../tutorials/tracking_policy.md) and @@ -99,7 +99,7 @@ Transport / bus DDS · SocketCAN · CANopen-like protocol · EtherCAT (SO Actuator / embedded motor firmware · drive state machine · encoder/current loop · safety · calibration ``` -`humanoid_control` lands its own packages on this stack as described in +`Humanoid Control` lands its own packages on this stack as described in [Architecture](../concepts/architecture.md) and the [Packages reference](./packages.md). diff --git a/docs/reference/topics_services.md b/docs/reference/topics_services.md index 89e0c02..dea268b 100644 --- a/docs/reference/topics_services.md +++ b/docs/reference/topics_services.md @@ -4,7 +4,7 @@ title: Topics & services # Topics & services -Index of the ROS topics and services that `humanoid_control` publishes, +Index of the ROS topics and services that `Humanoid Control` publishes, subscribes, or serves. Use this page to find "who publishes X" or "what topic carries Y". @@ -44,7 +44,7 @@ standard ROS infrastructure topics: - `/parameter_events`, `/rosout` - `~/get_parameters`, `~/set_parameters`, etc. (per node) -These are conventional ROS — not specific to `humanoid_control`. Mentioned +These are conventional ROS — not specific to `Humanoid Control`. Mentioned here so `ros2 topic list` output isn't confusing. ## Services diff --git a/docs/tutorials/run_gravity_compensation.md b/docs/tutorials/run_gravity_compensation.md index 9c1bc6f..624ff2a 100644 --- a/docs/tutorials/run_gravity_compensation.md +++ b/docs/tutorials/run_gravity_compensation.md @@ -14,7 +14,7 @@ gravity-compensation loop that reads joint states and publishes and the difference between the torque-mode and PD-mode gravity loops. This is the worked, end-to-end companion to -[How-to → Talk to humanoid_control from Python](../how_to/talk_to_humanoid_control_from_python.md): +[How-to → Talk to Humanoid Control from Python](../how_to/talk_to_humanoid_control_from_python.md): that page is the recipe, this is the lesson. ## Time + materials @@ -37,7 +37,7 @@ thing that touches the command interfaces; the external loop just feeds it `MITCommand`s: ``` - host-side process (pure pip, no rclpy) humanoid_control bringup (System 0, RT) + host-side process (pure pip, no rclpy) Humanoid Control bringup (System 0, RT) ┌───────────────────────────────┐ ┌──────────────────────────────┐ │ run_ros2_torque.py │ │ joint_state_broadcaster │ │ each tick @ COMMAND_HZ: │ rt/lite/ │ publishes /lite/joint_states│ @@ -86,7 +86,7 @@ the three rmw conventions — the `rt/` topic prefix, the `pkg::msg::dds_::Name_` type-name mangling, and RELIABLE/KEEP_LAST QoS — so `cyclonedds-python` pairs directly with `rmw_cyclonedds_cpp` *or* `rmw_fastrtps_cpp` on the bringup. See -[How-to → Talk to humanoid_control from Python](../how_to/talk_to_humanoid_control_from_python.md). +[How-to → Talk to Humanoid Control from Python](../how_to/talk_to_humanoid_control_from_python.md). ::: ## Step 2 — Bring up the stack @@ -203,7 +203,7 @@ Then Ctrl-C the runner, then the bringup launch. | Skill | Page where it's documented in detail | |---|---| -| The Tier-3 external-client (no-`rclpy`) DDS path | [How-to → Talk to humanoid_control from Python](../how_to/talk_to_humanoid_control_from_python.md) | +| The Tier-3 external-client (no-`rclpy`) DDS path | [How-to → Talk to Humanoid Control from Python](../how_to/talk_to_humanoid_control_from_python.md) | | `lite_sdk2` / `humanoid_control_msgs_dds` topic + QoS registry | [Reference → Packages](../reference/packages.md#humanoid_control_msgs_dds) | | The REMOTE mode + `start_remote` transition | [Concepts → Five-mode FSM](../concepts/five_mode_fsm.md) | | `RemotePolicyController` and the MIT command write | [Reference → Controllers](../reference/controllers.md) | diff --git a/docusaurus.config.ts b/docusaurus.config.ts index b998189..244d098 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -4,8 +4,8 @@ import type * as Preset from '@docusaurus/preset-classic'; // https://docusaurus.io/docs/api/docusaurus-config const config: Config = { - title: 'humanoid_control', - tagline: 'humanoid_control low-level control stack', + title: 'Humanoid Control', + tagline: 'Humanoid Control low-level control stack', favicon: 'img/logo.svg', // Production URL for GitHub Pages project site. @@ -50,9 +50,9 @@ const config: Config = { respectPrefersColorScheme: true, }, navbar: { - title: 'humanoid_control', + title: 'Humanoid Control', logo: { - alt: 'humanoid_control logo', + alt: 'Humanoid Control logo', src: 'img/logo.svg', }, items: [ @@ -100,7 +100,7 @@ const config: Config = { title: 'Project', items: [ { - label: 'humanoid_control on GitHub', + label: 'Humanoid Control on GitHub', href: 'https://github.com/Berkeley-Humanoids/humanoid_control', }, { diff --git a/package.json b/package.json index 5080f75..32763b8 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "humanoid-control-website", "version": "0.0.1", "private": true, - "description": "Documentation site for humanoid_control — the humanoid_control humanoid low-level control stack.", + "description": "Documentation site for Humanoid Control — the Humanoid Control humanoid low-level control stack.", "license": "BSD-3-Clause", "scripts": { "docusaurus": "docusaurus", diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 1a1f9ca..8092610 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -54,7 +54,7 @@ export default function Home(): ReactNode { return ( + description="Docs for Humanoid Control, the Humanoid Control humanoid low-level control stack.">