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; requiresfocusLock
field to be defined)Autofocus
(autofocus widget; requiresfocusLock
field to be defined)SLM
(SLM widget; requiresslm
field to be defined)Laser
(laser control widget)Positioner
(positioners widget)Scan
(scan widget; requiresscan
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; requiresImage
widget)FFT
(FFT tool widget)Console
(Python console widget)EtSTED
(etSTED widget; requiresetSTED
field to be defined)
You can also set this to
true
to enable all widgets, orfalse
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.
- positioners: Dict[str, PositionerInfo]
Positioners in this setup. This is a map from unique positioner names to DetectorInfo objects.
- pulseStreamer: PulseStreamerInfo
Pulse Streamer settings.
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}”.
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 connectedctrInputLine
– 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 mockerhamamatsu
– 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 mockertis
– 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 placechannel
– 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 placechannel_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 valueminVolt
– minimum voltagemaxVolt
– 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 tothe 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