Newport

Agilis Piezo Motor Controller

class instruments.newport.AGUC2(filelike)[source]

Handles the communication with the AGUC2 controller using the serial connection.

Example usage:

>>> import instruments as ik
>>> agl = ik.newport.AGUC2.open_serial(port='COM5', baud=921600)

This loads a controller into the instance agl. The two axis are called ‘X’ (axis 1) and ‘Y’ (axis 2). Controller commands and settings can be executed as following, as examples:

Reset the controller:

>>> agl.reset_controller()

Print the firmware version:

>>> print(agl.firmware_version)

Individual axes can be controlled and queried as following:

Relative move by 1000 steps:

>>> agl.axis["X"].move_relative(1000)

Activate jogging in mode 3:

>>> agl.axis["X"].jog(3)

Jogging will continue until the axis is stopped

>>> agl.axis["X"].stop()

Query the step amplitude, then set the postive one to +10 and the negative one to -20

>>> print(agl.axis["X"].step_amplitude)
>>> agl.axis["X"].step_amplitude = 10
>>> agl.axis["X"].step_amplitude = -20
class Axes[source]

Enumeration of valid delay channels for the AG-UC2 controller.

X = 1
Y = 2
ag_query(cmd, size=-1)[source]

This runs the query command. However, the query command often times out for this device. The response of all queries are always strings. If timeout occurs, the response will be: “Query timed out.”

ag_sendcmd(cmd)[source]

Sends the command, then sleeps

reset_controller()[source]

Resets the controller. All temporary settings are reset to the default value. Controller is put into local model.

axis

Gets a specific axis object.

The desired axis is accessed by passing an EnumValue from Channels. For example, to access the X axis (axis 1):

>>> import instruments as ik
>>> agl = ik.newport.AGUC2.open_serial(port='COM5', baud=921600)
>>> agl.axis["X"].move_relative(1000)

See example in AGUC2 for a more details

Return type:_Axis
enable_remote_mode

Gets / sets the status of remote mode.

error_previous_command

Retrieves the error of the previous command and translates it into a string. The string is returned

firmware_version

Returns the firmware version of the controller

limit_status

PARTLY UNTESTED: SEE COMMENT ABOVE

Returns the limit switch status of the controller. Possible returns are: - PH0: No limit switch is active - PH1: Limit switch of axis #1 (X) is active,

limit switch of axis #2 (Y) is not active
  • PH2: Limit switch of axis #2 (Y) is active,
    limit switch of axis #1 (X) is not active
  • PH3: Limit switches of axis #1 (X) and axis #2 (Y) are active

If device has no limit switch, this routine always returns PH0

sleep_time

The device often times out. Therefore a sleep time can be set. The routine will wait for this amount (in seconds) every time after a command or a query are sent. Setting the sleep time: Give time in seconds If queried: Returns the sleep time in seconds as a float

class instruments.newport._Axis(cont, ax)[source]

Class representing one axis attached to a Controller. This will likely work with the AG-UC8 controller as well.

Warning

This class should NOT be manually created by the user. It is designed to be initialized by a Controller class

am_i_still(max_retries=5)[source]

Function to test if an axis stands still. It queries the status of the given axis and returns True (if axis is still) or False if it is moving. The reason this routine is implemented is because the status messages can time out. If a timeout occurs, this routine will retry the query until max_retries is reached. If query is still not successful, an IOError will be raised.

Parameters:max_retries (int) – Maximum number of retries
Returns:True if the axis is still, False if the axis is moving
Return type:bool
stop()[source]

Stops the axis. This is useful to interrupt a jogging motion.

zero_position()[source]

Resets the step counter to zero. See number_of_steps for details.

axis_status

Returns the status of the current axis.

jog

Start jog motion / get jog mode Defined jog steps are defined with step_amplitude function (default 16). If a jog mode is supplied, the jog motion is started. Otherwise the current jog mode is queried. Valid jog modes are:

