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

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

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robot_hat
-Version: 3.3.2
+Version: 3.3.3
 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
@@ -362,6 +362,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 +533,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 +587,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 +600,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 +610,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 +876,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.3}/README.md

@@ -319,6 +319,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 +490,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 +544,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 +557,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 +567,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 +833,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.3}/robot_hat/i2c/i2c_bus.py

@@ -1,5 +1,6 @@
 import logging
 import os
+from threading import RLock
 from types import TracebackType
 from typing import TYPE_CHECKING, List, Optional, Sequence, Type, Union, cast
 
@@ -43,6 +44,8 @@ class I2CBus(SMBusABC):
             SMBus = cast(Type[SMBusProtocol], RealSMBus)
 
         self._bus = bus
+        self._lock = RLock()
+        self._closed = False
         self._smbus = SMBus(bus, force)
         self.emitter = EventEmitter()
         _log.debug("SMBus initialized on bus %s with force=%s", bus, force)
@@ -55,10 +58,10 @@ class I2CBus(SMBusABC):
             bus: Bus identifier to open.
         """
         _log.debug("Opening SMBus on bus %s", bus)
-        if hasattr(self._smbus, "open"):
+        with self._lock:
             self._smbus.open(bus)
-        else:
-            _log.warning("Underlying SMBus instance does not support 'open'.")
+            self._bus = bus
+            self._closed = False
 
     def close(self) -> None:
         """
@@ -68,17 +71,28 @@ class I2CBus(SMBusABC):
         is emitted and then removed from the emitter.
         """
         _log.debug("Closing SMBus on bus %s", self._bus)
-        try:
-            self._smbus.close()
-        except TimeoutError as err:
-            _log.error("Timeout closing SMBus '%s': %s", self._bus, err)
-        except OSError as err:
-            _log.error("OS Error closing SMBus '%s': %s", self._bus, err)
-        except Exception:
-            _log.error("Unexpected error closing SMBus '%s'", self._bus, exc_info=True)
-        finally:
-            self.emitter.emit("close", self)
-            self.emitter.off("close")
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            try:
+                self._smbus.close()
+            except TimeoutError as err:
+                _log.error("Timeout closing SMBus '%s': %s", self._bus, err)
+            except OSError as err:
+                _log.error("OS Error closing SMBus '%s': %s", self._bus, err)
+            except Exception:
+                _log.error(
+                    "Unexpected error closing SMBus '%s'", self._bus, exc_info=True
+                )
+        # Manager callbacks can acquire their own lock while another caller is
+        # opening a bus. Do not hold the transaction lock across callbacks.
+        self.emitter.emit("close", self)
+        self.emitter.off("close")
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("I2C bus is closed")
 
     @RETRY_DECORATOR
     def enable_pec(self, enable: bool = False) -> None:
@@ -89,7 +103,9 @@ class I2CBus(SMBusABC):
             enable: Whether to enable PEC.
         """
         _log.debug("Setting PEC to %s", enable)
-        self._smbus.enable_pec(enable)
+        with self._lock:
+            self._ensure_open()
+            self._smbus.enable_pec(enable)
 
     @RETRY_DECORATOR
     def write_quick(self, i2c_addr: int, force: Optional[bool] = None) -> None:
@@ -101,7 +117,9 @@ class I2CBus(SMBusABC):
             force: Optional override for force behavior.
         """
         _log.debug("write_quick: addr=%s, force=%s", i2c_addr, force)
-        self._smbus.write_quick(i2c_addr, force)
+        with self._lock:
+            self._ensure_open()
+            self._smbus.write_quick(i2c_addr, force)
 
     @RETRY_DECORATOR
     def read_byte(self, i2c_addr: int, force: Optional[bool] = None) -> int:
@@ -116,7 +134,9 @@ class I2CBus(SMBusABC):
             The byte value read from the device.
         """
         _log.debug("read_byte: addr=%s, force=%s", i2c_addr, force)
-        result = self._smbus.read_byte(i2c_addr, force)
+        with self._lock:
+            self._ensure_open()
+            result = self._smbus.read_byte(i2c_addr, force)
         _log.debug("read_byte result: %s", result)
         return result
 
