Skip to content

PI Tools

The PIPython pitools is a collection of high-level functions which simplify the work with PI controllers. These functions take into account different controller behaviors, so that you don't have to adjust anything to a specific controller. If specific options are needed for a function, this is explicitely stated in the function's help text.

Info

In the examples on this page, pidevice refers to an instance of pipython.GCSDevice.

enableaxes

Calling 'enableaxes' sets all specified axes to an enabled state. If a specified axis is already enabled, nothing is done with this axis. The same applies if an axis cannot be enabled, e.g. because the device does not support enabling axes. The caller doesn't have to worry about what specific options to set for axis enablement, because this is done by the function.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.enableaxes)

enableaxes(pidevice, axes, **kwargs)
    Enable all 'axes'.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes to enable.
    @param kwargs: Optional arguments with keywords that are passed to sub-functions.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Enable axis 'Axis_1'
pitools.enableaxes(pidevice, 'Axis_1')
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Enable the axes 'Axis_1' and 'Axis_2'
pitools.enableaxes(pidevice, ['Axis_1', 'Axis_2'])
...

startup

Calling 'startup' sets a stage into a specific working condition. The function enables the axes and performs further actions, if defined, like writing parameters from the PIStages3 database to the controller, making a reference move or running an auto zero procedure, setting the servo state, or switching to a specific control mode (only for controllers wit GCS 3.0 syntax).

Info

The axes are always enabled after a successfull 'startup' call. Further actions are optional.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.startup)

startup(pidevice, stages=None, refmodes=None, servostates=True, controlmodes=None, **kwargs)
    Define 'stages', stop all, enable servo on all connected axes and reference the axes with 'refmodes'.
    Defining stages and homing them is done only if necessary.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param stages: Name of stage(s) to initialize as string or list (not tuple!) or 'None' to skip.
    @param refmodes: Referencing command(s) as string (for all stages) or list (not tuple!) or 'None' to skip.
                     Please see the manual of the controller for the valid reference procedure.
                     'refmodes' can be:
                         'FRF': References the stage using the reference position.
                         'FNL': References the stage using the negative limit switch.
                         'FPL': References the stage using the positive limit switch.
                         'POS': Sets the current position of the stage to 0.0.
                         'ATZ': Runs an auto zero procedure.
    @param servostates: Desired servo state(s) as Boolean (for all stages) or dict {axis : state} or 'None' to skip.
                        For controllers with GCS 3.0 syntax:
                            If True the axis is switched to control mode 0x2.
                            If False the axis is switched to control mode 0x1.
    @param controlmodes: Only valid for controllers with GCS 3.0 syntax!
                         Switch the axis to the given control mode:
                             int (for all axes) or dict {axis : controlmode} or 'None' to skip.
                         To skip any control mode switch make sure the servostate is also 'None'!
                         If 'controlmodes' is set (not 'None') the parameter 'servostates' is ignored.
    @param kwargs: Optional arguments with keywords that are passed to sub-functions.

GCS 2.0 example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the stage parameters fom the stage 'M-111.1DG' out of the PIStages3 database and write
# them to the first two axes of the controller. Don't write any parameters to the third axis.
# Make a reference move for the first axis using the 'FNL' command, dont reference the second axis,
# and make a reference move for the third axis unsing the 'FPL' command.
# Doing this switches on the servo for the first two axes and turns it off for the third axis.
pitools.startup(pidevice, ['M-111.1DG', 'M-111.1DG', None], ['FNL', None, 'FPL'], [True, True, False])
...

GCS 2.0 example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Don't get any stage parameters fom the PIStages3 database (e.g. because they are already stored 
# on the controller). Make reference moves for all axes using the 'FRF' command.
# Turn on the servo for the first axis, don't change the servo state of the second axis,
# and turn off the servo for the third axis. Don't change the servo state of any other axis
# (if the controller has more than three axes).
pitools.startup(pidevice, None, 'FRF', [True, None, False, ])
...

