9.2. actuator

This section contains the script reference to the class actuator, used to access any actuator or motor hardware in itom. Read the overview document for more details about the Python interface of the class actuator.

class itom.actuator(name, *mandparams, *optparams) → creates new instance of actuator plugin ‘name’

This is the constructor for an actuator plugin. It initializes an new instance of the plugin specified by ‘name’. The initialisation parameters are parsed and unnamed parameters are used in their incoming order to fill first mandatory parameters and afterwards optional parameters. Parameters may be passed with name as well but after the first named parameter no more unnamed parameters are allowed.

See pluginHelp(name) for detail information about the specific initialisation parameters.

Parameters

name : {str}

is the fullname (case sensitive) of an ‘actuator’-plugin as specified in the plugin-window.

mandparams : {variant(s)}

arguments corresponding the mandatory initialization parameters. The number of arguments and their order must fit the the required mandatory parameters

optparams : {variant(s)}, optional

argument corresponding to the optional initialization parameters. If unnamed arguments are used, their order must correspond to the order of the optional parameters, keyword-based parameters are allowed as well.

Returns

inst : {actuator}

new instance of the actuator-plugin

calib(axis[, axis1, ...]) → starts calibration or homing of given axes (0-based).

Most actuators have the possibility to calibrate or home certain axes. Use this command to start the calibration.

Parameters

axis : {int}

index of the first axis to calibrate (e.g. 0 for first axis)

axis1 : {int}

add the indices of further axes as optional arguments if they should be calibrated as well

Raises

NotImplemented :

if calibration not available

connect(signalSignature, callableMethod, minRepeatInterval=0) → connects the signal of the actuator with the given callable python method

This instance of actuator wraps a actuator, that is defined by a C++-class, that is finally derived from QObject. Every Actuator can send various signals. Use this method to connect any signal to any callable python method (bounded or unbounded). This method must have the same number of arguments than the signal and the types of the signal definition must be convertable into a python object.

Parameters

signalSignature : {str}

This must be the valid signature, known from the Qt-method connect (e.g. ‘reachedTarget(bool)’)

callableMethod : {python method or function}

valid method or function that is called if the signal is emitted.

minRepeatInterval : {int}, optional