-4 — Negative direction, 666 steps/s at defined step amplitude. -3 — Negative direction, 1700 steps/s at max. step amplitude. -2 — Negative direction, 100 step/s at max. step amplitude. -1 — Negative direction, 5 steps/s at defined step amplitude.

0 — No move, go to READY state. 1 — Positive direction, 5 steps/s at defined step amplitude. 2 — Positive direction, 100 steps/s at max. step amplitude. 3 — Positive direction, 1700 steps/s at max. step amplitude. 4 — Positive direction, 666 steps/s at defined step amplitude.
Returns:Jog motion set
Return type:int
move_relative

Moves the axis by nn steps / Queries the status of the axis. Steps must be given a number that can be converted to a signed integer between -2,147,483,648 and 2,147,483,647. If queried, command returns the current target position. At least this is the expected behaviour, never worked with the rotation stage.

move_to_limit

UNTESTED: SEE COMMENT ON TOP

The command functions properly only with devices that feature a limit switch like models AG-LS25, AG-M050L and AG-M100L.

Starts a jog motion at a defined speed to the limit and stops automatically when the limit is activated. See jog command for details on available modes.

Returns the distance of the current position to the limit in 1/1000th of the total travel.

number_of_steps

Returns the number of accumulated steps in forward direction minus the number of steps in backward direction since powering the controller or since the last ZP (zero position) command, whatever was last.

Note: The step size of the Agilis devices are not 100% repeatable and vary between forward and backward direction. Furthermore, the step size can be modified using the SU command. Consequently, the TP command provides only limited information about the actual position of the device. In particular, an Agilis device can be at very different positions even though a TP command may return the same result.

Returns:Number of steps
Return type:int
step_amplitude

Sets / Gets the step_amplitude.

Sets the step amplitude (step size) in positive and / or negative direction. If the parameter is positive, it will set the step amplitude in the forward direction. If the parameter is negative, it will set the step amplitude in the backward direction. You can also provide a tuple or list of two values (one positive, one negative), which will set both values. Valid values are between -50 and 50, except for 0.

Returns:Tuple of first negative, then positive step amplitude response.
Return type:(int, int)
step_delay

Sets/gets the step delay of stepping mode. The delay applies for both positive and negative directions. The delay is programmed as multiple of 10µs. For example, a delay of 40 is equivalent to 40 x 10 µs = 400 µs. The maximum value of the parameter is equal to a delay of 2 seconds between pulses. By default, after reset, the value is 0. Setter: value must be integer between 0 and 200000 included

Returns:Step delay
Return type:int

NewportESP301 Motor Controller

class instruments.newport.NewportESP301(filelike)[source]

Handles communication with the Newport ESP-301 multiple-axis motor controller using the protocol documented in the user’s guide.

Due to the complexity of this piece of equipment, and relative lack of documentation and following of normal SCPI guidelines, this class more than likely contains bugs and non-complete behaviour.

define_program(program_id)[source]

Erases any existing programs with a given program ID and instructs the device to record the commands within this with block to be saved as a program with that ID.

For instance:

>>> controller = NewportESP301.open_serial("COM3")
>>> with controller.define_program(15):
...     controller.axis[0].move(0.001, absolute=False)
...
>>> controller.run_program(15)
Parameters:program_id (int) – An integer label for the new program. Must be in range(1, 101).
execute_bulk_command(errcheck=True)[source]

Context manager to execute multiple commands in a single communication with device

Example:

with self.execute_bulk_command():
    execute commands as normal...
Parameters:errcheck (bool) – Boolean to check for errors after each command that is sent to the instrument.
reset()[source]

Causes the device to perform a hardware reset. Note that this method is only effective if the watchdog timer is enabled by the physical jumpers on the ESP-301. Please see the user’s guide for more information.

run_program(program_id)[source]

Runs a previously defined user program with a given program ID.

