Force Actuator

COLUMNS `module-attribute`

COLUMNS = (
    "Time",
    "Displacement",
    "Value",
    "Factor",
    "Baseline",
    "Force",
)

Headers for output data from force sensor

G `module-attribute`

G = 9.81

Acceleration due to Earth's gravity

ForceActuator

ForceActuator(
    port: str,
    limits: Iterable[float] = (-30.0, 0),
    force_threshold: float = 10000,
    stabilize_timeout: float = 1,
    force_tolerance: float = 0.01,
    *,
    home_displacement: float = -1.0,
    max_speed: float = MAX_SPEED,
    steps_per_second: int = 6400,
    calibration_factor: float = 1.0,
    correction_parameters: tuple[float] = (1.0, 0.0),
    touch_force_threshold: float = 2 * G,
    touch_timeout: int = 300,
    from_top: bool = True,
    baudrate: int = 115200,
    verbose: bool = False,
    **kwargs,
)

ForceSensor provides methods to read out values from a force sensor

ATTRIBUTE	DESCRIPTION
`baseline`	baseline readout at which zero newtons is set TYPE: `float`
`calibration_factor`	calibration factor of device readout to newtons TYPE: `float`
`displacement`	machine displacement TYPE: `float`
`end_stop`	whether the end stop is triggered TYPE: `bool`
`home_displacement`	starting displacement of home position TYPE: `float`
`precision`	number of decimal places to print force value TYPE: `int`
`threshold`	force threshold to stop movement TYPE: `float`
`force`	force experienced TYPE: `float`
`limits`	lower and upper limits of movement TYPE: `ndarray`

METHOD	DESCRIPTION
`clearCache`	clear most recent data and configurations
`disconnect`	disconnect from device
`getForce`	get the force response
`home`	home the actuator
`isFeasible`	checks and returns whether the target displacement is feasible
`measure`	measure the stress-strain response of sample
`move`	move the actuator by desired distance. Alias of moveBy() method
`moveBy`	move the actuator by desired distance
`moveTo`	move the actuator to desired displacement
`reset`	reset the device
`setThreshold`	set the force threshold for the machine
`shutdown`	shutdown procedure for tool
`tare`	alias for zero()
`stream`	start or stop feedback loop
`record`	start or stop data recording
`touch`	touch the sample
`waitThreshold`	wait for force sensor to reach the force threshold
`zero`	set the current reading as baseline (i.e. zero force)

Initialize the actuated sensor

PARAMETER	DESCRIPTION
`port`	Serial port TYPE: `str`
`limits`	Lower and upper limits for the actuator TYPE: `Iterable[float]` DEFAULT: `(-30.0, 0)`
`force_threshold`	Force threshold TYPE: `float` DEFAULT: `10000`
`stabilize_timeout`	Time to wait for the device to stabilize TYPE: `float` DEFAULT: `1`
`force_tolerance`	Tolerance for TYPE: `float` DEFAULT: `0.01`
`home_displacement`	Home position TYPE: `float` DEFAULT: `-1.0`
`max_speed`	Maximum speed TYPE: `float` DEFAULT: `MAX_SPEED`
`steps_per_second`	Steps per second TYPE: `int` DEFAULT: `6400`
`calibration_factor`	Calibration factor TYPE: `float` DEFAULT: `1.0`
`correction_parameters`	Polynomial correction parameters TYPE: `tuple[float]` DEFAULT: `(1.0, 0.0)`
`baudrate`	Baudrate for serial communication TYPE: `int` DEFAULT: `115200`
`verbose`	Print verbose output TYPE: `bool` DEFAULT: `False`

connection_details `property`

connection_details: dict

Connection details for the device

is_busy `property`

is_busy: bool

Whether the device is busy

is_connected `property`

is_connected: bool

Whether the device is connected

records_df `property`

records_df: DataFrame

DataFrame of records

verbose `property` `writable`

verbose: bool

Verbosity of class

atDisplacement

atDisplacement(
    displacement: float,
    current_displacement: float | None = None,
) -> bool

Check if the device is at the target displacement

PARAMETER	DESCRIPTION
`displacement`	Target displacement TYPE: `float`
`current_displacement`	Current displacement. Defaults to None. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if the device is at the target displacement TYPE: `bool`

atForce

atForce(
    force: float,
    current_force: float | None = None,
    *,
    tolerance: float | None = None,
    stabilize_timeout: float = 0,
) -> bool

Check if the device is at the target force

PARAMETER	DESCRIPTION
`force`	Target force TYPE: `float`
`current_force`	Current force TYPE: `float \| None` DEFAULT: `None`
`tolerance`	Tolerance for force TYPE: `float` DEFAULT: `None`
`stabilize_timeout`	Time to wait for the device to stabilize TYPE: `float` DEFAULT: `0`

RETURNS	DESCRIPTION
`bool`	True if the device is at the target force TYPE: `bool`

clearCache

clearCache()

Clear most recent data and configurations

connect

connect()

Establish connection with device

disconnect

disconnect()

Disconnect from device

