Python API

Submodules

Classes

class pystages.Autofocus

Utility class to add autofocus support for scanning software. Given a set of focused coordinates, this class can calculate the correct Z-depth for other points.

clear()

Remove all registration points.

focus(x, y)

Guess the correct focus depth given abscissa and ordinate of a new point. This method will raise a RuntimeError if not enough points have been registered.

Warning: Always check for the returned value bounds to prevent stage dangerous displacements. Bad points registration or bugs can lead to unexpected big displacements.

Parameters:

  • x – Abscissa of the point.

  • y – Ordinate of the point.

Returns:

Calculated depth.

register(x, y, z)

Register a new focused point.

Parameters:

  • x – Abscissa of the point.

  • y – Ordinate of the point.

  • z – Depth of the point.

class pystages.CNCRouter(dev: str | None = None, reset_wait_time=2.0)

Class to command CNC routers.

get_current_status() → Tuple[CNCStatus, dict] | None

Sending ‘?’ character permits to get the status of the CNC router

Returns:

A tuple containing the status and a dictionary of all other parameters in the output of the command.

get_grbl_settings() → dict

Obtains and parse the list of GRBLSettings with the $$ command.

Returns:

A dictionary containing the GRBLSetting as key and its corresponding value

home(wait=False)

Sends a $H command. The stage responds a message [MSG:Sleeping] after ok. Take caution for collisions before calling this method !

Parameters:

wait – Optionally waits for move operation to be done.

property is_moving: bool

Queries the current status of the CNC in order to determine if the CNC is moving

Returns:

True if the CNC reports that a cycle is running (Run) or if it is in a middle of a homing cycle (Home).

property position: Vector

Current stage position. Vector.

Getter:

Query and return stage position.

Setter:

Move the stage.

receive() → str

Read input serial buffer to get a response. Blocks until a response is available.

Returns:

Received response string, CR-LF removed.

receive_lines(until: str = 'ok') → List[str]

Receive multiple lines until getting as specific value.

Parameters:

until – The expected response indicating the end of received lines.

Returns:

The list of all received lines. Note that the expected line is not included in the list.

reset_grbl(wait_time: float | None = None) → bool

Sends a CTRL+X control to reset the GRBL

Returns:

True if the GRBL sent the correct prompt at the end of the reset

Parameters:

wait_time – Depending on the state of the stage, it can take some time for GRBL to reset. This parameter makes the wait time to be tuned, by giving a time in seconds.

send(command: str, eol: str | None = None)

Send a command.

Parameters:

  • command – Command string.

  • eol – End of command character(s). If None, LF will be automatically append.

send_receive(command: str) → str

Send a command, wait and return the response.

Parameters:

command – Command string.

Returns:

Received response string, CR-LF removed.

set_grbl_setting(setting: GRBLSetting, value: float | bool | InvertMask | StatusReportMask | int)

Set the GRBL setting of the Router with given value. The value type must correspond to type defined in GRBLSetting.

set_origin() → str

Set current position as origin

Returns:

The response of the CNC (‘ok’ if command has been submitted correctly).

sleep() → str

Sends a $SLP command. The stage responds a message [MSG:Sleeping] after ok.

Returns:

The response of the CNC (‘ok’ if command has been submitted correctly).

unlock() → bool

Unlock the motor. It may happen when the stage has gone further its limits, and raised an alarm, or has been disabled when going in sleep mode ($SLP)

Returns:

True if message [MSG:Caution: Unlock] has been returned

class pystages.CNCStatus(value)

Possible statuses that the CNC can report.

class pystages.Corvus(dev: str | None = None, serial_number: str | None = None)

Class to command Corvus Eco XYZ stage controller.

property acceleration

Motors acceleration setting, in µm/s^2.

Getter:

Query and return current setting.

Setter:

Update controller setting.

calibrate()

Execute limit-switch move. Wait until calibration is done. Take caution for collisions before calling this method !

