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(*values)[source]

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

X = 1

Y = 2

class 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.

property axis_status: Returns the status of the current axis.

property 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

property 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.

property 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.

property 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

property 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)

property 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

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.

property 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:: AGUC2.Axis

property enable_remote_mode: Gets / sets the status of remote mode.

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

property firmware_version: Returns the firmware version of the controller

property 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

property 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

`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.

class Axis(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=None)[source]

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

Parameters:: search_mode (HomeSearchMode) – Method to detect when Home has been found. If None, the search mode is taken from HomeSearchMode.

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 NewportESP301.Units)(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 NewportESP301.Axis.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

property acceleration

Gets/sets the axis acceleration

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

property acceleration_feed_forward

Gets/sets the axis acceleration_feed_forward setting

Type:: int

property axis_id

Get axis number of Newport Controller

Type:: int

property 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

property 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

property derivative_gain

Gets/sets the axis derivative_gain

Type:: float

property 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

property 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

property encoder_position

Gets the encoder position

Type:

property 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

property error_threshold

Gets/sets the axis error threshold

Units:: units
Type:: Quantity or float

property 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

property feedback_configuration

Gets/sets the axis Feedback configuration

Type:: int

property 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

property hardware_limit_configuration

Gets/sets the axis hardware_limit_configuration

Type:: int

property 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

property 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

property integral_gain

Gets/sets the axis integral_gain

Type:: float

property integral_saturation_gain

Gets/sets the axis integral_saturation_gain

Type:: float

property 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

property 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

property 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

property 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

property left_limit

Gets/sets the axis left travel limit

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

property 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

property 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

property 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

property 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')>

property microstep_factor

Gets/sets the axis microstep_factor

Type:: int

property 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:: NewportESP301.MotorType

property 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

property position_display_resolution

Gets/sets the position display resolution

Type:: int

property proportional_gain

Gets/sets the axis proportional_gain

Type:: float

property right_limit

Gets/sets the axis right travel limit

Units:: units
Type:: Quantity or float

property trajectory

Gets/sets the axis trajectory

Type:: int

property 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

property 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

property 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 HomeSearchMode(*values)[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.

class MotorType(*values)[source]

Enum for different motor types.

commutated_brushless_servo = 4

commutated_stepper_motor = 3

dc_servo = 1

stepper_motor = 2

undefined = 0

class Units(*values)[source]

Enum containing what units return means.

degree = 7

encoder_step = 0

gradian = 8

inches = 4

micro_inches = 6

micrometer = 3

microradian = 11

milli_inches = 5

millimeter = 2

milliradian = 10

motor_step = 1

radian = 9

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 (HomeSearchMode) – Method to detect when Home has been found.
errcheck (bool) – Boolean to check for errors after each command that is sent to the instrument.

property 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:: NewportESP301.Axis

`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

property axis

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

Type:: int

property 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(2026, 5, 26, 19, 57, 47, 998766)

property timestamp

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

Type:: datetime

`PicoMotorController8742`

class instruments.newport.PicoMotorController8742(filelike)[source]

Newport Picomotor Controller 8742 Communications Class

Use this class to communicate with the picomotor controller 8742. Single-controller and multi-controller setup can be used.

Device can be talked to via TCP/IP or over USB. FixMe: InstrumentKit currently does not communicate correctly via USB!

Example for TCP/IP controller in single controller mode:

>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> motor1 = inst.axis[0]
>>> motor1.move_relative = 100

Example for communications via USB:

>>> import instruments as ik
>>> pid = 0x4000
>>> vid = 0x104d
>>> ik.newport.PicoMotorController8742.open_usb(pid=pid, vid=vid)
>>> motor3 = inst.axis[2]
>>> motor3.move_absolute = -200

Example for multicontrollers with controller addresses 1 and 2:

>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> inst.multiple_controllers = True
>>> contr1mot1 = inst.axis[0]
>>> contr2mot1 = inst.axis[4]
>>> contr1mot1.move_absolute = 200
>>> contr2mot1.move_relative = -212

class Axis(parent, idx)[source]

PicoMotorController8742 Axis class for individual motors.

class MotorType(*values)[source]

IntEnum Class containing valid MotorTypes

Use this enum to set the motor type. You can select that no or an unkown motor are connected. See also motor_check command to set these values per controller automatically.

none = 0

standard = 3

tiny = 2

unknown = 1

abort_motion()[source]: Instantaneously stops any motion in progress.

motor_check()[source]

Check what motors are connected and set parameters.

Use the save command save_settings if you want to save the configuration to the non-volatile memory.

move_indefinite(direction)[source]

Move the motor indefinitely in the specific direction.

To stop motion, issue stop_motion or abort_motion command. Direction is defined as a string of either “+” or “-“.

Parameters:: direction (str) – Direction in which to move the motor, “+” or “-”

Example:

>>> from time import sleep
>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.move_indefinite("+")
>>> sleep(1)   # wait a second
>>> ax.stop()

purge()[source]

Purge the non-volatile memory of the controller.

Perform a hard reset and reset all the saved variables. The following variables are reset to factory settings: 1. Hostname 2. IP Mode 3. IP Address 4. Subnet mask address 5. Gateway address 6. Configuration register 7. Motor type 8. Desired Velocity 9. Desired Acceleration

query(cmd, size=-1, axs=True)[source]

Query for an axis object.

Parameters:

cmd (str) – Command
size (int) – bytes to read, defaults to “until terminator” (-1)
axs (bool) – Send axis address along? Not used for controller commands. Defaults to True

Raises:

IOError – The wrong axis answered.

recall_parameters(value=0)[source]

Recall parameter set.

This command restores the controller working parameters from values saved in its non-volatile memory. It is useful when, for example, the user has been exploring and changing parameters (e.g., velocity) but then chooses to reload from previously stored, qualified settings. Note that *RCL 0 command just restores the working parameters to factory default settings. It does not change the settings saved in EEPROM.

Parameters:: value – 0 -> Recall factory default, 1 -> Recall last saved settings

reset()[source]

Reset the controller.

Perform a soft reset. Saved variables are not deleted! For a hard reset, see the purge command.

..note:: It might take up to 30 seconds to re-establish: communications via TCP/IP

save_settings()[source]

Save user settings.

This command saves the controller settings in its non-volatile memory. The controller restores or reloads these settings to working registers automatically after system reset or it reboots. The purge command is used to clear non-volatile memory and restore to factory settings. Note that the SM saves parameters for all motors.

Saves the following variables: 1. Controller address 2. Hostname 3. IP Mode 4. IP Address 5. Subnet mask address 6. Gateway address 7. Configuration register 8. Motor type 9. Desired Velocity 10. Desired Acceleration

sendcmd(cmd, axs=True)[source]

Send a command to an axis object.

Parameters:

cmd (str) – Command
axs (bool) – Send axis address along? Not used for controller commands. Defaults to True

stop()[source]

Stops the specific axis if in motion.

Example:

>>> from time import sleep
>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.move_indefinite("+")
>>> sleep(1)   # wait a second
>>> ax.stop()

property acceleration

Get / set acceleration of axis in steps / sec^2.

Valid values are between 1 and 200,000 (steps) 1 / sec^2 with the default as 100,000 (steps) 1 / sec^2. If quantity is not unitful, it is assumed that 1 / sec^2 is chosen.

Returns:: Acceleration in 1 / sec^2
Return type:: u.Quantity(int)
Raises:: ValueError – Limit is out of bound.

Example:

>>> import instruments as ik
>>> import instruments.units as u
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.acceleration = u.Quantity(500, 1/u.s**-2)

property controller_address

Get / set the controller address.

Valid address values are between 1 and 31. For setting up multiple instruments, see multiple_controllers.

Returns:: Address of this device if secondary, otherwise None
Return type:: int

property controller_configuration

Get / set configuration of some of the controller’s features.

Configuration is given as a bit mask. If changed, please save the settings afterward if you would like to do so. See save_settings.

The bitmask to be set can be either given as a number, or as a string of the mask itself. The following values are equivalent: 3, 0b11, “11”

Bit 0:
- Value 0: Perform auto motor detection. Check and set motor
  type automatically when commanded to move.
- Value 1: Do not perform auto motor detection on move.
Bit 1:
- Value 0: Do not scan for motors connected to controllers upon
  reboot (Performs ‘MC’ command upon power-up, reset or reboot).
- Value 1: Scan for motors connected to controller upon power-up
  or reset.

Returns:: Bitmask of the controller configuration.
Return type:: str, binary configuration

property error_code

Get error code only.

Error code0 means no error detected.

Returns:: Error code.
Return type:: int

property error_code_and_message

Get error code and message.

Returns:: Error code, error message
Return type:: int, str

property firmware_version: Get the controller firmware version.

property home_position

Get / set home position

The home position of the device is used, e.g., when moving to a specific position instead of a relative move. Valid values are between -2147483648 and 2147483647.

Returns:: Home position.
Return type:: int
Raises:: ValueError – Set value is out of range.

Example:

>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.home_position = 444

property is_stopped

Get if an axis is stopped (not moving).

Returns:: Is the axis stopped?
Return type:: bool

Example:

>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.is_stopped
True

property motor_type

Set / get the type of motor connected to the axis.

Use a MotorType IntEnum to set this motor type.

Returns:: Motor type set.
Return type:: MotorType
Raises:: TypeError – Set motor type is not of type MotorType.

Example:

>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.motor_type = ax.MotorType.tiny

property move_absolute

Get / set the absolute target position of a motor.

Set with absolute position in steps. Valid values between -2147483648 and +2147483647. See also: home_position.