Parameters:program_id (int) – ID number for previously saved user program
search_for_home(axis=1, search_mode=0, errcheck=True)[source]

Searches the specified axis for home using the method specified by search_mode.

Parameters:
  • axis (int) – Axis ID for which home should be searched for. This value is 1-based indexing.
  • search_mode (NewportESP301HomeSearchMode) – Method to detect when Home has been found.
  • errcheck (bool) – Boolean to check for errors after each command that is sent to the instrument.
axis

Gets the axes of the motor controller as a sequence. For instance, to move along a given axis:

>>> controller = NewportESP301.open_serial("COM3")
>>> controller.axis[0].move(-0.001, absolute=False)

Note that the axes are numbered starting from zero, so that Python idioms can be used more easily. This is not the same convention used in the Newport ESP-301 user’s manual, and so care must be taken when converting examples.

Type:NewportESP301Axis
class instruments.newport.NewportESP301Axis(controller, axis_id)[source]

Encapsulates communication concerning a single axis of an ESP-301 controller. This class should not be instantiated by the user directly, but is returned by NewportESP301.axis.

abort_motion()[source]

Abort motion

disable()[source]

Turns motor axis off.

enable()[source]

Turns motor axis on.

get_status()[source]
Returns Dictionary containing values:
‘units’ ‘position’ ‘desired_position’ ‘desired_velocity’ ‘is_motion_done’
Return type:dict
move(position, absolute=True, wait=False, block=False)[source]
Parameters:
  • position (float or Quantity) – Position to set move to along this axis.
  • absolute (bool) – If True, the position pos is interpreted as relative to the zero-point of the encoder. If False, pos is interpreted as relative to the current position of this axis.
  • wait (bool) – If True, will tell axis to not execute other commands until movement is finished
  • block (bool) – If True, will block code until movement is finished
move_indefinitely()[source]

Move until told to stop

move_to_hardware_limit()[source]

move to hardware travel limit

read_setup()[source]
Returns dictionary containing:
‘units’ ‘motor_type’ ‘feedback_configuration’ ‘full_step_resolution’ ‘position_display_resolution’ ‘current’ ‘max_velocity’ ‘encoder_resolution’ ‘acceleration’ ‘deceleration’ ‘velocity’ ‘max_acceleration’ ‘homing_velocity’ ‘jog_high_velocity’ ‘jog_low_velocity’ ‘estop_deceleration’ ‘jerk’ ‘proportional_gain’ ‘derivative_gain’ ‘integral_gain’ ‘integral_saturation_gain’ ‘home’ ‘microstep_factor’ ‘acceleration_feed_forward’ ‘trajectory’ ‘hardware_limit_configuration’
Return type:dict of pint.Quantity, float and int
search_for_home(search_mode=0)[source]

Searches this axis only for home using the method specified by search_mode.

Parameters:search_mode (NewportESP301HomeSearchMode) – Method to detect when Home has been found.
setup_axis(**kwargs)[source]

