dexbot-utils 0.4.0__py3-none-any.whl

dexbot_utils/__init__.py

@@ -0,0 +1,49 @@
+"""
+dexbot-utils: Common robot utility classes and functions.
+
+This package provides utilities for:
+- Robot identification and configuration
+- Component validation
+- URDF parsing for joint information
+"""
+
+__version__ = "0.1.0"
+
+# Main interface
+from .hand import HandType
+from .robot_info import RobotInfo
+
+# URDF utilities
+from .urdf_utils import (
+    get_joint_names,
+    get_movable_joint_names,
+    parse_urdf,
+)
+
+# Component validation
+from .validators import (
+    ComponentValidationError,
+    has_all_components,
+    has_component,
+    validate_component,
+    validate_components,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main interface
+    "RobotInfo",
+    # Validators
+    "ComponentValidationError",
+    "validate_component",
+    "validate_components",
+    "has_component",
+    "has_all_components",
+    # Hand
+    "HandType",
+    # URDF utilities
+    "parse_urdf",
+    "get_joint_names",
+    "get_movable_joint_names",
+]

dexbot_utils/_helpers.py

@@ -0,0 +1,49 @@
+"""Internal helper functions for robot configuration."""
+
+from functools import lru_cache
+
+
+@lru_cache(maxsize=None)
+def build_robot_type_abbreviation_mapping() -> dict[str, str]:
+    """Build robot type abbreviation mapping from registered configurations.
+
+    Scans all registered robot configurations and builds a mapping of abbreviations
+    to robot types (e.g., "vg" -> "vega").
+
+    Note: vega_1u (upper body) uses "vg" abbreviation with "u" suffix in robot name
+    (e.g., "dm/vg0123456789-1u" for vega upper body).
+
+    Returns:
+        Dictionary mapping abbreviations to robot types.
+
+    Example:
+        >>> mapping = build_robot_type_abbreviation_mapping()
+        >>> print(mapping)
+        {'vg': 'vega'}
+    """
+    from .configs import ConfigRegistry
+
+    mapping = {}
+
+    # Get all registered variants
+    for variant in ConfigRegistry.list_variants():
+        config = ConfigRegistry.get(variant)
+
+        # Get abbreviation and robot_model from config
+        abbr = config.abbr
+        robot_model = config.robot_model
+
+        # Extract robot type from robot_model (e.g., "vega_1" -> "vega")
+        # Split on '_' and take everything except the last part (version)
+        parts = robot_model.rsplit("_", 1)
+        robot_type = parts[0] if len(parts) > 1 else robot_model
+
+        # Add to mapping if not already present
+        if abbr not in mapping:
+            mapping[abbr] = robot_type
+
+    return mapping
+
+
+# Build once at module load
+ROBOT_TYPE_ABB_MAPPING = build_robot_type_abbreviation_mapping()

dexbot_utils/cfg_modifier.py