If > 0, the same signal only invokes a slot once within the given interval (in ms). Default: 0 (all signals will invoke the callable python method.

See also

disconnect

disconnect(signalSignature, callableMethod) → disconnects a connection which must have been established with exactly the same parameters.
Parameters

signalSignature : {str}

This must be the valid signature, known from the Qt-method connect (e.g. ‘clicked(bool)’)

callableMethod : {python method or function}

valid method or function, that should not be called any more, if the given signal is emitted.

See also

connect

exec(funcName[, param1, ...]) → invoke the function ‘funcName’ registered as execFunc within the plugin.

Every plugin can define further functions that can for instance be used in order to call specific calibration routines of cameras or actuators. This general method is used to call one of these specific functions registered under funcName.

Parameters

funcName : {str}

The name of the function

param1 : {variant}, optional

Further parameters depending on the requirements of the specific function.

Returns

out : {variant, list of variants}.

The return values depend on the function itself.

See also

getExecFuncsInfo

getExecFuncsInfo([funcName[, detailLevel]]) → plots a list of available execFuncs or a detailed description of the specified execFunc.

Every plugin can define further functions, that are called by plugin.exec(‘funcName’ [,param1, param2…]). This can for instance be used in order to call specific calibration routines of cameras or actuators. This method allows printing information about available functions of this type.

Parameters

funcName : {str}, optional

is the fullname or a part of any execFunc-name which should be displayed. If funcName is none or no execFunc matches funcName casesensitiv a list with all suitable execFuncs is given.

detailLevel : {dict}, optional

if detailLevel == 1, function returns a dictionary with parameters, else information is print to the command line [default: 0].

Returns

out : {None or dict}

depending on the value of detailLevel.

See also

exec

getExecFuncsList() → returns a list of the names of the additional Functions of this plugin

Each plugin may define a set of functions, extending the standard interface. These functions are not common to plugins of the same type. These functions are executed using instance.exec(“funcname”,params) to check exact function call use instance.getExecFuncsInfo()getExecFuncsInfo

getParam(name) → current value of the plugin parameter ‘name’.

Returns the current value of the internal plugin parameter with ‘name’. The type of the returned value depends on the real type of the internal plugin, which may be:

  • String -> str

  • Char, Integer -> int

  • Double -> float

  • CharArray, IntegerArray -> tuple of int

  • DoubleArray -> tuple of float

  • DataObject -> dataObject

  • PolygonMesh -> polygonMesh

  • PointCloud -> pointCloud

  • Another plugin instance -> dataIO or actuator

The name of the parameter must have the following form:

  • name

  • name:additionalTag (additionalTag can be a special feature of some plugins)

  • name[index] (only possible if parameter is an array type and you only want to get one single value, specified by the integer index [0,nrOfArrayItems-1])

  • name[index]:additionalTag

Parameters

name : {str}

name of the requested parameter

Returns

out : {variant}

value of the parameter

Raises

ValueError :

if parameter does not exist

getParamInfo(name) → returns dictionary with meta information of parameter ‘name’.
getParamList() → returns a list of the names of the internal parameters of the plugin

Each plugin defines a set of parameters, where each parameter has got a name and maps to any value. The value is represented by the C++ class ito::ParamBase and can have one of the following types:

  • String

  • Char

  • Integer

  • Double

  • CharArray

  • IntegerArray

  • DoubleArray

  • DataObject

  • PolygonMesh

  • PointCloud

  • Another plugin instance

Using one of the parameter names, its current value can be obtained by getParam(‘name’) and is writable by setParam(‘name’, newValue) (if not read-only)

Returns

out : {list}

list of parameter names

getParamListInfo(detailLevel=1) → prints detailed information about all plugin parameters.

Each plugin defines a set of parameters, where each parameter has got a name and maps to any value. The value is represented by the C++ class ito::ParamBase and can have one of the following types:

  • String

  • Char

  • Integer

  • Double

  • CharArray

  • IntegerArray

  • DoubleArray

  • DataObject

  • PolygonMesh

  • PointCloud

  • Another plugin instance

Using one of the parameter names, its current value can be obtained by getParam(‘name’) and is writable by setParam(‘name’, newValue) (if not read-only)

This method prints a detailed table with the name, current value, description string and further meta information of every plugin parameter. Additionally, the column R/W indicates if this parameter is writable or read-only.

Parameters

detailLevel : {dict}, optional

if detailLevel == 1, function returns a dictionary with parameters, else None is returned and the output is printed in a readable form to the console [default]

Returns

out : {None, dict}

If detailLevel == 1, a dictionary containing all printed information is returned

getPos(axis[, axis1, ...]) → returns the actual positions of the given axes (in mm or degree).

This method requests the current position(s) of the given axes and returns it.

Parameters

axis : {int}

index of the first axis (e.g. 0 for first axis)

axis1 : {int}

add the indices of further axes as optional arguments

Returns

positions : {float or tuple of float}

Current position as float value if only one axis is given or tuple of floats for multiple axes. The unit is mm or degree.

See also

setPosRel, setPosAbs

getStatus([axis = -1]) → returns a list of status values for each axis or the status value for a specific axis

Each axis of an actuator plugin has got a status value that is used for informing about the current status of the axis.

The status value is an or-combination of the following possible values:

Moving flags:

  • actuatorUnknown = 0x0001 : unknown current moving status

  • actuatorInterrupted = 0x0002 : movement has been interrupted by the user or another error during the movement occurred

  • actuatorMoving = 0x0004 : axis is currently moving

  • actuatorAtTarget = 0x0008 : axis reached the target position

  • actuatorTimeout = 0x0010 : timout during movement. Unknown status of the movement

Switches flags:

  • actuatorEndSwitch = 0x0100 : axis reached any end switch (e.g. if only one end switch is available)

  • actuatorEndSwitch1 = 0x0200 : axis reached the specified left end switch (if set, also set actuatorEndSwitch)

  • actuatorEndSwitch2 = 0x0400 : axis reached the specified left end switch (if set, also set actuatorEndSwitch)

  • actuatorRefSwitch = 0x0800 : axis reached any reference switch (e.g. for calibration…)

  • actuatorRefSwitch1 = 0x1000 : axis reached the specified right reference switch (if set, also set actuatorRefSwitch)

  • actuatorRefSwitch2 = 0x2000 : axis reached the specified right reference switch (if set, also set actuatorRefSwitch)

Status flags:

  • actuatorAvailable = 0x4000 : the axis is available

  • actuatorEnabled = 0x8000 : the axis is currently enabled and can be moved

  • actuatorError = 0x10000 : axis has encountered error/reports error

Parameters

axis : {int}, optional

index of desired axis. If given, the returned status value is a single value. If not given (default), the status of all axes is requested and returned as list.

Returns

status : {list of integers}

list of integers (size corresponds to number of axes) with the current status of each axis

getType() → returns actuator type
hideToolbox() → hides toolbox of the plugin
Raises

RuntimeError :

if plugin does not provide a toolbox

See also

showToolbox

info(verbose=0) → returns information about signal and slots.
Parameters

verbose : {int}

0: only slots and signals from the plugin class are printed (default) 1: all slots and signals from all inherited classes are printed

name() → returns the plugin name
Returns

name : {str}

name of the plugin, which corresponds to getParam(‘name’)

See also

getParam

setInterrupt() → interrupts a movement of an actuator

Sets the interrupt flag of an actuator. The actuator interrupts the movement of all running axes as soon as this flag is checked again.

setOrigin(axis[, axis1, ...]) → defines the actual position of the given axes to value 0.

The current positions of all indicated axes (axis, axis1,…) are considered to be 0 such that following positioning commands are relative with respect to the current position.

Parameters

axis : {int}

index of the first axis (e.g. 0 for first axis)

axis1 : {int}

add the indices of further axes as optional arguments

Raises

NotImplemented :

if actuator does not support this feature

setParam(name, value) → sets parameter ‘name’ to the given value.

Sets the internal plugin parameter with ‘name’ to a new value. The plugin itsself can decide whether the given value is accepted as new value. This may depend on the type of the given value, but also on the allowed value range indicated by further meta information of the internal parameter. Parameters that have the read-only flag set can not be reset.

The name of the parameter must have the following form:

  • name

  • name:additionalTag (additionalTag can be a special feature of some plugins)

  • name[index] (only possible if parameter is an array type and you only want to get one single value, specified by the integer index [0,nrOfArrayItems-1])

  • name[index]:additionalTag

Parameters

name : {str}

name of the parameter

value : {str, int, double, …}

value that will be set. Only the name and existance of the parameter is checked before passing the request to the plugin. The plugin itsself is responsible for further validations (including read-only attribute).

setPosAbs(axis0, pos0[, axis1, pos1, ...]) → moves given axes to given absolute values (in mm or degree).

All arguments are a pair of axis index and the new target position of this axis. This method starts the absolute positioning of all given axes. If the ‘async’ parameter of the plugin is 0 (usually default), a synchronous positioning is started, hence, this method returns after that all axes reached their target position or a timeout occurred. Else this method immediately returns and the actuator goes on moving.

Parameters

axisM : {int}

index of the axis to position

posM : {float}

absolute target position of the axisM (in mm or degree)

See also

getPos, setPosRel

setPosRel(axis0, pos0[, axis1, pos1, ...]) → relatively moves given axes by the given distances [in mm or degree].

All arguments are a pair of axis index and the relative moving-distance of this axis. This method starts the relative positioning of all given axes. If the ‘async’ parameter of the plugin is 0 (usually default), a synchronous positioning is started, hence, this method returns after that all axes reached their target position or a timeout occurred. Else this method immediately returns and the actuator goes on moving.

Parameters

axisM : {int}

index of the axis to position

posM : {float}

relative target position of the axisM (in mm or degree)

See also

getPos, setPosAbs

showConfiguration() → show configuration dialog of the plugin
Raises

RuntimeError :

if plugin does not provide a configuration dialog

showToolbox() → open toolbox of the plugin
Raises

RuntimeError :

if plugin does not provide a toolbox

See also

hideToolbox

currentPositions

Get the current positions (in mm or degree) of all axes

This property returns a tuple whose size corresponds to the number of axes of this actuator. The returned tuple contains the current positions of all axes (in mm or degree). This property is always updated if the plugin signals a change of any current position via the signal ‘actuatorStatusChanged’. Instead of reading this property, you can also connect to this signal in order to get instantly informed about new current positions.

This property always returns immediately, however it only contains the last reported values which can slightly differ from the real current positions (if the plugin rarely emits its current states for instance due to performance reasons).

currentStatus

Get the current status (flag mask, see getStatus()) of all axes

This property returns a tuple whose size corresponds to the number of axes of this actuator. The returned tuple contains the current positions of all axes (in mm or degree). This property is always updated if the plugin signals a change of any current position via the signal ‘actuatorStatusChanged’. Instead of reading this property, you can also connect to this signal in order to get instantly informed about new current positions.

The difference between this property and the method getStatus() is that getStatus will only return if the actuator plugin is currently idle. This property always returns immediately, however it only contains the last reported values which can slightly differ from the real current positions (if the plugin rarely emits its current states for instance due to performance reasons).

targetPositions

Get the target positions (in mm or degree) of all axes

This property returns a tuple whose size corresponds to the number of axes of this actuator. The returned tuple contains the current target positions of all axes (in mm or degree). This property is always updated if the plugin signals a change of any target position via the signal ‘targetChanged’. Instead of reading this property, you can also connect to this signal in order to get instantly informed about new target positions.

This property always returns immediately, however it only contains the last reported values which can slightly differ from the real target positions (if the plugin rarely emits its current states for instance due to performance reasons).