holosoma-inference 0.1.0__tar.gz

holosoma_inference-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: holosoma-inference
+Version: 0.1.0
+Summary: holosoma-inference: inference components for humanoid robot policies
+Author: Amazon FAR Team
+Keywords: humanoid robotics inference policy onnx
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic
+Requires-Dist: loguru
+Requires-Dist: netifaces
+Requires-Dist: onnx
+Requires-Dist: onnxruntime
+Requires-Dist: scipy
+Requires-Dist: sshkeyboard
+Requires-Dist: termcolor
+Requires-Dist: pyyaml
+Requires-Dist: tyro>=0.10.0a4
+Requires-Dist: wandb
+Requires-Dist: zmq
+Requires-Dist: defusedxml
+Requires-Dist: evdev
+Requires-Dist: importlib_metadata>=4.6; python_version < "3.12"
+Requires-Dist: eval_type_backport; python_version < "3.10"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
+Provides-Extra: unitree
+Requires-Dist: far-unitree-sdk==0.1.4; extra == "unitree"
+Provides-Extra: booster
+Requires-Dist: far-booster-sdk==0.1.0; extra == "booster"
+Dynamic: author
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

holosoma_inference-0.1.0/README.md

@@ -0,0 +1,227 @@
+# Holosoma Inference
+
+Policy inference for humanoid robot policies.
+
+## Supported Policies
+
+| Robot      | Locomotion | WBT |
+|:----------:|:----------:|:---:|
+| Unitree G1 | ✅         | ✅  |
+| Booster T1 | ✅         | ❌  |
+
+| Simulator               | Locomotion | WBT |
+|:-----------------------:|:----------:|:---:|
+| IsaacGym                | ✅         | ❌  |
+| IsaacSim                | ✅         | ✅  |
+| MuJoCo (inference only) | ✅         | ✅  |
+
+- ✅ (full support)
+- 🚧 (in progress/partial support)
+- ❌ (no support)
+
+## Quick Start
+
+### Setup the Environment
+
+```bash
+cd ~/holosoma
+bash scripts/setup_inference.sh             # Create a virtual environment with all dependencies
+source scripts/source_inference_setup.sh    # Activate the virtual environment
+```
+
+### Choose Your Workflow
+
+Select the appropriate workflow guide based on your setup:
+
+#### Real Robot Deployment
+- **[Real Robot Locomotion](docs/workflows/real-robot-locomotion.md)** - Run locomotion policies on physical Unitree G1 or Booster T1 robots
+- **[Real Robot Whole Body Tracking](docs/workflows/real-robot-wbt.md)** - Run WBT policies on physical Unitree G1 robots
+
+#### Simulation (MuJoCo)
+- **[Sim-to-Sim Locomotion](docs/workflows/sim-to-sim-locomotion.md)** - Test locomotion policies in MuJoCo simulation
+- **[Sim-to-Sim Whole Body Tracking](docs/workflows/sim-to-sim-wbt.md)** - Test WBT policies in MuJoCo simulation
+
+Each workflow guide includes:
+- Hardware/environment setup instructions
+- Step-by-step commands
+- Control references
+- Deployment options (offboard/onboard/Docker)
+- Troubleshooting tips
+
+---
+
+# Policy Controls
+
+Commands for controlling policies during execution.
+
+**Important**: All policy controls that use keyboard should be entered in the **policy terminal** (where you ran `run_policy.py`), not in the MuJoCo window. MuJoCo has separate controls for simulation (see workflow docs).
+
+## General Controls
+
+| Action | Keyboard | Joystick |
+|--------|----------|----------|
+| Start the policy | `]` | A button |
+| Stop the policy | `o` | B button |
+| Set robot to default pose | `i` | Y button |
+| Kill controller program | - | L1 (LB) + R1 (RB) |
+
+## Locomotion (Velocity Tracking)
+
+| Action | Keyboard | Joystick |
+|--------|----------|----------|
+| Switch walking/standing | `=` | Start button |
+| Adjust linear velocity | `w` `a` `s` `d` | Left stick |
+| Adjust angular velocity | `q` `e` | Right stick |
+
+**Default pose**: Standing pose
+
+## Whole-Body Tracking
+
+| Action | Keyboard | Joystick |
+|--------|----------|----------|
+| Start the policy | `]` | A button |
+| Start motion clip | `m` | Select+A |
+
+**Default pose**: Standing with raised arms
+
+## Joystick-Only Features
+
+- **Select button**: Switch between policies (when multiple policies are loaded)
+
+
+# Configuration Overrides
+
+## Loading ONNX Checkpoints from Wandb
+
+You can load ONNX checkpoints directly from Wandb without manually downloading them first. This is useful for quickly testing models from training runs.
+
+**Syntax:**
+```bash
+--task.model-path wandb://entity/project_name/run_id/model.onnx
+```
+
+**Example with G1 locomotion:**
+```bash
+source scripts/source_inference_setup.sh
+python3 src/holosoma_inference/holosoma_inference/run_policy.py inference:g1-29dof-loco \
+    --task.model-path wandb://my-username/my-project/run-abc123/fastsac_g1_29dof.onnx \
+    --task.use-joystick \
+    --task.interface eth0
+```
+
+**Example with Wandb HTTPS URL:**
+```bash
+python3 src/holosoma_inference/holosoma_inference/run_policy.py inference:g1-29dof-loco \
+    --task.model-path https://wandb.ai/username/project/runs/abc123/files/model.onnx \
+    --task.use-joystick \
+    --task.interface eth0
+```
+
+The model will be automatically downloaded and cached locally. The entity is your Wandb username or organization name.
+
+## Finding Your Network Interface
+
+The `--task.interface` parameter specifies which network interface to use for communicating with the robot. The correct interface name varies by computer and network card.
+
+**Common interface names:**
+- `eth0` - Common Ethernet interface name
+- `enp0s31f6` - Modern Linux Ethernet naming
+- `lo` - Loopback interface (for sim2sim)
+
+**To find your interface name:**
+```bash
+ifconfig
+```
+
+Look for the interface connected to your robot's network. For real robot deployments, use the interface with an IP address on the same subnet as your robot. For sim2sim deployments, use `lo` (loopback).
+
+## Observation History Length (> 1)
+
+If a policy was trained with stacked observations (e.g., history length 4), you must pass the same history length at inference time so the observation tensor matches the model's expected input size.
+
+Example:
+
+```bash
+python3 src/holosoma_inference/holosoma_inference/run_policy.py inference:g1-29dof-wbt \
+    --task.model-path <path-to-model>.onnx \
+    --task.interface eth0 \
+    --observation.history_length_dict.actor_obs=4
+```
+
+The override updates the `actor_obs` buffer before the ONNX session is initialized, so any policy (locomotion or WBT) can run with longer observation histories as long as the underlying model was trained that way.
+
+
+## Input Sources
+
+The policy supports two independent input channels that can each be set to `keyboard`, `joystick`, or `ros2`:
+
+| Channel | What it controls | CLI flag |
+|---------|-----------------|----------|
+| `velocity_input` | Continuous velocity commands (linear/angular) | `--task.velocity-input` |
+| `state_input` | Discrete commands: start/stop, walk/stand, kp tuning, policy switching | `--task.state-input` |
+
+### Shortcuts (backwards compatible)
+
+For the common case where both channels use the same source:
+
+```bash
+--task.use-joystick    # Sets both channels to joystick
+--task.use-keyboard    # Sets both channels to keyboard (this is the default)
+```
+
+### Mixed input examples
+
+**ROS2 `cmd_vel` with keyboard commands** — velocity from ROS2, operator uses keyboard for start/stop:
+
+```bash
+python3 src/holosoma_inference/holosoma_inference/run_policy.py inference:g1-29dof-loco \
+    --task.model-path <path-to-model>.onnx \
+    --task.velocity-input ros2 \
+    --task.state-input keyboard \
+    --task.interface eth0
+```
+
+**Fully autonomous** — both channels from ROS2:
+
+```bash
+python3 src/holosoma_inference/holosoma_inference/run_policy.py inference:g1-29dof-loco \
+    --task.model-path <path-to-model>.onnx \
+    --task.velocity-input ros2 \
+    --task.state-input ros2 \
+    --task.interface eth0
+```
+
+### ROS2 topics
+
+| Topic | Message type | Channel | Description |
+|-------|-------------|---------|-------------|
+| `cmd_vel` | `geometry_msgs/TwistStamped` | `velocity_input` | Linear (x, y) and angular (z) velocity, clamped to [-1, 1] |
+| `holosoma/state_input` | `std_msgs/String` | `state_input` | Text commands: `walk`, `stand`, `start`, `stop`, `init` |
+
+Topic names are configurable via `--task.ros-cmd-vel-topic` and `--task.ros-state-input-topic`.
+
+**Note**: Shortcut flags (`--task.use-joystick`, `--task.use-keyboard`) cannot be combined with `--task.velocity-input` or `--task.state-input`.
+
+## Overriding Control Gains
+
+By default, control gains (kp/kd) are loaded from ONNX model metadata. You can override these values in your configuration:
+
+### G1 29-DOF with Custom Control Gains
+
+```bash
+python3 src/holosoma_inference/holosoma_inference/run_policy.py inference:g1-29dof-loco \
+    --task.model-path src/holosoma_inference/holosoma_inference/models/loco/g1_29dof/fastsac_g1_29dof.onnx \
+    --robot.motor-kp 40.2 99.1 40.2 99.1 28.5 28.5 40.2 99.1 40.2 99.1 28.5 28.5 40.2 28.5 28.5 14.3 14.3 14.3 14.3 14.3 16.8 16.8 14.3 14.3 14.3 14.3 14.3 16.8 16.8 \
+    --robot.motor-kd 2.6 6.3 2.6 6.3 1.8 1.8 2.6 6.3 2.6 6.3 1.8 1.8 2.6 1.8 1.8 0.9 0.9 0.9 0.9 0.9 1.1 1.1 0.9 0.9 0.9 0.9 0.9 1.1 1.1
+```
+
+### T1 29-DOF with Custom Control Gains
+
+```bash
+python3 src/holosoma_inference/holosoma_inference/run_policy.py inference:t1-29dof-loco \
+    --task.model-path src/holosoma_inference/holosoma_inference/models/loco/t1_29dof/ppo_t1_29dof.onnx \
+    --robot.motor-kp 5.0 5.0 20.0 20.0 20.0 20.0 20.0 20.0 20.0 20.0 20.0 20.0 20.0 20.0 20.0 20.0 200.0 200.0 200.0 200.0 200.0 50.0 50.0 200.0 200.0 200.0 200.0 50.0 50.0 \
+    --robot.motor-kd 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 5.0 5.0 5.0 5.0 5.0 3.0 3.0 5.0 5.0 5.0 5.0 3.0 3.0
+```
+
+**Note**: When control gains are not specified, they will be automatically loaded from the ONNX model metadata. This is the recommended approach as it ensures the gains match those used during training.