GCS 3.0 example

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Don't get any stage parameters fom the PIStages3 database (e.g. because they are already stored 
# on the controller). Make reference moves for all axes using the 'FRF' command.
# Switch the control mode for the first two axes to 0x2 (Closed Loop Position), and for the
# third axis to 0x4 (Closed Loop Velocity). Don't change the control mode for any other axis
# (if the controller has more than three axes).
pitools.startup(pidevice, None, 'FRF', None, [0x2, 0x2, 0x4, ])
...

Detailed examples

See the samples datarecorder.py, datarecorder_gcs30.py, TrajectorySample.py, targets_from_cvs.py, wavegenerator_circle.py, wavegenerator_pnt.py, simplemove.py, and simplemove_gcs30.py.

setservo

Calling 'setservo' sets the servo state of the given axes to ON (closed loop) or OFF (open loop). If any preparatory actions are necessary, the function performs them before running 'setservo', e.g.: In the case of open-loop Nexline axes the function relaxes the piezo and waits for the servo operation to finish; if the servo is to be switched on for disabled axes, the function enables them first (see section 'enableaxes').

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.setservo)

setservo(pidevice, axes, states=None, toignore=None, **kwargs)
    Set servo of 'axes' to 'states'. Calls preparatory functions if necessary,
    e.g., for enabling disabled axes or for relaxing the piezo with open-loop Nexline axes.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or dictionary {axis : value, }.
    @param states: Boolean or list of Booleans, 'None' if 'axes' is a dictionary.
                   For controllers with GCS 3.0 syntax:
                       If True the axis is switched to control mode 0x2.
                       If False the axis is switched to control mode 0x1.
    @param toignore: GCS error(s) to ignore as integer or list of integers.
    @param kwargs: Optional arguments with keywords that are passed to sub-functions.
    @return: False if setting the servo failed.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Turn the servo on for 'Axis_1'.
success = pitools.setservo(pidevice, 'Axis_1', True)
print(success)

True
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Turn the servo on for 'Axis_1' and off for'Axis_2'.
success = pitools.setservo(pidevice, ['Axis_1', 'Axis_2'], [True, False])
print(success)

True
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Turn the servo on for 'Axis_1' and off for'Axis_2'.
success = pitools.setservo(pidevice, {'Axis_1': True, 'Axis_2': False}, None)
print(success)

True
...

getservo

Calling 'getservo' gets the servo state of the given axes. If no servo state is available for an axis, False ist returned for this axis.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.getservo)

getservo(pidevice, axes)
    Return dictionary of servo states or "False" if the qSVO command is not supported.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes to get values for or 'None' for all axes.
    @return: Dictionary of servo states of 'axes' as Booleans.  
             For controllers with GCS 3.0 syntax:
                 If True the axis is in control mode 0x2.
                 If False the axis is in any other control mode.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get servo state of axis 'Axis_1'.
servostates = pitools.getservo(pidevice, 'Axis_1')
print(servostates)

# The servo state of 'Axis_1' is ON (closed loop).
{'Axis_1': True}
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get servo states of axes 'Axis_1' and 'Axis_2'.
servostates = pitools.getservo(pidevice, ['Axis_1', 'Axis_2'])
print(servostates)

# The servo state of 'Axis_1' is ON (closed loop) and for 'Axis_2' OFF (open loop).
{'Axis_1': True, 'Axis_2': False}
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get servo states of all axes.
servostates = pitools.getservo(pidevice, None)
print(servostates)

# Example for a controller with three axes:
# The servo state of 'Axis_1' and 'Axis_2' is ON (closed loop) and for 'Axis_3' OFF (open loop).
{'Axis_1': True, 'Axis_2': True, 'Axis_3': False}
...

moveandwait

Calling 'moveandwait' moves all specified axes to the specified positions and waits until all axes have reached their target positions. Depending on the device and axis types, this can take a while.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.moveandwait)

moveandwait(pidevice, axes, values=None, timeout=300)
    Call MOV with 'axes' and 'values' and wait for motion to finish.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or dictionary of {axis : target, }.
    @param values: Optional list of values or value.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Move 'Axis_1' to the position 1.1 and wait 
