robot-hat 3.3.2__tar.gz → 3.3.4__tar.gz

{robot_hat-3.3.2 → robot_hat-3.3.4}/.github/workflows/ci.yml

@@ -37,7 +37,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python 3.14
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: "3.14"
           cache: pip
@@ -69,7 +69,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python 3.10
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: "3.10"
           cache: pip
@@ -132,7 +132,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -159,7 +159,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python 3.12
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: "3.12"
           cache: pip
@@ -208,7 +208,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python 3.14
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: "3.14"
           cache: pip

{robot_hat-3.3.2 → robot_hat-3.3.4}/.github/workflows/release.yml

@@ -33,7 +33,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python 3.14
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: "3.14"
 
@@ -160,6 +160,6 @@ jobs:
           path: dist/
 
       - name: Publish distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
         with:
           attestations: true

{robot_hat-3.3.2 → robot_hat-3.3.4}/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## v3.3.4 (2026-11-11)
+
+### Fixed
+
+- Normalize `LSM9DS1.read_sample()` to a right-handed sensor-local frame by
+  reversing native Y for both acceleration and angular velocity. X, Z, SI
+  sensitivities, timestamps, and `read_raw_sample()` native counts are unchanged.
+  **Compatibility:** remove any application-side Y inversion that performs this
+  same normalization, and express mounting rotations relative to
+  `(native X, -native Y, native Z)`. A mounting rotation alone cannot correct the
+  previous left-handed output. The separate magnetometer driver is unchanged.
+
+### Documentation
+
+- Define the shared `IMUSample` and `IMUABC.read_sample()` contract: one
+  right-handed local frame, right-hand-rule angular velocity, SI units,
+  accelerometer specific force with its stationary gravity response, and host
+  monotonic observation timestamps. Document native raw-count semantics and
+  keep mounting transforms, bias estimation, and fusion in the application.
+- Identify the native frame references for LSM6DS33 and SH3001 and the
+  corresponding sample conventions for the mock IMU.
+
+## v3.3.3 (2026-10-16)
+
+### Fixed
+
+- Keep servo travel limits independent of pulse calibration. `Servo` maps
+  `real_min_angle`/`real_max_angle` to the configured pulse endpoints; narrower
+  `min_angle`/`max_angle` limits reduce travel without stretching the pulse range.
+- Validate servo calibration ranges and reject non-finite commands. Serialize
+  servo commands with cleanup and reject writes after close.
+- Initialize GPIO servos without pulses until commanded, and apply the service's
+  calibrated center consistently during initialization and calibration updates.
+- Preserve servo calibration state when a hardware write fails and release
+  servo resources after failed service initialization.
+- Hold GPIO motor enables low until direction outputs are ready, disable and
+  stop motors before releasing GPIO resources. Serialize movement and cleanup.
+- Attempt stops for every managed motor after a command or stop failure, stop
+  all motors before service cleanup, and report cleanup failures to callers.
+- Stop phase/enable motors before closing GPIO resources.
+- Serialize shared I²C transactions and cleanup to protect SMBus address
+  selection, notify bus managers when context managers close.
+- Keep shared GPIO factories open when deinitializing an individual pin, and
+  preserve active bus registrations when a different instance closes.
+
 ## v3.3.2 (2026-10-11)
 
 ### Fixed

