dexcontrol 0.2.10__py3-none-any.whl → 0.3.0__py3-none-any.whl

dexcontrol/utils/os_utils.py

@@ -12,8 +12,11 @@
 
 import os
 import re
-from typing import Final
+from typing import Any, Final
 
+from loguru import logger
+
+import dexcontrol
 from dexcontrol.utils.constants import ROBOT_NAME_ENV_VAR
 
 
@@ -56,3 +59,182 @@ def get_robot_model() -> str:
         raise ValueError(f"Unknown robot model: {robot_model_abb}")
     model = robot_model_abb_mapping[robot_model_abb] + "-" + robot_name.split("-")[-1]
     return model
+
+
+def check_version_compatibility(
+    version_info: dict[str, Any], show_warnings: bool = True
+) -> None:
+    """Check version compatibility between client and server.
+
+    This function uses the new JSON-based version interface to:
+    1. Compare client library version with server's minimum required version
+    2. Check server component versions for compatibility
+    3. Provide clear guidance for version mismatches
+
+    Args:
+        version_info: Dictionary containing version information from get_version_info()
+        show_warnings: Whether to show warning messages (default: True)
+    """
+    validate_client_version(version_info)
+    validate_server_version(version_info)
+
+
+def validate_client_version(version_info: dict[str, Any]) -> None:
+    """Validate client library version against server requirements.
+
+    Args:
+        version_info: Dictionary containing server and client version information.
+    """
+
+    client_info = version_info.get("client", {})
+    min_required_version = client_info.get("minimal_version")
+
+    if not min_required_version:
+        logger.debug("No minimum version requirement from server")
+        return
+
+    # Get current library version
+    current_version = getattr(dexcontrol, "__version__", "unknown")
+
+    if current_version == "unknown":
+        logger.warning("Could not determine current library version")
+        return
+
+    # Compare versions
+    comparison = compare_versions(current_version, min_required_version)
+
+    if comparison < 0:
+        show_version_upgrade_warning(current_version, min_required_version)
+
+
+def show_version_upgrade_warning(current: str, required: str) -> None:
+    """Display version upgrade warning to user.
+
+    Args:
+        current: Current library version
+        required: Required minimum version
+    """
+    logger.error(
+        f"🚨 CLIENT VERSION TOO OLD! 🚨\n"
+        f"Current library version: {current}\n"
+        f"Minimum required version: {required}\n"
+        f"\n"
+        f"⚠️  Your dexcontrol library is outdated and may not work correctly!\n"
+        f"📦 Please update your library using: pip install --upgrade dexcontrol\n"
+    )
+
+
+def validate_server_version(version_info: dict[str, Any]) -> None:
+    """Validate server software versions against minimum requirements.
+
+    Args:
+        version_info: Dictionary containing server and client version information.
+    """
+    server_info = version_info.get("server", {})
+
+    if not server_info:
+        logger.debug("No server version information available")
+        return
+
+    # Check each component's software version
+    components_below_min = []
+    for component_name, component_info in server_info.items():
+        if isinstance(component_info, dict):
+            software_version = component_info.get("software_version")
+            if software_version is not None:
+                try:
+                    # Convert to int if it's a string
+                    software_version_int = int(software_version)
+                    if software_version_int < dexcontrol.MIN_SOC_SOFTWARE_VERSION:
+                        components_below_min.append(
+                            (component_name, software_version_int)
+                        )
+                except (ValueError, TypeError) as e:
+                    logger.debug(
+                        f"Could not parse software version for {component_name}: {e}"
+                    )
+
+    # If any components are below minimum version, show warning
+    if components_below_min:
+        show_server_version_warning(
+            components_below_min, dexcontrol.MIN_SOC_SOFTWARE_VERSION
+        )
+
+
+def show_server_version_warning(
+    components: list[tuple[str, int]], min_version: int
+) -> None:
+    """Display server version warning to user.
+
+    Args:
+        components: List of (component_name, version) tuples for components below minimum.
+        min_version: Minimum required server software version.
+    """
+    components_str = "\n".join(
+        f"  - {name}: version {version}" for name, version in components
+    )
+
+    logger.error(
+        f"🚨 SERVER VERSION TOO OLD! 🚨\n"
+        f"The following server components are below minimum version {min_version}:\n"
+        f"{components_str}\n"
+        f"\n"
+        f"⚠️  Your robot's firmware may be outdated and some features may not work correctly!\n"
+        f"📦 Please contact your robot admin or check https://github.com/dexmate-ai/vega-firmware.\n"
+    )
+
+
+def compare_versions(version1: str, version2: str) -> int:
+    """Compare two semantic version strings.
+
+    Args:
+        version1: First version string (e.g., "1.2.3")
+        version2: Second version string (e.g., "1.1.0")
+
+    Returns:
+        -1 if version1 < version2
+         0 if version1 == version2
+         1 if version1 > version2
+    """
+    try:
+        # Clean version strings (remove 'v' prefix, handle pre-release suffixes)
+        def clean_version(v: str) -> list[int]:
+            v = v.strip().lower()
+            if v.startswith("v"):
+                v = v[1:]
+            # Split by dots and take only numeric parts
+            parts = v.split(".")
+            numeric_parts = []
+            for part in parts:
+                # Remove any non-numeric suffixes (like -alpha, -rc1, etc.)
+                numeric_part = ""
+                for char in part:
+                    if char.isdigit():
+                        numeric_part += char
+                    else:
+                        break
+                if numeric_part:
+                    numeric_parts.append(int(numeric_part))
+            return numeric_parts
+
+        parts1 = clean_version(version1)
+        parts2 = clean_version(version2)
+
+        # Pad shorter version with zeros
+        max_len = max(len(parts1), len(parts2))
+        parts1.extend([0] * (max_len - len(parts1)))
+        parts2.extend([0] * (max_len - len(parts2)))
+
+        # Compare part by part
+        for p1, p2 in zip(parts1, parts2):
+            if p1 < p2:
+                return -1
+            elif p1 > p2:
+                return 1
+
+        return 0
+
+    except Exception as e:
+        logger.debug(f"Version comparison error: {e}")
+        # Fallback to string comparison
+        return -1 if version1 < version2 else (1 if version1 > version2 else 0)

