Actuators

Regular Actuators

Adafruit DC Motor Hat

class crappy.actuator.DCMotorHat(backend: str, device_address: int = 96, i2c_port: int = 1)[source]

Class for driving Adafruit’s DC motor HAT.

It can drive up to four DC motors in speed only. The acquisition of the speed has not been implemented so far. It can either rely on Adafruit’s Blinka library, or on smbus2 if used from a Raspberry Pi.

Important

As this Actuator can drive up to 4 motors simultaneously, it takes a tuple as a command, see set_speed(). Regular Actuators receive their commands as float. A Modifier can be used for converting a float command from a Generator to a tuple.

Note

The DC Motor Hat can also drive stepper motors, but this feature isn’t included here.

New in version 2.0.0.

__init__(backend: str, device_address: int = 96, i2c_port: int = 1) → None[source]

Checks the validity of the arguments.

Parameters:

backend –
Should be one of :
```
'Pi4', 'blinka'
```
The ‘Pi4’ backend is optimized but only works on boards supporting the smbus2 module, like the Raspberry Pis. The ‘blinka’ backend may be less performant and requires installing adafruit-circuitpython-motorkit and Adafruit-Blinka, but these modules are compatible with and maintained on a wide variety of boards.
device_address – The I2C address of the HAT. The default address is 0x60, but it is possible to change this setting by cutting traces on the board.
i2c_port – The I2C port over which the HAT should communicate. On most Raspberry Pi models the default I2C port is 1.

open() → None[source]: Opens the connection to the motor hat and initializes it.

set_speed(cmd: Tuple[int, float]) → None[source]

Sets the desired voltage on the selected motor.

The provided voltage should be between -12 and 12V which are the limits of the motor hat. If not, it will be silently clamped in this interval.

Warning

Unlike most Actuators, this one takes tuple as commands instead of float.

Parameters:: cmd – A tuple containing first the index of the motor to drive as an int between 1 and 5, and second the voltage to apply to the selected motor as a float.

stop() → None[source]: Simply sets the command to 0 to stop the motors.

close() → None[source]: Closes the I2C connection to the motor hat.

Fake DC Motor

class crappy.actuator.FakeDCMotor(inertia: float = 0.5, torque: float = 0.0, kv: float = 1000, rv: float = 0.4, fv: float = 2e-05, simulation_speed: float = 1, initial_speed: float = 0, initial_pos: float = 0)[source]

Emulates the behavior of a DC electric machine, driven through its input voltage.

It is mainly intended for testing scripts without requiring any hardware.

New in version 1.4.0.

Changed in version 2.0.0: Renamed from Fake_motor to FakeDCMotor

__init__(inertia: float = 0.5, torque: float = 0.0, kv: float = 1000, rv: float = 0.4, fv: float = 2e-05, simulation_speed: float = 1, initial_speed: float = 0, initial_pos: float = 0) → None[source]

Sets the instance attributes.

Parameters:

inertia – The inertia of the motor, in kg.m².
torque – A constant torque applied on the shaft of the motor in N.m.
kv – The electrical constant of the motor, in`t/min/V`.
rv – The internal solid friction coefficient of the motor, no unit.
fv – The internal fluid friction coefficient of the motor, no unit.
simulation_speed –
Speed factor of the simulation, to speed it up or slow it down.

Changed in version 2.0.0: renamed from sim_speed to simulation_speed
initial_speed – The initial speed of the motor, in RPM.
initial_pos – The initial position of the motor, in turns.

open() → None[source]: Sets the variables describing the state of the motor.

get_speed() → float[source]: Return the speed of the motor, in RPM.

get_position() → float[source]: Returns the position of the motor, in rounds.

Changed in version 1.5.2: renamed from get_pos to get_position

set_speed(volt: float) → None[source]: Sets the command of the motor, in volts.

stop() → None

This method should stop all movements of the actuator, and if possible make sure that the actuator cannot move anymore.