# until the axis has reached its target position.
pitools.moveandwait(pidevice, 'Axis_1', 1.1)
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Move 'Axis_1' to the position 1.1 and 'Axis_2' to 2.5 and wait 
# until both axes have reached their target positions.
pitools.moveandwait(pidevice, ['Axis_1', 'Axis_2'], [1.1, 2.5])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Move 'Axis_1' to the position 1.1 and 'Axis_2' to 2.5 and wait 
# until both axes have reached their target positions.
pitools.moveandwait(pidevice, {'Axis_1': 1.1, 'Axis_2': 2.5}, None)
...

movetomiddle

Calling 'movetomiddle' moves all specified axes to the middle position but does not wait until the target positions are reached.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.movetomiddle)

movetomiddle(pidevice, axes=None)
    Move 'axes' to their middle positions but do not wait until they are on target.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Move 'Axis_1' to its middle position,
# don't wait until the target position is reached.
pitools.movetomiddle(pidevice, 'Axis_1')
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Move 'Axis_1' and 'Axis_1' to their middle positions,
# don't wait until the target positions are reached.
pitools.movetomiddle(pidevice, ['Axis_1', 'Axis_2'])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Move all axes to their middle positions,
# don't wait until the target position is reached.
pitools.movetomiddle(pidevice, None)
...

Detailed examples

See the sample datarecorder_gcs30.py.

ontarget

Calling 'ontarget' gets the 'on-target' state of the specified open-loop or closed-loop axes. For open-loop axes which support open-loop step motion and the commnad 'OSN?' to get the remaining number of open-loop steps to execute, there is also an 'on-targt' state availabe. For all other open-loop axes True is returned.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.ontarget)

ontarget(pidevice, axes)
    Return dictionary of on-target states for open- or closed-loop 'axes'.
    If qOSN is not supported, open-loop axes will return True.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @return: Dictionary of on-target states of 'axes' as Booleans {axis : on-target-state, }.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the 'on-target' state of axis 'Axis_1'.
ontargetstate = pitools.ontarget(pidevice, 'Axis_1')
print (ontargetstate)

# The axis 'Axis_1' is on target.
{'Axis_1': True}
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the 'on-target' states of axes 'Axis_1' and 'Axis_2'.
ontargetstate = pitools.ontarget(pidevice, ['Axis_1', 'Axis_2'])
print (ontargetstate)

# The axis 'Axis_1' is on target, 'Axis_2' is not on target.
{'Axis_1': True, 'Axis_2': False}
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the 'on-target' state of all axes'.
ontargetstate = pitools.ontarget(pidevice, None)
print(ontargetstate)

# Example for a controller with three axes:
# The axes 'Axis_1' and 'Axis_2' are on target, 'Axis_3' is not on target.
{'Axis_1': True, 'Axis_2': True, 'Axis_3': False}
...

stopall

Calling 'stopall' stops all axes. For GCS 3.0 controllers: Waits until the affected axes have finished their stop procedures.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.stopall)

stopall(pidevice, **kwargs)
    For GCS 2.0 controllers: Stop motion of all axes and give "error 10" warning.
    For GCS 3.0 controllers: Stop all axes and wait until the affected axes have finished their stop procedures.
    @param pidevice: instance of GCS2Commands or GCS30Commands object
    @param kwargs: Optional arguments with keywords that are passed to sub-functions.

Example

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Stop all axes and return the affected axes in case of a GCS 3.0 controller.
pitools.stopall(pidevice)
...

getaxeslist

Calling 'getaxeslist' returns a list of all axes of the controller or converts different axes formats into a list.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.getaxeslist)

getaxeslist(pidevice, axes)
    Return list of 'axes'.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @return: List of axes from 'axes' or all axes or empty list.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Convert the axis string to an axis list.
axes = pitools.getaxeslist(pidevice, 'Axis_1')
print(axes)