dexcontrol/utils/pb_utils.py

@@ -20,28 +20,6 @@ TYPE_SOFTWARE_VERSION = dict[
 ]
 
 
-def software_version_to_dict(
-    version_msg: dexcontrol_query_pb2.SoftwareVersion,
-) -> dict[str, TYPE_SOFTWARE_VERSION]:
-    """Convert a SoftwareVersion protobuf message to a dictionary.
-
-    Args:
-        version_msg: SoftwareVersion protobuf message.
-
-    Returns:
-        Dictionary containing version information with component names as keys.
-    """
-    return {
-        key: {
-            "hardware_version": value.hardware_version,
-            "software_version": value.software_version,
-            "main_hash": value.main_hash,
-            "compile_time": value.compile_time,
-        }
-        for key, value in version_msg.firmware_version.items()
-    }
-
-
 class ComponentStatus(Enum):
     """Enum representing the status of a component."""
 

dexcontrol/utils/subscribers/lidar.py

@@ -92,6 +92,7 @@ class LidarSubscriber(BaseZenohSubscriber):
                 - ranges: Array of range measurements in meters
                 - angles: Array of corresponding angles in radians
                 - qualities: Array of quality values (0-255) if available, None otherwise
+                - timestamp: Timestamp in nanoseconds (int)
         """
         with self._data_lock:
             if self._latest_raw_data is None:

dexcontrol/utils/trajectory_utils.py

@@ -16,7 +16,7 @@ import numpy as np
 def generate_linear_trajectory(
     current_pos: np.ndarray,
     target_pos: np.ndarray,
-    max_vel: float = 0.5,
+    max_vel: float | np.ndarray = 0.5,
     control_hz: float = 100,
 ) -> tuple[np.ndarray, int]:
     """Generate a linear trajectory between current and target positions.