@@ -0,0 +1,99 @@
+from loguru import logger
+
+from .configs import BaseRobotConfig
+from .configs.components.vega_1.hand import (
+    DexDGripperConfig,
+    DexSGripperConfig,
+    F5D6HandV1Config,
+    F5D6HandV2Config,
+)
+from .hand import HandType
+
+
+def runtime_override_robot_config(
+    config: BaseRobotConfig,
+    hand_types: dict[str, HandType],
+    enable_hand_type_override: bool = True,
+    disable_estop_checking: bool = False,
+    disable_heartbeat: bool = False,
+):
+    """Apply runtime-driven overrides to a robot's configuration.
+
+    This function mutates `robot_info.config` in place based on runtime inputs:
+    - Optionally disables the `estop` and `heartbeat` components.
+    - Updates end-effector (hand) components per detected `hand_types`.
+      - Removes a hand component when the detected type is `HandType.UNKNOWN`.
+      - Replaces a mismatched hand component when `enable_hand_type_override` is True.
+      - Disables arm end-effector pass-through (`enable_ee_pass_through = False`)
+        when a concrete hand type is provided.
+    - Emits warnings via the logger when overrides or removals occur.
+
+    Args:
+        robot_info: Robot metadata and configuration container to be mutated.
+        hand_types: Mapping from side name (`"left"`, `"right"`) to detected
+            `HandType`. Use `HandType.UNKNOWN` when no hand is detected.
+        enable_hand_type_override: If True, replaces an existing hand component in
+            the config when it does not match the detected `HandType`. If False,
+            leaves the original component and logs a warning.
+        disable_estop_checking: If True, disables the `estop` component (when
+            present) and logs a warning.
+        disable_heartbeat: If True, disables the `heartbeat` component (when
+            present) and logs a warning.
+
+    """
+
+    if disable_estop_checking:
+        if "estop" in config.components:
+            config.components["estop"].enabled = False
+            logger.warning("EStop checking is disabled via environment variable")
+
+    if disable_heartbeat:
+        if "heartbeat" in config.components:
+            config.components["heartbeat"].enabled = False
+            logger.warning("Heartbeat is disabled via environment variable")
+
+    # Handling hand types
+    hand_type_mapping = {
+        DexSGripperConfig: HandType.DexGripper,
+        DexDGripperConfig: HandType.DexGripper,
+        F5D6HandV1Config: HandType.HandF5D6_V1,
+        F5D6HandV2Config: HandType.HandF5D6_V2,
+    }
+    hand_type_reverse_mapping = {
+        HandType.DexGripper: DexDGripperConfig,
+        HandType.HandF5D6_V1: F5D6HandV1Config,
+        HandType.HandF5D6_V2: F5D6HandV2Config,
+    }
+    for side in ("left", "right"):
+        if side in hand_types:
+            hand_type = hand_types[side]
+            if f"{side}_arm" in config.components:
+                arm = config.components[f"{side}_arm"]
+                # EE pass-through is disabled when hand type is specified
+                if hand_type != HandType.UNKNOWN:
+                    arm.enable_ee_pass_through = False
+
+            hand_key = f"{side}_hand"
+            if hand_key in config.components:
+                if hand_type == HandType.UNKNOWN:
+                    # config.components.pop(hand_key)
+                    logger.warning(
+                        f"No {side}_hand detected at runtime, the future version will remove the hand component from the config in this case. For now, we will keep the hand component in the config."
+                    )
+                else:
+                    desired_hand_type = hand_type_mapping[
+                        type(config.components[hand_key])
+                    ]
+                    if desired_hand_type != hand_type:
+                        if enable_hand_type_override:
+                            override_hand_cfg = hand_type_reverse_mapping[hand_type](
+                                side=side
+                            )
+                            config.components[hand_key] = override_hand_cfg
+                            logger.warning(
+                                f"Override {side}_hand config to {override_hand_cfg} based on detected hand type {hand_type}"
+                            )
+                        else:
+                            logger.warning(
+                                f"Detected {side}_hand type is {hand_type}, but the input config is {desired_hand_type}."
+                            )