['AXIS_1']
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Convert the specified axes to an axis list.
axes = pitools.getaxeslist(pidevice, ('Axis_1', 'Axis_2))
print(axes)

['Axis_1', 'Axis_2']
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Convert the axes dictionary to an axis list.
axes = pitools.getaxeslist(pidevice, {'Axis_1': 1.1, 'Axis_2': 2.5})
print(axes)

['Axis_1', 'Axis_2']
...

Example 4

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get a list of all axes of the controller (here: a controller with three axes).
axes = pitools.getaxeslist(pidevice, None)
print(axes)

['AXIS_1', 'AXIS_2', 'AXIS_3']
...

waitonready

Calling 'waitonready' waits until the controller is ready. Some controllers don't react while executing long-lasting commands. 'waitonready' waits until the controller is ready for new commands.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonready)

waitonready(pidevice, timeout=300, predelay=0, polldelay=0.1)
    Wait until controller is in "ready" state, then query and raise controller error.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until the controller is ready.
pitools.waitonready(pidevice)
...

Detailed examples

See the sample wavegenerator_circle.py.

waitontarget

Calling 'waitontarget' waits until all specified closed-loop axes are on target.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitontarget)

waitontarget(pidevice, axes=None, timeout=300, predelay=0, postdelay=0, polldelay=0.1)
    Wait until all closed-loop 'axes' are on target.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param postdelay: Additional delay time in seconds after reaching the desired state, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until the axis 'Axis_1' is on target.
pitools.waitontarget(pidevice, 'Axis_1')
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until the axes 'Axis_1' and 'Axis_2 are on target.
pitools.waitontarget(pidevice, ['Axis_1', 'Axis_2'])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until all axes are on target.
pitools.waitontarget(pidevice, None)
...

Detailed examples

See the samples TrajectorySample.py, targets_from_cvs.py, wavegenerator_circle.py, wavegenerator_pnt.py, simplemove.py, and simplemove_gcs30.py.

waitonreferencing

Calling 'waitonreferencing' waits until referencing of all specified axes has finished.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonreferencing)

waitonreferencing(pidevice, axes=None, timeout=300, predelay=0, postdelay=0, polldelay=0.1)
    Wait until referencing of 'axes' has finished or timeout is reached.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param postdelay: Additional delay time in seconds after reaching the desired state, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until referencing of axis 'Axis_1' is finished.
pitools.waitonreferencing(pidevice, 'Axis_1')
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until referencing of axes 'Axis_1' and 'Axis_2 is finished.
pitools.waitonreferencing(pidevice, ['Axis_1', 'Axis_2'])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until referencing of all axes is finished.
pitools.waitonreferencing(pidevice, None)
...

getmaxtravelrange

Calling 'getmaxtravelrange' gets the maximum travel ranges in positive direction for the specified axes.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.getmaxtravelrange)

getmaxtravelrange(pidevice, axes)
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @return: Dictionary of {axis : maximum _travelrange, }.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the maximum travel range for 'Axis_1'.
maxrange = pitools.getmaxtravelrange(pidevice, 'Axis_1')
print (maxrange)

{'Axis_1': 5.0}
...

example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the maximum travel ranges for 'Axis_1' and 'Axis_2'.
maxrange = pitools.getmaxtravelrange(pidevice, ['Axis_1', 'Axis_2'])
print (maxrange)

{'Axis_1': 5.0, 'Axis_2': 5.0}
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the maximum travel ranges for all axes.
maxrange = pitools.getmaxtravelrange(pidevice, None)
print (maxrange)

# For a controller with three axes:
{'Axis_1': 5.0, 'Axis_2': 5.0, 'Axis_3': 10.0}
...

getmintravelrange

Calling 'getmintravelrange' gets the maximum travel ranges in negative direction for the specified axes.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.getmintravelrange)

getmintravelrange(pidevice, axes)
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @return: Dictionary of {axis : minimum _travelrange, }.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the minimum travel range for 'Axis_1'.
minrange = pitools.getmintravelrange(pidevice, 'Axis_1')
print (minrange)

{'Axis_1': -5.0}
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the minimum travel ranges for 'Axis_1' and 'Axis_2'.
minrange = pitools.getmintravelrange(pidevice, ['Axis_1', 'Axis_2'])
print (minrange)

{'Axis_1': -5.0, 'Axis_2': -5.0}
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the minimum travel ranges for all axes.
minrange = pitools.getmintravelrange(pidevice, None)
print (minrange)