getAttributes

getAttributes() -> dict

Get attributes

RETURNS	DESCRIPTION
`dict`	Attributes TYPE: `dict`

getData

getData(*args, **kwargs) -> MoveForceData | None

Get data from device

RETURNS	DESCRIPTION
`MoveForceData`	Data from device TYPE: `MoveForceData \| None`

getDataframe

getDataframe(
    data_store: Iterable[tuple[NamedTuple, datetime]],
) -> DataFrame

Get dataframe of data collected

PARAMETER	DESCRIPTION
`data_store`	data store TYPE: `Iterable[tuple[NamedTuple, datetime]]`

RETURNS	DESCRIPTION
`DataFrame`	pd.DataFrame: dataframe of data collected

getDisplacement

getDisplacement() -> float | None

Get displacement

RETURNS	DESCRIPTION
`float`	Displacement in mm TYPE: `float \| None`

getForce

getForce() -> float | None

Get the force response and displacement of actuator

RETURNS	DESCRIPTION
`str`	device response TYPE: `float \| None`

getValue

getValue() -> float | None

Get the value readout from device

RETURNS	DESCRIPTION
`float \| None`	float\|None: Value readout

home

home() -> bool

Home the actuator

RETURNS	DESCRIPTION
`bool`	whether homing is a success TYPE: `bool`

loadProgram

loadProgram(
    program: Program,
    docstring_parser: Callable[[Any, bool], ProgramDetails]
    | None = None,
)

Load a program to the Measurer

PARAMETER	DESCRIPTION
`program`	program to load TYPE: `Program`

measure

measure(
    *args,
    parameters: dict | None = None,
    blocking: bool = True,
    **kwargs,
) -> DataFrame | None

Run the measurement program

args: positional arguments parameters (dict, optional): dictionary of kwargs. Defaults to None. blocking (bool, optional): whether to block until completion. Defaults to True. *kwargs: keyword arguments

RETURNS	DESCRIPTION
`DataFrame \| None`	pd.DataFrame\|None: dataframe of data collected

move

move(by: float, speed: float | None = None) -> bool

Move the actuator to the target displacement and apply the target force

PARAMETER	DESCRIPTION
`by`	distance in mm TYPE: `float`
`speed`	movement speed. Defaults to 0.375. TYPE: `float` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	whether movement is successful TYPE: `bool`

moveBy

moveBy(by: float, speed: float | None = None) -> bool

Move the actuator by desired distance

PARAMETER	DESCRIPTION
`by`	distance in mm TYPE: `float`
`speed`	movement speed. Defaults to 0.375. TYPE: `float` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	whether movement is successful TYPE: `bool`

moveTo

moveTo(to: float, speed: float | None = None) -> bool

Move the actuator to desired displacement

PARAMETER	DESCRIPTION
`to`	displacement in mm TYPE: `float`
`speed`	movement speed. Defaults to 0.375. TYPE: `float` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	whether movement is successful TYPE: `bool`

record

record(
    on: bool, show: bool = False, clear_cache: bool = False
)

Start or stop data recording

PARAMETER	DESCRIPTION
`on`	whether to start recording data TYPE: `bool`

reset

reset()

Reset the device

resetFlags

resetFlags()

Reset all flags to class attribute _default_flags

saveData

saveData(filepath: str | Path)

Save data to file

PARAMETER	DESCRIPTION
`filepath`	path to save file TYPE: `str \| Path`

shutdown

shutdown()

Shutdown procedure for tool

stream

stream(on: bool, show: bool = False)

Start or stop feedback loop

PARAMETER	DESCRIPTION
`on`	whether to start loop to continuously read from device TYPE: `bool`

touch

touch(
    force_threshold: float = 0.1,
    displacement_threshold: float | None = None,
    speed: float | None = None,
    from_top: bool = True,
    record: bool = False,
    timeout: int = None,
) -> bool

Apply the target force

PARAMETER	DESCRIPTION
`force_threshold`	target force. Defaults to 0.1. TYPE: `float` DEFAULT: `0.1`
`displacement_threshold`	target displacement. Defaults to None. TYPE: `float` DEFAULT: `None`
`speed`	movement speed. Defaults to None. TYPE: `float` DEFAULT: `None`
`from_top`	whether compression direction is towards negative displacement. Defaults to True. TYPE: `bool` DEFAULT: `True`
`record`	whether to record data. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`bool`	whether movement is successful (i.e. force threshold is not reached) TYPE: `bool`

waitThreshold

waitThreshold(
    displacement: float, timeout: float | None = None
) -> float

Wait for force sensor to reach the threshold

PARAMETER	DESCRIPTION
`displacement`	target displacement TYPE: `float`
`timeout`	timeout duration in seconds. Defaults to None. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`float`	actual displacement upon reaching threshold TYPE: `float`

zero

zero(timeout: int = 5)

Set current reading as baseline (i.e. zero force)

PARAMETER	DESCRIPTION
`timeout`	duration to wait while zeroing, in seconds. Defaults to 5. TYPE: `int` DEFAULT: `5`