Setup a non-newport DC servo motor stage. Necessary parameters are.

  • ‘motor_type’ = type of motor see ‘QM’ in Newport documentation
  • ‘current’ = motor maximum current (A)
  • ‘voltage’ = motor voltage (V)
  • ‘units’ = set units (see NewportESP301Units)(U)
  • ‘encoder_resolution’ = value of encoder step in terms of (U)
  • ‘max_velocity’ = maximum velocity (U/s)
  • ‘max_base_velocity’ = maximum working velocity (U/s)
  • ‘homing_velocity’ = homing speed (U/s)
  • ‘jog_high_velocity’ = jog high speed (U/s)
  • ‘jog_low_velocity’ = jog low speed (U/s)
  • ‘max_acceleration’ = maximum acceleration (U/s^2)
  • ‘acceleration’ = acceleration (U/s^2)
  • ‘velocity’ = velocity (U/s)
  • ‘deceleration’ = set deceleration (U/s^2)
  • ‘error_threshold’ = set error threshold (U)
  • ‘estop_deceleration’ = estop deceleration (U/s^2)
  • ‘jerk’ = jerk rate (U/s^3)
  • ‘proportional_gain’ = PID proportional gain (optional)
  • ‘derivative_gain’ = PID derivative gain (optional)
  • ‘integral_gain’ = PID internal gain (optional)
  • ‘integral_saturation_gain’ = PID integral saturation (optional)
  • ‘trajectory’ = trajectory mode (optional)
  • ‘position_display_resolution’ (U per step)
  • ‘feedback_configuration’
  • ‘full_step_resolution’ = (U per step)
  • ‘home’ = (U)
  • ‘acceleration_feed_forward’ = between 0 to 2e9
  • ‘microstep_factor’ = axis microstep factor
  • ‘reduce_motor_torque_time’ = time (ms) between 0 and 60000,
  • ‘reduce_motor_torque_percentage’ = percentage between 0 and 100
stop_motion()[source]

Stop all motion on axis. With programmed deceleration rate

wait_for_motion(poll_interval=0.01, max_wait=None)[source]

Blocks until all movement along this axis is complete, as reported by is_motion_done.

Parameters:
  • poll_interval (float) – How long (in seconds) to sleep between checking if the motion is complete.
  • max_wait (float) – Maximum amount of time to wait before raising a IOError. If None, this method will wait indefinitely.
wait_for_position(position)[source]

Wait for axis to reach position before executing next command

Parameters:position (float or Quantity) – Position to wait for on axis
wait_for_stop()[source]

Waits for axis motion to stop before next command is executed

acceleration

Gets/sets the axis acceleration

Units:As specified (if a Quantity) or assumed to be of current newport unit
Type:Quantity or float
acceleration_feed_forward

Gets/sets the axis acceleration_feed_forward setting

Type:int
axis_id

Get axis number of Newport Controller

Type:int
current

Gets/sets the axis current (amps)

Units:As specified (if a Quantity) or assumed to be of current newport \(\text{A}\)
Type:Quantity or float
deceleration

Gets/sets the axis deceleration

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s^2}\)
Type:Quantity or float
derivative_gain

Gets/sets the axis derivative_gain

Type:float
desired_position

Gets desired position on axis in units

Units:As specified (if a Quantity) or assumed to be of current newport unit
Type:Quantity or float
desired_velocity

Gets the axis desired velocity in unit/s

Units:As specified (if a Quantity) or assumed to be of current newport unit/s
Type:Quantity or float
encoder_position

Gets the encoder position

Type:
encoder_resolution

Gets/sets the resolution of the encode. The minimum number of units per step. Encoder functionality must be enabled.

Units:The number of units per encoder step
Type:Quantity or float
error_threshold

Gets/sets the axis error threshold

Units:units
Type:Quantity or float
estop_deceleration

Gets/sets the axis estop deceleration

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s^2}\)
Type:Quantity or float
feedback_configuration

Gets/sets the axis Feedback configuration

Type:int
full_step_resolution

Gets/sets the axis resolution of the encode. The minimum number of units per step. Encoder functionality must be enabled.

Units:The number of units per encoder step
Type:Quantity or float
hardware_limit_configuration

Gets/sets the axis hardware_limit_configuration

Type:int
home

Gets/sets the axis home position. Default should be 0 as that sets current position as home

Units:As specified (if a Quantity) or assumed to be of current newport unit
Type:Quantity or float
homing_velocity

Gets/sets the axis homing velocity

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s}\)
Type:Quantity or float
integral_gain

Gets/sets the axis integral_gain

Type:float
integral_saturation_gain

Gets/sets the axis integral_saturation_gain

Type:float
is_motion_done

True if and only if all motion commands have completed. This method can be used to wait for a motion command to complete before sending the next command.

Type:bool
jerk

Gets/sets the jerk rate for the controller