# For a controller with three axes:
{'Axis_1': -5.0, 'Axis_2': -5.0, 'Axis_3': -10.0}
...

writewavepoints

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'writewavepoints' sends wave points to a wave table on the controller. Normally, it is not possible to send all wave points that are needed to the controller at once. Therefore, they have to be sent in smaller bunches. See the manual of your controller for the allowed bunch size. The 'writewavepoints' function hides this from you: 'wavepoints' can include all needed wave points, the splitting-up is done automatically.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.writewavepoints)

writewavepoints(pidevice, wavetable, wavepoints, bunchsize=None)
    Write 'wavepoints' for 'wavetable' in bunches of 'bunchsize'.
    The 'bunchsize' is device specific. Please refer to the controller manual.
    @param pidevice: instance of a GCS2Commands object
    @param wavetable: Wave table ID as integer.
    @param wavepoints: Single wavepoint as float convertible or list/tuple of them.
    @param bunchsize: Number of wavepoints per bunch or 'None' to send all 'wavepoints' in a single bunch.

Example

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Write the wave points in WAVEPOINTS_AS_ARRAY to the wave table with id 1. Write them in
# bunches of 10 values. If e.g. the WAVEPOINTS_AS_ARRAY has the size 100, the function sends
# 10 bunches of 10 wave points each: first points 1-10, then 11-20, ..., 99-100.
pitools.writewavepoints(pidevice, 1, WAVEPOINTS_AS_ARRAY, 10)
...

Detailed examples

See the sample wavegenerator_pnt.py.

waitonfastalign

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'waitonfastalign' waits until the specified fast alignment processes have finished.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonfastalign)

waitonfastalign(pidevice, name=None, timeout=300, predelay=0, postdelay=0, polldelay=0.1)
    Wait until the fast alignment process has finished.
    @param pidevice: instance of a GCS2Commands object
    @param name: Name of the process as string or list/tuple of processes.
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param postdelay: Additional delay time in seconds after reaching the desired state, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until the process 'TestProcess_1' is finished.
pitools.waitonfastalign(pidevice, 'TestProcess_1')
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until the processes 'TestProcess_1' and 'TestProcess_2' are finished.
pitools.waitonfastalign(pidevice, ['TestProcess_1', 'TestProcess_2'])
...

waitonwavegen

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'waitonwavegen' waits until all the specified wave generators have stopped running.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonwavegen)

waitonwavegen(pidevice, wavegens=None, timeout=300, predelay=0, postdelay=0, polldelay=0.1)
    Wait until all 'wavegens' have stopped running.
    @param pidevice: instance of a GCS2Commands object
    @param wavegens: Integer convertible or list/tuple of them or 'None' for all wave generators.
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param postdelay: Additional delay time in seconds after reaching the desired state, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait while wave generator 1 is running.
pitools.waitonwavegen(pidevice, 1)
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait while wave generators 1 and 2 are running.
pitools.waitonwavegen(pidevice, [1, 2])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until all wave generators have stopped running.
pitools.waitonwavegen(pidevice, None)
...

waitonautozero

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'waitonautozero' waits until the auto zero procedure has finished on all specified axes.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonautozero)

waitonautozero(pidevice, axes=None, timeout=300, predelay=0, postdelay=0, polldelay=0.1)
    Wait until all 'axes' have finished their auto zero procedure.
    @param pidevice: instance of a GCS2Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param postdelay: Additional delay time in seconds after reaching the desired state, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait while axis 'Axis_1' is running an auto zero procedure.
pitools.waitonautozero(pidevice, 'Axis_1')
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait while axes 'Axis_1' and 'Axis_2' are running an auto zero procedure.
pitools.waitonautozero(pidevice, ['Axis_1', 'Axis_2'])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until all axes have finished their auto zero procedure.
pitools.waitonautozero(pidevice, None)
...

waitonphase

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'waitonphase' waits until a find phase procedure has finished for the specified axes.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonphase)

waitonphase(pidevice, axes=None, timeout=300, predelay=0, postdelay=0, polldelay=0.1)
    Wait until all 'axes' are on phase.
    @param pidevice: instance of a GCS2Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param postdelay: Additional delay time in seconds after reaching the desired state, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until axis 'Axis_1' is on phase.