That includes for example de-energizing the actuator, or switching it to a locked state.

This method will only be called once at the very end of the test. The default behavior is to call set_speed() to set the speed to 0. This method doesn’t need to be overriden if the actuator doesn’t have any feature for stopping other than speed control.

New in version 2.0.0.

close() → None

This method should perform any action required for properly ending the test and closing the communication with hardware.

It will be called when the associated Machine receives the order to stop (usually because the user hit CTRL+C, or because a Generator Block reached the end of its path, or because an exception was raised in any of the Blocks).

It is fine for this method not to perform anything.

New in version 2.0.0.

Fake Stepper Motor

class crappy.actuator.FakeStepperMotor(steps_per_mm: float = 100, microsteps: int = 256, acceleration: float = 20, max_speed: float = 10)[source]

This Actuator can emulate the behavior of a stepper motor used as a linear actuator.

It can drive the motor either in speed or in position, unlike the other fake Actuator FakeDCMotor that can only be driven in speed. This class can also return the current speed and position of the motor.

Internally, the behavior of the motor is emulated in a separate Thread and is based on the fundamental equations of the constantly accelerated linear movement.

New in version 2.0.0.

__init__(steps_per_mm: float = 100, microsteps: int = 256, acceleration: float = 20, max_speed: float = 10) → None[source]

Sets the arguments and initializes the parent class.

Parameters:

steps_per_mm – The number of full steps needed for the motor to move by 1 mm. The higher this value, the more precise the motor is but the lower the maximum achievable speed.
microsteps – The number of microsteps into which a full step is divided. The higher this value, the more precise the resolution of the motor, but the lower the maximum achievable speed.
acceleration – The maximum acceleration the motor can achieve, in mm/s². In this demo Actuator, this parameter only has an incidence on the responsiveness of the motor.
max_speed – The maximum achievable speed of the motor, in mm/s.

open() → None[source]: Starts the Thread emulating the stepper motor.

set_position(position: float, speed: float | None) → None[source]

Sets the target position that the motor should reach.

It first converts the given position from mm to steps. If a speed value is given, also sets the maximum speed to the given value.

Parameters:

position – The target position to reach, in mm.
speed – Optionally, the maximum speed at which to move for moving to the target position, in mm/s. If the current and target position are too close, the motor might not reach this position during its movement.

set_speed(speed: float) → None[source]

Sets the target speed that the motor should reach.

It first converts the speed to steps/s, and also checks that the command is consistent with the given maximum speed.

Parameters:: speed – The target speed of the motor, in mm/s. Can be negative.

get_speed() → float[source]: Returns the current speed of the motor, in mm/s.

get_position() → float[source]: Returns the current position of the motor, in mm.

stop() → None[source]: Instantly sets the speed and the speed command to 0.

close() → None[source]: Stops the Thread emulating the stepper motor if it was started.

JVL Mac140

class crappy.actuator.JVLMac140(port: str = '/dev/ttyUSB0')[source]

This class allows driving JVL’s MAC140 integrated servomotor in speed or in position.

It interfaces with the servomotor over a serial connection.

New in version 1.4.0.

Changed in version 2.0.0: renamed class from Biotens to JVLMac140

__init__(port: str = '/dev/ttyUSB0') → None[source]

Initializes the parent class.

Parameters:: port – Path to the serial port to use for communication.

Removed in version 2.0.0: baudrate argument

open() → None[source]: Initializes the serial connection and clears any serial error.

set_speed(speed: float) → None[source]

Sets the desired speed on the actuator.

Parameters:: speed – The target speed, in mm/min.

set_position(position: float, speed: float | None) → None[source]

Sets the desired target position on the servomotor.

Parameters:

position – The target position, in mm.
speed –
The target speed for reaching the desired position, in mm/min. The speed must be given, otherwise an exception is raised.

Changed in version 2.0.0: speed is now a mandatory argument

get_position() → float[source]: Reads and returns the current position of the servomotor, in mm.

