Class Motor
The motor class provides a uniform interface for using motors with
Declaration
source linkDocumentation
positional and directional feedback such as the EV3 and NXT motors. This feedback allows for precise control of the motors. This is the most common type of motor, so we just call it motor.
Methods
▶ def __init__(self, address=None, name_pattern=SYSTEM_DEVICE_NAME_CONVENTION, ...) overrideinherited doc Spin through the Linux sysfs class for the device type and find a device that matches the provided name pattern and attributes (if any).
def __init__(
self,
address=None,
name_pattern=SYSTEM_DEVICE_NAME_CONVENTION,
name_exact=False,
**kwargs,
)
This method overrides ev3dev2.Device.__init__.
- Parameters:
- class_name: class name of the device, a subdirectory of /sys/class.
For example, 'tacho-motor'.
- name_pattern: pattern that device name should match.
For example, 'sensor*' or 'motor*'. Default value: '*'.
- name_exact: when True, assume that the name_pattern provided is the
exact device name and use it directly.
- keyword arguments: used for matching the corresponding device
attributes. For example, address='outA', or driver_name=['lego-ev3-us', 'lego-nxt-us']. When argument value is a list, then a match against any entry of the list is enough.
Example:
d = ev3dev.Device('tacho-motor', address='outA')
s = ev3dev.Device('lego-sensor', driver_name=['lego-ev3-us', 'lego-nxt-us'])If there was no valid connected device, an error is thrown.
Overrides
This method is overriden in:
▷ def address(self) @property Returns the name of the port that this motor is connected to.
@property
def address(self)
▷ def command(self) @property Sends a command to the motor controller. See ``commands`` for a list of possible values.
@property
def command(self)
▷ def command(self, value) @command.setter @command.setter
def command(
self,
value,
)
▶ def commands(self) @property Returns a list of commands that are supported by the motor controller. Possible values are ``run-forever``, ``run-to-abs-pos``, ``run-to-rel-pos``, ``run-timed``, ``run-direct``, ``stop`` and ``reset``. Not all commands may be supported.
@property
def commands(self)
run-forever will cause the motor to run until another command is sent.
run-to-abs-pos will run to an absolute position specified by position_sp and then stop using the action specified in stop_action.
run-to-rel-pos will run to a position relative to the current position value. The new position will be current position + position_sp. When the new position is reached, the motor will stop using the action specified by stop_action.
run-timed will run the motor for the amount of time specified in time_sp and then stop the motor using the action specified by stop_action.
run-direct will run the motor at the duty cycle specified by duty_cycle_sp. Unlike other run commands, changing duty_cycle_sp while running will take effect immediately.
stop will stop any of the run commands before they are complete using the action specified by stop_action.
reset will reset all of the motor parameter attributes to their default value. This will also have the effect of stopping the motor.
▷ def count_per_m(self) @property Returns the number of tacho counts in one meter of travel of the motor. Tacho counts are used by the position and speed attributes, so you can use this value to convert from distance to tacho counts. (linear motors only)
@property
def count_per_m(self)
▷ def count_per_rot(self) @property Returns the number of tacho counts in one rotation of the motor. Tacho counts are used by the position and speed attributes, so you can use this value to convert rotations or degrees to tacho counts. (rotation motors only)
@property
def count_per_rot(self)
@property
def degrees(self)
▷ def driver_name(self) @property Returns the name of the driver that provides this tacho motor device.
@property
def driver_name(self)
▷ def duty_cycle(self) @property Returns the current duty cycle of the motor. Units are percent. Values are -100 to 100.
@property
def duty_cycle(self)
▷ def duty_cycle_sp(self) @property Writing sets the duty cycle setpoint. Reading returns the current value. Units are in percent. Valid values are -100 to 100. A negative value causes the motor to rotate in reverse.
@property
def duty_cycle_sp(self)
@duty_cycle_sp.setter
def duty_cycle_sp(
self,
value,
)
▷ def full_travel_count(self) @property Returns the number of tacho counts in the full travel of the motor. When combined with the ``count_per_m`` atribute, you can use this value to calculate the maximum travel distance of the motor. (linear motors only)
@property
def full_travel_count(self)
▷ def is_holding(self) @property The motor is not turning, but rather attempting to hold a fixed position.
@property
def is_holding(self)
▷ def is_overloaded(self) @property The motor is turning, but cannot reach its ``speed_sp``.
@property
def is_overloaded(self)
▷ def is_ramping(self) @property The motor is ramping up or down and has not yet reached a constant output level.
@property
def is_ramping(self)
▷ def is_running(self) @property Power is being sent to the motor.
@property
def is_running(self)
▷ def is_stalled(self) @property The motor is not turning when it should be.
@property
def is_stalled(self)
▷ def max_speed(self) @property Returns the maximum value that is accepted by the ``speed_sp`` attribute. This may be slightly different than the maximum speed that a particular motor can reach - it's the maximum theoretical speed.
@property
def max_speed(self)
▷ def off(self, brake=True) ▶ def on(self, speed, brake=True, block=False) Rotate the motor at ``speed`` for forever
speed can be a percentage or a :class:`ev3dev2.motor.SpeedValue` object, enabling use of other units.
System Message: ERROR/3 (<string>, line 1); backlink
Unknown interpreted text role "class".
Note that block is False by default, this is different from the other on_for_XYZ methods.
▶ def on_for_degrees(self, speed, degrees, brake=True, block=True) Rotate the motor at ``speed`` for ``degrees``
▶ def on_for_rotations(self, speed, rotations, brake=True, block=True) Rotate the motor at ``speed`` for ``rotations``
▶ def on_for_seconds(self, speed, seconds, brake=True, block=True) Rotate the motor at ``speed`` for ``seconds``
▶ def on_to_position(self, speed, position, brake=True, block=True) Rotate the motor at ``speed`` to ``position``
▶ def polarity(self) @property Sets the polarity of the motor. With ``normal`` polarity, a positive duty
@property
def polarity(self)
cycle will cause the motor to rotate clockwise. With inversed polarity, a positive duty cycle will cause the motor to rotate counter-clockwise. Valid values are normal and inversed.
▷ def polarity(self, value) @polarity.setter @polarity.setter
def polarity(
self,
value,
)
▶ def position(self) @property Returns the current position of the motor in pulses of the rotary
@property
def position(self)
encoder. When the motor rotates clockwise, the position will increase. Likewise, rotating counter-clockwise causes the position to decrease. Writing will set the position to that value.
▷ def position(self, value) @position.setter @position.setter
def position(
self,
value,
)
▷ def position_d(self) @property The derivative constant for the position PID.
@property
def position_d(self)
@position_d.setter
def position_d(
self,
value,
)
▷ def position_i(self) @property The integral constant for the position PID.
@property
def position_i(self)
@position_i.setter
def position_i(
self,
value,
)
▷ def position_p(self) @property The proportional constant for the position PID.
@property
def position_p(self)
@position_p.setter
def position_p(
self,
value,
)
▶ def position_sp(self) @property Writing specifies the target position for the ``run-to-abs-pos`` and ``run-to-rel-pos``
@property
def position_sp(self)
commands. Reading returns the current value. Units are in tacho counts. You can use the value returned by count_per_rot to convert tacho counts to/from rotations or degrees.
@position_sp.setter
def position_sp(
self,
value,
)
▶ def ramp_down_sp(self) @property Writing sets the ramp down setpoint. Reading returns the current value. Units
@property
def ramp_down_sp(self)
are in milliseconds and must be positive. When set to a non-zero value, the motor speed will decrease from 0 to 100% of max_speed over the span of this setpoint. The actual ramp time is the ratio of the difference between the speed_sp and the current speed and max_speed multiplied by ramp_down_sp.
@ramp_down_sp.setter
def ramp_down_sp(
self,
value,
)
▶ def ramp_up_sp(self) @property Writing sets the ramp up setpoint. Reading returns the current value. Units
@property
def ramp_up_sp(self)
are in milliseconds and must be positive. When set to a non-zero value, the motor speed will increase from 0 to 100% of max_speed over the span of this setpoint. The actual ramp time is the ratio of the difference between the speed_sp and the current speed and max_speed multiplied by ramp_up_sp.
@ramp_up_sp.setter
def ramp_up_sp(
self,
value,
)
▷ def reset(self, **kwargs) Reset all of the motor parameter attributes to their default value. This will also have the effect of stopping the motor.
@property
def rotations(self)
▷ def run_direct(self, **kwargs) Run the motor at the duty cycle specified by ``duty_cycle_sp``. Unlike other run commands, changing ``duty_cycle_sp`` while running *will* take effect immediately.
▷ def run_forever(self, **kwargs) Run the motor until another command is sent.
▷ def run_timed(self, **kwargs) Run the motor for the amount of time specified in ``time_sp`` and then stop the motor using the action specified by ``stop_action``.
▷ def run_to_abs_pos(self, **kwargs) Run to an absolute position specified by ``position_sp`` and then stop using the action specified in ``stop_action``.
▶ def run_to_rel_pos(self, **kwargs) Run to a position relative to the current ``position`` value.
The new position will be current position + position_sp. When the new position is reached, the motor will stop using the action specified by stop_action.
▷ def speed(self) @property Returns the current motor speed in tacho counts per second. Note, this is not necessarily degrees (although it is for LEGO motors). Use the ``count_per_rot`` attribute to convert this value to RPM or deg/sec.
▷ def speed_d(self) @property The derivative constant for the speed regulation PID.
@property
def speed_d(self)
▷ def speed_d(self, value) @speed_d.setter @speed_d.setter
def speed_d(
self,
value,
)
▷ def speed_i(self) @property The integral constant for the speed regulation PID.
@property
def speed_i(self)
▷ def speed_i(self, value) @speed_i.setter @speed_i.setter
def speed_i(
self,
value,
)
▷ def speed_p(self) @property The proportional constant for the speed regulation PID.
@property
def speed_p(self)
▷ def speed_p(self, value) @speed_p.setter @speed_p.setter
def speed_p(
self,
value,
)
▶ def speed_sp(self) @property Writing sets the target speed in tacho counts per second used for all ``run-*``
@property
def speed_sp(self)
commands except run-direct. Reading returns the current value. A negative value causes the motor to rotate in reverse with the exception of run-to-*-pos commands where the sign is ignored. Use the count_per_rot attribute to convert RPM or deg/sec to tacho counts per second. Use the count_per_m attribute to convert m/s to tacho counts per second.
▷ def speed_sp(self, value) @speed_sp.setter @speed_sp.setter
def speed_sp(
self,
value,
)
▷ def state(self) @property Reading returns a list of state flags. Possible flags are ``running``, ``ramping``, ``holding``, ``overloaded`` and ``stalled``.
▷ def stop(self, **kwargs) Stop any of the run commands before they are complete using the action specified by ``stop_action``.
▶ def stop_action(self) @property Reading returns the current stop action. Writing sets the stop action.
@property
def stop_action(self)
The value determines the motors behavior when command is set to stop. Also, it determines the motors behavior when a run command completes. See stop_actions for a list of possible values.
@stop_action.setter
def stop_action(
self,
value,
)
▶ def stop_actions(self) @property Returns a list of stop actions supported by the motor controller.
@property
def stop_actions(self)
Possible values are coast, brake and hold. coast means that power will be removed from the motor and it will freely coast to a stop. brake means that power will be removed from the motor and a passive electrical load will be placed on the motor. This is usually done by shorting the motor terminals together. This load will absorb the energy from the rotation of the motors and cause the motor to stop more quickly than coasting. hold does not remove power from the motor. Instead it actively tries to hold the motor at the current position. If an external force tries to turn the motor, the motor will 'push back' to maintain its position.
▷ def time_sp(self) @property Writing specifies the amount of time the motor will run when using the ``run-timed`` command. Reading returns the current value. Units are in milliseconds.
@property
def time_sp(self)
▷ def time_sp(self, value) @time_sp.setter @time_sp.setter
def time_sp(
self,
value,
)
▶ def wait(self, cond, timeout=None) Blocks until ``cond(self.state)`` is ``True``. The condition is checked when there is an I/O event related to the ``state`` attribute. Exits early when ``timeout`` (in milliseconds) is reached.
Returns True if the condition is met, and False if the timeout is reached.
▶ def wait_until(self, s, timeout=None) Blocks until ``s`` is in ``self.state``. The condition is checked when there is an I/O event related to the ``state`` attribute. Exits early when ``timeout`` (in milliseconds) is reached.
Returns True if the condition is met, and False if the timeout is reached.
Example:
m.wait_until('stalled')▶ def wait_until_not_moving(self, timeout=None) Blocks until ``running`` is not in ``self.state`` or ``stalled`` is in
self.state. The condition is checked when there is an I/O event related to the state attribute. Exits early when timeout (in milliseconds) is reached.
Returns True if the condition is met, and False if the timeout is reached.
Example:
m.wait_until_not_moving()
▶ def wait_while(self, s, timeout=None) Blocks until ``s`` is not in ``self.state``. The condition is checked when there is an I/O event related to the ``state`` attribute. Exits early when ``timeout`` (in milliseconds) is reached.
Returns True if the condition is met, and False if the timeout is reached.
Example:
m.wait_while('running')