Hardware control configurations

ImSwitch’s hardware control module is designed to be flexible and be usable in a wide variety of microscopy setups. In order to provide this flexibility, hardware configurations are defined in .json files that are loaded when the hardware control module starts.

Hardware configuration files are loaded from the imcontrol_setups directory, which is automatically created inside your user directory for ImSwitch the first time the hardware control module starts. It contains some pre-made configuration files by default. The user directory is located at %USERPROFILE%\Documents\ImSwitch on Windows and ~/ImSwitch on macOS/Linux.

The first time you start the hardware control module, you will be prompted to select a setup file to load. If you want to switch to another hardware configuration later, select “Tools” -> “Pick hardware setup…” in the hardware control module’s menu bar.

How configurations are defined

Hardware configurations are defined in JSON format. Behind the scenes, they are automatically translated to Python class instances when loaded into the software.

A central concept in ImSwitch is that of device managers. Device managers define what kind of device you have, and how ImSwitch communicates with it. For example, if you have a Hamamatsu camera that you would like to control, you would define a detector that uses the HamamatsuManager in the hardware setup file and set its appropriate properties. The list of available managers and their properties can be found here. Each device must have a unique name, which is represented by its object key in the JSON.

Signal designers, which are relevant for users who use the scan functionality, are similar. Microscopy scans can be set up in different ways; in a point-scanning setup, for instance, you might want to set your scan settings to use the PointScanTTLCycleDesigner to generate the appropriate TTL signals. They are documented here.

As a very simple example, a hardware configuration file that allows you to control a single Cobolt 06-01 (non-DPL) laser connected to COM port 11 can look like this:

{
    "lasers": {
        "Cobolt405nm": {
            "managerName": "Cobolt0601LaserManager",
            "managerProperties": {
                "digitalPorts": ["COM11"]
            },
            "valueRangeMin": 0,
            "valueRangeMax": 200,
            "wavelength": 405
        }
    },
    "availableWidgets": [
        "Laser"
    ]
}

Note that the digitalPorts property is specific to Cobolt0601LaserManager.

Configuration file specification

class ViewSetupInfo

This is the object represented by the hardware configuration JSON file. All fields are optional, unless explicitly otherwise specified.

autofocus: Optional[AutofocusInfo]

Autofocus settings. Required to be defined to use autofocus functionality.

availableWidgets: Union[List[str], bool]

Which widgets to load. The following values are possible to include (case sensitive):

  • Settings (detector settings widget)

  • View (image controls widget)

  • Recording (recording widget)

  • Image (image display widget)

  • FocusLock (focus lock widget; requires focusLock field to be defined)

  • Autofocus (autofocus widget; requires focusLock field to be defined)

  • SLM (SLM widget; requires slm field to be defined)

  • Laser (laser control widget)

  • Positioner (positioners widget)

  • Scan (scan widget; requires scan field to be defined)

  • BeadRec (bead reconstruction widget)

  • AlignAverage (axial alignment tool widget)

  • AlignXY (rotation alignment tool widget)

  • AlignmentLine (line alignment tool widget)

  • uLenses (uLenses tool widget; requires Image widget)

  • FFT (FFT tool widget)

  • Console (Python console widget)

  • EtSTED (etSTED widget; requires etSTED field to be defined)

You can also set this to true to enable all widgets, or false to disable all widgets.

This field is required.

defaultLaserPresetForScan: Optional[str]

Default laser preset for scanning.

detectors: Dict[str, DetectorInfo]

Detectors in this setup. This is a map from unique detector names to DetectorInfo objects.

etSTED: Optional[EtSTEDInfo]

EtSTED settings. Required to be defined to use etSTED functionality.

focusLock: Optional[FocusLockInfo]

Focus lock settings. Required to be defined to use focus lock functionality.

laserPresets: Dict[str, Dict[str, LaserPresetInfo]]

Laser presets available to select (map preset name -> laser name -> LaserPresetInfo).

lasers: Dict[str, LaserInfo]

Lasers in this setup. This is a map from unique laser names to LaserInfo objects.

nidaq: NidaqInfo

NI-DAQ settings.

positioners: Dict[str, PositionerInfo]

Positioners in this setup. This is a map from unique positioner names to DetectorInfo objects.

pulseStreamer: PulseStreamerInfo

Pulse Streamer settings.

rois: Dict[str, ROIInfo]

Additional ROIs available to select in detector settings.

rs232devices: Dict[str, RS232Info]

RS232 connections in this setup. This is a map from unique RS232 connection names to RS232Info objects. Some detector/laser/positioner managers will require a corresponding RS232 connection to be referenced in their properties.