pitools.waitonphase(pidevice, 'Axis_1')
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until axes 'Axis_1' and 'Axis_2' are on phase.
pitools.waitonphase(pidevice, ['Axis_1', 'Axis_2'])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until all axes are on phase.
pitools.waitonphase(pidevice, None)
...

waitonwalk

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'waitonwalk' waits until the remaining number of steps for the specified piezo walk channels in an open-loop step move is zero. To move an open-loop piezo walk channel you tell the channel the number of steps to do. Once the remaining number of steps is 0, the motion is complete.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonwalk)

waitonwalk(pidevice, channels, timeout=300, predelay=0, postdelay=0, polldelay=0.1)
    Wait until qOSN for channels is zero.
    @param pidevice: instance of a GCS2Commands object
    @param channels: Channel or list/tuple of channels to wait for motion to finish.
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param postdelay: Additional delay time in seconds after reaching the desired state, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until the remaining number of steps for piezo walk channel 1 is zero.
pitools.waitonwalk(pidevice, 1)
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until the remaining number of steps for piezo walk channels 1 and 2 is zero.
pitools.waitonwalk(pidevice, [1, 2])
...

waitonoma

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'waitonoma' waits until the absolute open-loop motion for the specified axes has finished. Please see the manual of the controller to find out if absolute open-loop motion is possible (GSC commands 'OMA' and 'OMA?').

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonoma)

waitonoma(pidevice, axes=None, timeout=300, predelay=0, polldelay=0.1)
    Wait until open-loop motion of 'axes' has finished.
    @param pidevice: instance of a GCS2Commands object
    @param axes: Axis as string or list/tuple of axes or 'None' for all axes.
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until axis 'Axis_1' has finished open-loop motion.
pitools.waitonoma(pidevice, 'Axis_1')
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until axes 'Axis_1' and 'Axis_2' have finished open-loop motion.
pitools.waitonoma(pidevice, ['Axis_1', 'Axis_2'])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until all axes have finished open-loop motion.
pitools.waitonoma(pidevice, None)
...

waitontrajectory

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'waitontrajectory' waits until the specified trajectories have been completed. (GSC commands starting with 'TG', e.g. 'TGL?')

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitontrajectory)

waitontrajectory(pidevice, trajectories=None, timeout=300, predelay=0, postdelay=0, polldelay=0.1)
    Wait until all 'trajectories' are done and all axes are on target.
    @param pidevice: instance of a GCS2Commands object
    @param trajectories: Integer convertible or list/tuple of them or 'None' for all trajectories.
    @param timeout: Timeout in seconds for trajectory and motion, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param postdelay: Additional delay time in seconds after reaching the desired state, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example 1

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until trajectory 1 is done.
pitools.waitontrajectory(pidevice, 1)
...

Example 2

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until trajectories 1 and 2 are done.
pitools.waitontrajectory(pidevice, [1, 2])
...

Example 3

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until all trajectories are done.
pitools.waitontrajectory(pidevice, None)
...

Detailed examples

See the sample TrajectorySample.py.

waitonmacro

Info

This function is not supported for controllers with GCS 3.0 syntax.

Calling 'waitonmacro' waits until all macros on the device have finished running.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.waitonmacro)

waitonmacro(pidevice, timeout=300, predelay=0, polldelay=0.1)
    Wait until all macros are finished, then query and raise macro error.
    @param pidevice: instance of a GCS2Commands object
    @param timeout: Timeout in seconds, as float.
    @param predelay: Time in seconds until querying any state from controller, as float.
    @param polldelay: Delay time between polls in seconds, as float.

Example

import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until macros have finished.
pitools.waitonmacro(pidevice)
...

savegcsarray

Calling 'savegcsarray' saves datasets and their header information in a PI GCS array file. The PI GCS array file format is a PI specific file format to store datasets, such as values recorded with the data recorder (e.g. actual and target position of an axis), and their header information. Please see the data recorder sections to find out how to read recorded values from the controller and how to retrieve the dataset and header. After the retrieval of the data you can store them in a PI GCS array file with 'savegcsarray'. The PI GCS array file format is a human-readable file format which is understood by all PI programs (such as e.g. PIMikroMove), so you can use it to e.g. display the data in a graph.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.savegcsarray)

