Scientifica

class acq4.devices.Scientifica.Scientifica(man, config, name)

Bases: Stage

A Scientifica motorized device driver for manipulators and stages.

• Supports PatchStar, MicroStar, SliceScope, objective changers, and other Scientifica devices.

• Requires the pyserial package for serial communication.

• Recommends Scientifica’s LinLab software for initial configuration and testing, but note that ACQ4 will not be able to access the serial port while LinLab is running.

Configuration options:

• port (str, optional): Serial port (e.g., ‘COM1’ or ‘/dev/ttyACM0’) Either port or name must be specified.

• name (str, optional): Device name as assigned in LinLab software (e.g., ‘SliceScope’ or ‘MicroStar 2’). Either port or name must be specified.

• baudrate (int, optional): Serial baud rate (9600 or 38400) Both rates will be attempted if not specified.

• version (int, optional): Controller version (default: 2) Some devices require version=1 for compatibility.

• scale (tuple, optional): (x, y, z) scale factors in m/step (default: (1e-6, 1e-6, 1e-6))

• userSpeed (float, optional): Default speed for manual control (m/sec). Sets the maximum speed when device is under manual control.

• autoZeroDirection (tuple, optional): Auto-zero direction for each axis. This affects the direction traveled when “auto-set zero position” is clicked from the manager dock. (default: (-1, -1, -1)). Set to None to disable auto-zero for an axis.

• monitorObjective (bool, optional): Monitor objective changer state (default: False). Set to True to track objective position changes.

• capabilities (dict, optional): Override device capabilities Format: {“getPos”: (x, y, z), “setPos”: (x, y, z), “limits”: (x, y, z)} where each tuple contains booleans for each axis.

• isManipulator (bool, optional): Override manipulator detection If not specified, detection is automatic based on device type.

• params (dict, optional): Low-level device parameters that are set on the device at ACQ4 startup time. These may also be configured using LinLab, but we recommend setting them here in order to enforce consistent settings.

  • axisScale: (x, y, z) axis scaling factors affect the size and direction of steps reported by the device. The absolute value of these is determined by the manufacturer and should not be changed. The sign may be changed to flip the direction of the axis.

  • joyDirectionX/Y/Z: (bool) Used to switch the direction of the patch pad / patch cube rotary control for each axis. Note that the rotary control direction is also affected by the sign of the axisScale values.

  • minSpeed, maxSpeed: Speed limits in device units

  • maxZSpeed, minZSpeed: Z-axis specific speed limits (for devices with separate Z control)

  • accel: Acceleration setting

  • joySlowScale, joyFastScale: Joystick speed scaling

  • joyAccel: Joystick acceleration

  • approachAngle: Approach mode angle (degrees)

  • approachMode: Approach mode enabled (bool) Note: the approach mode is also set using a physical switch on the device; setting this parameter here may cause the device to behave contrary to the physical switch state until it is toggled.

  • objLift: Distance to lift objectives before switching (int; 1 = 10 nm) Note: the sign of this distance depends on the sign of the Z axisScale parameter.

  • objDisp: Distance between focal planes of objectives (int; 1 = 10 nm) Note: the sign of this distance depends on the sign of the Z axisScale parameter.

  • objL1, objL2: Legacy objective switching parameters for version 2 devices (int)

  • currents: Motor current limits (not recommended to change these; be careful to follow manufacturer specs!)

Example configuration:

SliceScope:
    driver: 'Scientifica'
    name: 'SliceScope'
    scale: [-1e-6, -1e-6, 1e-6]
    params:
        axisScale: [5.12, -5.12, -6.4]
        joyDirectionX: True
        joyDirectionY: True
        joyDirectionZ: False
        minSpeed: 1000
        maxSpeed: 30000
        accel: 500
        joySlowScale: 4
        joyFastScale: 80
        joyAccel: 500

Testing:

python -i -m acq4.drivers.Scientifica.test “Slicescope”

abort(reason=None)

Stop the manipulator immediately.

axes()

Return a tuple of axis names implemented by this device, like (‘x’, ‘y’, ‘z’).

The axes described in the above data structure correspond to the mechanical actuators on the device; they do not necessarily correspond to the axes in the global coordinate system or the local coordinate system of the device.

This method must be reimplemented by subclasses.

capabilities()

Return a structure describing the capabilities of this device

deviceInterface(win)

Return a widget with a UI to put in the device rack

getSwitch(name)

property positionUpdatesPerSecond

Return the rate at which the device reports position updates.

quit()

setUserSpeed(v)

Set the maximum speed of the stage (m/sec) when under manual control.

The stage’s maximum speed is reset to this value when it is not under programmed control.

startMoving(vel)

Begin moving the stage at a continuous velocity.

stop(reason=None)

Stop the manipulator immediately.

targetPosition()

If the stage is moving, return the target position. Otherwise return the current position.

Zero Offset Calibration

Scientifica devices track position internally relative to a hardware zero point, which is retained across power cycles. It only needs to be re-established if a motor has slipped or was physically rotated while powered off.

Two buttons in the device’s Manager dock control this:

• “Zero position”: Declares the current position to be zero on all axes.

• “Auto-set zero position”: Drives each axis to its mechanical limit switch and sets that as zero. Per-axis variants (“Auto-set X/Y/Z zero”) are also available. A confirmation dialog appears before any movement begins.

Consistency between axisScale, autoZeroDirection, and limits

Three configuration values must be self-consistent:

1. ``params -> axisScale``: Absolute value is set by the manufacturer and should not be changed. The sign determines which physical direction of motion corresponds to positive position values. The Scientifica default gives +Z = downward (toward the sample). On some devices the sign cannot be changed.

2. ``autoZeroDirection`` (default (-1, -1, -1)): The direction each axis is driven when auto-zeroing — -1 drives toward very negative position, +1 toward very positive. Choose the value that sends each axis toward a safe limit switch (one where an unobstructed move is guaranteed). After zeroing, that limit switch becomes position 0.

3. ``limits``: Software-enforced (min, max) position range in device position coordinates (micrometers, the same units returned by getPosition() — not meters). After zeroing, one end of the range is 0 (at the zero limit switch) and the other end is the signed travel distance in µm. Positions slightly outside the configured range near the physical limit switches are normal.

Example

With the Scientifica default (+Z = downward), the top of travel is in the negative direction. autoZeroDirection[Z] = -1 drives upward to the top limit switch (Z = 0); the full downward range is then positive:

autoZeroDirection: -1, -1, -1
limits:
    z: 0, 20000    # µm (= 20 mm of downward travel)

If the sign of axisScale[Z] is flipped so that +Z = upward, the top of travel is in the positive direction and autoZeroDirection[Z] = +1 is needed; the full downward range is then negative:

autoZeroDirection: -1, -1, 1
limits:
    z: -20000, 0    # µm