scan: Optional[ScanInfo]

Scan settings. Required to be defined to use scan functionality.

slm: Optional[SLMInfo]

SLM settings. Required to be defined to use SLM functionality.

Item types that may be included

class DetectorInfo
analogChannel: Optional[Union[int, str]]

Channel for analog communication. null if the device is digital or doesn’t use NI-DAQ. If an integer is specified, it will be translated to “Dev1/ao{analogChannel}”.

digitalLine: Optional[Union[int, str]]

Line for digital communication. null if the device is analog or doesn’t use NI-DAQ. If an integer is specified, it will be translated to “Dev1/port0/line{digitalLine}”.

forAcquisition: bool = False

Whether the detector is used for acquisition.

forFocusLock: bool = False

Whether the detector is used for focus lock.

managerName: str

Manager class name.

managerProperties: Dict[str, Any]

Properties to be read by the manager.

class LaserInfo
analogChannel: Optional[Union[int, str]]

Channel for analog communication. null if the device is digital or doesn’t use NI-DAQ. If an integer is specified, it will be translated to “Dev1/ao{analogChannel}”.

digitalLine: Optional[Union[int, str]]

Line for digital communication. null if the device is analog or doesn’t use NI-DAQ. If an integer is specified, it will be translated to “Dev1/port0/line{digitalLine}”.

freqRangeInit: Optional[int] = 0

Initial value of frequency modulation. Don’t fill if laser doesn’t support it.

freqRangeMax: Optional[int] = 0

Minimum value of frequency modulation. Don’t fill if laser doesn’t support it.

freqRangeMin: Optional[int] = 0

Minimum value of frequency modulation. Don’t fill if laser doesn’t support it.

managerName: str

Manager class name.

managerProperties: Dict[str, Any]

Properties to be read by the manager.

valueRangeMax: Optional[Union[int, float]]

maximum value of the laser. null if laser doesn’t setting a value.

valueRangeMin: Optional[Union[int, float]]

Minimum value of the laser. null if laser doesn’t setting a value.

valueRangeStep: float = 1.0

The default step size of the value range that the laser can be set to.

wavelength: Union[int, float]

Laser wavelength in nanometres.

class PositionerInfo
analogChannel: Optional[Union[int, str]]

Channel for analog communication. null if the device is digital or doesn’t use NI-DAQ. If an integer is specified, it will be translated to “Dev1/ao{analogChannel}”.

axes: List[str]

A list of axes (names) that the positioner controls.

digitalLine: Optional[Union[int, str]]

Line for digital communication. null if the device is analog or doesn’t use NI-DAQ. If an integer is specified, it will be translated to “Dev1/port0/line{digitalLine}”.

forPositioning: bool = False

Whether the positioner is used for manual positioning.

forScanning: bool = False

Whether the positioner is used for scanning.

isPositiveDirection: bool = True

Whether the direction of the positioner is positive.

managerName: str

Manager class name.

managerProperties: Dict[str, Any]

Properties to be read by the manager.

class RS232Info
managerName: str

RS232 manager class name.

managerProperties: Dict[str, Any]

Properties to be read by the RS232 manager.

class SLMInfo
angleMount: float

The angle of incidence and reflection of the laser line that is shaped by the SLM, in radians. For adding a blazed grating to create off-axis holography.

correctionPatternsDir: str

Directory of .bmp images provided by Hamamatsu for flatness correction at various wavelengths. A combination will be chosen based on the wavelength.

height: int

Height of SLM, in pixels.

monitorIdx: int

Index of the monitor in the system list of monitors (indexing starts at 0).

pixelSize: float

Pixel size or pixel pitch of the SLM, in millimetres.

wavelength: int

Wavelength of the laser line used with the SLM.

width: int

Width of SLM, in pixels.

class FocusLockInfo
camera: str

Detector name.

frameCroph: int

Height of frame crop.

frameCropw: int

Width of frame crop.

frameCropx: int

Starting X position of frame crop.

frameCropy: int

Starting Y position of frame crop.

positioner: str

Positioner name.

updateFreq: int

Update frequency, in milliseconds.

class ScanInfo
TTLCycleDesigner: str

Name of the TTL cycle designer class to use.

TTLCycleDesignerParams: Dict[str, Any]

Params to be read by the TTL cycle designer.

sampleRate: int

Scan sample rate.

scanDesigner: str

Name of the scan designer class to use.

scanDesignerParams: Dict[str, Any]

Params to be read by the scan designer.

