diff --git a/CHANGELOG.md b/CHANGELOG.md index f78e480..e2f41f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ - Improved presentation and docstrings of the ``ubuiltins`` and other MicroPython modules - Moved the random numbers example for Move Hub to the Move Hub page. +- Moved `done()`, `stalled()`, `load()` from `Control` to `Motor` object. ## 3.2.0b5 - 2022-11-11 diff --git a/doc/main/pupdevices/motor.rst b/doc/main/pupdevices/motor.rst index 698f38c..674a679 100644 --- a/doc/main/pupdevices/motor.rst +++ b/doc/main/pupdevices/motor.rst @@ -24,6 +24,10 @@ Motors with rotation sensors .. automethod:: pybricks.pupdevices.Motor.reset_angle + .. automethod:: pybricks.pupdevices.Motor.load + + .. automethod:: pybricks.pupdevices.Motor.stalled + .. rubric:: Stopping .. automethod:: pybricks.pupdevices.Motor.stop @@ -32,10 +36,14 @@ Motors with rotation sensors .. automethod:: pybricks.pupdevices.Motor.hold - .. rubric:: Action + .. rubric:: Running forever .. automethod:: pybricks.pupdevices.Motor.run + .. automethod:: pybricks.pupdevices.Motor.dc + + .. rubric:: Running by a fixed amount + .. automethod:: pybricks.pupdevices.Motor.run_time .. automethod:: pybricks.pupdevices.Motor.run_angle @@ -46,32 +54,20 @@ Motors with rotation sensors .. automethod:: pybricks.pupdevices.Motor.run_until_stalled - .. automethod:: pybricks.pupdevices.Motor.dc + .. automethod:: pybricks.pupdevices.Motor.done .. _settings: - .. rubric:: Motor status - - .. attribute:: control.scale - - Number of degrees that the motor turns to complete one degree at the - output of the gear train. This is the gear ratio determined from the - ``gears`` argument when initializing the motor. - - .. automethod:: pybricks.pupdevices.Motor.control.done - - .. automethod:: pybricks.pupdevices.Motor.control.stalled - - .. automethod:: pybricks.pupdevices.Motor.control.load - .. rubric:: Motor settings + .. automethod:: pybricks.pupdevices.Motor.settings + + .. rubric:: Control settings + You can only change these settings while the controller is stopped. For example, you can change them at the start of your program. Alternatively, first call :meth:`stop() `, and then change the settings. - .. automethod:: pybricks.pupdevices.Motor.settings - .. automethod:: pybricks.pupdevices.Motor.control.limits .. automethod:: pybricks.pupdevices.Motor.control.pid @@ -80,6 +76,12 @@ Motors with rotation sensors .. automethod:: pybricks.pupdevices.Motor.control.stall_tolerances + .. attribute:: control.scale + + Number of degrees that the motor turns to complete one degree at the + output of the gear train. This is the gear ratio determined from the + ``gears`` argument when initializing the motor. + Initialization examples ----------------------- diff --git a/src/pybricks/_common.py b/src/pybricks/_common.py index bc1bfb5..278d93c 100644 --- a/src/pybricks/_common.py +++ b/src/pybricks/_common.py @@ -299,40 +299,6 @@ class Control: minimum ``speed`` before we say it is stalled. """ - def stalled(self) -> bool: - """stalled() -> bool - - Checks if the controller is currently stalled. - - A controller is stalled when it cannot reach the target speed or - position, even with the maximum actuation signal. - - Returns: - ``True`` if the controller is stalled, ``False`` if not. - """ - - def done(self) -> bool: - """done() -> bool - - Checks if an ongoing command or maneuver is done. - - Returns: - ``True`` if the command is done, ``False`` if not. - """ - - def load(self) -> int: - """load() -> int: mNm - - Estimates the load based on the torque required to maintain the - specified speed or angle. - - When coasting, braking, or controlling the duty cycle manually, the - load cannot be estimated in this way. Then this method returns zero. - - Returns: - The load torque. It returns 0 if control is not active. - """ - class Motor(DCMotor): """Generic class to control motors with built-in rotation sensors.""" @@ -394,6 +360,27 @@ class Motor(DCMotor): """ + def stalled(self) -> bool: + """stalled() -> bool + + Checks if the motor is currently stalled. + + It is stalled when it cannot reach the target speed or position, even + with the maximum actuation signal. + + Returns: + ``True`` if the motor is stalled, ``False`` if not. + """ + + def load(self) -> int: + """load() -> int: mNm + + Estimates the load that holds back the motor when it tries to move. + + Returns: + The load torque. + """ + def reset_angle(self, angle: Optional[Number]) -> None: """ reset_angle(angle) @@ -505,6 +492,15 @@ class Motor(DCMotor): Angle at which the motor becomes stalled. """ + def done(self) -> bool: + """done() -> bool + + Checks if an ongoing command or maneuver is done. + + Returns: + ``True`` if the command is done, ``False`` if not. + """ + def track_target(self, target_angle: Number) -> None: """track_target(target_angle)