Changed in version 1.5.2: renamed from get_pos to get_position

stop() → None[source]: Sends a command for stopping the servomotor.

close() → None[source]: Closes the serial connection to the servomotor.

reset_position() → None[source]: Makes the servomotor reach its limit position, in order to re-calibrate the position readout.

Kollmorgen ServoStar 300

class crappy.actuator.ServoStar300(port: str, baudrate: int = 38400, mode: str = 'serial')[source]

This class can drive a Kollmorgen ServoStar 300 servomotor conditioner in position, and set it to the analog or serial driving mode.

It communicates with the servomotor over a serial connection. The Biaxe Actuator can drive the same hardware, but only in speed.

New in version 1.4.0.

Changed in version 2.0.0: renamed from Servostar to ServoStar300

__init__(port: str, baudrate: int = 38400, mode: str = 'serial') → None[source]

Sets the instance attributes and initializes the parent class.

Parameters:

port –
Path to the serial port used for communication.

Changed in version renamed: from device to port
baudrate – The serial baud rate to use, as an int.
mode – The driving mode to use when starting the test. Can be ‘analog’ or ‘serial’. It can be changed afterward while the test is running, by sending the right command.

open() → None[source]: Initializes the serial connection and sets the desired driving mode.

set_position(pos: float | bool, speed: float | None) → None[source]

Sets the target position for the motor.

Also allows switching to the serial or analog driving mode if the target position is a bool. The acceleration and deceleration are set to 200.

Parameters:

pos – The target position to reach, as a float. Alternatively, a value of True sets the driving mode to serial, and False sets the driving mode to analog.
speed –
The speed at which the actuator should reach its target position. If no speed is specified, the default is 20000.

Changed in version 2.0.0: speed is now a mandatory argument

Removed in version 2.0.0: acc and dec arguments

get_position() → float | None[source]: Reads and returns the current position of the motor.

Changed in version 1.5.2: renamed from get_pos to get_position

stop() → None[source]: Sends a command for stopping the motor.

close() → None[source]: Closes the serial connection.

Newport TRA6PPD

class crappy.actuator.NewportTRA6PPD(baudrate: int = 57600, port: str = '/dev/ttyUSB0')[source]

Drives the Newport TRA6PPD linear actuator in position.

Warning

This actuator cannot handle a high serial messages rate. It is recommended to set the frequency of the corresponding Machine Block to a few dozen Hz at most.

Note

This Actuator ignores new position commands while it is moving.

New in version 1.5.10.

Changed in version 2.0.0: renamed from TRA6PPD to NewportTRA6PPD

__init__(baudrate: int = 57600, port: str = '/dev/ttyUSB0') → None[source]

Sets the instance attributes and initializes the parent class.

Parameters:

baudrate – The baudrate for the serial connection.
port – Path to the port to use for serial communication.

open() → None[source]: Resets the device and performs homing.

set_position(position: float, speed: float | None) → None[source]

Sends the actuator a command to reach a given position.

The command is ignored if the actuator is already moving.

Parameters:

position – The position to reach. Should be between 0 and 6 mm.
speed – The speed at which the actuator should move. Should be between 0 and 0.2 mm/s. If None is received, the default is 0.2 mm/s.

get_position() → float[source]

Reads the current position.

Returns:: Current position of the motor.

close() → None[source]: Closes the serial port.

stop() → None[source]: Stops the motor and sets the device to “disable” state.

Oriental ARD-K

class crappy.actuator.OrientalARDK(baudrate: int = 115200, port: str = '/dev/ttyUSB0', gain: float = 14.285714285714285)[source]

This class can drive an Oriental Motor’s ARD-K stepper motor driver in speed or in position.

It communicates with the stepper motor over a serial connection. This class was designed so that the Machine Block drives several of its instances at a time, corresponding to different axes to drive.

New in version 1.4.0.

Changed in version 2.0.0: renamed from Oriental to OrientalARDK

