 |
HORIBA C++ SDK
Library for HORIBA devices
|
|
HORIBA C++ SDK
Library for HORIBA devices
|
revision: 0.2
date: 01/06/2025 ICL version: 2.0.0.179
This document describes the remote command and data API provided by the ICL.
The ICL is a Windows console application that can be executed:
URL to connecting to a locally running ICL:
ws://localhost:25010
When connecting to a remote running ICL replace the localhost with the remote ICL's network address.
Currently, a secure websocket connection (wss:) is not yet implemented.
...
The text based payload of a websocket message uses JSON formatting.
Command Payload:
id optional field. An integer number that can be used to line-up/sync-up outgoing commands with incoming asynchronous response. May remove.
command is a string indicating the command to execute.
parameters: optional - depends on command. Can be used to pass in 1 or more parameters. The key/value parameters (JSON object(s)) can be strings, number (int or float) booleans (true or false) and array - as described in the individual commands.
Note 1: All commands have a prefix xxx_ to indicate the target module in the ICL.
Note 2: Currently all commands are case sensitive.
Reply Payload:
id is the integer number that was sent with the command. If no id was sent with the command this field will have a value of 0 (currently – may change this so it is not present if it wasn’t present in the command).
command is a string indicating the command that was executed.
results Optional - depends on command. A collection of key/value pairs where value can be a string, number or Boolean.
errors Optional - only if error(s). Report zero (0) or more errors. And array of strings. Currently format of an error string is:
This section describes general ICL commands.
Gets detailed information about the connected to ICL.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >|nodeAlias|The name of the node.| >|nodeApiVersion|An integer number indicating the API version| >|nodeBuilt|Built date| >|nodeDescription|Text description of the ICL| >|nodeId|An integer number indicating this ICL's id| >|nodeVersion|String describing the detailed version number|
Example command:
Example response:
Command to start a safe shutdown of the connected to ICL.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >|state|Text message indicating action taken. Normally Shutting down|
Example command:
Example response:
Command to control if binary messages are to be sent to this client. Binary message types include: "logs", "information" and "data".
Command parameters: >| parameter | description | >|—|—| >|mode|String. Possible values: "none", "all". all = receive all binary message types|
Response results: >| results | description | >|—|—| >|state|Text message indicating action taken. Normally "_Shutting down_"|
Example command:
Example response:
Attempts to find supported monos connected and powered on the USB bus.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >|count|Integer value indicating number of monochromators discovered|
Example command:
Example response:
Returns a formatted list of discovered mono devices.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >| devices | Array of discovered mono devices. Each discovered mono consists of the following details:
deviceType - Mono device description
index - Index of the discovered device
serialNumber - Mono device serial number|
Example command:
Example response:
Returns the number of monochromators found on the USB bus.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >|count|Integer. Indicates the number of monochromators found|
Example command:
Example response:
Opens communications with the monochromator indicated by the index command parameter.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to target. See mono_list command|
Response results: >| results | description | >|—|—| >|_none_||
Example command: Open first mono in the list of monos discoverd.
Example response:
Closes communications with the monochromator indicated by the index.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to target. See mono_list command|
Response Results: >| results | description | >|—|—| >|_none_||
Example command:
Example response:
Returns true if selected monochromator is open.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to target. See mono_list command|
Return Results: >| results | description | >|—|—| >| open | Boolean. True = open |
Example command:
Example response:
Returns true if selected monochromator is busy.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to target. See mono_list command|
Response results: >| results | description | >|—|—| >| busy | Boolean. True = busy |
Example command:
Example response:
Starts the monochromator initialization process (homing...). This is a "long-running" asynchronous command. Use the mono_isBusy command to know when initialization has completed.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >| force | Boolean. Force starts the initialization process.
Response results: >| results | description | >|—|—| >|_none_||
Example command: Start the initialization process of the first mono.
Example response:
This command returns true when the mono is initialized. Otherwise it returns false.
Note: This command may also return false when the mono is busy with another command.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command |
Response results: >| results | description | >|—|—| >|initialized | Boolean. True when the mono is initialized, otherwise false |
Example command:
Example response:
This command returns the monochromator configuration.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command|
Response results: >| results | description | >|—|—| >|configuration| String. Mono device configuration.|
Port Descriptions: >| parameter | description | >|—|—| >| locationId | Integer. Used to identify the slit location.
1 = Front entrance (axial)
2 = Side entrance (lateral)
3 = Front exit (axial)
4 = Side exit (lateral) | >| slitType | Integer. Used to identify the slit size.
1 = 2mm slit
2 = 7mm slit |
Example command:
Example response:
Returns the wavelength value, in nm, of the monochromator's current position.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command|
Response results: >| results | description | >|—|—| >|wavelength|Float. Position in nm.|
Example command:
Example response:
This command sets the wavelength value of the current grating position of the monochromator. This could potentially un-calibrate the monochromator and report an incorrect wavelength compared to the actual output wavelength.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >|wavelength| Float. Set the wavelength of the mono at the current position.|
Response results: >| results | description | >|—|—| >|_none_||
Example command: Sets the position wavelength value to 320nm.
Example response:
This command starts the monochromator moving to the requested wavelength in nm. This is an asynchronous command. Use the mono_isBusy command to know when the move has completed.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >|wavelength| Float. Move to wavelength.|
Response results: >| results | description | >|—|—| >|_none_||
Example command: Sets the position wavelength value to 320nm.
Example response:
Returns the current grating turret position.
Note: Prior to the initialization of the grating turret, this value may not reflect the actual position of the turret. To read the current position of the grating turret, please run mono_init prior to running this command.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command|
Response results: >| results | description | >|—|—| >|position|Integer. Current position of the grating turret.|
Example command:
Example response:
Moves the grating turret to the specified position.
Note: The turret sensor does not re-read the position each time it is moved, therefore the position may not be accurate prior to initialization. See note for mono_getGratingPosition.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >|position| Integer. Position to move the grating turret.|
Response results: >| results | description | >|—|—| >|_none_||
Example command: Move grating turret to position 1.
Example response:
Returns the current filter wheel position.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >| locationId | Integer. Specifies the filter wheel location.
0 = Filter wheel 1 (Internal)
1 = Filter wheel 2 (External) |
Response results: >| results | description | >|—|—| >|position|Integer. Current filter wheel position|
Example command:
Example response:
Move the filter wheel to a position.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command | >| locationId | Integer. Specifies which filter wheel to move.
0 = Filter wheel 1 (Internal)
1 = Filter wheel 2 (External) | >|position| Integer. Position to move the filter wheel. |
Response results: >| results | description | >|—|—| >|_none_||
Example command: Move the internal filter wheel to position 2.
Example response:
Returns the position of the specified mirror.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command | >| locationId | Integer. Identifies which mirror to get the position from.
0 = Mirror 1 (Entrance)
1 = Mirror 2 (Exit) |
Response results: >| results | description | >|—|—| >|position|Integer. Position of the specified mirror.
0 = Axial
1 = Lateral |
Example command:
Example response:
Moves the specified mirror to a position.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >| locationId | Integer. Identifies which mirror to move (zero-based).
0 = Mirror 1 (Entrance)
1 = Mirror 2 (Exit) | >| position | Integer. Position to move to.
0 = Axial
1 = Lateral |
Response results: >| results | description | >|—|—| >|_none_||
Example command: Move mirror 2 to position 1.
Example response:
Returns the position of the specified slit in millimeters. The location id of each configured slit can be found under the ports section of the mono configuration. See mono_getConfig for additional information.
For example:
Note: The "locationId" parameter found in the mono configuration is 1-based. However, the mono_getSlitPositionInMM command uses a 0-based "locationId".
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >| locationId | Integer. Slit location (zero-based) |
Response results: >| results | description | >|—|—| >| position | Float. Slit position in millimeters|
Example command: Get position of slit in port 4
Example response:
Moves the specified slit to the position in millimeters. The location id of each configured slit can be found under the ports section of the mono configuration. See mono_getConfig for additional information.
For example:
Note: The "locationId" parameter found in the mono configuration is 1-based. However, the mono_moveSlitMM command uses a 0-based "locationId".
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >| locationId | Integer. Slit location (zero-based) | >| position | Float. Position in millimeters |
Response results: >| results | description | >|—|—| >|_none_||
Example command: Move slit in port 2 to 1.5mm position
Example response:
Activates the currently selected shutter solenoid.
Note: The device must be configured for internal shutter mode. The shutter solenoid will not respond in External (Bypass) mode.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command|
Response results: >| results | description | >|—|—| >|_none_||
Example command:
Example response:
Deactivates the currently selected shutter solenoid.
Note: The device must be configured for internal shutter mode. The shutter solenoid will not respond in External (Bypass) mode.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command|
Response results: >| results | description | >|—|—| >|_none_||
Example command:
Example response:
Returns the status of the currently selected shutter.
Note: To view the status of the shutter solenoid the device must be configured for internal shutter mode.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command|
Response results: >| results | description | >|—|—| >| locationId | Integer. Identifies the currently selected shutter.
0 = Shutter 1 (Front shutter)
1 = Shutter 2 (Side shutter) >| position | Integer. Shutter position status.
0 = Closed
1 = Open
Example command:
Example response:
This command searches for all supported CCD devices that are connected to the computer system via their USB interface. When this command occurs, references to previously discovered CCDs are cleared and a new search is made.
If this command does not discover a particular CCD, please insure that the device’s power supply is turned on and its USB cable is connected to the computer.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >|count|Integer value indicating number of CCD's discovered|
Example command:
Example response:
This command returns a list of the CCD devices that were discovered in the computer system.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >|devices| Array of discovered CCD devices. Each discovered CCD consists of the following details:
deviceType - CCD device description
index - Index of the discovered device
productId - CCD USB product id (PID)
serialNumber - CCD device serial number|
Example command:
Example response:
This command returns the number of CCD devices discovered on the USB bus.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >|count|Integer. Indicates the number of CCD's found|
Example command:
Example response:
This command initializes the CCD and gets it’s the CCD configuration from the device. The device is also connected to the API. Since a CCD hardware initialization occurs, all CCD parameters, including any previously set parameters, will be reset to their default values.
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Response results: >| results | description | >|—|—| >|_none_||
Example command: Open first (index 0) CCD in the list of monos discoverd.
Example response:
Closes communications with the CCD indicated by the index.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Response Results: >| results | description | >|—|—| >|_none_||
Example command:
Example response:
Returns true if selected CCD is open.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >|open|boolean. true = open|
Example command:
Example response:
Performs a restart on the CCD.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >|_none_| |
Example command:
Example response:
Returns the CCD device configuration.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| configuration | JSON. CCD device configuration. |
Example command:
Example response:
Returns the chip sensor’s pixel width and height size.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| x | Integer. Chip sensor's x size in pixels (width)| >| y | Integer. Chip sensor's y size in pixels (height)|
Example command:
Example response:
Returns the temperature of the chip sensor in degrees C.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| temperature | Float. Chip sensor temperature in degrees C. |
Example command:
Example response:
Gets the current gain token and the associated description information for the gain token. Gain tokens and their descriptions are part of the CCD configuration information. See ccd_getConfig command.
For example:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| info | String. Description of the current gain token. | >| token | Integer. Current gain token. |
Example command:
Example response:
Sets the CCD gain token. A list of supported gain tokens can be found in the CCD configuration. See ccd_getConfig command.
For example:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| token | Integer. Gain token from CCD config. |
Return Results: >| results | description | >|—|—| >| none | |
Example command:
Example response:
Gets the current speed token and the associated description information for the speed token. Speed tokens and their descriptions are part of the CCD configuration information. See ccd_getConfig command.
For example:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| info | String. Description of the current speed token. | >| token | Integer. Current speed token. |
Example command:
Example response:
Sets the CCD speed token. A list of supported speed tokens can be found in the CCD configuration. See ccd_getConfig command.
For example:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| token | Integer. Speed token from CCD config. |
Return Results: >| results | description | >|—|—| >| none | |
Example command:
Example response:
Gets the current parallel speed token and token description. Parallel speed tokens and their descriptions are contained in the CCD configuration information. See ccd_getConfig command.
For example:
Note: The Parallel Speed value may also be referred to as the Vertical Shift Rate. These terms are interchangeable.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| info | String. Description of the current parallel speed token. | >| token | Integer. Current parallel speed token. |
Example command:
Example response:
Sets the CCD parallel speed token. A list of supported parallel speed tokens can be found in the CCD configuration. See ccd_getConfig command.
For example:
Note: The Parallel Speed value may also be referred to as the Vertical Shift Rate. These terms are interchangeable.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| token | Integer. Parallel speed token from CCD config. |
Return Results: >| results | description | >|—|—| >| none | |
Example command:
Example response:
Gets the FIT parameters contained in the CCD configuration.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| fitParameters | Array. CCD FIT parameters. |
Example command:
Example response:
Gets the exposure time (expressed in Timer Resolution units).
Note: To check the current Timer Resolution value see ccd_getTimerResolution. Alternatively the Timer Resolution value can be set using ccd_setTimerResolution.
Example:
If Exposure Time is set to 50, and the Timer Resolution value is 1000, the CCD exposure time (integration time) = 50 milliseconds.
If Exposure Time is set to 50, and the Timer Resolution value is 1, the CCD exposure time (integration time) = 50 microseconds.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| time | Integer. Exposure time (expressed in Timer Resolution units).
Example command:
Example response:
Sets the exposure time (expressed in Timer Resolution units).
Note: To check the current Timer Resolution value see ccd_getTimerResolution. Alternatively the Timer Resolution value can be set using ccd_setTimerResolution.
Example:
If Exposure Time is set to 50, and the Timer Resolution value is 1000, the CCD exposure time (integration time) = 50 milliseconds.
If Exposure Time is set to 50, and the Timer Resolution value is 1, the CCD exposure time (integration time) = 50 microseconds.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| time | Integer. Exposure time (expressed in Timer Resolution units).
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Gets the current timer resolution token.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| resolutionToken | Integer. Timer resolution token.
0 - Timer resolution is set to 1000 microseconds
1 - Timer resolution is set to 1 microsecond
Example command:
Example response:
Sets the current timer resolution token.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| resolutionToken | Integer. Timer resolution token.
0 - Sets the timer resolution to 1000 microseconds
1 - Sets the timer resolution to 1 microsecond*
_*Note:_ The timer resolution value of 1 microsecond is not supported by every CCD.
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Sets the acquisition format and the number of ROIs (Regions of Interest) or areas. This command will remove all previously defined ROIs. After using this command, the ccd_setRoi command should be used to define each ROI.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| numberOfRois | Integer. Number of ROIs (Regions of Interest / areas) >| format | Integer. The acquisition format.
0 = Spectra
1 = Image
2 = Crop*
3 = Fast Kinetics*
_* Note:_ The Crop (2) and Fast Kinetics (3) acquisition formats are not supported by every CCD.
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Sets a single (roiIndex) ROI (Region of Interest) or area as defined by the X and Y origin, size, and bin parameters. The number of ROIs may be set using the ccd_setAcqFormat command. For Spectral acquisition format set yBin = ySize.
Note: All values must fall within the x and y limits of the chip sensor, see ccd_getChipSize. If the ROI is not valid, the device will not be properly setup for acquisition.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| roiIndex | Integer. The region of interest’s index (one-based) >| xOrigin | Integer. The starting pixel in the x direction (zero-based) >| yOrigin | Integer. The starting pixel in the y direction (zero-based) >| xSize | Integer. The number of pixels in the x direction (one-based) >| ySize | Integer. The number of pixels in the y direction (one-based) >| xBin | Integer. The number of pixels to “bin” (x pixels summed to 1 value) >| yBin | Integer. The number of pixels to “bin” (y pixels summed to 1 value) Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Gets the X axis pixel conversion type to be used when retrieving the acquisition data with the ccd_getAcquisitionData command.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| type | Integer. The X-axis pixel conversion type to be used.
0 = None (default)
1 = CCD FIT parameters contained in the CCD firmware
2 = Mono Wavelength parameters contained in the icl_settings.ini file
Example command:
Example response:
Sets the X-axis pixel conversion type to be used when retrieving the acquisition data with the ccd_getAcquisitionData command.
Note: To use the parameters contained in the icl_settings.ini file, the ccd_setCenterWavelength command must be called first.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| type | Integer. The X-axis pixel conversion type to be used.
0 = None (default)
1 = CCD FIT parameters contained in the CCD firmware
2 = Mono Wavelength parameters contained in the icl_settings.ini file
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Gets the number of acquisition measurements to be perform sequentially by the hardware.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| count | Integer. The number of acquisition measurements to be performed.
Example command:
Example response:
Sets the number of acquisition measurements to be performed sequentially by the hardware. A count > 1 is commonly referred to as "MultiAcq".
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| count | Integer. The number of acquisition measurements.
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Gets the number of cleans to be performed prior to measurement.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| count | Integer. Number of cleans. | >| mode | Integer. Specifies how the cleans will be performed.
0 = Never
1 = First Only
2 = Between Only
3 = Each |
Example command:
Example response:
Sets the number of cleans to be performed according to the specified mode setting.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| count | Integer. Number of cleans. | >| mode | Integer. Specifies how the cleans will be performed.
0 = Never
1 = First Only
2 = Between Only
3 = Each |
Return Results: >| results | description | >|—|—| >| none | |
Example command:
Example response:
Gets the number of pixels to be returned based on the current settings.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| size | Integer. Byte data size for all ROIs and acquisitions. |
Example command:
Example response:
This command is used to get the current setting of the input trigger. The address, event, and signalType parameters are used to define the input trigger based on the supported options of that particular CCD.
The supported trigger options are retrieved using the ccd_getConfig command, and begin with the "Triggers" string contained in the configuration.
For example:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| address | Integer. Token used to specify where the trigger is located.
(e.g. 0 = Trigger Input)
Note: Trigger name and token can be found in the CCD config, see ccd_getConfig
Value of -1 indicates that the input trigger is disabled | >| event | Integer. Token used to specify when the trigger event should occur.
(e.g. 0 = Once - Start All)
Note: Event name and token can be found in the CCD config, see ccd_getConfig
Value of -1 indicates that the input trigger is disabled | >| signalType | Integer. Token used to specify how the signal will cause the input trigger.
(e.g. 0 = TTL Falling Edge)
Note: Signal type and token can be found in the CCD config, see ccd_getConfig
Value of -1 indicates that the input trigger is disabled |
Example command:
Example response:
This command is used to enable or disable the trigger input. When enabling the trigger input, the address, event, and signalType parameters are used to define the input trigger based on the supported options of that particular CCD.
The supported trigger options are retrieved using the ccd_getConfig command, and begin with the "Triggers" string contained in the configuration.
For example:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| enable | Boolean. Enables or disables the input trigger.
true = enable
false = disable
Note: When disabling the input trigger, the address, event, and signalType parameters are ignored.| >| address | Integer. Token used to specify where the trigger is located.
(e.g. 0 = Trigger Input)
Note: Trigger name and token can be found in the CCD config, see ccd_getConfig | >| event | Integer. Token used to specify when the trigger event should occur.
(e.g. 0 = Once - Start All)
Note: Event name and token can be found in the CCD config, see ccd_getConfig | >| signalType | Integer. Token used to specify how the signal will cause the input trigger.
(e.g. 0 = TTL Falling Edge)
Note: Signal type and token can be found in the CCD config, see ccd_getConfig |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
This command is used to get the current setting of the signal output. The address, event, and signalType parameters are used to define the signal based on the supported options of that particular CCD.
The supported signal options are retrieved using the ccd_getConfig command, and begin with the "Signals" string contained in the configuration.
For example:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| address | Integer. Token setting used to specify where the signal is located.
(e.g. 0 = Signal Output)
Note: Signal name and token can be found in the CCD config, see ccd_getConfig
Value of -1 indicates that the signal output is disabled | >| event | Integer. Token setting used to specify when the signal event should occur.
(e.g. 3 = Shutter Open)
Note: Event name and token can be found in the CCD config, see ccd_getConfig
Value of -1 indicates that the signal output is disabled | >| signalType | Integer. Token setting used to specify how the signal will cause the event.
(e.g. 0 = TTL Active High)
Note: Signal type and token can be found in the CCD config, see ccd_getConfig
Value of -1 indicates that the signal output is disabled |
Example command:
Example response:
This command is used to enable or disable the signal output. When enabling the signal output, the address, event, and signalType parameters are used to define the signal based on the supported options of that particular CCD.
The supported signal options are retrieved using the ccd_getConfig command, and begin with the "Signals" string contained in the configuration.
For example:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| enable | Boolean. Enables or disables the signal.
true = enable
false = disable
Note: When disabling the signal output, the address, event, and signalType parameters are ignored.| >| address | Integer. Token used to specify where the signal is located.
(e.g. 0 = Signal Output)
Note: Signal name and token can be found in the CCD config, see ccd_getConfig | >| event | Integer. Token used to specify when the signal event should occur.
(e.g. 3 = Shutter Open)
Note: Event name and token can be found in the CCD config, see ccd_getConfig | >| signalType | Integer. Token used to specify how the signal will cause the event.
(e.g. 0 = TTL Active High)
Note: Signal type and token can be found in the CCD config, see ccd_getConfig |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Starts an acquisition that has been set up according to the previously defined acquisition parameters.
Note: To specify the acquisition parameters please see ccd_setROI and ccd_setXAxisConversionType. If there are no acquisition parameters specified at the time of acquisition it may result in no data being generated.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| open shutter | Boolean. Sets the state of the shutter during the acquisition.
True = open
False = close
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Stops the current acquisition.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Gets the current busy-state of an acquisition.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| isBusy | Boolean. Acquisition busy state.
False = Not busy
True = Busy
Example command:
Example response:
Retrieves data from the last acquisition.
The acquisition description string consists of the following information:
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command|
Return Results: >| results | description | >|—|—| >| acquisition | String. Acquisition data.
Example command:
Example response:
This command sets the center wavelength value and other parameters to be used in the pixel to wavelength conversion.
Note: This command should be called before ccd_setXAxisConversionType and ccd_setAcquisitionStart.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command| >| monoIndex | Integer. Used to identify which mono to target for the current grating density. See mono_list command | >| wavelength | Float. Center wavelength. |
Return Results: >| results | description | >|—|—| >| none |
Example command:
Example response:
Finds the center wavelength positions based on the input range and pixel overlap. The following commands are prerequisites and should be called prior to using this command: ccd_setXAxisConversionType, ccd_setAcqFormat, and ccd_setRoi.
Command Parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which CCD to target. See ccd_list command | >| monoIndex | Integer. Used to identify which mono to target for the current grating density. See mono_list command | >| start | Float. Start wavelength. | >| end | Float. End wavelength. | >| overlap | Float. Pixel overlap. |
Return Results: >| results | description | >|—|—| >| centerWavelengths | Array. Center wavelength positions. | >| covers | Integer. Number of covers needed for range. |
Example command:
Example response:
Attempts to discover SpectrAcq3 hardware that is connected and powered on via the USB bus.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >|count|Integer value indicating number of SpectrAcq3's discovered|
Example command:
Example response:
The saq3_list command retrieves a list of SpectrAcq3 devices discovered by the saq3_discover command, providing detailed information about each connected device.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >| devices | Array of discovered SpectrAcq3 devices. Each discovered SpectrAcq3 consists of the following details:
deviceType - SpectrAcq3 device description
index - Index of the discovered device
serialNumber - SpectrAcq3 device serial number|
Example command:
Example response:
The saq3_listCount command retrieves a count of SpectrAcq3 devices discovered by the saq3_discover command.
Command parameters: >| parameter | description | >|—|—| >|_none_||
Response results: >| results | description | >|—|—| >| count | Number of discovered SpectrAcq3 devices. Example command:
Example response:
Opens communication with the SpectrAcq3 device specified by the index parameter.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device you want to open communication with. |
Return Results: >| results | description | >|—|—| >| none|
Example command:
Example response:
Closes communication with the SpectrAcq3 device specified by the index parameter.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to close the communication. |
Return Results: >| results | description | >|—|—| >| none|
Example command:
Example response:
Checks if communication with the SpectrAcq3 device is open for the given index.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to check the communication status |
Return Results: >| results | description | >|—|—| >| open | Indicates whether the USB communication is open (true) or closed (false).
Example command:
Example response:
Checks whether the instrument is busy (e.g., performing initialization or data acquisition).
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to check the busy status |
Return Results: >| results | description | >|—|—| >| isBusy | Indicates whether the SpectrAcq3 is busy (true) or idle (false).
Example command:
Example response:
Get the firmware version of the device for the given index.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to get the firmware version |
Return Results: >| results | description | >|—|—| >| firmwareVersion | Firmware version of the device
Example command:
Example response:
Get the FPGA version of the device for the given index.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to get the FPGA version |
Return Results: >| results | description | >|—|—| >| FpgaVersion | FPGA version of the device
Example command:
Example response:
Get the Board revision of the device for the given index.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to get the Board revision |
Return Results: >| results | description | >|—|—| >| boardRevision | Board Revision of the device
Example command:
Example response:
Get the Serial number of the device for the given index.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to get the Serial number |
Return Results: >| results | description | >|—|—| >| serialNumber | Serial number of the device
Example command:
Example response:
Set the High bias voltage in Volts. If not set then default value will be used.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to set the high bias voltage | >|biasVoltage| Set the high voltage in volts
Return Results: >| results | description | >|—|—| >| none|
Example command:
Example response:
Gets the bias voltage that was previously set. If no bias voltage has been explicitly set, the default value is returned.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to get the bias voltage |
Return Results: >| results | description | >|—|—| >| biasVoltage | Gets the voltage that was previously set. The voltage time is returned in volts.
Example command:
Example response:
Gets the maximum bias high voltage allowed in Volts
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to get the maximum high bias voltage |
Return Results: >| results | description | >|—|—| >| biasVoltage | Gets the voltage that was previously set. The voltage is returned in volts.
Example command:
Example response:
Defines and sends the parameters for the acquisition set to perform the acquisition.
If the acquisition set is not defined, a single-point scan with default settings is performed.
Parameters that are not explicitly defined are set to their default values.
Parameters to define for the acquisition
Returns an error if an acquisition is already in progress.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to define the acquisition set | >|scanCount|Must be at least 1. The total accumulated value for all Acquisition sets cannot exceed 131,070.(Max. Total Point Count)| >|timeStep|Interval between successive scans for time based scan.
If 0/not defined, the scans take place as fast as possible (limited by integration time and monochromator move if applicable)| >|integrationTime|Integration time in seconds | >|externalParam|User defined value|
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Get the acquisition set parameters.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to get the acquisition set |
Return Results: >| results | description | >|—|—| >|scanCount|Number of acquisition to perform| >|timeStep|Interval between successive scans for time based scan in seconds. If 0/not defined, the scans take place as fast as possible (limited by integration time and monochromator move if applicable)| >|integrationTime| Integration time in seconds| >|externalParam|User defined value|
Example command:
Example response:
Define acquisition sets before starting an acquisition. Ensure acquisition preparation is completed successfully.
Starting an acquisition will return an error if:
errorCount field indicating the number of errors detected.Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to start the acquisition | >|trigger| Integer indicating the trigger mode |
Trigger Modes: >| Mode | description | >|—|—| >|1| 1st data started on Start command, all subsequent data acquired based on interval time| >|2| 1st data started by Trigger after start Command, all subsequent data acquired based on interval time | >|3| Each data acquisition waits for Trigger|
Return Results: >| results | description | >|—|—| >|errorCount| field indicating the number of errors detected
Example command:
Example response:
Stops the current acquisition. The current data point is discarded. The acquisition process must be checked and restarted if needed.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to stop the acquisition |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Pause active Acquisition. Current point is completed. Can be continued. Needs to be Stopped to start a new Acquisition.
An error will be returned if a pause is received while an acquisition is not running.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to pause the acquisition |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Restart a paused acquisition.
An error will be returned if continue is received when not paused.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to restart the paused acquisition |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Check whether the acquired data is available.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to restart the paused acquisition |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Retrieve the acquired data that is available so far.
Note: Once the acquired data is read, it will be removed from the device/software's data buffer.
Ensure that you save the data to a local buffer or storage before reading to prevent data loss.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device for which you want to restart the paused acquisition |
Return Results:
| Field | Description |
|---|---|
data | Array of measurement records containing the following fields: |
└─ currentSignal | Current measurement. |
└─ unit | "uAmps" (microamps). |
└─ value | Current value (e.g., 9.151). |
└─ elapsedTime | Time since start (in microseconds). |
└─ eventMarker | true if an event occurred; otherwise, false. |
└─ overscaleCurrentChannel | true if the current channel is over-scaled. |
└─ overscaleVoltageChannel | true if the voltage channel is over-scaled. |
└─ pmtSignal | PMT signal measurement. |
└─ unit | "Counts/Second". |
└─ value | Signal value (e.g., 436278). |
└─ pointNumber | Sequential point identifier (e.g., 0). |
└─ ppdSignal | PPD signal measurement. |
└─ unit | "Counts/Second". |
└─ value | Signal value (e.g., 0). |
└─ voltageSignal | Voltage measurement. |
└─ unit | "Volts". |
└─ value | Voltage value (e.g., -0.3545). |
Example command:
Example response:
Software Trigger, treated the same as Hardware Trigger (IN).
If no acquisition is in progress, the trigger will be ignored.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Defines the polarity of the input trigger.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device | >|polarity| Input trigger polarity
0 - Active Low (falling edge)
1 - Active High (rising edge)|
Return Results: >| results | description | >|—|—| >|none|
Example command:
Example response:
Returns the polarity of the input trigger.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device |
Return Results: >| results | description | >|—|—| >|polarity| Input trigger polarity
0 - Active Low (falling edge)
1 - Active High (rising edge)|
Example command:
Example response:
Tell the device how Hardware Trigger pin is used. Returns Error if Acquisition is in Progress.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device | >|mode| Mode of hardware trigger pin.
0: TTL input
1: Event marker input
2: Hardware trigger input
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Returns the acquisition trigger mode defined in saq3_acqStart, as well as, the hardware input trigger mode defined in saq3_setInTriggerMode.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device |
Return Results: >| results | description | >|—|—| >|scanStartMode|Mode of the acquisition trigger defined in saq3_startAcq
1: First data started on Start command, all subsequent data acquired based on interval time
2: First data started by Trigger after Start command, all subsequent data acquired based on interval time
3: Each data acquisition waits for Trigger | >|inputTriggerMode|Mode of the hardware input trigger defined in saq3_setInTriggerMode
0: TTL input
1: Event marker input
2: Hardware trigger input|
Example command:
Example response:
Returns and clears the last error.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device |
Return Results: >| results | description | >|—|—| >|error | The last error |
Example command:
Example response:
Read the error buffer containing a list of logged errors.
The error log is cleared on receipt of an Initialize All command or a Clear Error Log command.
The error log is cleared at power on.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Clear All the errors.
Command parameters: >| parameter | description | >|—|—| >|index| The index of the SpectrAcq3 device |
Return Results: >| results | description | >|—|—| >|_none_|
Example command:
Example response:
Moves the specified slit to the position in steps. The location id of each configured slit can be found under the ports section of the mono configuration. See mono_getConfig for additional information.
For example:
Note: The "locationId" parameter found in the mono configuration is 1-based. However, the mono_moveSlit command uses a 0-based "locationId".
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >| locationId | Integer. Slit location (zero-based) | >| position | Integer. Position in steps |
Response results: >| results | description | >|—|—| >|_none_||
Example command: Move slit in port 2 to step position 250
Example response:
Returns the position of the specified slit in steps. The location id of each configured slit can be found under the ports section of the mono configuration. See mono_getConfig for additional information.
For example:
Note: The "locationId" parameter found in the mono configuration is 1-based. However, the mono_getSlitStepPosition command uses a 0-based "locationId".
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See mono_list command| >| locationId | Integer. Slit location (zero-based) |
Response results: >| results | description | >|—|—| >| position | Integer. Slit position in steps.|
Example command: Get step position of slit in port 4
Example response:
Opens the shutter, if the device is configured with a controllable shutter
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See ccd_list command|
Response results: >| results | description | >|—|—| >|_none_ |
Example command:
Example response:
Closes the shutter, if the device is configured with a controllable shutter
Command parameters: >| parameter | description | >|—|—| >| index | Integer. Used to identify which mono to control. See ccd_list command|
Response results: >| results | description | >|—|—| >|_none_ |
Example command:
Example response:
1.13.2