calibrate_xy()

Execute limit-switch move only on X and Y axises. Wait until calibration si done. Take caution for collisions before calling this method !

enable_joystick()

Enable joystick (manual mode)

home(wait=False)

Execute limit-switch move. Take caution for collisions before calling this method !

Parameters:

wait – Optionally waits for move operation to be done.

property is_connected
Returns:

True if the instance is connected to the stage.

property is_moving

Queries the status of the stage to determine if it is moving

move_relative(x, y, z)

Move stage relative to current position.

Parameters:

  • x – Relative distance on X-axis, in micrometers.

  • y – Relative distance on Y-axis, in micrometers.

  • z – Relative distance on Z-axis, in micrometers.

property position

Current stage position. Vector.

Getter:

Query and return stage position.

Setter:

Move the stage.

receive() → str

Read input serial buffer to get a response. Blocks until a response is available.

Returns:

Received response string, CR-LF removed.

restore()

Reactivates the last saved parameters. Beware this might change units, which may be dangerous if care is not taken.

save()

Save current parameters in non-volatile memory.

send(command: str)

Send a command.

Parameters:

command – Command string. CR or blank must not be present at the end of this string.

send_receive(command: str) → str

Send a command, wait and return the response.

Parameters:

command – Command string. CR or blank must not be present at the end of this string.

Returns:

Received response string, CR-LF removed.

set_origin()

Set current stage’s coordinates as the new origin.

property velocity

Motors velocity setting, in µm/s.

Getter:

Query and return current setting.

Setter:

Update controller setting.

class pystages.M3FS(dev: str | None = None, baudrate=250000)

Class to command New Scale Technologies M3-FS focus modules in serial mode (VCP). If a M3-FS device is seen as a USBXpress chip, it may be used as a Virtual-Com-Port after a few cumbersome operations (custom driver with correct VID/DID).

command(command: M3FSCommand, data=None)

Send a command to the controller and get the response.

Parameters:

  • command – Command integer ID.

  • data – Extra data string.

Returns:

Response data string.

property is_moving: bool

Queries the status of the stage to determine if it is moving

property position: Vector

Stage position, in micrometers.

Getter:

Query and return current stage position.

Setter:

Move stage. Wait until position is reached.

class pystages.SMC100(dev: str | Link | SMC100 | None, addresses: List[int])

Class to command Newport SMC100 controllers.

controller_address(addr: int)

Get controller’s RS-485 address. int in [2, 31].

enter_configuration_state(addr: int)

Enter configuration state.

enter_leave_disable_state(addr: int | None, enter: bool = True)

Permits for a specified axis to enter or leave the DISABLE state. DISABLE state makes the motor not energized and opens the control loop.

Parameters:

  • addr – address of the axis to operate. If None is passed, it applies to all controllers

  • enter – True to enter, False to leave DISABLE state

get_error_and_state(addr: int)

Query current motion controller errors and state. Querying the error and state may clear error flags.

Parameters:

addr – Address of the axis.

Returns:

Current error and state, in a ErrorAndState instance.

home(wait=False)

Perform home search.

Parameters:

wait – Optionally waits for move operation to be done.

Perform home search. Home search is performed even if the axes are already referenced. It may be better to use home_search_if_required.

home_search_if_required()

Perform home search for all axes which are not referenced.

property is_disabled: bool

Indicates if the stage is currently in DISABLE state. :return: Disabled state of the stage

property is_moving: bool

Indicates if the stage is currently moving due to MOVE, HOME or JOG operation.

Returns:

Moving state of the stage

leave_configuration_state(addr)

Leave configuration state. If defined parameters are valid, the controller saves them in the flash memory.

move_relative(addr: int, offset: float)

Moves relatively an axis from a given offset

Parameters:

  • addr – addr of axis to move

  • offset – offset value

property position

Stage position, in micrometers.

Getter:

Query and return current stage position.

Setter:

Move stage.