holosoma_inference-0.1.0/holosoma_inference/compat.py

@@ -0,0 +1,10 @@
+"""Python version compatibility shims."""
+
+import sys
+
+if sys.version_info >= (3, 12):
+    from importlib.metadata import entry_points
+else:
+    from importlib_metadata import entry_points
+
+__all__ = ["entry_points"]

holosoma_inference-0.1.0/holosoma_inference/config/__init__.py

@@ -0,0 +1,11 @@
+"""Tyro-based configuration system for holosoma_inference.
+
+This module provides a type-safe configuration system using Pydantic dataclasses and Tyro CLI.
+"""
+
+from . import config_types, config_values
+
+__all__ = [
+    "config_types",
+    "config_values",
+]

holosoma_inference-0.1.0/holosoma_inference/config/config_types/__init__.py

@@ -0,0 +1,13 @@
+"""Type definitions for holosoma_inference configuration system."""
+
+from .inference import InferenceConfig
+from .observation import ObservationConfig
+from .robot import RobotConfig
+from .task import TaskConfig
+
+__all__ = [
+    "InferenceConfig",
+    "ObservationConfig",
+    "RobotConfig",
+    "TaskConfig",
+]

holosoma_inference-0.1.0/holosoma_inference/config/config_types/inference.py

@@ -0,0 +1,33 @@
+"""Top-level inference configuration types for holosoma_inference."""
+
+from __future__ import annotations
+
+from pydantic.dataclasses import dataclass
+
+from .observation import ObservationConfig
+from .robot import RobotConfig
+from .task import TaskConfig
+
+
+@dataclass(frozen=True)
+class InferenceConfig:
+    """Top-level configuration for policy inference.
+
+    Combines robot, observation, and task configurations
+    for running policies on real robots or in simulation.
+    """
+
+    robot: RobotConfig
+    """Robot hardware and control configuration."""
+
+    observation: ObservationConfig
+    """Observation space configuration."""
+
+    task: TaskConfig
+    """Task execution configuration."""
+
+    secondary: InferenceConfig | None = None
+    """Secondary policy config for dual-mode (X-button switch).
+    When set, enables runtime switching between this (primary) policy and the secondary.
+    Override any field: --secondary.task.model-path, --secondary.task.rl-rate, etc.
+    Set to None to disable dual-mode."""