@@ -24,7 +24,9 @@ def generate_linear_trajectory(
     Args:
         current_pos: Current position array.
         target_pos: Target position array.
-        max_vel: Maximum velocity in units per second.
+        max_vel: Maximum velocity in units per second. Can be:
+            - float: Same velocity limit for all dimensions
+            - numpy array: Per-dimension velocity limits (same length as current_pos)
         control_hz: Control frequency in Hz.
 
     Returns:
@@ -32,9 +34,19 @@ def generate_linear_trajectory(
         - trajectory: Array of waypoints from current to target position.
         - num_steps: Number of steps in the trajectory.
     """
-    # Calculate linear interpolation between current and target positions
-    max_diff = np.max(np.abs(target_pos - current_pos))
-    num_steps = int(max_diff / max_vel * control_hz)
+    # Calculate time needed for each dimension
+    pos_diff = np.abs(target_pos - current_pos)
+
+    if isinstance(max_vel, np.ndarray):
+        # Per-dimension velocity limits - find the dimension that takes longest
+        time_needed = pos_diff / max_vel
+        max_time = np.max(time_needed)
+    else:
+        # Single velocity limit for all dimensions
+        max_diff = np.max(pos_diff)
+        max_time = max_diff / max_vel
+
+    num_steps = int(max_time * control_hz)
 
     # Ensure at least one step
     num_steps = max(1, num_steps)

dexcontrol/utils/viz_utils.py

@@ -10,13 +10,14 @@
 
 """Utility functions for displaying information in a Rich table format."""
 
+from loguru import logger
 from rich.console import Console
 from rich.table import Table
 
 from dexcontrol.utils.pb_utils import TYPE_SOFTWARE_VERSION
 
 
-def show_software_version(version_info: dict[str, TYPE_SOFTWARE_VERSION]) -> None:
+def show_software_version(version_info: dict[str, TYPE_SOFTWARE_VERSION]):
     """Create a Rich table for displaying firmware version information.
 
     Args:
@@ -42,25 +43,26 @@ def show_software_version(version_info: dict[str, TYPE_SOFTWARE_VERSION]) -> Non
     console.print(table)
 
 
-def show_component_status(status_info: dict[str, dict]) -> None:
+def show_component_status(status_info: dict[str, dict]):
     """Create a Rich table for displaying component status information.
 
     Args:
         status_info: Dictionary containing status info for each component.
     """
+    from dexcontrol.utils.error_code import get_error_description
     from dexcontrol.utils.pb_utils import ComponentStatus
 
     table = Table(title="Component Status")
     table.add_column("Component", style="cyan")
     table.add_column("Connected", justify="center")
     table.add_column("Enabled", justify="center")
-    table.add_column("Error", justify="center")
+    table.add_column("Error", justify="left")
 
     status_icons = {
-        True: ":white_check_mark:",
-        False: ":x:",
-        ComponentStatus.NORMAL: ":white_check_mark:",
-        ComponentStatus.NA: "N/A",
+        True: "[green]:white_check_mark:[/green]",
+        False: "[red]:x:[/red]",
+        ComponentStatus.NORMAL: "[green]:white_check_mark:[/green]",
+        ComponentStatus.NA: "[dim]N/A[/dim]",
     }
 
     # Sort components by name to ensure consistent order
@@ -70,15 +72,51 @@ def show_component_status(status_info: dict[str, dict]) -> None:
         connected = status_icons[status["connected"]]
 
         # Format enabled status
-        enabled = status_icons.get(status["enabled"], ":x:")
+        enabled = status_icons.get(status["enabled"], "[red]:x:[/red]")
 
         # Format error status
         if status["error_state"] == ComponentStatus.NORMAL:
-            error = ":white_check_mark:"
+            error = "[green]:white_check_mark:[/green]"
         elif status["error_state"] == ComponentStatus.NA:
-            error = "N/A"
+            error = "[dim]N/A[/dim]"
         else:
-            error = status["error_code"]
+            # Convert error code to human-readable text
+            error_code = status["error_code"]
+            if isinstance(error_code, int):
+                error_desc = get_error_description(component, error_code)
+                # Show both raw code and description with formatting
+                if error_code == 0:
+                    error = "[green]:white_check_mark:[/green]"
+                else:
+                    # Check if this is an unknown error
+                    if "Unknown" in error_desc:
+                        # For unknown errors, show the hex code prominently
+                        error = f"[bold red]:warning: 0x{error_code:08X}[/bold red]\n[dim italic]Unknown error code[/dim italic]"
+                    else:
+                        # For known errors, show both code and description
+                        error = f"[bold red]:warning: 0x{error_code:08X}[/bold red]\n[yellow]{error_desc}[/yellow]"
+            else:
+                # Handle hex string format if provided
+                try:
+                    error_code_int = (
+                        int(error_code, 16)
+                        if isinstance(error_code, str)
+                        else error_code
+                    )
+                    error_desc = get_error_description(component, error_code_int)
+                    # Show both raw code and description with formatting
+                    if error_code_int == 0:
+                        error = "[green]:white_check_mark:[/green]"
+                    else:
+                        # Check if this is an unknown error
+                        if "Unknown" in error_desc:
+                            # For unknown errors, show the hex code prominently
+                            error = f"[bold red]:warning: 0x{error_code_int:08X}[/bold red]\n[dim italic]Unknown error code[/dim italic]"
+                        else:
+                            # For known errors, show both code and description
+                            error = f"[bold red]:warning: 0x{error_code_int:08X}[/bold red]\n[yellow]{error_desc}[/yellow]"
+                except (ValueError, TypeError):
+                    error = f"[red]{str(error_code)}[/red]"
 
         table.add_row(
             component,
@@ -89,3 +127,40 @@ def show_component_status(status_info: dict[str, dict]) -> None:
 
     console = Console()
     console.print(table)
+
+
+def show_ntp_stats(stats: dict[str, float]):
+    """Display NTP statistics in a Rich table format.
+
+    Args:
+        stats: Dictionary containing NTP statistics (e.g., mean_offset, mean_rtt, etc.).
+    """
+    table = Table()
+    table.add_column("Time Statistic", style="cyan")
+    table.add_column("Value (Unit: second)", justify="right")
+
+    for key, value in stats.items():
+        # Format floats to 6 decimal places, lists as comma-separated, others as str
+        if isinstance(value, float):
+            value_str = f"{value:.6f}"
+        elif isinstance(value, list):
+            value_str = ", ".join(
+                f"{v:.6f}" if isinstance(v, float) else str(v) for v in value
+            )
+        else:
+            value_str = str(value)
+        table.add_row(key, value_str)
+
+    console = Console()
+    console.print(table)
+
+    if "offset (mean)" in stats:
+        offset = stats["offset (mean)"]
+        if offset > 0:
+            logger.info(
+                f"To synchronize: server_time ≈ local_time + {offset:.3f} second"
+            )
+        else:
+            logger.info(
+                f"To synchronize: server_time ≈ local_time - {abs(offset):.3f} second"
+            )