diff --git a/docs/concepts/workspace_and_environment.md b/docs/concepts/workspace_and_environment.md index e49699c..c7b84b1 100644 --- a/docs/concepts/workspace_and_environment.md +++ b/docs/concepts/workspace_and_environment.md @@ -22,8 +22,8 @@ or topic: | | **Tier 1 — ROS native** | **Tier 2 — workspace tooling** | **Tier 3 — separate project** | |---|---|---|---| -| Location | `src//` | per-package `scripts/`, the `hc` CLI, a future top-level `scripts/` | its own git repo, outside the workspace | -| Examples | `humanoid_controllers`, `humanoid_devices_robstride`, `humanoid_drivers_socketcan` | `robstride_probe`, calibration helpers, `hc bus ping` | `Lite-SDK2`, `Lite-Gravity-Compensation` | +| Location | `src//` | per-package `scripts/`, the workspace pixi tasks, a future top-level `scripts/` | its own git repo, outside the workspace | +| Examples | `humanoid_controllers`, `humanoid_devices_robstride`, `humanoid_drivers_socketcan` | `robstride_probe`, calibration helpers, `pixi run ping-bus` | `Lite-SDK2`, `Lite-Gravity-Compensation` | | Build / run | `colcon` + `ros2 run` | `pixi run …` | own toolchain (`uv run …`) | | Imports `rclpy`? | **yes** | no | **no** | | Talks to ROS via | native pub / sub / service / action | doesn't talk to running nodes | **DDS (CycloneDDS)** + file handoff | diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md index 75b991d..c547963 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -78,13 +78,11 @@ platforms = ["linux-64", "linux-aarch64"] # ROS 2 CLI + launch + runtime (ros2 launch / run / pkg). The bar packages # declare their library deps but not the CLI tooling, so pull a ROS base # yourself. Use ros-jazzy-desktop instead if you want the RViz-based -# viewers (`hc viz urdf`, `view_lite.launch.py`). +# viewers (`view_lite.launch.py`). ros-jazzy-ros-base = "*" # The whole Lite bringup: humanoid_controllers (ONNX-enabled), humanoid_control_msgs, # lite_description, humanoid_devices_robstride, humanoid_drivers_socketcan, humanoid_control_common, humanoid_control_policy. ros-jazzy-humanoid-control-bringup-lite = "*" -# Optional: the `hc` toolbox CLI — lands on PATH (hc viz / hc bus ping / ...). -ros-jazzy-humanoid-control-cli = "*" ``` `berkeley-humanoids` is listed **first** so `ros-jazzy-humanoid-control-*` resolves from there, with @@ -113,18 +111,22 @@ pixi run ros2 launch humanoid_bringup_lite real.launch.py RoboStack ROS core — no build step. Everything the packages ship (launch files, URDFs, meshes, controller YAMLs, console executables) lands on the ament index, so `ros2 launch …` / `ros2 run …` work inside `pixi shell` (or via -`pixi run …`). The `hc` toolbox CLI installs a `bin/` shim, so `hc` itself -is on `PATH` inside `pixi shell` (or via `pixi run -- hc …`). +`pixi run -- ros2 …`). ```sh pixi shell ros2 pkg list | grep '^humanoid_control_' # the humanoid_control_* packages you pulled in ros2 launch humanoid_bringup_lite real.launch.py --show-args # dry-parse the launch (no hardware) -hc bus discover --iface can0 --scan-to 32 # read-only CAN scan, e.g. +ros2 run humanoid_devices_robstride robstride_discover --iface can0 --scan-to 32 # read-only CAN scan, e.g. ``` +To get the standard one-word aliases (`pixi run scan-bus`, +`pixi run viz`, …) in your own project, copy the task reference block +from [How-to → Workspace commands](../how_to/use_pixi_tasks.md#the-reference-block) +into your `pixi.toml`. + :::note[What the channel ships today] -`berkeley-humanoids` carries the **11 `ros-jazzy-humanoid-control-*` packages** for both `linux-64` +`berkeley-humanoids` carries the **`ros-jazzy-humanoid-control-*` packages** for both `linux-64` and `linux-aarch64` (Jetson). That covers the full control stack and the real-hardware **Lite** bringup (`real.launch.py`). Not yet published: the MuJoCo simulation deps (`mujoco_*`), the piano task (`pianist_*`), and the EtherCAT / @@ -216,7 +218,7 @@ and the compile-commands export come from `config/colcon-defaults.yaml` via `COLCON_DEFAULTS_FILE`, so the manual invocation behaves identically.) `pixi shell` sources the conda env and (via `scripts/activate.sh`) the -`install/setup.sh` overlay once it exists, so `ros2`, `colcon`, `hc`, and every +`install/setup.sh` overlay 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_*` deps). `--symlink-install` means edits to launch / config / Python files are @@ -228,18 +230,17 @@ re-sources the overlay whenever you enter `pixi shell`. Then run ### 5. Sanity-check ```sh -ros2 pkg list | grep '^humanoid_control_' # 12 entries from Humanoid Control +ros2 pkg list | grep '^humanoid_control_' # the humanoid_control_* packages 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 `Humanoid Control` packages (Lite's `lite_description` comes separately, via `bar.repos`): ``` humanoid_bringup_lite humanoid_bringup_prime -humanoid_control_cli humanoid_control_common humanoid_controllers humanoid_devices_robstride diff --git a/docs/how_to/diagnose_enobufs.md b/docs/how_to/diagnose_enobufs.md index ed101d7..2aa65c5 100644 --- a/docs/how_to/diagnose_enobufs.md +++ b/docs/how_to/diagnose_enobufs.md @@ -52,12 +52,12 @@ each motor. ```bash # Quick read-only probe to confirm motors are responding -hc bus discover --iface can0 -hc bus discover --iface can1 +pixi run scan-bus --iface can0 +pixi run scan-bus --iface can1 # Should report 7 motors on each bus, no ENOBUFS warnings in the output. ``` -If `hc bus discover` itself reports `tx_dropped > 0`, motors are +If the scan itself reports `tx_dropped > 0`, motors are still off the bus. Don't proceed until that scan is clean. ## Step 2 — Check the kernel CAN state @@ -157,8 +157,8 @@ bottleneck. Either drop the rate or upgrade the adapter. ``` ENOBUFS warnings observed -├── hc bus discover reports 0 motors → motor power off → fix power, relaunch -├── hc bus discover reports motors but ENOBUFS persists at activation only +├── pixi run scan-bus reports 0 motors → motor power off → fix power, relaunch +├── pixi run scan-bus reports motors but ENOBUFS persists at activation only │ └── Burst-on-Enable. Drop activate-time WriteParameter calls (already done │ in our plugin via write_firmware_limits=false default). If recurring, │ raise txqueuelen or stagger Enables. diff --git a/docs/how_to/first_real_bringup.md b/docs/how_to/first_real_bringup.md index 1d20577..fc6db3f 100644 --- a/docs/how_to/first_real_bringup.md +++ b/docs/how_to/first_real_bringup.md @@ -46,15 +46,16 @@ acceptable; `BUS-OFF` means power-cycle the adapter.) ## Step 2 — Confirm motors are alive -A read-only scan before anything claims the bus: +A read-only scan before anything claims the bus (`scan-bus` is the +workspace task wrapping +`ros2 run humanoid_devices_robstride robstride_discover`): ```bash cd humanoid_control_ws -pixi shell -hc bus discover --iface can0 --scan-to 32 +pixi run scan-bus --iface can0 --scan-to 32 # Expect 7 actuators at ids 11..17 -hc bus discover --iface can1 --scan-to 32 +pixi run scan-bus --iface can1 --scan-to 32 # Expect 7 actuators at ids 21..27 ``` @@ -66,6 +67,7 @@ warnings**, the actuators aren't powered — see ## Step 3 — Launch the bringup ```bash +pixi shell # enter the workspace env so ros2 is on PATH ros2 launch humanoid_bringup_lite real.launch.py ``` diff --git a/docs/how_to/mit_slider_gui.md b/docs/how_to/mit_slider_gui.md index 533a511..6815f85 100644 --- a/docs/how_to/mit_slider_gui.md +++ b/docs/how_to/mit_slider_gui.md @@ -54,10 +54,13 @@ This brings up: - `zero_torque_controller` (active — safe default) - `forward_mit_controller` (loaded, **inactive**) -In a second terminal, open the slider GUI: +In a second terminal, open the slider GUI. It's a rarely-used tool, +so it has no pixi task — run the canonical executable (plain +`ros2 run …` inside a `pixi shell`, or via `pixi run --` from any +terminal): ```bash -hc motor slider +pixi run -- ros2 run humanoid_devices_robstride mit_slider_gui ``` A Qt window appears with five sliders (position, velocity, effort, diff --git a/docs/how_to/probe_can_bus.md b/docs/how_to/probe_can_bus.md index 424a9ea..95bac1b 100644 --- a/docs/how_to/probe_can_bus.md +++ b/docs/how_to/probe_can_bus.md @@ -39,11 +39,14 @@ and the bus is acking. `ERROR-WARNING` is transient and self-recovers; ## Scan all IDs on a bus +`scan-bus` is the workspace task wrapping +`ros2 run humanoid_devices_robstride robstride_discover`; trailing +args forward verbatim: + ```bash cd humanoid_control_ws -pixi shell -hc bus discover --iface can0 -hc bus discover --iface can1 +pixi run scan-bus --iface can0 +pixi run scan-bus --iface can1 ``` Default scan range: 1..32. Sends one `GetDeviceId` per ID with 8 ms @@ -68,11 +71,11 @@ on `can1` (right arm). ```bash # Default range is 1..32; widen if you suspect IDs outside that. -hc bus discover --iface can0 \ +pixi run scan-bus --iface can0 \ --scan-from 1 --scan-to 127 # Tighter scan (faster) if you only want to check specific IDs: -hc bus discover --iface can0 \ +pixi run scan-bus --iface can0 \ --scan-from 11 --scan-to 17 ``` @@ -81,7 +84,7 @@ hc bus discover --iface can0 \ If the bus is slow / cheap-USB-adapter, raise `--per-id-wait-ms`: ```bash -hc bus discover --iface can0 \ +pixi run scan-bus --iface can0 \ --per-id-wait-ms 20 ``` @@ -90,7 +93,7 @@ hc bus discover --iface can0 \ When you know the ID and want a deeper status check: ```bash -hc bus ping --iface can0 --id 11 +pixi run ping-bus --iface can0 --id 11 # TX GetDeviceId id=... # RX GetDeviceId reply device=11 uid=... # stats: rx=1 tx=1 rx_dropped=0 tx_failed=0 @@ -101,11 +104,11 @@ With `--read-status` the ping briefly Enables, prompts an responds with calibrated-looking values: ```bash -hc bus ping --iface can0 --id 11 --read-status +pixi run ping-bus --iface can0 --id 11 --read-status # RX OperationStatus device=11 pos= 4.9200 rad vel= 0.0 torque= 0.0 temp=24.0 C fault_bits=0x00 ``` -The `pos` value is **motor-frame, no calibration** (this CLI doesn't +The `pos` value is **motor-frame, no calibration** (the probe doesn't load `calibration.yaml`). It's the raw absolute-encoder reading. If it's plausibly in `[-4π, 4π]` and the motor reports temp around room temp with `fault_bits=0x00`, the motor is healthy. @@ -129,7 +132,7 @@ how you confirm `on_deactivate`'s Disable made it through. ## Common findings -| `hc bus discover` reports | Likely cause | +| `pixi run scan-bus` reports | Likely cause | |---|---| | `found : 0 actuator(s)` | Bus down, adapter unplugged, or motors not powered. Check `ip -d link` and the bench power. | | `found : N < expected` | Some motors are off the bus. Trace the daisy-chain — usually a connector. | diff --git a/docs/how_to/recover_from_fault.md b/docs/how_to/recover_from_fault.md index 98812eb..af5ab45 100644 --- a/docs/how_to/recover_from_fault.md +++ b/docs/how_to/recover_from_fault.md @@ -60,7 +60,7 @@ from. **Recovery**: 1. Confirm motors are powered: - `hc bus discover --iface canN` + `pixi run scan-bus --iface canN` 2. Confirm wiring — wiggle the daisy chain connector at each motor. 3. Restart the launch. `RX_TIMEOUT` clears on `on_activate` so a relaunch is sufficient; no power-cycle needed. @@ -90,7 +90,7 @@ generic flag. every joint. 2. If the fault persists, single-step diagnosis: ```bash - hc bus ping --iface canN --id --read-status + pixi run ping-bus --iface canN --id --read-status ``` The reply's `fault_bits` byte tells you which specific sub-cause: - `bit 0` = overtemperature (also raised as `FLAG_TEMPERATURE_LIMIT`) diff --git a/docs/how_to/use_pixi_tasks.md b/docs/how_to/use_pixi_tasks.md index f21425a..720de10 100644 --- a/docs/how_to/use_pixi_tasks.md +++ b/docs/how_to/use_pixi_tasks.md @@ -1,26 +1,35 @@ --- id: use_pixi_tasks -title: Workspace commands (pixi tasks + hc) -sidebar_label: Workspace commands (pixi + hc) +title: Workspace commands (pixi tasks) +sidebar_label: Workspace commands (pixi tasks) --- -# Workspace commands (pixi tasks + hc) +# Workspace commands (pixi tasks) The rest of this site documents commands in canonical `ros2 launch …` / `ros2 run …` form. Those work everywhere — Jetson, workstation, CI. On top of that, every Humanoid Control workspace exposes the same -standardized command interface, organized in **three levels**: +standardized command interface, organized in **two levels**: | Level | Commands | What it is | |---|---|---| | **1 — lifecycle tasks** | `setup` `build` `test` `clean` `doctor` | pixi tasks with reserved names *and* meanings — identical in every workspace | -| **2 — product toolbox** | `hc bus` / `hc motor` / `hc viz` / `hc calibrate` | a packaged CLI on `PATH` — ships with the code, identical everywhere the stack is installed | -| **3 — scenario tasks** | `sim` `real` `policy` (+ variants) | pixi tasks with reserved *names* — each workspace defines their scope | +| **2 — workspace tasks** | `sim` `real` `policy` `deploy-sim` `deploy-real` `viz` `calibrate` + utility tasks (`ping-bus`, `scan-bus`, …) | pixi tasks with reserved names — each workspace declares the ones that apply to its stack | Discovery is built in: bare `pixi run` (or `pixi task list`) prints the -workspace's task menu with descriptions, and bare `hc` prints the -toolbox menu. This page explains each level and how to extend them. +workspace's task menu with descriptions. This page explains each level +and how to extend them. + +:::note[What happened to the `hc` CLI] +Rev 1 of this interface had a third level: a packaged `hc` CLI (the +`humanoid_control_cli` package) carrying diagnostics, viewers, and +calibration verbs. Rev 2 retired it — the package is deleted, and its +verbs became workspace tasks (`hc bus ping` → `pixi run ping-bus`, +`hc viz` → `pixi run viz`, …) or plain documented `ros2 run` commands. +The full mapping is in +[Reference → Diagnostics and utility commands](../reference/cli_tools.md). +::: :::tip[Why this layer exists] `pixi run build` is shorter than the colcon invocation it wraps, but the @@ -42,9 +51,10 @@ pixi run doctor # verifies the result; prints what to fix if unhealthy chains the `setup` task, which is idempotent and **cached**: it only re-executes when `humanoid_control.repos` changes or after a `clean`, so daily builds never touch the network. Nothing else auto-chains — in -particular, **no scenario task ever triggers a build** (a hardware -bringup must never start with a surprise rebuild; `doctor` is the -staleness check). +particular, **no scenario or utility task ever triggers a build** (a +hardware bringup must never start with a surprise rebuild). If the +workspace isn't built, those tasks fail with guidance pointing at +`pixi run build`; `doctor` is the staleness check. ## Level 1 — lifecycle tasks @@ -68,35 +78,15 @@ pre-push gate), `gen-dds`, `test-dds`. Colcon *style* flags `colcon build` inside `pixi shell` behaves identically to `pixi run build`. -## Level 2 — the `hc` toolbox +## Level 2 — workspace tasks -Diagnostics, viewers, and calibration ship **with the code** as the -`hc` CLI (`humanoid_control_cli`), not as per-workspace tasks — it is on -`PATH` in any environment that has the stack, whether built from source -or installed from the `berkeley-humanoids` binary channel: +Reserved names; each workspace declares the ones that apply, scoped to +its stack. Two vocabularies live here: **scenario tasks** and +**utility tasks**. -| Command | What it does | -|---|---| -| `hc bus ping` | single-actuator GetDeviceId ping (no Enable) | -| `hc bus discover` | scan a CAN bus for Robstride device ids | -| `hc bus probe` / `hc bus probe-report` | link RTT/jitter probe + report | -| `hc motor slider` | live MIT-mode slider GUI against one motor | -| `hc viz` | live state viewer of a running robot (`viewer:=viser` default, `viewer:=rerun`) | -| `hc viz urdf` | static URDF/kinematic inspector — sliders + RViz, no robot needed | -| `hc calibrate` | calibration bringup (writes `calibration.yaml`) | - -Every verb `execvp`s into the canonical `ros2 run` / `ros2 launch` -command, so signals and trailing arguments pass straight through -(`hc bus ping --iface can0 --id 11`). Run `hc help` for the menu. - -The scope rule: `hc` carries only commands whose **meaning is invariant -across workspaces**. Anything whose scope depends on the workspace -(`sim`, `real`, `policy`) is a task, level 3. - -## Level 3 — scenario tasks - -Reserved *names*; each workspace defines their scope. Grammar: -`scenario[-qualifier]`, **at most one qualifier**, where the +### Scenario tasks + +Grammar: `scenario[-qualifier]`, **at most one qualifier**, where the unqualified name is the workspace's default target. The qualifier encodes only the *primary* task variant; every secondary parameter (robot, backend, checkpoint, scene, …) stays a ROS launch argument: @@ -106,6 +96,17 @@ pixi run sim-piano robot:=prime policy:=latest # right pixi run sim-prime-piano-latest # wrong — name explosion ``` +The scenario words have **uniform semantics in every workspace**: + +- `sim` / `real` — **plant bringup only**: hardware or physics plus the + controller stack, **no policy**. +- `policy` — prepare and load a policy against an already-running + plant. +- `deploy-sim` / `deploy-real` — the **one-command pipeline**: bringup + *plus* policy in a single invocation. +- `viz` — live state viewer of a running robot. +- `calibrate` — calibration bringup. + In `humanoid_control_ws` (scope = the base control stack; unqualified = Lite): @@ -117,45 +118,138 @@ Lite): | `pixi run sim-piano` | `ros2 launch pianist_bringup mujoco.launch.py` | | `pixi run policy` | `ros2 launch humanoid_control_policy lite_policy.launch.py` | | `pixi run policy-piano` | `ros2 launch pianist_policy piano_policy.launch.py` | +| `pixi run deploy-sim` | `ros2 launch humanoid_bringup_lite deploy.launch.py backend:=mujoco` | +| `pixi run deploy-real` | `ros2 launch humanoid_bringup_lite deploy.launch.py backend:=real` | +| `pixi run viz` | `ros2 launch humanoid_bringup_lite viz.launch.py` (`viewer:=viser` default, `viewer:=rerun`) | +| `pixi run calibrate` | `ros2 launch humanoid_bringup_lite calibrate.launch.py` | + +The `deploy-*` tasks take the policy source as launch args +(`wandb_run_path:=` or `checkpoint_file:=`); `deploy-real` additionally +accepts `hardware_config:=` / `calibration_file:=` for the per-machine +setup. The task `description` always states the scope; `pixi task list` +shows it. In a deployment workspace (e.g. [Lite-Deployment](https://github.com/Berkeley-Humanoids/Lite-Deployment)), -`sim` / `real` mean **the full task stack** — bringup plus policy in one -command — because that is the workspace's reason to exist. The task -`description` always states the scope; `pixi task list` shows it. +`deploy-sim` / `deploy-real` are the same one-command pipeline — +bringup plus policy — because that is the workspace's reason to exist. +The scenario words never change meaning per workspace; a deployment +repo that doesn't declare plant-only `sim` / `policy` tasks simply +documents the canonical `ros2 launch` forms instead. + +### Utility tasks + +Frequently-used diagnostics get free kebab-case task names. Each one +**must be a one-line wrapper** over its canonical `ros2 run` / +`ros2 launch` command — no logic, no flags of its own: + +| Task | Wraps | +|---|---| +| `pixi run ping-bus` | `ros2 run humanoid_devices_robstride robstride_ping` | +| `pixi run scan-bus` | `ros2 run humanoid_devices_robstride robstride_discover` | +| `pixi run profile-bus` | `ros2 run humanoid_devices_robstride robstride_probe` | + +Rarely-used tools deliberately get **no task** — their canonical +`ros2 run` / `ros2 launch` forms are documented instead (e.g. +`robstride_probe_report`, `mit_slider_gui`, the standalone +`viser_viz` / `rerun_viz` executables, `view_lite.launch.py`). See +[Reference → Diagnostics and utility commands](../reference/cli_tools.md). ## Forwarding arguments -Scenario tasks are thin, argument-less wrappers, so trailing launch -arguments forward verbatim, the same way they do under raw -`ros2 launch`: +Tasks are thin, argument-less wrappers, so trailing arguments forward +verbatim, the same way they do under the raw command: ```sh pixi run real enable_gamepad:=false pixi run real hardware_config:=$HOME/lite_hardware.jetson.yaml +pixi run deploy-sim wandb_run_path:=entity/project/run-id pixi run policy checkpoint_file:=$HOME/model.onnx -pixi run policy-piano wandb_run_path:=entity/project/run-id +pixi run ping-bus --iface can0 --id 11 +pixi run scan-bus --iface can1 --scan-to 32 +``` + +## Escape hatches + +The tasks are shortcuts, not a wall. Two first-class ways out: + +- `pixi shell` — drop into the sourced environment and type plain + `ros2 launch …` / `ros2 run …` exactly as the launch-file docs show. +- `pixi run -- ros2 run humanoid_devices_robstride mit_slider_gui` — + run *any* command inside the pixi-managed env from a vanilla + terminal, no task declaration needed. + +## The reference block + +The `viz`, `calibrate`, and bus-utility one-liners are meant to be +**identical in every workspace** that carries the Lite stack. This TOML +block is the copy source — paste it into a consumer workspace's +`pixi.toml` verbatim rather than re-typing the wrappers, so +`pixi run ping-bus` means exactly the same thing everywhere: + +```toml +# --- Humanoid Control task reference block ------------------------------- +# Copy verbatim. Each task is a one-line wrapper over the canonical +# command; trailing arguments forward verbatim. + +[tasks.viz] +cmd = "ros2 launch humanoid_bringup_lite viz.launch.py" +description = "Live state viewer of a running robot (viewer:=viser default, viewer:=rerun)" + +[tasks.calibrate] +cmd = "ros2 launch humanoid_bringup_lite calibrate.launch.py" +description = "Calibration bringup — writes calibration.yaml on Ctrl+C" + +[tasks.ping-bus] +cmd = "ros2 run humanoid_devices_robstride robstride_ping" +description = "Single-actuator GetDeviceId ping, read-only (--iface, --id)" + +[tasks.scan-bus] +cmd = "ros2 run humanoid_devices_robstride robstride_discover" +description = "Scan a CAN bus for Robstride device ids, read-only (--iface, --scan-to)" + +[tasks.profile-bus] +cmd = "ros2 run humanoid_devices_robstride robstride_probe" +description = "Link RTT / jitter probe against one actuator (--iface, --id)" ``` +## Task lists per workspace + +`humanoid_control_ws` declares 25 tasks: + +- **Lifecycle (+ local extras)**: `setup` `build` `build-all` `test` + `test-result` `lint` `check` `clean` `doctor` `gen-dds` `test-dds` +- **Scenario**: `sim` `real` `sim-prime` `real-prime` `sim-piano` + `policy` `policy-piano` `deploy-sim` `deploy-real` `viz` `calibrate` +- **Utility**: `ping-bus` `scan-bus` `profile-bus` + +[Lite-Deployment](https://github.com/Berkeley-Humanoids/Lite-Deployment) +declares: `setup` `build` `clean` `doctor` `deploy-sim` `deploy-real` +`teleop`. (Its former `sim` / `real` tasks — which were the full +bringup-plus-policy pipeline — are renamed `deploy-sim` / +`deploy-real` under rev 2, freeing `sim` / `real` for their uniform +plant-only meaning.) + ## Adding a new command Decision rule, in order: -1. **Invariant meaning everywhere** (a diagnostic, viewer, calibration - tool) — add an `hc` verb in `humanoid_control_cli`, never a task. -2. **Scenario or workspace-local script** — add a task in that - workspace's `pixi.toml`, using the reserved scenario vocabulary - where it applies (`sim`, `real`, `policy`, plus at most one - `-qualifier` for the primary variant; secondary parameters stay - launch args), free kebab-case otherwise. Give it a `description` — - `pixi task list` is the menu. +1. **A scenario** (bringup, policy, deploy, viz, calibrate) — use the + reserved vocabulary, plus at most one `-qualifier` for the primary + variant; secondary parameters stay launch args. +2. **A frequently-used diagnostic or utility** — a free kebab-case + task that is a one-line wrapper over the canonical `ros2` command. + If it already exists in the reference block above, copy it from + there instead of re-typing it. 3. **Operates on the workspace** (fetch, build, verify) — lifecycle task, universal names only. 4. **Needs root or mutates host state** (CAN buses, kernel) — a script under `scripts/`, run explicitly with `sudo`, never a task. -5. **Rarely used** — no alias at all; document the canonical +5. **Rarely used** — no task at all; document the canonical `ros2 …` command. +Give every task a `description` — `pixi task list` is the menu: + ```toml [tasks.my-scenario] cmd = "ros2 launch my_pkg my_launch.py" @@ -164,7 +258,7 @@ description = "One line explaining scope and key launch args" ## Tradeoffs vs. plain `ros2 launch` -When to use the tasks and `hc`: +When to use the tasks: - One-off interactive bringups where you'll type the command often. - Operator runbooks — `pixi run real` reads more cleanly than the full diff --git a/docs/reference/cli_tools.md b/docs/reference/cli_tools.md index 5fb0447..b722607 100644 --- a/docs/reference/cli_tools.md +++ b/docs/reference/cli_tools.md @@ -1,16 +1,45 @@ --- -title: CLI tools +title: Diagnostics and utility commands --- -# CLI tools +# Diagnostics and utility commands -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 -reachable directly as `ros2 run `; the `hc` -CLI is a thin verb/noun wrapper that calls `os.execvp` on those -same targets. +Standalone executables shipped by `Humanoid Control`, and the workspace +pixi tasks that wrap the common ones. Every tool is reachable as +`ros2 run ` — that canonical form is what the +per-tool sections below document. The frequently-used ones also have a +workspace task (`pixi run ping-bus`, `pixi run scan-bus`, …), each a +one-line wrapper over the same canonical command. + +:::note[The `hc` CLI was retired] +Rev 1 of the workspace interface protocol shipped these tools behind a +packaged `hc` CLI (`humanoid_control_cli`). Rev 2 dissolved it — the +package is deleted. Its verbs became the workspace tasks in the table +below, or, for rarely-used tools, plain documented `ros2 run` commands. +See [How-to → Workspace commands](../how_to/use_pixi_tasks.md) for the +task interface itself. +::: + +## Task ↔ canonical command mapping + +| Former `hc` verb | Task (if any) | Canonical command | +|---|---|---| +| `hc bus ping` | `pixi run ping-bus` | `ros2 run humanoid_devices_robstride robstride_ping` | +| `hc bus discover` | `pixi run scan-bus` | `ros2 run humanoid_devices_robstride robstride_discover` | +| `hc bus probe` | `pixi run profile-bus` | `ros2 run humanoid_devices_robstride robstride_probe` | +| `hc bus probe-report` | — | `ros2 run humanoid_devices_robstride robstride_probe_report` | +| `hc motor slider` | — | `ros2 run humanoid_devices_robstride mit_slider_gui` | +| `hc viz` | `pixi run viz` | `ros2 launch humanoid_bringup_lite viz.launch.py` (`viewer:=viser` default, `viewer:=rerun`) | +| `hc viz viser` | — | `ros2 run humanoid_bringup_lite viser_viz` | +| `hc viz rerun` | — | `ros2 run humanoid_bringup_lite rerun_viz` | +| `hc viz urdf` | — | `ros2 launch humanoid_bringup_lite view_lite.launch.py` | +| `hc calibrate` | `pixi run calibrate` | `ros2 launch humanoid_bringup_lite calibrate.launch.py` | + +Tasks forward trailing arguments verbatim +(`pixi run ping-bus --iface can0 --id 11`). Commands without a task are +deliberate — rarely-used tools get no alias. Run them inside +`pixi shell` as plain `ros2 run …`, or from any terminal as +`pixi run -- ros2 run …`. `humanoid_control_policy` and `pianist_policy` each ship a `prepare` console script (the launch-time policy-artifact prep step); `pianist_policy` also ships @@ -22,9 +51,10 @@ 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. | +| `robstride_probe` | `humanoid_devices_robstride` | Humanoid Control | Link RTT / jitter probe against one actuator. | +| `robstride_probe_report` | `humanoid_devices_robstride` | Humanoid Control | Report companion for `robstride_probe` captures. | | `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. | @@ -43,8 +73,8 @@ These are normally driven by their launch files, but are reachable via ros2 run humanoid_devices_robstride robstride_ping --iface can0 --id 11 ros2 run humanoid_devices_robstride robstride_ping --iface can0 --id 11 --read-status -# Equivalent via the unified CLI: -hc bus ping --iface can0 --id 11 +# Equivalent one-line task wrapper: +pixi run ping-bus --iface can0 --id 11 ``` | Arg | Default | Description | @@ -69,8 +99,8 @@ ros2 run humanoid_devices_robstride robstride_discover --iface can0 ros2 run humanoid_devices_robstride robstride_discover --iface can0 \ --scan-from 1 --scan-to 127 --per-id-wait-ms 8 -# Equivalent via the unified CLI: -hc bus discover --iface can0 +# Equivalent one-line task wrapper: +pixi run scan-bus --iface can0 ``` | Arg | Default | Description | @@ -91,6 +121,23 @@ with zero replies. Both are useful in CI. Used in: [How-to → Probe CAN bus](../how_to/probe_can_bus.md), [Hardware specs → Bus-bring-up checklist](./hardware_specs.md#bus-bring-up-checklist). +### `robstride_probe` / `robstride_probe_report` + +```bash +# Link RTT / jitter probe against one actuator: +ros2 run humanoid_devices_robstride robstride_probe --iface can0 --id 11 +# Equivalent one-line task wrapper: +pixi run profile-bus --iface can0 --id 11 + +# Report companion — rarely used, no task: +ros2 run humanoid_devices_robstride robstride_probe_report +``` + +`robstride_probe` measures round-trip latency and jitter on the +command → reply path for a single actuator; `robstride_probe_report` +renders the captured data into a report. The report tool is rarely +used, so it deliberately has no task wrapper. + ### `mit_slider_gui` ```bash @@ -101,8 +148,8 @@ ros2 run humanoid_devices_robstride mit_slider_gui \ --position-range -3.14 3.14 \ --kp-range 0 10 -# Equivalent via the unified CLI: -hc motor slider +# Rarely used, no task — from outside `pixi shell`: +pixi run -- ros2 run humanoid_devices_robstride mit_slider_gui ``` | Arg | Default | Description | @@ -161,7 +208,8 @@ ros2 run humanoid_bringup_lite calibrate_robot \ | `--sweep-threshold` | `0.5` | Min sweep (rad) below which the prior `homing_offset` is preserved | Normally launched by `calibrate.launch.py` (which sets `--output` -from a launch arg and brings up the rest of the stack). Standalone +from a launch arg and brings up the rest of the stack) — that launch +is what the `pixi run calibrate` task wraps. Standalone invocation is useful if you already have `real.launch.py` running with `calibration_file:=''`. @@ -172,8 +220,9 @@ Used in: [How-to → Calibrate the zero pose](../how_to/calibrate_zero_pose.md). The two live-viewer executables. **On the tethered deployment they are spawned via `ros2 launch humanoid_bringup_lite viz.launch.py` on the operator workstation** (`viewer:=viser` by default; `viewer:=rerun` -for the native window). Direct invocation is the single-machine -sim/dev shortcut: +for the native window) — that launch is what the `pixi run viz` task +wraps. Direct invocation is the single-machine sim/dev shortcut (no +task; run inside `pixi shell` or via `pixi run --`): ```bash ros2 run humanoid_bringup_lite rerun_viz # native rerun window @@ -208,6 +257,11 @@ For a tool that ships from one of the existing packages: `install(TARGETS ... RUNTIME DESTINATION ...)` lines. 3. Rebuild with `colcon build --symlink-install --packages-select `. 4. Verify with `ros2 pkg executables `. +5. Only if the tool will be used often: add a one-line wrapper task to + the reference block in + [How-to → Workspace commands](../how_to/use_pixi_tasks.md#the-reference-block) + so every workspace inherits the same alias. Rarely-used tools stay + task-less by design. The `--symlink-install` flag means Python scripts edit-loop without rebuilding — useful while iterating. diff --git a/docs/reference/hardware_specs.md b/docs/reference/hardware_specs.md index 10d6077..445624a 100644 --- a/docs/reference/hardware_specs.md +++ b/docs/reference/hardware_specs.md @@ -162,9 +162,9 @@ sudo ip link set can1 down 2>/dev/null sudo ip link set can1 up type can bitrate 1000000 # 2. Read-only sanity scan — no Enable, no MIT. -# (the `hc` and `ros2` CLIs assume you've `cd humanoid_control_ws && pixi shell`'d.) -hc bus discover --iface can0 --scan-to 32 -hc bus discover --iface can1 --scan-to 32 +# (run from humanoid_control_ws; the `ros2` lines below assume `pixi shell`.) +pixi run scan-bus --iface can0 --scan-to 32 +pixi run scan-bus --iface can1 --scan-to 32 # Expect 7 + 7 = 14 actuators replying at ids 11..17 and 21..27. # 3. Calibrate the zero pose (once per physical robot). @@ -175,7 +175,7 @@ ros2 launch humanoid_bringup_lite calibrate.launch.py ros2 launch humanoid_bringup_lite real.launch.py ``` -If `hc bus discover` reports `ENOBUFS` / TX-drop warnings, the actuator +If `pixi run scan-bus` reports `ENOBUFS` / TX-drop warnings, the actuator power is off (no ACKs → frames pile up in the kernel qdisc). Power the motors first. diff --git a/docs/reference/packages.md b/docs/reference/packages.md index 44733cd..151eb48 100644 --- a/docs/reference/packages.md +++ b/docs/reference/packages.md @@ -4,7 +4,7 @@ The control stack is split across **two sibling repos** that are cloned side-by-side under `humanoid_control_ws/src/`: - **[`Berkeley-Humanoids/humanoid_control`](https://github.com/Berkeley-Humanoids/humanoid_control)** — - 12 packages making up the unified low-level control surface (URDF, + 11 packages making up the unified low-level control surface (URDF, controllers including in-process ONNX inference, hardware plugins, the launch-time policy-prep tool, both Lite and Prime bringups), plus a pip-only `humanoid_control_msgs_dds` package for off-ROS (Tier-3) clients. No @@ -196,19 +196,6 @@ never depends on `humanoid_control_policy` or any task message package. See [Controllers reference](controllers.md). -### `humanoid_control_cli` - -The packaged product toolbox: a unified verb/noun CLI surface -(`hc bus ping`, `hc bus discover`, `hc motor slider`, `hc viz`, -`hc viz urdf`, `hc calibrate`). An ament_python package that thin-wraps -the underlying executables shipped by `humanoid_devices_robstride` and -`humanoid_bringup_lite`, and installs a `bin/` shim so `hc` is on `PATH` -in any sourced overlay or conda env — invoke it directly once the -workspace env is active. Scope: only verbs whose meaning is invariant -across workspaces; scenario commands (`sim`, `real`, `policy`) are pixi -tasks in each workspace — see -[Workspace commands](../how_to/use_pixi_tasks.md).) - ### `humanoid_control_policy` An ament_python package that is a **launch-time prep tool**, not a diff --git a/docs/reference/quick_reference.md b/docs/reference/quick_reference.md index fc8f1c8..9ef1f55 100644 --- a/docs/reference/quick_reference.md +++ b/docs/reference/quick_reference.md @@ -13,7 +13,7 @@ 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 scripts are on `PATH`. Looking for the workspace tasks (`pixi run sim`, -`pixi run build`, …) or the `hc` toolbox? See +`pixi run build`, `pixi run ping-bus`, …)? See [How-to → Workspace commands](../how_to/use_pixi_tasks.md). ## Launch invocations @@ -109,24 +109,28 @@ ip -d link show can1 ## Diagnostic CLIs -These are the `hc` (humanoid_control_cli) verbs — equivalent `ros2 run humanoid_devices_robstride …` -invocations are listed in [CLI tools](./cli_tools.md). +These are the workspace utility tasks — one-line wrappers over the +`ros2 run humanoid_devices_robstride …` invocations listed in +[Diagnostics and utility commands](./cli_tools.md). ```bash # Scan an ID range; read-only, no Enable -hc bus discover --iface can0 --scan-to 32 -hc bus discover --iface can1 --scan-to 32 +pixi run scan-bus --iface can0 --scan-to 32 +pixi run scan-bus --iface can1 --scan-to 32 # One-shot GetDeviceId / OperationStatus probe -hc bus ping --iface can0 --id 11 +pixi run ping-bus --iface can0 --id 11 -# Per-joint slider window (forward_command_controller frontend) -hc motor slider +# Per-joint slider window (forward_command_controller frontend; no task) +ros2 run humanoid_devices_robstride mit_slider_gui -# Live URDF + /lite/joint_states viewers (single-machine sim/dev shortcuts; -# on the tethered host, prefer `ros2 launch humanoid_bringup_lite viz.launch.py`) -hc viz viser # browser at :8080 -hc viz rerun # native rerun window +# Live URDF + /lite/joint_states viewer — pixi run viz wraps this launch +ros2 launch humanoid_bringup_lite viz.launch.py # viser, browser at :8080 +ros2 launch humanoid_bringup_lite viz.launch.py viewer:=rerun # native rerun window + +# Single-machine sim/dev shortcuts for the raw viewer executables (no task) +ros2 run humanoid_bringup_lite viser_viz +ros2 run humanoid_bringup_lite rerun_viz ``` ## Mode-FSM gamepad bindings (Xbox layout) diff --git a/docs/tutorials/drive_one_robstride.md b/docs/tutorials/drive_one_robstride.md index 6735730..b2eea5a 100644 --- a/docs/tutorials/drive_one_robstride.md +++ b/docs/tutorials/drive_one_robstride.md @@ -56,19 +56,20 @@ ip -d link show can0 ```bash cd humanoid_control_ws -pixi shell -hc bus ping --iface can0 --id +pixi run ping-bus --iface can0 --id # TX GetDeviceId id=... # RX GetDeviceId reply device= uid=... # stats: rx=1 tx=1 rx_dropped=0 tx_failed=0 ``` -Replace `` with the motor's configured ID (factory default 0x7F -on new Robstride; vendor tool to reassign). If you don't know the -ID, scan: +(`ping-bus` is the workspace task wrapping +`ros2 run humanoid_devices_robstride robstride_ping`; trailing args +forward verbatim.) Replace `` with the motor's configured ID +(factory default 0x7F on new Robstride; vendor tool to reassign). If +you don't know the ID, scan: ```bash -hc bus discover --iface can0 --scan-to 127 +pixi run scan-bus --iface can0 --scan-to 127 ``` A clean reply confirms three things: the bus is up, the motor is @@ -78,7 +79,7 @@ Enabled the motor yet — `GetDeviceId` is read-only. ## Step 4 — Read live status (still read-only) ```bash -hc bus ping --iface can0 --id --read-status +pixi run ping-bus --iface can0 --id --read-status # RX OperationStatus device= pos= ... rad vel= 0.0 torque= 0.0 temp= ... C fault_bits=0x00 ``` @@ -90,9 +91,12 @@ re-ping, `pos` should change correspondingly. ## Step 5 — Launch the single-motor test stack -`humanoid_devices_robstride` ships a self-contained launch for this: +`humanoid_devices_robstride` ships a self-contained launch for this +(enter the workspace env first — `pixi shell` — so `ros2` is on PATH): ```bash +cd humanoid_control_ws +pixi shell ros2 launch humanoid_devices_robstride single_robstride_gui.launch.py \ can_id:= ``` @@ -120,8 +124,12 @@ ros2 control list_controllers ## Step 6 — Slider GUI +The slider GUI is a rarely-used tool, so it has no pixi task — run +the canonical executable (from any terminal, `pixi run --` provides +the env): + ```bash -hc motor slider +pixi run -- ros2 run humanoid_devices_robstride mit_slider_gui ``` A Qt window with five sliders (position, velocity, effort, kp, kd) @@ -184,8 +192,8 @@ sudo ip link add dev vcan0 type vcan sudo ip link set up vcan0 ``` -Then run the same `hc bus ping --iface vcan0` and -`hc bus discover --iface vcan0`. You won't get replies +Then run the same `pixi run ping-bus --iface vcan0` and +`pixi run scan-bus --iface vcan0`. You won't get replies (nothing's listening), but the TX path lights up and you can see your own frames with `candump vcan0`. The single-motor launch will boot but report `RX_TIMEOUT` in `/safety_status`.