holosoma_inference-0.1.0/holosoma_inference/config/config_types/observation.py

@@ -0,0 +1,53 @@
+"""Observation configuration types for holosoma_inference."""
+
+from __future__ import annotations
+
+from pydantic.dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ObservationConfig:
+    """Observation space configuration.
+
+    Defines which observations are used, their dimensions,
+    scaling factors, history lengths, etc. for policy inference.
+    """
+
+    obs_dict: dict[str, list[str]]
+    """Maps observation group names to lists of observation components.
+
+    Each key represents an observation group (e.g., "actor_obs", "critic_obs"),
+    and each value is a list of observation component names that belong to that group.
+
+    Example:
+        {"actor_obs": ["base_ang_vel", "projected_gravity", "dof_pos"]}
+    """
+
+    obs_dims: dict[str, int]
+    """Dimension of each observation component.
+
+    Maps each observation component name to its dimensionality.
+
+    Example:
+        {"base_ang_vel": 3, "dof_pos": 29, "actions": 29}
+    """
+
+    obs_scales: dict[str, float]
+    """Scaling factor applied to each observation component.
+
+    Maps each observation component name to a scaling factor that will be
+    multiplied with the raw observation values during preprocessing.
+
+    Example:
+        {"base_ang_vel": 0.25, "dof_vel": 0.05, "projected_gravity": 1.0}
+    """
+
+    history_length_dict: dict[str, int]
+    """Number of timesteps to keep in history for each observation group.
+
+    Maps each observation group name to the number of historical timesteps
+    to maintain. A value of 1 means only the current observation is used.
+
+    Example:
+        {"actor_obs": 1, "critic_obs": 3}
+    """