{robot_hat-3.3.2 → robot_hat-3.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robot_hat
-Version: 3.3.2
+Version: 3.3.4
 Summary: Extensible, typed robotics hardware library for motors, servos, sensors, 2D lidar, I2C, and UART.
 Author-email: Karim Aziiev <karim.aziiev@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -241,7 +241,8 @@ finally:
     imu.close()
 ```
 
-The driver reports the LSM9DS1's native axes; configure the measured transform
+The driver reports a right-handed local frame: native X, reversed native Y,
+and native Z for both acceleration and angular velocity. Configure the transform
 from the HAT to the robot base in the consuming application.
 
 The Sense HAT's independently addressed magnetometer, humidity/temperature
@@ -362,6 +363,22 @@ for examples and custom `MotorABC` requirements.
 
 GPIO motors are motors that are controlled entirely via direct GPIO calls; no I²C address or external PWM driver is needed. Examples include the Waveshare RPi Motor Driver Board with the MC33886 module.
 
+`GPIODCMotor` holds its optional active-high enable pin low during initialization,
+while stopped, and before releasing GPIO resources. It enables the bridge only
+after setting the direction outputs. Each GPIO must belong to one device;
+an indicator LED must not share a motor's enable or direction pin.
+
+Motor services stop every motor before releasing resources and attempt every
+stop even if one output fails. Stop and close failures are reported to the caller.
+A failed movement command triggers a stop attempt for all managed motors, and
+closed services reject movement commands.
+
+GPIO cleanup releases pin ownership. Software cannot guarantee the electrical
+state during boot, OS halt, power loss, or a crashed process. The motor driver
+must have a hardware-defined disabled state when control inputs are undriven,
+and an independent power cutoff or inhibit appropriate to the mechanism.
+Validate startup, shutdown, and loss of control with wheels clear of the ground.
+
 ```python
 from robot_hat import GPIODCMotorConfig, MotorFactory, MotorService, setup_env_vars
 
@@ -517,6 +534,29 @@ calibrated_angle = -1 × (input_angle + (-1 × calibration_offset))
 
 The `ServoService` provides a high-level abstraction for managing servo operations. It allows easy configuration of the calibration mode, movement bounds, and custom calibration logic if needed.
 
+`Servo` separates permitted travel (`min_angle`, `max_angle`) from pulse
+calibration (`real_min_angle` at `min_pulse`, `real_max_angle` at `max_pulse`).
+An allowed angle produces the same pulse when travel limits change. For
+example, with measured calibration points of -45° at 1000 µs and +45° at
+2000 µs, limits of -10° to +10° produce approximately 1389–1611 µs.
+The default calibration assumes -90° to +90°; verify it for the particular
+servo. These are two calibration points, not a request to find mechanical
+end stops. Pulse rounding, PWM resolution, backlash, and servo behavior limit
+physical accuracy. Wheel steering angle also depends on the linkage geometry.
+
+When using `ServoService`, set its bounds to the desired movement relative
+to the calibrated center. Give its underlying `Servo` the full calibrated
+angle range so that the center offset can be applied without a second travel
+clamp. `GPIOAngularServo` follows gpiozero's convention: its `min_angle` and
+`max_angle` are the measured pulse endpoints; use `ServoService` for narrower
+travel limits. GPIO servos start with pulses disabled until the first angle
+command, including the calibrated center command issued by `ServoService`.
+
+Direct `pulse_width_time()` calls are calibration operations and bypass travel
+limits. Use angle commands for normal movement. Non-finite angle, offset, and
+pulse commands are rejected before hardware writes; closed servos reject
+further commands.
+
 Here's how to use `ServoCalibrationMode` in your servo configuration:
 
 **Example 1**: Steering servo using `ServoCalibrationMode.SUM`
@@ -548,6 +588,7 @@ driver = PWMFactory.create_pwm_driver(
     bus=pwm_config.bus,  # either a bus number or an smbus instance.
     config=pwm_config,
 )
+driver.set_pwm_freq(pwm_config.freq)
 
 steering_servo = ServoService(
     servo=Servo(
@@ -560,8 +601,7 @@ steering_servo = ServoService(
         # The minimum and maximum pulse widths (in microseconds) corresponding to the servo's physical movement.
         min_pulse=500,
         max_pulse=2500,
-        # The minimum and maximum physical angles (in degrees) that the servo can achieve.
-        # These values are used to map the logical angle to the physical angle.
+        # Measured angles at min_pulse and max_pulse, respectively.
         real_min_angle=-90.0,
         real_max_angle=90.0,
     ),
@@ -571,8 +611,6 @@ steering_servo = ServoService(
     calibration_mode=ServoCalibrationMode.SUM,
     calibration_offset=-14.4,
 )
-driver.set_pwm_freq(pwm_config.freq)
-
 steering_servo.set_angle(-30)  # Turn left.
 steering_servo.set_angle(15)  # Turn slightly to the right.
 steering_servo.reset()  # Reset to the center position.
@@ -839,8 +877,6 @@ class MyRobotCar:
         else:
             servo = GPIOAngularServo(
                 pin=channel,
-                min_angle=min_angle,
-                max_angle=max_angle,
             )
         return ServoService(
             servo=servo,

{robot_hat-3.3.2 → robot_hat-3.3.4}/README.md

@@ -198,7 +198,8 @@ finally:
     imu.close()
 ```
 
-The driver reports the LSM9DS1's native axes; configure the measured transform
+The driver reports a right-handed local frame: native X, reversed native Y,
+and native Z for both acceleration and angular velocity. Configure the transform
 from the HAT to the robot base in the consuming application.
 
 The Sense HAT's independently addressed magnetometer, humidity/temperature
@@ -319,6 +320,22 @@ for examples and custom `MotorABC` requirements.
 
 GPIO motors are motors that are controlled entirely via direct GPIO calls; no I²C address or external PWM driver is needed. Examples include the Waveshare RPi Motor Driver Board with the MC33886 module.
 
+`GPIODCMotor` holds its optional active-high enable pin low during initialization,
+while stopped, and before releasing GPIO resources. It enables the bridge only
+after setting the direction outputs. Each GPIO must belong to one device;
+an indicator LED must not share a motor's enable or direction pin.
+
+Motor services stop every motor before releasing resources and attempt every
+stop even if one output fails. Stop and close failures are reported to the caller.
+A failed movement command triggers a stop attempt for all managed motors, and
+closed services reject movement commands.
+
+GPIO cleanup releases pin ownership. Software cannot guarantee the electrical
+state during boot, OS halt, power loss, or a crashed process. The motor driver
+must have a hardware-defined disabled state when control inputs are undriven,
+and an independent power cutoff or inhibit appropriate to the mechanism.
+Validate startup, shutdown, and loss of control with wheels clear of the ground.
+
 ```python
 from robot_hat import GPIODCMotorConfig, MotorFactory, MotorService, setup_env_vars
 
@@ -474,6 +491,29 @@ calibrated_angle = -1 × (input_angle + (-1 × calibration_offset))
 
 The `ServoService` provides a high-level abstraction for managing servo operations. It allows easy configuration of the calibration mode, movement bounds, and custom calibration logic if needed.
 
+`Servo` separates permitted travel (`min_angle`, `max_angle`) from pulse
+calibration (`real_min_angle` at `min_pulse`, `real_max_angle` at `max_pulse`).
+An allowed angle produces the same pulse when travel limits change. For
+example, with measured calibration points of -45° at 1000 µs and +45° at
+2000 µs, limits of -10° to +10° produce approximately 1389–1611 µs.
+The default calibration assumes -90° to +90°; verify it for the particular
+servo. These are two calibration points, not a request to find mechanical
+end stops. Pulse rounding, PWM resolution, backlash, and servo behavior limit
+physical accuracy. Wheel steering angle also depends on the linkage geometry.
+
+When using `ServoService`, set its bounds to the desired movement relative
+to the calibrated center. Give its underlying `Servo` the full calibrated
+angle range so that the center offset can be applied without a second travel
+clamp. `GPIOAngularServo` follows gpiozero's convention: its `min_angle` and
+`max_angle` are the measured pulse endpoints; use `ServoService` for narrower
+travel limits. GPIO servos start with pulses disabled until the first angle
+command, including the calibrated center command issued by `ServoService`.
+
+Direct `pulse_width_time()` calls are calibration operations and bypass travel
+limits. Use angle commands for normal movement. Non-finite angle, offset, and
+pulse commands are rejected before hardware writes; closed servos reject
+further commands.
+
 Here's how to use `ServoCalibrationMode` in your servo configuration:
 
 **Example 1**: Steering servo using `ServoCalibrationMode.SUM`
@@ -505,6 +545,7 @@ driver = PWMFactory.create_pwm_driver(
     bus=pwm_config.bus,  # either a bus number or an smbus instance.
     config=pwm_config,
 )
+driver.set_pwm_freq(pwm_config.freq)
 
 steering_servo = ServoService(
     servo=Servo(
@@ -517,8 +558,7 @@ steering_servo = ServoService(
         # The minimum and maximum pulse widths (in microseconds) corresponding to the servo's physical movement.
         min_pulse=500,
         max_pulse=2500,
-        # The minimum and maximum physical angles (in degrees) that the servo can achieve.
-        # These values are used to map the logical angle to the physical angle.
+        # Measured angles at min_pulse and max_pulse, respectively.
         real_min_angle=-90.0,
         real_max_angle=90.0,
     ),
@@ -528,8 +568,6 @@ steering_servo = ServoService(
     calibration_mode=ServoCalibrationMode.SUM,
     calibration_offset=-14.4,
 )
-driver.set_pwm_freq(pwm_config.freq)
-
 steering_servo.set_angle(-30)  # Turn left.
 steering_servo.set_angle(15)  # Turn slightly to the right.
 steering_servo.reset()  # Reset to the center position.
@@ -796,8 +834,6 @@ class MyRobotCar:
         else:
             servo = GPIOAngularServo(
                 pin=channel,
-                min_angle=min_angle,
-                max_angle=max_angle,
             )
         return ServoService(
             servo=servo,

{robot_hat-3.3.2 → robot_hat-3.3.4}/docs/localization_sensors.md

@@ -8,25 +8,40 @@ mounting transforms, filtering, fusion, wheel geometry, and SLAM state.
 
 `IMUABC.read_sample()` returns an immutable `IMUSample` with:
 
-- acceleration in metres per second squared;
+- accelerometer specific force in metres per second squared, without gravity removal;
 - angular velocity in radians per second;
 - a process-local `time.monotonic_ns()` observation timestamp.
 
-The axis order is `(x, y, z)`. A concrete driver must document its positive axis
-directions. The application must transform that local frame into its robot base
-frame instead of hiding board mounting assumptions inside the hardware driver.
+Both vectors use axis order `(x, y, z)` in the same right-handed local frame.
+Positive angular velocity follows the right-hand rule. A stationary sensor with
+local +Z pointing upward reports approximately `(0, 0, +9.80665)` m/s²; ideal free
+fall reports zero. A concrete driver must document its positive axis directions
+and normalize hardware conventions before returning an `IMUSample`. The
+application applies the mounting rotation into its robot base frame and owns
+bias estimation, gravity compensation, and fusion.
+
+`RawIMUSample` contains signed native register counts for diagnostics. Its axis
+signs may differ from the normalized SI sample, as documented by each driver.
 
 `SH3001` defaults to ±2 g and ±2000 degrees/s. Its conversion uses the
 manufacturer sensitivity values for those configured ranges and standard gravity
 of 9.80665 m/s². `read_raw_sample()` is available for calibration and diagnostics;
-normal application code should consume `read_sample()`.
+normal application code should consume `read_sample()`. Its local frame follows
+the native right-handed axes in the Senodia SH3001 datasheet, section 7.1,
+Figure 15 (pin-1 marker identifies the package orientation).
 
 `LSM9DS1` provides the same six-axis contract for the Raspberry Pi Sense HAT v1
 and v2, and for standalone LSM9DS1 devices. The Sense HAT accelerometer/gyroscope
 function is wired to I²C bus 1 at `0x6a`; its separately addressed magnetometer at
-`0x1c` uses `MagnetometerABC` rather than the six-axis `IMUABC` contract. The IMU driver uses ST's
-native X/Y/Z signs without the undocumented application-specific remapping,
-calibration, bias learning, or fusion performed by RTIMULib. Its defaults are
+`0x1c` uses `MagnetometerABC` rather than the six-axis `IMUABC` contract. The IMU
+driver reports a right-handed local frame for both acceleration and angular
+velocity: `(native X, -native Y, native Z)`. ST's native A/G axes are left-handed
+([datasheet, Figure 1](https://www.st.com/resource/en/datasheet/lsm9ds1.pdf));
+the Y sign normalization lets applications use ordinary rigid mounting rotations.
+With a Sense HAT viewed from above and GPIO at the top, local X points right,
+local Y points toward GPIO, and local Z points out of the board. Robot mounting,
+bias calibration, and fusion belong to the application. `read_raw_sample()`
+returns native signed register counts. The driver's defaults are
 ±2 g, ±245 degrees/s, and 119 Hz. Pass a shared `SMBusABC` to combine it safely
 with other drivers on the bus; closing the IMU does not close an injected bus.
 See [Sense HAT environmental and magnetic sensors](sense_hat_sensors.md) for the
@@ -37,7 +52,9 @@ Pololu's MiniIMU-9 v5 and AltIMU-10 v5, as well as standalone LSM6DS33 carriers.
 It defaults to I²C address `0x6b`, ±2 g, ±245 degrees/s, and 104 Hz. The
 independent `LIS3MDL` driver provides magnetic samples in teslas at address
 `0x1e`. Driving the Pololu board's shared `SA0` pin low changes those addresses
-to `0x6a` and `0x1c`, respectively. Both drivers expose native axes, typed
+to `0x6a` and `0x1c`, respectively. The IMU's local frame follows the native
+right-handed axes in the [LSM6DS33 datasheet, Figure 1](https://www.pololu.com/file/0J1087/LSM6DS33.pdf).
+Both drivers expose native axes, typed
 configuration, diagnostic raw counts, and caller-owned shared-bus injection.
 In a driver selector, these components should be identified as
 **LSM6DS33 (gyro and accelerometer)** and **LIS3MDL (magnetometer)**.
@@ -47,7 +64,9 @@ See [Pololu MiniIMU-9 v5 support](pololu_miniimu9_v5.md) for wiring, complete
 configuration ranges, and calibration responsibilities.
 
 The monotonic timestamp is not Unix time. It is suitable for ordering and fusing
-observations acquired in the same process and monotonic clock domain.
+observations acquired in the same monotonic clock domain. It records host
+observation time, not a hardware sampling timestamp or a guarantee that the
+accelerometer and gyroscope sampled simultaneously.
 
 ## Wheel encoders
 

{robot_hat-3.3.2 → robot_hat-3.3.4}/docs/sense_hat_sensors.md

@@ -31,6 +31,13 @@ driver deliberately does not apply hard-iron offsets, soft-iron correction,
 declination, board rotation, or heading calculation. Those depend on the
 installation and belong in application calibration or sensor fusion.
 
+The six-axis `LSM9DS1.read_sample()` frame is right-handed, with native A/G X,
+reversed native A/G Y, and native A/G Z. Its `read_raw_sample()` frame contains
+native register counts. The independently addressed magnetometer uses the
+magnetic axes shown in ST's datasheet, Figure 1. Applications combining IMU and
+magnetometer samples must align their documented local frames before fusion;
+matching tuple indices alone does not establish a shared frame.
+
 The Sense HAT temperature sensors are physically close to the Raspberry Pi and
 LED matrix. Their readings can therefore be warmer than ambient air. The two
 temperature values also come from different physical devices and should remain

{robot_hat-3.3.2 → robot_hat-3.3.4}/robot_hat/data_types/imu.py

@@ -18,9 +18,23 @@ def _validate_vector(name: str, value: Vector3) -> None:
 class IMUSample:
     """One six-axis inertial observation in SI units.
 
-    Axes use the concrete sensor driver's documented local frame. Consumers are
-    responsible for applying the rigid transform from that frame to the robot
-    base frame.
+    Both vectors use axis order ``(x, y, z)`` in the same right-handed,
+    sensor-local frame. Concrete drivers document the positive axis directions
+    and normalize hardware axis conventions before constructing this sample.
+    Positive angular velocity follows the right-hand rule about each axis.
+
+    ``acceleration_mps2`` is accelerometer specific force in m/s², without
+    gravity removal. A stationary sensor with local +Z pointing upward reports
+    approximately ``(0, 0, +9.80665)``; ideal free fall reports zero.
+    ``angular_velocity_radps`` is angular velocity in rad/s.
+
+    ``timestamp_monotonic_ns`` is the host observation time in nanoseconds,
+    using ``time.monotonic_ns()`` or an injected clock with the same semantics.
+    It is not Unix time or a guarantee of simultaneous hardware acquisition.
+    Compare timestamps only within a shared monotonic clock domain.
+
+    Consumers apply the installation-specific mounting rotation into the robot
+    frame and own bias calibration, gravity compensation, and sensor fusion.
     """
 
     acceleration_mps2: Vector3
@@ -36,7 +50,12 @@ class IMUSample:
 
 @dataclass(frozen=True)
 class RawIMUSample:
-    """Unscaled signed sensor counts for diagnostics and calibration tools."""
+    """Unscaled signed sensor counts for diagnostics and calibration tools.
+
+    Axis order and signs follow the concrete driver's documented native
+    register convention, which may differ from the normalized ``IMUSample``
+    frame. The timestamp has the same host monotonic semantics as ``IMUSample``.
+    """
 
     accelerometer_counts: RawVector3
     gyroscope_counts: RawVector3