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

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

execFuncsInfo

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

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]) → 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() → returns a list of status values for each 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)
  • actuatorLeftEndSwitch = 0x0200 : axis reached the left end switch
  • actuatorRightEndSwitch = 0x0400 : axis reached the right end switch
  • actuatorRefSwitch = 0x0800 : axis reached any reference switch (e.g. for calibration...)
  • actuatorLeftRefSwitch = 0x1000 : axis reached left reference switch
  • actuatorRightRefSwitch = 0x2000 : axis reached right reference switch

Status flags:

  • actuatorAvailable = 0x4000 : the axis is available
  • actuatorEnabled = 0x8000 : the axis is currently enabled and can be moved
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

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