__init__(baudrate: int = 115200, port: str = '/dev/ttyUSB0', gain: float = 14.285714285714285) → None[source]

Sets the instance attributes and initializes the parent class.

Parameters:

baudrate – The baudrate to use for the serial communication.
port – The path to the serial port to use for communication.
gain – The gain to apply to speed commands, in mm/min. The default value corresponds to 0.07mm/min for a command value of 1.

open() → None[source]: Opens the serial connection to the motor and initializes the motor.

set_speed(cmd: float) → None[source]

Sets the target speed for the motor.

Also manages the sign of the speed, i.e. the direction of the movement. Features a check to avoid sending the same speed command multiple times.

Parameters:: cmd – The target speed value, no units. The actual speed reached by the motor in mm/min depends on the gain that was set.

set_position(position: float, speed: float | None) → None[source]

Sets the target position for the motor.

Parameters:

position – The target position to reach, in arbitrary units.
speed –
The speed to use for reaching the target position, in arbitrary units. A speed must be given, otherwise an exception is raised.

Changed in version 2.0.0: speed is now a mandatory argument

get_position() → float[source]: Reads and returns the current position of the motor.

Changed in version 1.5.2: renamed from get_pos to get_position

stop() → None[source]: Sends a command for stopping the motor.

close() → None[source]: Closes the serial connection to the motor.

Phidget Stepper4A

class crappy.actuator.Phidget4AStepper(steps_per_mm: float, current_limit: float, max_acceleration: float | None = None, remote: bool = False, absolute_mode: bool = False, reference_pos: float = 0, switch_ports: Tuple[int, ...] = (), save_last_pos: bool = False, save_pos_folder: str | Path | None = None)[source]

This class can drive Phidget’s 4A Stepper module in speed or in position.

It relies on the Phidget22 module to communicate with the motor driver. The driver can deliver up to 4A to the motor, and uses 16 microsteps by default. Its acquisition rate is set to 10 values per second in this class.

The distance unit is the mm and the time unit is the s, so speeds are in mm/s and accelerations in mm/s².

New in version 2.0.3.

__init__(steps_per_mm: float, current_limit: float, max_acceleration: float | None = None, remote: bool = False, absolute_mode: bool = False, reference_pos: float = 0, switch_ports: Tuple[int, ...] = (), save_last_pos: bool = False, save_pos_folder: str | Path | None = None) → None[source]

Sets the args and initializes the parent class.

Parameters:

steps_per_mm – The number of steps necessary to move by 1 mm. This value is used to set a conversion factor on the driver, so that it can be driven in mm and s units.
current_limit – The maximum current the driver is allowed to deliver to the motor, in A .
max_acceleration – If given, sets the maximum acceleration the motor is allowed to reach in mm/s².
remote – Set to True to drive the stepper via a network VINT Hub, or to False to drive it via a USB VINT Hub.
absolute_mode –
If True, the target position of the motor will be calculated from a reference position. If False, the target position of the motor will be calculated from its current position.

New in version 2.0.4.
reference_pos –
The position considered as the reference position at the beginning of the test. Only takes effect if absolute_mode is True.

New in version 2.0.4.
switch_ports –
The indexes of the VINT Hub ports where the switches are connected.

New in version 2.0.4.
save_last_pos –
If True, the last position of the actuator will be saved in a .npy file.

New in version 2.0.4.
save_pos_folder –
The path to the folder where to save the last position of the motor. Only takes effect if save_last_pos is True.

New in version 2.0.4.

open() → None[source]: Sets up the connection to the motor driver as well as the various callbacks, and waits for the motor driver to attach.

set_speed(speed: float) → None[source]

Sets the requested speed for the motor.

Switches to the correct driving mode if needed.

Parameters:: speed – The speed to reach, in mm/s.

set_position(position: float, speed: float | None = None) → None[source]

Sets the requested position for the motor.

Switches to the correct driving mode if needed.

Parameters:

position – The position to reach, in mm.
speed – If not None, the speed to use for moving to the desired position.

get_speed() → float | None[source]: Returns the last known speed of the motor.

get_position() → float | None[source]: Returns the last known position of the motor.

stop() → None[source]: Deenergizes the motor.

close() → None[source]: Closes the connection to the motor.

Pololu Tic

class crappy.actuator.PololuTic(steps_per_mm: float, current_limit: float, step_mode: int | str = 8, max_accel: float = 20, t_shutoff: float = 0, config_file: str | None = None, serial_number: str | None = None, model: str | None = None, reset_command_timeout: bool = True, backend: str = 'USB', unrestricted_current_limit: bool = False, pin_function: Dict[str, str] | None = None, pin_polarity: Dict[str, str] | None = None)[source]

Class for controlling Pololu’s Tic stepper motor divers.

The PololuTic Actuator block is meant for controlling a Pololu Tic stepper motor driver. It can be driven in both speed and position. Several Tic models are supported. The length unit is the millimeter (mm), and time unit is the second (s).

Important

Only for Linux users: In order to drive the Tic, the appropriate udev rule should be set. This is done automatically when installing ticcmd, or can be done using the udev_rule_setter utility in crappy’s util folder. It is also possible to add it manually by running:

$ echo "SUBSYSTEM==\"usb\", ATTR{idVendor}==\"1ffb\", MODE=\"0666\"" | sudo tee pololu.rules > /dev/null 2>&1

in a shell opened in /etc/udev/rules.d.

New in version 1.4.0.

Changed in version 2.0.0: renamed from Pololu_tic to PololuTic

__init__(steps_per_mm: float, current_limit: float, step_mode: int | str = 8, max_accel: float = 20, t_shutoff: float = 0, config_file: str | None = None, serial_number: str | None = None, model: str | None = None, reset_command_timeout: bool = True, backend: str = 'USB', unrestricted_current_limit: bool = False, pin_function: Dict[str, str] | None = None, pin_polarity: Dict[str, str] | None = None) → None[source]

Checks args validity, finds the right device, reads the current limit tables.

Parameters:

steps_per_mm – The number of full steps needed for the motor to travel 1 mm. This varies according to the motor model, and can be deduced from the datasheet or directly measured. This value is usually between 50 and 500.
current_limit – The maximum current the motor is able to withstand, in mA. It is usually around 1A for small stepper motors, and can go up to a few Amps. The maximum allowed current_limit value depends on the Tic model. The Tic 36v4 default maximum current limit can be increased using the unrestricted_current_limit parameter.
step_mode – Sets the number of microsteps used for driving the motor. This number is always a power of 2. The minimum number of microsteps is 1 (full steps), and the maximum depends on the Tic model. All models however support modes 1 to 8. The speed and length conversions are managed automatically so that changing the step mode doesn’t affect the motor behaviour.
max_accel – The maximum allowed acceleration for the motor, in mm/s². When asked to reach a given speed or position, the motor accelerates at this rate. It also corresponds to the maximum allowed deceleration. Usually doesn’t need to be changed.
t_shutoff – This class features an auto-shutoff thread that deenergizes the motor after a period of t_shutoff seconds of inactivity. The timer counts in steps of 0.1s, which is thus the maximum precision for this setting. When set to 0, this feature is disabled and the motor remains energized until the close() method is called.
config_file – The path to the config file to be loaded to the Tic. It only works if backend is ‘ticcmd’. The config file contains some specific settings that can only be accessed this way using the ‘ticcmd’ backend. Not necessary for most applications.
serial_number – The serial number of the Tic to be controlled. It must be given as a str, and it is an 8-digits number. Allows to control the right device if several Tic of the same model are connected. Otherwise, an error is raised.
model –
The model of the Tic to be controlled. Available models are:
```
'T825', 'T824', 'T500', 'N825', 'T249', '36v4'
```
Allows to control the right device if several Tic of different models are connected. Otherwise, an error is raised.
reset_command_timeout – Enables or disables the reset_command_timeout thread. It can only be disabled if backend is ‘USB’. This thread pings the Tic every 0.5s, so that it doesn’t block due to a Command Timeout error. This feature is a safety to prevent the motor from running indefinitely if the USB connection is down, so it is better not to disable it. When disabled, the Tic never raises Command Timeout errors.
backend –
The backend for communicating with the Tic. Available backends are:
```
'USB', 'ticcmd'
```
They both communicate over USB, but ‘ticcmd’ requires Pololu’s firmware to be installed. Some features are specific to each backend.
unrestricted_current_limit – Enables or disables the unrestricted current limit feature. Only works if backend is ‘USB’, and for the 36v4 Tic model. When disabled, the maximum current allowed is 3939mA. If enabled, it goes up to 9095mA. The Tic should however be cooled in order to withstand currents higher than 3939mA.
pin_function –
Allows setting the Tic GPIO functions. It is a dict whose keys are the pin names, and values are the functions. Only works if backend is ‘USB’. Only the pins indicated in pin_function are set, the others are left in their previous state. The available pins are:
```
'SCL', 'SDA', 'TX', 'RX', 'RC'
```
and can be set to:
```
'Default', 'Kill switch', 'Limit switch forward', 'Limit switch reverse'
```
The GPIO functions remain set as long as they are not changed by the user, so for a given setup it is only necessary to set them once.
pin_polarity –
Allows setting the polarity of the GPIOs used as switches. It is a dict, whose keys are the pin names, and values are the pin polarities. Only works if backend is ‘USB’. Only the pins indicated in pin_function are set, the others are left in their previous state. The available pins are:
```
'SCL', 'SDA', 'TX', 'RX', 'RC'
```
and can be set to:
```
'Active high', 'Active low'
```
The GPIO polarities remain set as long as they are not changed by the user, so for a given setup it is only necessary to set them once.

Warning

current_limit: If the current_limit setting is higher than the motor max current, there’s a risk of overheating and damaging the motor !

Note

steps_per_mm: If you have to measure this value, it can be done easily following this procedure. Set steps_per_mm to spm (100 should be fine), and step_mode to sm (8 should be fine). Run a Crappy script for moving the motor from position 0 to position p (a few tenth of millimeters should be fine). The motor will reach an actual position ap that can be measured. The actual steps_per_mm value aspm for this motor can be calculated as follows:
```
aspm = spm * p / ap
```
step_mode: Increasing the number of microsteps allows to reduce the noise, the vibrations, and improve the precision. However, the more microsteps, the lower the maximum achievable speed for the motor. Chances that the motor misses microsteps are also higher when the number of microsteps is high.
t_shutoff: This functionality was originally added for long tests in temperature controlled environments, so that the motor doesn’t unnecessarily heat the setup when inactive. In other assays, it may still be useful for reducing the noise, the electromagnetic interference, or the energy consumption.
serial_number: Serial numbers can be accessed using the lsusb command in Linux shell, or running ticcmd --list if ticcmd is installed. This number is also displayed during __init__() if only one device is connected and serial_number is None.
model: The model is written on the Tic board, and can be accessed by running ticcmd --list in a shell if ticcmd is installed. It is also displayed during __init__() if only one device is connected and model is None.
Pins settings: The pin functions and polarity can also be set independently of crappy before starting the test, in the ticgui.

open() → None[source]: Sets the communication, the motor parameters and starts the threads.

get_speed() → float[source]

Reads the current motor speed.

Returns:: The speed in mm/s

get_position() → float[source]

Reads the current motor position.

Returns:: The position in mm

Changed in version 1.5.2: renamed from get_pos to get_position

set_position(position: float, speed: float | None) → None[source]

Sends a position command to the motor.

Parameters:

position – The position to reach in mm
speed –
The speed at which the motor should move to the given position, in mm/s Giving a speed other than None will set the maximum speed of the motor to that speed.