Units:As specified (if a Quantity) or assumed to be of current newport unit
Type:Quantity or float
jog_high_velocity

Gets/sets the axis jog high velocity

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s}\)
Type:Quantity or float
jog_low_velocity

Gets/sets the axis jog low velocity

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s}\)
Type:Quantity or float
left_limit

Gets/sets the axis left travel limit

Units:The limit in units
Type:Quantity or float
max_acceleration

Gets/sets the axis max acceleration

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s^2}\)
Type:Quantity or float
max_base_velocity

Gets/sets the maximum base velocity for stepper motors

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s}\)
Type:Quantity or float
max_deceleration

Gets/sets the axis max decceleration. Max deaceleration is always the same as acceleration.

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s^2}\)
Type:Quantity or float
max_velocity

Gets/sets the axis maximum velocity

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s}\)
Type:Quantity or float
micro_inch = <Unit('microinch')>
microstep_factor

Gets/sets the axis microstep_factor

Type:int
motor_type

Gets/sets the axis motor type * 0 = undefined * 1 = DC Servo * 2 = Stepper motor * 3 = commutated stepper motor * 4 = commutated brushless servo motor

Type:int
Return type:NewportESP301MotorType
position

Gets real position on axis in units

Units:As specified (if a Quantity) or assumed to be of current newport unit
Type:Quantity or float
position_display_resolution

Gets/sets the position display resolution

Type:int
proportional_gain

Gets/sets the axis proportional_gain

Type:float
right_limit

Gets/sets the axis right travel limit

Units:units
Type:Quantity or float
trajectory

Gets/sets the axis trajectory

Type:int
units

Get the units that all commands are in reference to.

Type:Unit corresponding to units of axis connected or int which corresponds to Newport unit number
velocity

Gets/sets the axis velocity

Units:As specified (if a Quantity) or assumed to be of current newport \(\frac{unit}{s}\)
Type:Quantity or float
voltage

Gets/sets the axis voltage

Units:As specified (if a Quantity) or assumed to be of current newport \(\text{V}\)
Type:Quantity or float
class instruments.newport.NewportESP301HomeSearchMode[source]

Enum containing different search modes code

home_index_signals = 1

Search for combined Home and Index signals.

home_signal_only = 2

Search only for the Home signal.

neg_index_signals = 6

Search for the negative limit and Index signals.

neg_limit_signal = 4

Search for the negative limit signal.

pos_index_signals = 5

Search for the positive limit and Index signals.

pos_limit_signal = 3

Search for the positive limit signal.

zero_position_count = 0

Search along specified axes for the +0 position.

NewportError

class instruments.newport.NewportError(errcode=None, timestamp=None)[source]

Raised in response to an error with a Newport-brand instrument.

static get_message(code)[source]

Returns the error string for a given error code

Parameters:code (str) – Error code as returned by instrument
Returns:Full error code string
Return type:str
axis

Gets the axis with which this error is concerned, or None if the error was not associated with any particlar axis.

Type:int
errcode

Gets the error code reported by the device.

