from __future__ import annotations from abc import ABC, abstractmethod from dataclasses import dataclass, field from typing import Any @dataclass class HardwareFrame: gyro_raw: list[float] proj_gravity_raw: list[float] ticks: list[int] raw_speeds: list[int] voltage_v: float = 7.4 max_temp_c: float = 35.0 imu_ok: bool = True servo_err_mask: int = 0 timestamp_s: float = 0.0 extra: dict[str, Any] = field(default_factory=dict) class HardwareBridge(ABC): name: str = "abstract" @abstractmethod def connect(self) -> None: """Initialize connection to the MCU / servo bus.""" @abstractmethod def close(self) -> None: """Release hardware resources safely.""" @abstractmethod def configure(self, joint_names: list[str], profile: dict[str, Any]) -> None: """Push servo IDs, I2C address, watchdog, and IMU bias config to HAL.""" @abstractmethod def sync_step( self, enable_torque: bool, target_ticks: list[int], speed_limit: int = 0, acc: int = 50, ) -> HardwareFrame: """Send target joint ticks and read fresh IMU + servo feedback.""" @abstractmethod def set_torque(self, enable: bool) -> None: """Immediately enable or disable torque on all configured servos.""" @abstractmethod def ping_servos(self, max_id: int = 20) -> list[int]: """Scan and return responding servo IDs.""" @abstractmethod def calibrate_imu_raw(self, samples: int = 200) -> list[float]: """Collect stationary gyro readings (rad/s in sensor frame) and return mean bias."""