Changed in version 2.0.0: speed is now a mandatory argument

Note

speed: The only way to reach a position at a given speed is to change the maximum speed. The Tic will try to accelerate to the maximum speed but may remain slower if it doesn’t have time to do so before reaching the given position.

set_speed(speed: float) → None[source]

Sends a speed command to the motor.

Parameters:: speed – The speed the motor should reach

stop() → None[source]: Sets the speed to 0.

close() → None[source]: Stops the motor, joins the threads and deenergizes the motor.

Schneider MDrive 23

class crappy.actuator.SchneiderMDrive23(port: str = '/dev/ttyUSB0', baudrate: int = 9600)[source]

This class can drive Schneider Electric MDrive 23 stepper motor in speed and in position.

It communicates with the motor over a serial connection.

New in version 1.4.0.

Changed in version 2.0.0: renamed from CM_drive to SchneiderMDrive23

__init__(port: str = '/dev/ttyUSB0', baudrate: int = 9600) → None[source]

Sets the instance attributes and initializes the parent class.

Parameters:

port – The path to the serial port to open for the serial connection.
baudrate – The baudrate to use for serial communication.

open() → None[source]: Opens the serial connection to the stepper motor.

set_speed(speed: float) → None[source]

Sets the target speed of the stepper motor.

Parameters:: speed – The target speed to set, in mm/min.

set_position(position: float, _: float | None) → None[source]

Sets the target position for the stepper motor.

Parameters:

position – The target position to reach, in mm.
_ –
The speed argument is ignored.

Changed in version 2.0.0: speed is now a mandatory argument

Removed in version 2.0.0: motion_type argument

get_position() → float[source]: Reads, displays and returns the current position in mm.

Changed in version 1.5.2: renamed from get_pos to get_position

stop() → None[source]: Sends a command for stopping the motor.

close() → None[source]: Close the serial connection.

FT232H Actuators

Adafruit DC Motor Hat FT232H

class crappy.actuator.DCMotorHatFT232H(device_address: int = 96, _ft232h_args: Tuple[int, RLock, FileIO, FileIO, RLock, Synchronized] = ())[source]

Class for driving Adafruit’s DC motor HAT via an FT232H USB to I2C converter.

It can drive up to four DC motors in speed only. The acquisition of the speed has not been implemented so far. It implements the same functionality as the DCMotorHat, but communicates with the hat over USB via an FT232H device.

Important

As this Actuator can drive up to 4 motors simultaneously, it takes a tuple as a command, see set_speed(). Regular Actuators receive their commands as float. A Modifier can be used for converting a float command from a Generator to a tuple.

Note

The DC Motor Hat can also drive stepper motors, but this feature isn’t included here.

New in version 2.0.0.

__init__(device_address: int = 96, _ft232h_args: Tuple[int, RLock, FileIO, FileIO, RLock, Synchronized] = ()) → None[source]

Checks the validity of the arguments and opens the connection to the FT232H.

Parameters:

device_address – The I2C address of the HAT. The default address is 0x60, but it is possible to change this setting by cutting traces on the board.
_ft232h_args – This argument is meant for internal use only and should not be provided by the user. It contains the information necessary for setting up the FT232H.

open() → None[source]: Opens the connection to the motor hat and initializes it.

set_speed(cmd: Tuple[int, float]) → None[source]

Sets the desired voltage on the selected motor.

The provided voltage should be between -12 and 12V which are the limits of the motor hat. If not, it will be silently clamped in this interval.

Warning

Unlike most Actuators, this one takes tuple as commands instead of float.

Parameters:: cmd – A tuple containing first the index of the motor to drive as an int between 1 and 5, and second the voltage to apply to the selected motor as a float.

stop() → None[source]: Simply sets the command to 0 to stop the motors.

close() → None[source]: Closes the I2C connection to the motor hat.

Parent Actuator

Actuator