class NidaqInfo
startTrigger: bool = False

Boolean for start triggering for sync.

timerCounterChannel: Optional[Union[int, str]] = None

Output for Counter for timing purposes. If an integer is specified, it will be translated to “Dev1/ctr{timerCounterChannel}”.

class ROIInfo
h: int

Height of ROI, in pixels.

w: int

Width of ROI, in pixels.

x: int

Starting X position of ROI, in pixels.

y: int

Starting Y position of ROI, in pixels.

class LaserPresetInfo
value: float

Laser value.

class EtSTEDInfo
detectorFast: str

Name of the STED detector to use.

detectorSlow: str

Name of the widefield detector to use.

laserFast: str

Name of the widefield laser to use.

Available managers

Detector managers

class APDManager

DetectorManager that deals with an avalanche photodiode connected to a counter input on a Nidaq card.

Manager properties:

  • terminal – the physical input terminal on the Nidaq to which the APD is connected

  • ctrInputLine – the counter that the physical input terminal is connected to

class HamamatsuManager

DetectorManager that deals with the Hamamatsu parameters and frame extraction for a Hamamatsu camera.

Manager properties:

  • cameraListIndex – the camera’s index in the Hamamatsu camera list (list indexing starts at 0); set this to an invalid value, e.g. the string “mock” to load a mocker

  • hamamatsu – dictionary of DCAM API properties to pass to the driver

class PhotometricsManager

DetectorManager that deals with frame extraction for a Photometrics camera.

Manager properties:

  • cameraListIndex – the camera’s index in the Photometrics camera list (list indexing starts at 0)

class TISManager

DetectorManager that deals with TheImagingSource cameras and the parameters for frame extraction from them.

Manager properties:

  • cameraListIndex – the camera’s index in the TIS camera list (list indexing starts at 0); set this string to an invalid value, e.g. the string “mock” to load a mocker

  • tis – dictionary of TIS camera properties

Laser managers

class AAAOTFLaserManager

LaserManager for controlling one channel of an AA Opto-Electronic acousto-optic modulator/tunable filter through RS232 communication.

Manager properties:

  • rs232device – name of the defined rs232 communication channel through which the communication should take place

  • channel – index of the channel in the acousto-optic device that should be controlled (indexing starts at 1)

class Cobolt0601LaserManager

LaserManager for Cobolt 06-01 lasers. Uses digital modulation mode when scanning. Does currently not support DPL type lasers.

Manager properties:

  • digitalPorts – a string array containing the COM ports to connect to, e.g. ["COM4"]

class CoolLEDLaserManager

LaserManager for controlling the LEDs from CoolLED. Each LaserManager instance controls one LED.

Manager properties:

  • rs232device – name of the defined rs232 communication channel through which the communication should take place

  • channel_index – laser channel (A to H)

class NidaqLaserManager

LaserManager for analog-value NI-DAQ-controlled lasers.

Manager properties: None

Positioner managers

class MHXYStageManager

PositionerManager for control of a Marzhauser XY-stage through RS232 communication.

Manager properties:

  • rs232device – name of the defined rs232 communication channel through which the communication should take place

class NidaqPositionerManager

PositionerManager for analog-value NI-DAQ-controlled positioners.

Manager properties:

  • conversionFactor – float value

  • minVolt – minimum voltage

  • maxVolt – maximum voltage

class PiezoconceptZManager

PositionerManager for control of a Piezoconcept Z-piezo through RS232 communication.

Manager properties:

  • rs232device – name of the defined rs232 communication channel through which the communication should take place

RS232 managers

class RS232Manager

A general-purpose RS232 manager that together with a general-purpose RS232Driver interface can handle an arbitrary RS232 communication channel, with all the standard serial communication protocol parameters as defined in the hardware control configuration.

Manager properties:

  • port

  • encoding

  • recv_termination

  • send_termination

  • baudrate

  • bytesize

  • parity

  • stopbits

  • rtscts

  • dsrdtr

  • xonxoff

Available signal designers

Scan designers

class BetaScanDesigner

Scan designer for X/Y/Z stages that move a sample. Designer params: - return_time – time to wait between lines for the stage to return to

the first position of the next line, in seconds.

class GalvoScanDesigner

Scan designer for scan systems with galvanometric mirrors.

Designer params: None

TTL cycle designers

class BetaTTLCycleDesigner

TTL cycle designer for camera-based applications where each pulse scheme is one frame.

Designer params: None

class PointScanTTLCycleDesigner

Line-based TTL cycle designer, for point-scanning applications. Treats input ms as lines.

Designer params: None