Returns:: Absolute motion target position.
Return type:: int
Raises:: ValueError – Requested position out of range.

Example:

>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.move_absolute = 100

property move_relative

Get / set the relative target position of a motor.

Set with relative motion in steps. Valid values between -2147483648 and +2147483647. See also: home_position.

Returns:: Relative motion target position.
Return type:: int
Raises:: ValueError – Requested motion out of range.

Example:

>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.move_relative = 100

property name: Get the name of the controller.

property position

Queries current, actual position of motor.

Positions are with respect to the home position.

Returns:: Current position in steps.
Return type:: int

Example:

>>> import instruments as ik
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.position
123

property velocity

Get / set velocty of the connected motor (unitful).

Velocity is given in (steps) per second (1/s). If a MotorType.tiny motor is connected, the maximum velocity allowed is 1750 /s, otherwise 2000 /s. If no units are given, 1/s are assumed.

Returns:: Velocity in 1/s
Return type:: u.Quantity(int)
Raises:: ValueError – Set value is out of the allowed range.

Example:

>>> import instruments as ik
>>> import instruments.units as u
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> ax = inst.axis[0]
>>> ax.velocity = u.Quantity(500, 1/u.s)

abort_motion()[source]

Instantaneously stop any motion in progress.

Example:

>>> import instruments as ik
>>> import instruments.units as u
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> inst.abort_motion()

motor_check()[source]

Check what motors are connected and set parameters.

Use the save command save_settings if you want to save the configuration to the non-volatile memory.

Example:

>>> import instruments as ik
>>> import instruments.units as u
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> inst.motor_check()

purge()[source]

Purge the non-volatile memory of the controller.

Perform a hard reset and reset all the saved variables. The following variables are reset to factory settings: 1. Hostname 2. IP Mode 3. IP Address 4. Subnet mask address 5. Gateway address 6. Configuration register 7. Motor type 8. Desired Velocity 9. Desired Acceleration

Example:

>>> import instruments as ik
>>> import instruments.units as u
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> inst.purge()

query(cmd, size=-1)[source]

Query’s the device and returns ASCII string.

Must be queried as a raw string with terminator line ending. This is currently not implemented in instrument and therefore must be called directly from file.

Sometimes, the instrument sends an undecodable 6 byte header along (usually for the first query). We’ll catch it with a try statement. The 6 byte header was also remarked in this matlab script: https://github.com/cnanders/matlab-newfocus-model-8742

recall_parameters(value=0)[source]

Recall parameter set.

This command restores the controller working parameters from values saved in its non-volatile memory. It is useful when, for example, the user has been exploring and changing parameters (e.g., velocity) but then chooses to reload from previously stored, qualified settings. Note that *RCL 0 command just restores the working parameters to factory default settings. It does not change the settings saved in EEPROM.

Parameters:: value (int) – 0 -> Recall factory default, 1 -> Recall last saved settings

Example:

>>> import instruments as ik
>>> import instruments.units as u
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> inst.recall_parameters(1)

reset()[source]

Reset the controller.

Perform a soft reset. Saved variables are not deleted! For a hard reset, see the purge command.

..note:: It might take up to 30 seconds to re-establish communications via TCP/IP

Example:

>>> import instruments as ik
>>> import instruments.units as u
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> inst.reset()

save_settings()[source]

Save user settings.

This command saves the controller settings in its non-volatile memory. The controller restores or reloads these settings to working registers automatically after system reset or it reboots. The purge command is used to clear non-volatile memory and restore to factory settings. Note that the SM saves parameters for all motors.

Saves the following variables: 1. Controller address 2. Hostname 3. IP Mode 4. IP Address 5. Subnet mask address 6. Gateway address 7. Configuration register 8. Motor type 9. Desired Velocity 10. Desired Acceleration

Example:

>>> import instruments as ik
>>> import instruments.units as u
>>> ip = "192.168.1.2"
>>> port = 23   # this is the default port
>>> inst = ik.newport.PicoMotorController8742.open_tcpip(ip, port)
>>> inst.save_settings()

scan(value=2)[source]

Initialize and set controller addresses automatically.

Scans the RS-485 network for connected controllers and set the addresses automatically. Three possible scan modes can be selected:

Mode 0:: Primary controller scans the network but does not resolve any address conflicts.
Mode 1:: Primary controller scans the network and resolves address conflicts, if any. This option preserves the non-conflicting addresses and reassigns the conflicting addresses starting with the lowest available address.
Mode 2 (default):: Primary controller reassigns the addresses of all controllers on the network in a sequential order starting with master controller set to address 1.

Newport

Agilis Piezo Motor Controller

NewportESP301 Motor Controller

NewportError

PicoMotorController8742

`Agilis` Piezo Motor Controller

`NewportESP301` Motor Controller

`NewportError`

`PicoMotorController8742`