tools: add odometry calibration tool

- Orchestrate calibration via Socket.IO connection to cogip-server
- Coordinate firmware operations through FirmwareAdapter
- Provide interactive user interface via ConsoleUI
- Include calculation engine for odometry parameter tuning

Author: mlecriva

cogip/models/__init__.py

@@ -23,3 +23,9 @@
     ShellMenu,
     Vertex,
 )
+from .odometry_calibration import (  # noqa
+    CalibrationResult,
+    CalibrationState,
+    EncoderDeltas,
+    OdometryParameters,
+)

cogip/models/odometry_calibration.py

@@ -0,0 +1,49 @@
+"""
+Odometry Calibration Models
+
+Pydantic models for odometry calibration data.
+"""
+
+from pydantic import BaseModel
+
+
+class CalibrationResult(BaseModel):
+    """Result of a calibration computation."""
+
+    wheels_distance: float
+    right_wheel_radius: float
+    left_wheel_radius: float
+
+
+class CalibrationState(BaseModel):
+    """
+    State container for calibration intermediate values.
+
+    Tracks alpha and beta coefficients computed during calibration phases.
+    """
+
+    alpha_l: float = 0.0
+    alpha_r: float = 0.0
+    beta: float = 0.0
+
+
+class EncoderDeltas(BaseModel):
+    """Encoder tick deltas captured during a motion sequence."""
+
+    left: int
+    right: int
+
+
+class OdometryParameters(BaseModel):
+    """
+    Container for odometry parameters.
+
+    Holds all parameters needed for odometry calibration.
+    """
+
+    wheels_distance: float = 0.0
+    right_wheel_radius: float = 0.0
+    left_wheel_radius: float = 0.0
+    left_polarity: float = 0.0
+    right_polarity: float = 0.0
+    encoder_ticks: float = 0.0

cogip/tools/firmware_odometry_calibration/__init__.py

@@ -0,0 +1,5 @@
+import logging
+
+from cogip.utils.logger import Logger
+
+logger = Logger("cogip-odometry-calibration", level=logging.WARNING)

cogip/tools/firmware_odometry_calibration/__main__.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""
+CLI entry point for the Odometry Calibration tool.
+
+Provides a command-line interface to calibrate robot odometry parameters
+by communicating with the firmware via SocketIO through cogip-server.
+"""
+
+from __future__ import annotations
+import asyncio
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import typer
+import yaml
+
+from cogip.models import FirmwareParametersGroup
+from cogip.tools.firmware_odometry_calibration import logger
+from cogip.tools.firmware_odometry_calibration.odometry_calibration import OdometryCalibration
+
+
+def main_opt(
+    *,
+    server_url: Annotated[
+        str | None,
+        typer.Option(
+            "-s",
+            "--server-url",
+            help="cogip-server URL",
+            envvar="COGIP_SOCKETIO_SERVER_URL",
+        ),
+    ] = None,
+    robot_id: Annotated[
+        int,
+        typer.Option(
+            "-i",
+            "--id",
+            min=1,
+            help="Robot ID.",
+            envvar=["ROBOT_ID"],
+        ),
+    ] = 1,
+    debug: Annotated[
+        bool,
+        typer.Option(
+            "-d",
+            "--debug",
+            help="Turn on debug messages",
+            envvar="CALIBRATION_DEBUG",
+        ),
+    ] = False,
+):
+    if debug:
+        logger.setLevel(logging.DEBUG)
+
+    if not server_url:
+        server_url = f"http://localhost:809{robot_id}"
+
+    # Load bundled parameters definition YAML
+    params_path = Path(__file__).with_name("odometry_parameters.yaml")
+    parameters_data = yaml.safe_load(params_path.read_text())
+
+    parameters_group = FirmwareParametersGroup.model_validate(parameters_data["parameters"])
+
+    # Run calibration
+    calibration = OdometryCalibration(server_url, parameters_group)
+    asyncio.run(calibration.run())
+
+
+def main():
+    """
+    Run odometry calibration tool.
+
+    During installation of cogip-tools, `setuptools` is configured
+    to create the `cogip-odometry-calibration` script using this function as entrypoint.
+    """
+    typer.run(main_opt)
+
+
+if __name__ == "__main__":
+    main()