savegcsarray(filepath, header, data)
    Save data recorder output to a GCS array file.
    @param filepath: Full path to target file as string.
    @param header: Header information from qDRR() as dictionary or 'None'.
    @param data: Dataset as one- or two-dimensional list of floats or NumPy array.

Example

import pipython
from pipython import GCSDevice, pitools

header = {'TYPE': 1,                    # The dataset is a two-dimensional table
          'SEPARATOR': 9,               # Seperator between the data tables as ASCII value
          'DIM': 2,                     # Number of data tables in the dataset
          'SAMPLE_TIME': 9.999999e-05,  # Sample time
          'NDATA': 5,                   # Number of values in each data table
          'NAME0': 'Real Position',     # Name of the first data table (table 0)
          'NAME1': 'Target Position'}   # Name of the second data table (table 1)

data = [[0.0, 1.0, 2.0, 3.0, 4.0, 5.0],   # Data table 0 with actual positions
        [0.1, 1.1, 2.1, 3.1, 4.1, 5.1]]   # Data table 1 with target positions
...
# Save the header and data to the file 'testfile.dat'.
pitools.savegcsarray('testfile.dat', header, data)
...

The so created file looks like this:

testfile.dat

# TYPE = 1 
# SEPARATOR = 9 
# DIM = 2 
# SAMPLE_TIME = 9.999999e-05 
# NDATA = 5 
# NAME0 = Real Position 
# NAME1 = Target Position 
# 
# END_HEADER 
0.000000    0.100000 
1.000000    1.100000 
2.000000    2.100000 
3.000000    3.100000 
4.000000    4.100000 
5.000000    5.100000

Detailed examples

See the samples datarecorde.py, datarecorder_gcs30.py.

readgcsarray

Calling 'readgcsarray' reads datasets and header information from a PI GCS array file. The PI GCS array file format is a PI specific file format to store datasets, such as values recorded with the data recorder (e.g. actual and target position of an axis), and their header information. The PI GCS array file format is a human-readable file format which is understood by all PI programs (such as e.g. PIMikroMove), so you can use it to e.g. display the data in a graph.

Getting help

import pipython
from pipython import pitools

help(pipython.pitools.readgcsarray)

readgcsarray(filepath)
    Read a GCS array file and return header and data.
    Scan the file until the start of the data is found to account
    for additional information at the start of the file.
    @param filepath: Full path to file as string.
    @return header: Header information from qDRR() as dictionary.
    @return data: Dataset as two column list of floats.

For the example below, let's assume the following file exists:

testfile.dat

# TYPE = 1 
# SEPARATOR = 9 
# DIM = 2 
# SAMPLE_TIME = 9.999999e-05 
# NDATA = 5 
# NAME0 = Real Position 
# NAME1 = Target Position 
# 
# END_HEADER 
0.000000    0.100000 
1.000000    1.100000 
2.000000    2.100000 
3.000000    3.100000 
4.000000    4.100000 
5.000000    5.100000

Example

import pipython
from pipython import GCSDevice, pitools
...
# Read the header and data from the file 'testfile.dat'.
header, data = pitools.readgcsarray('testfile.dat')

print(header)   
{'TYPE': 1,                     # The dataset is a two-dimensional table
  'SEPARATOR': 9,               # Seperator between the data tables as ASCII value
  'DIM': 2,                     # Number of data tables in the dataset
  'SAMPLE_TIME': 9.999999e-05,  # Sample time
  'NDATA': 5,                   # Number of values in each data table
  'NAME0': 'Real Position',     # Name of the first data table (table 0)
  'NAME1': 'Target Position'}   # Name of the second data table (table 1)

print(data)
[[0.0, 1.0, 2.0, 3.0, 4.0, 5.0],   # Data table 0 with actual positions
 [0.1, 1.1, 2.1, 3.1, 4.1, 5.1]]   # Data table 1 with target positions
...