holosoma_inference-0.1.0/holosoma_inference/config/config_types/robot.py

@@ -0,0 +1,236 @@
+"""Robot configuration types for holosoma_inference."""
+
+from __future__ import annotations
+
+import typing
+from typing import Any
+
+from pydantic.dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RobotConfig:
+    """Robot hardware and control configuration.
+
+    Defines all robot-specific parameters including kinematics,
+    control gains, limits, and SDK configuration.
+
+    Examples
+    --------
+    G1 29-DOF robot configuration:
+    >>> robot_config = RobotConfig(
+    ...     robot_type="g1_29dof",
+    ...     robot="g1",
+    ...     num_motors=29,
+    ...     num_joints=29,
+    ...     default_dof_angles=(...),  # 29 values
+    ...     motor_kp=(...),  # 29 values
+    ...     # ... other required fields
+    ... )
+    """
+
+    # =========================================================================
+    # Identity (REQUIRED - no defaults)
+    # =========================================================================
+
+    robot_type: str
+    """Robot identifier (e.g., 'g1_29dof', 't1_29dof')."""
+
+    robot: str
+    """Robot family name (e.g., 'g1', 't1')."""
+
+    # =========================================================================
+    # Default Positions (REQUIRED - immutable tuples, no defaults)
+    # =========================================================================
+
+    default_dof_angles: tuple[float, ...]
+    """Default joint angles in radians (length: num_joints).
+
+    These are the target positions when the robot is in its default standing pose.
+    """
+
+    default_motor_angles: tuple[float, ...]
+    """Default motor angles in radians (length: num_motors).
+
+    Typically identical to default_dof_angles unless there's a motor-to-joint mapping.
+    """
+
+    # =========================================================================
+    # Mappings (REQUIRED - no defaults)
+    # =========================================================================
+
+    motor2joint: tuple[int, ...]
+    """Motor index to joint index mapping (length: num_motors).
+
+    Maps motor indices to their corresponding joint indices.
+    For most robots, this is an identity mapping [0, 1, 2, ..., n-1].
+    """
+
+    joint2motor: tuple[int, ...]
+    """Joint index to motor index mapping (length: num_joints).
+
+    Inverse of motor2joint mapping.
+    """
+
+    dof_names: tuple[str, ...]
+    """Joint names in order (length: num_joints).
+
+    Example: ('left_hip_pitch_joint', 'left_hip_roll_joint', ...)
+    """
+
+    # =========================================================================
+    # Deprecation candidates with no defaults
+    # =========================================================================
+
+    dof_names_upper_body: tuple[str, ...]
+    """Upper body joint names (length: num_upper_body_joints).
+
+    Subset of dof_names containing only upper body joints.
+    """
+
+    dof_names_lower_body: tuple[str, ...]
+    """Lower body joint names (length: num_joints - num_upper_body_joints).
+
+    Subset of dof_names containing only lower body joints (legs + waist).
+    """
+
+    # =========================================================================
+    # Control Gains (OPTIONAL - can be loaded from ONNX metadata)
+    # =========================================================================
+
+    motor_kp: tuple[float, ...] | None = None
+    """Proportional gains for PD control (length: num_motors).
+
+    These gains are applied in the motor-space PD controller:
+    tau = kp * (q_target - q_current) + kd * (dq_target - dq_current)
+
+    If None, values will be loaded from ONNX model metadata during inference.
+    If provided, these values override the ONNX metadata.
+    """
+
+    motor_kd: tuple[float, ...] | None = None
+    """Derivative gains for PD control (length: num_motors).
+
+    These gains are applied in the motor-space PD controller.
+
+    If None, values will be loaded from ONNX model metadata during inference.
+    If provided, these values override the ONNX metadata.
+    """
+
+    default_per_joint_action_scale: tuple[float, ...] | None = None
+    """Fallback per-joint action scales used when ONNX metadata is missing."""
+
+    # =========================================================================
+    # WBT Stiff Startup Configuration (OPTIONAL - for WBT policies)
+    # =========================================================================
+
+    stiff_startup_pos: tuple[float, ...] | None = None
+    """Stiff startup joint positions for WBT policy (length: num_joints).
+
+    Target positions used during stiff hold mode before policy activation.
+    Only used by WholeBodyTracking policy.
+    """
+
+    stiff_startup_kp: tuple[float, ...] | None = None
+    """Stiff startup position gains for WBT policy (length: num_joints).
+
+    Proportional gains used during stiff hold mode before policy activation.
+    Only used by WholeBodyTracking policy.
+    """
+
+    stiff_startup_kd: tuple[float, ...] | None = None
+    """Stiff startup velocity gains for WBT policy (length: num_joints).
+
+    Derivative gains used during stiff hold mode before policy activation.
+    Only used by WholeBodyTracking policy.
+    """
+
+    # =========================================================================
+    # SDK Configuration (OPTIONAL - with defaults)
+    # =========================================================================
+
+    sdk_type: str = "unitree"
+    """SDK type for robot communication.
+
+    Built-in types: 'unitree', 'booster'.
+    Extensions can register additional SDK types.
+    """
+
+    motor_type: typing.Literal["serial", "parallel"] = "serial"
+    """Motor communication type."""
+
+    message_type: typing.Literal["HG", "GO2"] = "HG"
+    """Message protocol type."""
+
+    # =========================================================================
+    # Dimensions (OPTIONAL - with defaults)
+    # =========================================================================
+
+    num_motors: int = 29
+    """Number of motors in the robot."""
+
+    num_joints: int = 29
+    """Number of joints in the robot."""
+
+    # =========================================================================
+    # Link Names (OPTIONAL - with defaults)
+    # =========================================================================
+
+    torso_link_name: str = "torso_link"
+    """Name of the torso/base link in the robot model."""
+
+    left_hand_link_name: str | None = None
+    """Name of the left hand/end-effector link (if applicable)."""
+
+    right_hand_link_name: str | None = None
+    """Name of the right hand/end-effector link (if applicable)."""
+
+    # =========================================================================
+    # SDK-Specific Configuration (optional)
+    # =========================================================================
+
+    unitree_legged_const: dict[str, Any] | None = None
+    """Unitree SDK-specific constants.
+
+    Contains protocol-specific values like HIGHLEVEL, LOWLEVEL, etc.
+    Only used when sdk_type='unitree'.
+    """
+
+    weak_motor_joint_index: dict[str, int] | None = None
+    """Mapping of joint names to their weak motor indices.
+
+    Used for robots with weak motors that need special handling.
+    """
+
+    motion: dict[str, list[str]] | None = None
+    """Motion reference configuration.
+
+    Specifies body names used for motion tracking/reference.
+    Example: {'body_name_ref': ['torso_link']}
+    """
+
+    # =========================================================================
+    # Deprecation candidates
+    # (I'm moving for parity with hydra, but I'd like to remove in the future)
+    # =========================================================================
+
+    dof_names_parallel_mech: tuple[str, ...] = ()
+    """Parallel mechanism joint names (optional, booster specific)."""
+
+    use_sensor: bool = False
+    """Whether to use sensor feedback instead of joint states."""
+
+    num_upper_body_joints: int = 14
+    """Number of upper body degrees of freedom."""
+
+    # =========================================================================
+    # Per-Robot Calibration
+    # =========================================================================
+
+    joint_offsets_deg: tuple[float, ...] | None = None
+    """Per-joint offsets in degrees applied to lowcmd (action-space only).
+
+    These offsets correct for per-robot motor calibration differences without
+    affecting the observation/state space. Converted to radians at init time.
+    Length must equal num_joints when provided.
+    """