@@ -133,7 +153,9 @@ class I2CBus(SMBusABC):
             force: Optional override for force behavior.
         """
         _log.debug("write_byte: addr=%s, value=%s, force=%s", i2c_addr, value, force)
-        self._smbus.write_byte(i2c_addr, value, force)
+        with self._lock:
+            self._ensure_open()
+            self._smbus.write_byte(i2c_addr, value, force)
 
     @RETRY_DECORATOR
     def read_byte_data(
@@ -153,7 +175,9 @@ class I2CBus(SMBusABC):
         _log.debug(
             "Read_byte_data: addr=%s, register=%s, force=%s", i2c_addr, register, force
         )
-        result = self._smbus.read_byte_data(i2c_addr, register, force)
+        with self._lock:
+            self._ensure_open()
+            result = self._smbus.read_byte_data(i2c_addr, register, force)
         _log.debug("read_byte_data result: %s", result)
         return result
 
@@ -177,7 +201,9 @@ class I2CBus(SMBusABC):
             value,
             force,
         )
-        self._smbus.write_byte_data(i2c_addr, register, value, force)
+        with self._lock:
+            self._ensure_open()
+            self._smbus.write_byte_data(i2c_addr, register, value, force)
 
     @RETRY_DECORATOR
     def read_word_data(
@@ -197,7 +223,9 @@ class I2CBus(SMBusABC):
         _log.debug(
             "read_word_data: addr=%s, register=%s, force=%s", i2c_addr, register, force
         )
-        result = self._smbus.read_word_data(i2c_addr, register, force)
+        with self._lock:
+            self._ensure_open()
+            result = self._smbus.read_word_data(i2c_addr, register, force)
         _log.debug("read_word_data result: %s", result)
         return result
 
@@ -221,7 +249,9 @@ class I2CBus(SMBusABC):
             value,
             force,
         )
-        self._smbus.write_word_data(i2c_addr, register, value, force)
+        with self._lock:
+            self._ensure_open()
+            self._smbus.write_word_data(i2c_addr, register, value, force)
 
     @RETRY_DECORATOR
     def process_call(
@@ -246,7 +276,9 @@ class I2CBus(SMBusABC):
             value,
             force,
         )
-        result = self._smbus.process_call(i2c_addr, register, value, force)
+        with self._lock:
+            self._ensure_open()
+            result = self._smbus.process_call(i2c_addr, register, value, force)
         _log.debug("process_call result: %s", result)
         return result
 
@@ -268,7 +300,9 @@ class I2CBus(SMBusABC):
         _log.debug(
             "read_block_data: addr=%s, register=%s, force=%s", i2c_addr, register, force
         )
-        result = self._smbus.read_block_data(i2c_addr, register, force)
+        with self._lock:
+            self._ensure_open()
+            result = self._smbus.read_block_data(i2c_addr, register, force)
         _log.debug("read_block_data result: %s", result)
         return result
 
@@ -296,7 +330,9 @@ class I2CBus(SMBusABC):
             data,
             force,
         )
-        self._smbus.write_block_data(i2c_addr, register, data, force)
+        with self._lock:
+            self._ensure_open()
+            self._smbus.write_block_data(i2c_addr, register, data, force)
 
     @RETRY_DECORATOR
     def block_process_call(
@@ -325,7 +361,9 @@ class I2CBus(SMBusABC):
             data,
             force,
         )
-        result = self._smbus.block_process_call(i2c_addr, register, data, force)
+        with self._lock:
+            self._ensure_open()
+            result = self._smbus.block_process_call(i2c_addr, register, data, force)
         _log.debug("block_process_call result: %s", result)
         return result
 
@@ -352,7 +390,9 @@ class I2CBus(SMBusABC):
             length,
             force,
         )
-        result = self._smbus.read_i2c_block_data(i2c_addr, register, length, force)
+        with self._lock:
+            self._ensure_open()
+            result = self._smbus.read_i2c_block_data(i2c_addr, register, length, force)
         _log.debug("read_i2c_block_data result: %s", result)
         return result
 
@@ -380,7 +420,9 @@ class I2CBus(SMBusABC):
             data,
             force,
         )
-        self._smbus.write_i2c_block_data(i2c_addr, register, data, force)
+        with self._lock:
+            self._ensure_open()
+            self._smbus.write_i2c_block_data(i2c_addr, register, data, force)
 
     @RETRY_DECORATOR
     def i2c_rdwr(self, *i2c_msgs: "i2c_msg") -> None:
@@ -391,11 +433,15 @@ class I2CBus(SMBusABC):
             *i2c_msgs: One or more message objects describing the transactions.
         """
         _log.debug("i2c_rdwr: messages=%s", i2c_msgs)