reset(addr: int | None = None)

Resets the controller at specified address. For all controllers if not specified

Parameters:

addr – address of the controller to reset

set_controller_address(addr: int, value: int)

Set controller’s RS-485 address. int in [2, 31]. Changing the address is only possible when the controller is in configuration state.

set_position(addr: int, value: float, blocking=True)

Sets the position of a single axis

Parameters:

  • addr – address of the axis to set the position

  • value – stage position, in micrometers

  • blocking – if True, blocking mode: wait for the position to be reached before exit.

stop(addr: int | None = None)

Stops the motion on an axis. On all axis if addr not specified.

Parameters:

addr – Address of the axis to stop. If None, stop all the controllers

class pystages.Stage(num_axis=1)

Stage is an abstract class from which all stage implementation must inherit to get a consistent behavior and value checking for getting and setting position, setting software limits…

check_dimension(value: Vector)

Check if the given value’s dimension is consistent according to the number of axes of the Stage. :param value: The vector to check :raises ValueError: If dimension is inconsistent with the number of axis of the Stage.

check_range(value: Vector)

Check if the given value is in range according to minimums/maximums. If it is not the case, a ValueException is raised.

Parameters:

value – The vector to check if it is within authorized range.

find_device(pid: int | None = None, vid: int | None = None, serial_number: str | None = None) → str

Find automatically one device according to given information in parameters

Parameters:

  • pid – Product ID of the device. If None, not a limiting criteria.

  • vid – Vendor ID of the device. If None, not a limiting criterial.

  • serial_number – serial number of the device. If not None, the device must have a serial number and matches the given value.

Returns:

The device path to the communication port.

home(wait=False)

Triggers a homing command.

Parameters:

wait – Optionally waits for move operation to be done.

abstract property is_moving: bool

Queries the status of the stage to determine if it is moving

move_to(value: Vector, wait: bool = True)

Move stage to a new position, with the possibility to poll device until the move finishes.

Parameters:

  • value – New stage position.

  • wait – If True, wait for stage to be at the new position, otherwise return immediately.

abstract property position: Vector

Current stage position. Vector.

Getter:

Query and return stage position.

Setter:

Move the stage.

wait_move_finished()

Wait until all axis are ready.

class pystages.Tic

Very basic driver class for Polulu Tic Stepper Motor controller, connected in USB.

Variables:

poll_interval – Interval between successive state polling for some long motor operations.

block_read(command: TicCommand, offset, length) → bytes

Read data from the device.

Parameters:

  • command – Command code.

  • offset – Data offset.

  • length – Data length.

go_home(direction: TicDirection, wait: bool = True)

Run the homing procedure. :param direction: Homing direction. :param wait: If True, wait for homing procedure end.

home(wait=False)

Triggers a Home command.

Parameters:

wait – Optionally waits for move operation to be done.

property is_moving: bool

Because there is no specific command to get the current moving state of the Tic, and the positioning/homing is always blocking, this function returns False in all cases.

property position: Vector

Motor position, in steps.

Getter:

Returns current target position.

Setter:

Set target position and wait until position is reached.

quick(command: TicCommand)

Send a quick command with no data.

Parameters:

command – Command.

set_setting(command: TicCommand, data, offset)

Set setting data.

Parameters:

  • command – Command code.

  • data – Value to be written.

  • offset – Write offset.

write_32(command: TicCommand, data: int)

Write 32 bits.

Parameters:

  • command – Command code.

  • data – Value to be written.

write_7(command: TicCommand, data: int)

Write 7 bits.

Parameters:

  • command – Command.

  • data – Value to be written.

class pystages.TicDirection(value)

Possible directions for homing

class pystages.Vector(*args, dim=None)

Some basic vector manipulation class for stages control.

property w

Fourth element of the vector.

property x

First element of the vector.

property xy

First and second elements of the vector, as a 2D Vector.

property y

Second element of the vector.

property z

Third element of the vector.