Type:int
messageDict = {'0': 'NO ERROR DETECTED', '1': 'PCI COMMUNICATION TIME-OUT', '10': 'Reserved for future use', '11': 'Reserved for future use', '12': 'Reserved for future use', '13': 'GROUP NUMBER MISSING', '14': 'GROUP NUMBER OUT OF RANGE', '15': 'GROUP NUMBER NOT ASSIGNED', '16': 'GROUP NUMBER ALREADY ASSIGNED', '17': 'GROUP AXIS OUT OF RANGE', '18': 'GROUP AXIS ALREADY ASSIGNED', '19': 'GROUP AXIS DUPLICATED', '2': 'Reserved for future use', '20': 'DATA ACQUISITION IS BUSY', '21': 'DATA ACQUISITION SETUP ERROR', '22': 'DATA ACQUISITION NOT ENABLED', '23': 'SERVO CYCLE (400 µS) TICK FAILURE', '24': 'Reserved for future use', '25': 'DOWNLOAD IN PROGRESS', '26': 'STORED PROGRAM NOT STARTEDL', '27': 'COMMAND NOT ALLOWEDL', '28': 'STORED PROGRAM FLASH AREA FULL', '29': 'GROUP PARAMETER MISSING', '3': 'Reserved for future use', '30': 'GROUP PARAMETER OUT OF RANGE', '31': 'GROUP MAXIMUM VELOCITY EXCEEDED', '32': 'GROUP MAXIMUM ACCELERATION EXCEEDED', '33': 'GROUP MAXIMUM DECELERATION EXCEEDED', '34': ' GROUP MOVE NOT ALLOWED DURING MOTION', '35': 'PROGRAM NOT FOUND', '36': 'Reserved for future use', '37': 'AXIS NUMBER MISSING', '38': 'COMMAND PARAMETER MISSING', '39': 'PROGRAM LABEL NOT FOUND', '4': 'EMERGENCY SOP ACTIVATED', '40': 'LAST COMMAND CANNOT BE REPEATED', '41': 'MAX NUMBER OF LABELS PER PROGRAM EXCEEDED', '5': 'Reserved for future use', '6': 'COMMAND DOES NOT EXIST', '7': 'PARAMETER OUT OF RANGE', '8': 'CABLE INTERLOCK ERROR', '9': 'AXIS NUMBER OUT OF RANGE', 'x00': 'MOTOR TYPE NOT DEFINED', 'x01': 'PARAMETER OUT OF RANGE', 'x02': 'AMPLIFIER FAULT DETECTED', 'x03': 'FOLLOWING ERROR THRESHOLD EXCEEDED', 'x04': 'POSITIVE HARDWARE LIMIT DETECTED', 'x05': 'NEGATIVE HARDWARE LIMIT DETECTED', 'x06': 'POSITIVE SOFTWARE LIMIT DETECTED', 'x07': 'NEGATIVE SOFTWARE LIMIT DETECTED', 'x08': 'MOTOR / STAGE NOT CONNECTED', 'x09': 'FEEDBACK SIGNAL FAULT DETECTED', 'x10': 'MAXIMUM VELOCITY EXCEEDED', 'x11': 'MAXIMUM ACCELERATION EXCEEDED', 'x12': 'Reserved for future use', 'x13': 'MOTOR NOT ENABLED', 'x14': 'Reserved for future use', 'x15': 'MAXIMUM JERK EXCEEDED', 'x16': 'MAXIMUM DAC OFFSET EXCEEDED', 'x17': 'ESP CRITICAL SETTINGS ARE PROTECTED', 'x18': 'ESP STAGE DEVICE ERROR', 'x19': 'ESP STAGE DATA INVALID', 'x20': 'HOMING ABORTED', 'x21': 'MOTOR CURRENT NOT DEFINED', 'x22': 'UNIDRIVE COMMUNICATIONS ERROR', 'x23': 'UNIDRIVE NOT DETECTED', 'x24': 'SPEED OUT OF RANGE', 'x25': 'INVALID TRAJECTORY MASTER AXIS', 'x26': 'PARAMETER CHARGE NOT ALLOWED', 'x27': 'INVALID TRAJECTORY MODE FOR HOMING', 'x28': 'INVALID ENCODER STEP RATIO', 'x29': 'DIGITAL I/O INTERLOCK DETECTED', 'x30': 'COMMAND NOT ALLOWED DURING HOMING', 'x31': 'COMMAND NOT ALLOWED DUE TO GROUP', 'x32': 'INVALID TRAJECTORY MODE FOR MOVING'}
start_time = datetime.datetime(2020, 12, 19, 5, 0, 23, 129891)
timestamp

Geturns the timestamp reported by the device as the time at which this error occured.

Type:datetime