-        return self._smbus.i2c_rdwr(*i2c_msgs)
+        with self._lock:
+            self._ensure_open()
+            return self._smbus.i2c_rdwr(*i2c_msgs)
 
     def __enter__(self) -> "I2CBus":
         _log.debug("Entering I2CBus context manager")
-        self._smbus.__enter__()
+        with self._lock:
+            self._ensure_open()
+            self._smbus.__enter__()
         return self
 
     def __exit__(
@@ -405,7 +451,7 @@ class I2CBus(SMBusABC):
         exc_tb: Optional[TracebackType],
     ) -> None:
         """
-        Exit context manager and perform cleanup by delegating to the SMBus.
+        Close the bus and notify its manager when leaving the context.
         """
         _log.debug("Exiting I2CBus context manager")
-        self._smbus.__exit__(exc_type=exc_type, exc_val=exc_val, exc_tb=exc_tb)
+        self.close()

{robot_hat-3.3.2 → robot_hat-3.3.3}/robot_hat/i2c/smbus_manager.py

@@ -28,7 +28,7 @@ class SMBusManager:
     def _on_bus_close(cls, closed_bus: "I2CBus") -> None:
         normalized_bus = cls._normalize_bus(closed_bus._bus)
         with cls._lock:
-            if normalized_bus in cls._instances:
+            if cls._instances.get(normalized_bus) is closed_bus:
                 _log.debug("Removing closed bus %s from instances", normalized_bus)
                 cls._instances.pop(normalized_bus, None)
 

{robot_hat-3.3.2 → robot_hat-3.3.3}/robot_hat/motor/gpio_dc_motor.py

@@ -2,9 +2,9 @@
 This module is intended for cases where a motor is controlled directly via
 GPIO pins without I²C.
 
-It typically uses one or more GPIO pins to drive the motor in forward or
-reverse direction, and, if available, an RPi.GPIO.PWM instance for speed
-control.
+gpiozero controls forward and reverse direction outputs, with optional PWM
+on those outputs for speed control. A separate optional active-high enable
+output gates the motor driver.
 
 This class is suitable when the motor driver board (e.g., a
 Waveshare/MC33886-based module) does not require or use an external PWM driver