dexbot_utils/cli.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Command-line interface for dexbot-utils.
+
+Provides CLI commands for exploring robot configurations and utilities.
+"""
+
+from pathlib import Path
+
+import typer
+
+from dexbot_utils.configs import get_available_variants, get_robot_config
+
+app = typer.Typer(
+    name="dexbot",
+    help="DexBot Utilities - Robot configuration and utility tools",
+    no_args_is_help=True,
+)
+
+cfg_app = typer.Typer(
+    name="cfg",
+    help="Robot configuration management commands",
+    no_args_is_help=True,
+)
+app.add_typer(cfg_app, name="cfg")
+
+
+@cfg_app.command("list")
+def config_list() -> None:
+    """List all available robot configuration variants."""
+    variants = get_available_variants()
+
+    typer.echo(f"Available robot configurations: {len(variants)}")
+    for variant in sorted(variants):
+        typer.echo(f"  - {variant}")
+
+
+@cfg_app.command("show")
+def config_show(
+    config: str = typer.Argument(
+        ...,
+        help="Robot variant name (e.g., vega_1) or path to config file",
+    ),
+) -> None:
+    """Show detailed information for a specific robot configuration.
+
+    CONFIG can be either:
+    - A variant name (e.g., vega_1, vega_1_gripper)
+    - A path to a configuration file
+    """
+    # Check if config is a file path
+    config_path = Path(config)
+    if config_path.exists() and config_path.is_file():
+        typer.echo(f"Loading config from file: {config_path}")
+        # TODO: Implement file-based config loading if needed
+        typer.echo("File-based config loading not yet implemented.", err=True)
+        raise typer.Exit(1)
+
+    # Treat as variant name
+    variant = config
+    try:
+        robot_config = get_robot_config(variant)
+
+        typer.echo(f"Robot Configuration: {variant}")
+        typer.echo("=" * 70)
+        typer.echo(f"Robot Model: {robot_config.robot_model}")
+        typer.echo(f"Abbreviation: {robot_config.abbr}")
+        typer.echo(f"URDF Path: {robot_config.urdf_path}")
+
+        # List components
+        typer.echo(f"\nComponents ({len(robot_config.components)}):")
+        for comp_name in sorted(robot_config.components.keys()):
+            comp = robot_config.components[comp_name]
+            comp_type = type(comp).__name__
+            typer.echo(f"  - {comp_name}: {comp_type}")
+
+        # List sensors
+        if hasattr(robot_config, "sensors") and robot_config.sensors:
+            typer.echo(f"\nSensors ({len(robot_config.sensors)}):")
+            for sensor_name in sorted(robot_config.sensors.keys()):
+                sensor = robot_config.sensors[sensor_name]
+                sensor_type = type(sensor).__name__
+                typer.echo(f"  - {sensor_name}: {sensor_type}")
+
+        # List queryables
+        if hasattr(robot_config, "querables") and robot_config.querables:
+            typer.echo(f"\nQueryables ({len(robot_config.querables)}):")
+            for query_name in sorted(robot_config.querables.keys()):
+                query_path = robot_config.querables[query_name]
+                typer.echo(f"  - {query_name}: {query_path}")
+
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()

dexbot_utils/configs/__init__.py

@@ -0,0 +1,31 @@
+"""Robot configuration system using dataclasses."""
+
+from .components import BaseComponentConfig
+from .registry import (
+    ConfigRegistry,
+    get_available_variants,
+    get_robot_config,
+    register_variant,
+)
+from .robots.base import BaseRobotConfig
+from .robots.vega_1 import Vega1Config, Vega1DGripperConfig, Vega1F5D6Config
+from .robots.vega_1p import Vega1pConfig, Vega1pDGripperConfig, Vega1pF5D6Config
+from .robots.vega_1u import Vega1UConfig, Vega1UDGripperConfig, Vega1UF5D6Config
+
+__all__ = [
+    "ConfigRegistry",
+    "register_variant",
+    "get_robot_config",
+    "get_available_variants",
+    "BaseRobotConfig",
+    "BaseComponentConfig",
+    "Vega1Config",
+    "Vega1DGripperConfig",
+    "Vega1F5D6Config",
+    "Vega1UConfig",
+    "Vega1UDGripperConfig",
+    "Vega1UF5D6Config",
+    "Vega1pConfig",
+    "Vega1pDGripperConfig",
+    "Vega1pF5D6Config",
+]

dexbot_utils/configs/components/__init__.py

@@ -0,0 +1,8 @@
+"""Component configuration dataclasses for robot components."""
+
+from .base import BaseComponentConfig, BaseJointComponentConfig
+
+__all__ = [
+    "BaseComponentConfig",
+    "BaseJointComponentConfig",
+]

dexbot_utils/configs/components/base.py

@@ -0,0 +1,28 @@
+"""Base component configuration classes."""
+
+from dataclasses import MISSING, dataclass, field
+
+
+@dataclass
+class BaseComponentConfig:
+    """Base configuration for a generic robot component.
+
+    Attributes:
+        enabled: Whether the component is enabled in the configuration
+    """
+
+    enabled: bool = True
+
+
+@dataclass
+class BaseJointComponentConfig(BaseComponentConfig):
+    """Base configuration for a robot component with joints.
+
+    Subclasses must define a `joints` attribute, either as a dataclass field
+    or as a property that computes joint names dynamically.
+
+    Attributes:
+        joints: List of joint names for the component (field or property)
+    """
+
+    joints: list[str] = field(default=MISSING, init=False)

dexbot_utils/configs/components/sensors/__init__.py

@@ -0,0 +1,20 @@
+"""Vega-specific component configuration dataclasses.
+
+This module contains Vega robot family specific component configurations.
+"""
+
+from .cameras import CameraConfig, ZedXCameraConfig, ZedXOneCameraConfig
+from .imu import ChassisIMUConfig, ZedIMUConfig
+from .lidar import Lidar3DConfig, RPLidarConfig
+from .ultrasonic import UltraSonicConfig
+
+__all__ = [
+    "CameraConfig",
+    "ZedXCameraConfig",
+    "ZedXOneCameraConfig",
+    "ChassisIMUConfig",
+    "ZedIMUConfig",
+    "Lidar3DConfig",
+    "RPLidarConfig",
+    "UltraSonicConfig",
+]

dexbot_utils/configs/components/sensors/cameras/__init__.py

@@ -0,0 +1,20 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+"""Camera sensor configurations."""
+
+from .camera import CameraConfig
+from .zed_camera import ZedXCameraConfig, ZedXOneCameraConfig
+
+__all__ = [
+    "CameraConfig",
+    "ZedXCameraConfig",
+    "ZedXOneCameraConfig",
+]

dexbot_utils/configs/components/sensors/cameras/camera.py

@@ -0,0 +1,38 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+"""Configuration for USB camera sensor."""
+
+from dataclasses import dataclass
+
+from ...base import BaseComponentConfig
+
+
+@dataclass
+class CameraConfig(BaseComponentConfig):
+    """Configuration for camera sensor.
+
+    This configuration supports both Zenoh (reliable, JPEG compressed) and
+    RTC (low latency, hardware accelerated video) transports.
+
+    Attributes:
+        name: Camera name identifier
+        transport: Transport protocol ("zenoh" or "rtc")
+        topic: Topic for camera data publishing
+        rtc_channel: Channel name for RTC transport
+    """
+
+    enabled: bool = False
+
+    name: str = "usb_camera"
+    transport: str = "zenoh"  # or "rtc"
+    topic: str = "sensors/camera/rgb"
+
+    rtc_channel: str = "sensors/camera/rgb_rtc"

dexbot_utils/configs/components/sensors/cameras/zed_camera.py

@@ -0,0 +1,102 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+"""Configuration for ZED camera sensor."""
+
+from dataclasses import dataclass
+
+from ...base import BaseComponentConfig
+from .camera import CameraConfig
+
+
+@dataclass
+class ZedXCameraConfig(BaseComponentConfig):
+    """Configuration for ZED stereo camera sensor.
+
+    This configuration supports multi-stream ZED cameras with independent
+    transport settings for each RGB stream. Depth always uses Zenoh.
+
+    Attributes:
+        name: Camera name identifier
+        transport: Transport protocol for RGB streams ("zenoh" or "rtc")
+        enable_rgb: Enable left and right RGB stream capture
+        enable_depth: Enable depth stream capture
+        left_rgb: Property returning left RGB camera configuration
+        right_rgb: Property returning right RGB camera configuration
+        depth: Property returning depth camera configuration
+    """
+
+    enabled: bool = False
+    name: str = "head_camera"
+    transport: str = "zenoh"
+    enable_rgb: bool = True
+    enable_depth: bool = True
+
+    @property
+    def left_rgb(self) -> CameraConfig:
+        return CameraConfig(
+            enabled=self.enabled & self.enable_rgb,
+            name="left_rgb",
+            transport=self.transport,
+            topic=f"sensors/{self.name}/left_rgb",
+            rtc_channel=f"sensors/{self.name}/left_rgb_rtc",
+        )
+
+    @property
+    def right_rgb(self) -> CameraConfig:
+        return CameraConfig(
+            enabled=self.enabled & self.enable_rgb,
+            name="right_rgb",
+            transport=self.transport,
+            topic=f"sensors/{self.name}/right_rgb",
+            rtc_channel=f"sensors/{self.name}/right_rgb_rtc",
+        )
+
+    @property
+    def depth(self) -> CameraConfig:
+        return CameraConfig(
+            enabled=self.enabled & self.enable_depth,
+            name="depth",
+            transport=self.transport,
+            topic=f"sensors/{self.name}/depth",
+        )
+
+
+@dataclass
+class ZedXOneCameraConfig(BaseComponentConfig):
+    """Configuration for ZED stereo camera sensor.
+
+    This configuration supports multi-stream ZED cameras with independent
+    transport settings for each RGB stream. Depth always uses Zenoh.
+
+    Attributes:
+        name: Camera name identifier
+        transport: Transport protocol for RGB streams ("zenoh" or "rtc")
+        enable_rgb: Enable left and right RGB stream capture
+        enable_depth: Enable depth stream capture
+        left_rgb: Property returning left RGB camera configuration
+        right_rgb: Property returning right RGB camera configuration
+        depth: Property returning depth camera configuration
+    """
+
+    enabled: bool = False
+    name: str = "wrist_camera"
+    transport: str = "zenoh"
+    side: str = "left"
+
+    @property
+    def rgb(self) -> CameraConfig:
+        return CameraConfig(
+            enabled=self.enabled,
+            name="rgb",
+            transport=self.transport,
+            topic=f"sensors/{self.side}_{self.name}/rgb",
+            rtc_channel=f"sensors/{self.name}/rgb_rtc",
+        )

dexbot_utils/configs/components/sensors/imu/__init__.py

@@ -0,0 +1,17 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+from .chassis_imu import ChassisIMUConfig
+from .zed_imu import ZedIMUConfig
+
+__all__ = [
+    "ChassisIMUConfig",
+    "ZedIMUConfig",
+]

dexbot_utils/configs/components/sensors/imu/chassis_imu.py

@@ -0,0 +1,20 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+from dataclasses import dataclass
+
+from ...base import BaseComponentConfig
+
+
+@dataclass
+class ChassisIMUConfig(BaseComponentConfig):
+    enabled: bool = False
+    topic: str = "state/chassis_imu"
+    name: str = "chassis_imu"

dexbot_utils/configs/components/sensors/imu/zed_imu.py

@@ -0,0 +1,20 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+from dataclasses import dataclass
+
+from ...base import BaseComponentConfig
+
+
+@dataclass
+class ZedIMUConfig(BaseComponentConfig):
+    enabled: bool = False
+    topic: str = "sensors/head_camera/imu"
+    name: str = "head_camera_imu"

dexbot_utils/configs/components/sensors/lidar/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+from .lidar_3d import Lidar3DConfig
+from .rplidar import RPLidarConfig
+
+__all__ = ["RPLidarConfig", "Lidar3DConfig"]

dexbot_utils/configs/components/sensors/lidar/lidar_3d.py

@@ -0,0 +1,22 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+from dataclasses import dataclass
+
+from ...base import BaseComponentConfig
+
+
+@dataclass
+class Lidar3DConfig(BaseComponentConfig):
+    """Configuration for 3D LIDAR point cloud sensor."""
+
+    enabled: bool = False
+    topic: str = "sensors/lidar_3d/points"
+    name: str = "lidar_3d"

dexbot_utils/configs/components/sensors/lidar/rplidar.py

@@ -0,0 +1,20 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+from dataclasses import dataclass
+
+from ...base import BaseComponentConfig
+
+
+@dataclass
+class RPLidarConfig(BaseComponentConfig):
+    enabled: bool = False
+    topic: str = "sensors/lidar_front/scan"
+    name: str = "rplidar"

dexbot_utils/configs/components/sensors/ultrasonic/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (C) 2025 Dexmate Inc.
+#
+# This software is dual-licensed:
+#
+# 1. GNU Affero General Public License v3.0 (AGPL-3.0)
+#    See LICENSE-AGPL for details
+#
+# 2. Commercial License
+#    For commercial licensing terms, contact: contact@dexmate.ai
+
+from .ultrasonic import UltraSonicConfig
+
+__all__ = ["UltraSonicConfig"]