class crappy.actuator.Actuator(*_, **__)[source]

The base class for all Actuator classes, allowing to keep track of them and defining methods shared by all of them.

The Actuator objects are helper classes used by the Machine Block to communicate with motors or other actuators.

New in version 1.4.0.

__init__(*_, **__) → None[source]: Initializes the instance attributes.

log(level: int, msg: str) → None[source]

Records log messages for the Actuator.

Also instantiates the logger when logging the first message.

Parameters:

level – An int indicating the logging level of the message.
msg – The message to log, as a str.

New in version 2.0.0.

open() → None[source]

This method should perform any action that’s required for initializing the hardware and the communication with it.

Communication with hardware should be avoided in the __init__() method, and this method is where it should start. This method is called after Crappy’s processes start, i.e. when the associated Machine already runs separately from all the other Blocks.

It is fine for this method not to perform anything.

New in version 2.0.0.

set_speed(speed: float) → None[source]

This method should drive the actuator so that it reaches the desired speed.

It is used if the mode given in the actuators argument of the Machine Block is 'speed'.

The value passed as the speed argument will be that received over the cmd_label given in the actuators argument of the Machine Block.

Parameters:: speed – The speed to reach, as a float.

New in version 1.5.10.

set_position(position: float, speed: float | None) → None[source]

This method should drive the actuator so that it reaches the desired position.

It is used if the mode given in the actuators argument of the Machine Block is 'position'.

The value passed as the position argument will be that received over the cmd_label given in the actuators argument of the Machine Block.

The value passed as the speed argument will be either :

None if no speed nor speed_cmd_label were specified in the actuators argument of the Machine Block.
The value given with the speed key of the actuators argument of the Machine Block, if no other speed command was received in the meantime.
The last value received over the speed_cmd_label if it was set in the actuators argument of the Machine Block. Before the first speed command is received, the value will either be None if no speed was specified, else the value given as speed in the actuators argument of the Machine Block.

Important

The speed value might be None, but it is not optional ! When writing a custom Actuator, make sure to always handle it.

Parameters:

position – The position to reach, as a float.
speed –
The speed at which to move to the desired position, as a float, or None if no speed is specified.

Changed in version 2.0.0: speed is now a mandatory argument even if it is None

New in version 1.5.10.

get_speed() → float | None[source]

This method should return the current speed of the actuator, as a float.

This speed will be sent to downstream Blocks, over the label given with the speed_label key of the actuators argument of the Machine Block.

It is also fine for this method to return None if the speed could not be acquired.

New in version 1.5.10.

get_position() → float | None[source]

This method should return the current position of the actuator, as a float.

This position will be sent to downstream Blocks, over the label given with the position_label key of the actuators argument of the Machine Block.

It is also fine for this method to return None if the position could not be acquired.

New in version 1.5.10.

stop() → None[source]

This method should stop all movements of the actuator, and if possible make sure that the actuator cannot move anymore.

That includes for example de-energizing the actuator, or switching it to a locked state.

This method will only be called once at the very end of the test. The default behavior is to call set_speed() to set the speed to 0. This method doesn’t need to be overriden if the actuator doesn’t have any feature for stopping other than speed control.

New in version 2.0.0.

close() → None[source]

This method should perform any action required for properly ending the test and closing the communication with hardware.

It will be called when the associated Machine receives the order to stop (usually because the user hit CTRL+C, or because a Generator Block reached the end of its path, or because an exception was raised in any of the Blocks).

It is fine for this method not to perform anything.

New in version 2.0.0.

Meta Actuator

class crappy.actuator.MetaActuator(name: str, bases: tuple, dct: dict)[source]

Metaclass ensuring that two Actuators don’t have the same name, and keeping track of all the Actuator classes. It also allows including the user-defined Actuators.

New in version 1.4.0.

Changed in version 2.0.0: not checking anymore for mandatory methods in __init__()

__init__(name: str, bases: tuple, dct: dict) → None[source]