@@ -12,7 +12,8 @@ and is controlled entirely through direct GPIO calls.
 """
 
 import logging
-from typing import Optional, Union, cast
+from threading import RLock
+from typing import Callable, Optional, Union, cast
 
 from robot_hat.data_types.config.motor import MotorDirection
 from robot_hat.interfaces.motor_abc import MotorABC
@@ -27,8 +28,8 @@ class GPIODCMotor(MotorCalibration, MotorABC):
     This implementation controls a motor using direct GPIO control. It drives the motor by toggling
     GPIO output pins for forward and reverse directions.
 
-    If speed control is desired and available, an RPi.GPIO.PWM object can be
-    used in conjunction with the direction pins.
+    gpiozero PWMOutputDevice instances provide speed control on the direction
+    pins when PWM is enabled.
 
     Use Case:
       - Ideal for hardware setups (like the Waveshare MC33886 module) that do not rely on a dedicated PWM
@@ -37,7 +38,8 @@ class GPIODCMotor(MotorCalibration, MotorABC):
 
     Example wiring:
       - Two GPIO pins are used for direction control (one for forward, one for reverse).
-      - Optionally, a third GPIO pin can be used to generate PWM (using RPi.GPIO.PWM) for variable speed.
+      - An optional third GPIO pin is a digital active-high enable, held low
+        while the motor is stopped.
     """
 
     def __init__(
@@ -57,14 +59,18 @@ class GPIODCMotor(MotorCalibration, MotorABC):
         Args:
             forward_pin: GPIO pin for forward direction.
             backward_pin: GPIO pin for reverse direction.
-            pwm_pin: PWM (enable) pin for speed control.
-            pwm: Whether to construct PWM Output Device instances, allowing both direction
-                 and speed control.
+            pwm_pin: Optional digital active-high enable pin for the motor driver.
+            pwm: Whether to use PWM on the direction outputs for variable speed.
             calibration_direction: Initial calibration for the motor direction (+1 or -1).
             calibration_speed_offset: Adjustment for the motor speed calibration.
             name: Optional identifier for the motor for logging and debugging.
         """
-        from gpiozero import Motor
+        from gpiozero import DigitalOutputDevice, Motor
+
+        self._lock = RLock()
+        self._closed = False
+        self._motor: Optional[Motor] = None
+        self._enable: Optional[DigitalOutputDevice] = None
 
         super().__init__(
             calibration_direction=calibration_direction,
@@ -75,9 +81,14 @@ class GPIODCMotor(MotorCalibration, MotorABC):
         self.name = name or f"F{forward_pin}-B{backward_pin}-P{pwm_pin}"
         self._speed: float = 0
         self._applied_speed: float = 0
-        self._motor = Motor(
-            forward=forward_pin, backward=backward_pin, enable=pwm_pin, pwm=pwm
-        )
+        try:
+            # Hold the bridge disabled while its direction outputs are acquired.
+            if pwm_pin is not None:
+                self._enable = DigitalOutputDevice(pwm_pin, initial_value=False)
+            self._motor = Motor(forward=forward_pin, backward=backward_pin, pwm=pwm)
+        except Exception:
+            self.close()
+            raise
         _log.debug(
             f"Initialized motor {self.name} with forward_pin={forward_pin}, backward_pin={backward_pin}, pwm_pin={pwm_pin}"
         )
@@ -115,6 +126,20 @@ class GPIODCMotor(MotorCalibration, MotorABC):
         Args:
             speed: Target speed percentage within [-max_speed, max_speed].
         """
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("Motor is closed")
+            try:
+                self._set_speed(speed)
+            except Exception:
+                try:
+                    self.stop()
+                except Exception:
+                    _log.exception("Failed to stop motor after a command failure")
+                raise
+
+    def _set_speed(self, speed: float) -> None:
+        assert self._motor is not None
         logical_speed, applied_speed = self.apply_calibration(speed, self.max_speed)
         if applied_speed == 0:
             self.stop()
@@ -122,6 +147,9 @@ class GPIODCMotor(MotorCalibration, MotorABC):
 
         applied_sign = 1 if applied_speed > 0 else -1
 
+        if self._enable is not None:
+            self._enable.off()
+
         if applied_sign > 0:
             command = self._motor.forward
             log_direction = "forward"
@@ -144,6 +172,9 @@ class GPIODCMotor(MotorCalibration, MotorABC):
             command(1)
             applied_speed = applied_sign * self.max_speed
 
+        if self._enable is not None:
+            self._enable.on()
+
         self._speed = logical_speed
         self._applied_speed = applied_speed
 
@@ -151,24 +182,72 @@ class GPIODCMotor(MotorCalibration, MotorABC):
         """
         Stop the motor.
         """
-        _log.debug("Motor stopped.")
-        self._motor.stop()
-        self._speed = 0
-        self._applied_speed = 0
+        with self._lock:
+            if self._closed:
+                return
+            actions: list[Callable[[], None]] = []
+            if self._enable is not None:
+                actions.append(self._enable.off)
+            if self._motor is not None:
+                actions.append(self._motor.stop)
+            first_error: Exception | None = None
+            for action in actions:
+                try:
+                    action()
+                except Exception as error:
+                    if first_error is None:
+                        first_error = error
+            if first_error is not None and self._motor is not None:
+                from gpiozero import OutputDevice
+
+                # A composite stop can fail before reaching its second output.
+                for output in (
+                    self._motor.forward_device,
+                    self._motor.backward_device,
+                ):
+                    try:
+                        if isinstance(output, OutputDevice):
+                            output.off()
+                    except Exception:
+                        _log.exception("Failed to clear motor direction output")
+            if first_error is not None:
+                raise first_error
+            self._speed = 0
+            self._applied_speed = 0
+            _log.debug("Motor stopped.")
 
     def close(self) -> None:
         """
         Close the underlying resources.
         """
-        _log.debug("Closing motor.")
-        if self._motor and hasattr(self._motor, "close"):
-            self._motor.close()
+        with self._lock:
+            if self._closed:
+                return
+            first_error: Exception | None = None
+            actions: list[Callable[[], None]] = [self.stop]
+            if self._motor is not None:
+                actions.append(self._motor.close)
+            if self._enable is not None:
+                actions.append(self._enable.close)
+            for action in actions:
+                try:
+                    action()
+                except Exception as error:
+                    if first_error is None:
+                        first_error = error
+                    _log.exception("Failed to stop or close motor output")
+            self._closed = True
+            if first_error is not None:
+                raise first_error
 
     def __del__(self) -> None:
         """
         Destructor method.
         """
-        self.close()
+        try:
+            self.close()
+        except Exception:
+            _log.exception("Failed to close motor during destruction")
 
 
 def main() -> None: