`MEASure` - Measurement control

The MEASure root path provides access to various measurement adjustments and the measurement itself. All value changes are applied instantaneously.

`:SPECtrum` - Spectral sample retrieval

Spektralwerk Core offers two possibilities to obtain spectral data. The commands starting with :REQuest will return spectral samples within the SCPI response (in-band), while :EMITter will send the spectral samples to a configured destination (e.g. via TCP over the network; out-of-band).

`:REFerence` - Reference spectra handling

The :REFerence attribute allows access to set and get up to two reference spectra on the spectrometer. Reference spectra can influence the processing of a spectrum.

`:DARK` - Dark reference spectrum

query and command

The dark reference node MEASure:SPECtrum:REFerence:Dark allows to set a dark reference spectrum. It will be applied if the reference_dark flag is enabled in MEASure:SPECtrum:CONFig:PROCessing.

A dark reference spectrum typically represents the noisy background of a measurement. Therefore the dark reference spectrum is subtracted from the raw spectrum to remove the background noise. The dark reference spectrum should contain a spectrum obtained without any light source or environmental lighting reaching the spectrometer input. If a shutter is used to control incoming light to Spektralwerk Core, this shutter should be closed. Alternatively use an opaque cap on the spectrometer input and darken the environment as much as possible (turn off the light, close the doors, ...).

To acquire or set a dark reference spectrum, two sub commands are available:

:ACQuire: Acquire an averaged sample and store it in the MEASure:SPECtrum:REFerence:DARK attribute. The number of raw samples to be used for averaging can be specified as an optional parameter. Without a parameter, MEASure:SPECtrum:CONFig:AVERage:NUMBer is used as a default.
:SET: Store a list of pixel intensities as the dark reference spectrum.

Parent path: MEASure:SPECtrum:REFerence

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:DARK`	returns current dark reference spectrum	-
`:ACQuire`	-	`[<INTEGER>]`: acquire an averaged spectrum and store it as the dark reference
`:SET`	-	`<FLOAT,FLOAT,...>`: set the provided array as the dark reference spectrum

Example response:

> MEASure:SPECtrum:REFerence:DARK?
2.3,3.2,1.0,...,4.1
> MEASure:SPECtrum:REFerence:DARK:ACQuire
# acquires a dark reference spectrum using the current average number value
> MEASure:SPECtrum:REFerence:DARK:ACQuire 123
# acquires a dark reference spectrum by averaging over 123 spectral samples
> MEASure:SPECtrum:REFerence:DARK:SET 1.2,2.2,4.1,...,2.3

> MEASure:SPECtrum:REQuest:PROCESSING reference_dark
# enables the dark reference consolidation for in-band spectral requests

`:LIGHt` - Light reference spectrum

query and command

The light reference node MEASure:SPECtrum:REFerence:LIGHt allows to set a light reference spectrum. It will be applied if the reference_light flag is enabled in MEASure:SPECtrum:CONFig:PROCessing.

A light reference spectrum typically represents the overlaying background light signal, thus the raw spectrum is subtracted from the light reference. The light reference spectrum should contain a spectrum obtained without any reference signal. A sample should be removed from the optical path and the light source itself should be gathered as light reference spectrum.

To acquire or set a light reference spectrum, two possible child commands are available:

:ACQuire: Acquire an averaged sample and store it in the MEASure:SPECtrum:REFerence:LIGHt attribute. The number of raw samples to be used for averaging can be specified as an optional parameter. Without a parameter, MEASure:SPECtrum:CONFig:AVERage:NUMBer is used as a default.
:SET: Store a list of pixel intensities as the light reference spectrum.

Parent path: MEASure:SPECtrum:REFerence

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:LIGHt`	returns current light reference spectrum	-
`:ACQuire`	-	`[<INTEGER>]`: acquire an averaged spectrum and store it as the light reference
`:SET`	-	`<FLOAT,FLOAT,...>`: set the provided array as the light reference spectrum

Example response:

> MEASure:SPECtrum:REFerence:LIGHt?
65232.3,65223.2,65231.0,...,65234.1
> MEASure:SPECtrum:REFerence:LIGHt:ACQuire
# acquires a light reference spectrum using the current average number value
> MEASure:SPECtrum:REFerence:LIGHt:ACQuire 123
# acquires a light reference spectrum by averaging over 123 spectral samples
> MEASure:SPECtrum:REFerence:LIGHt:SET 65231.2,65232.2,65234.1,...,652342.3

> MEASure:SPECtrum:REQuest:PROCESSING reference_light
# enables the light reference consolidation for in-band spectral requests

`:REQuest` - In-band spectra retrieval

query only

The MEASure:SPECtrum:REQuest path allows to retrieve spectrum data via the SCPI interface.

To transfer spectrum data outside the SCPI interface (out-of-band, _e.g., via TCP or UDP over the network), the MEASure:SPECtrum:EMITter path should be used instead.

Requesting spectra with MEASure:SPECtrum:REQuest? will return spectral samples as configured in the endpoints below MEASure:SPECtrum:CONFig (see documentation of the ...:CONFIG node).

MEASure:SPECtrum:REQuest:RAW? will always return a single raw spectrum without any processing applied. The default output format is human. The first parameter allows selecting a different format. Available format descriptions are human, base64_float, base64_int16 and cobs_int16. Please consider the appendix Spectral output format for more details.

Parent path: MEASure:SPECtrum

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:REQuest`	returns in-band processed and configured spectra.	-
`:RAW`	`[<OUTPUT_FORMAT>]` returns in-band raw spectra.	-

Example:

> MEASure:SPECtrum:REQuest?
12822.3,24398.2,32893.2,...,23892.4
> MEASure:SPECtrum:REQuest:RAW?
12822.3,24398.2,32893.2,...,23892.4
> MEASure:SPECtrum:REQuest:RAW? base64_float
MTI4MjIuMywyNDM5OC4yLDMyODkzLjIsLi4uLDIzODkyLjQK
# base64 encoded spectral sample

`:CONFig` - In-band and out-of-band spectral retrieval configuration

command and query

CONFig collects all configurable parameters which affect the spectral emission, both, in-band and out-of-band.

MEASure:SPECtrum:CONFig:COUNt allows to specify the amount of spectra to be returned upon calling the in-band emission MEASure:SPECtrum:REQuest? or the out-of-band emission with MEASure:SPECtrum:EMITter:RUN. An infinite emission of spectra can be started by setting the count to 0. Multiple spectra are separated by ;. The default value is 1.
MEASure:SPECtrum:CONFig:FORMat alters the notation of the returned spectra. The default value is human. Other possible values are: base64_float, base64_int16 and cobs_int16. The last one allows the highest possible sample frequency (see Appendix - Spectral output format for further information).
MEASure:SPECtrum:CONFig:PROCessing collects possible processing steps to be applied on the spectra before they are returned. By default no processing is applied. Possible values are reference_dark (see MEASure:SPECtrum:REFerence:DARK), reference_light (see MEASure:SPECtrum:REFerence:LIGHt), scale (see MEASure:SPECtrum:SCALe), average (see MEASure:SPECtrum:CONFig:AVERage:NUMBer). The processing steps are listed in Appendix - Processing steps.
MEASure:SPECtrum:CONFig:ROI restricts the returned pixel range to the provided values (region-of-interest). The default value varies depending on the built-in spectrometer. For Spektralwerk Core NIR, the default would be 0,255 (first and last pixel in the region-of-interest). The last pixel cannot be higher than the number of pixels of the built-in spectrometer array subtracted by one.
MEASure:SPECtrum:CONFig:FREQuency sets the sample rate for spectra. The default value is 0 which will make the spectrometer return spectra as fast as possible. The unit of the frequency can be obtained with the subquery MEASure:SPECtrum:CONFig:FREQuency:UNIT?. The sample rate is affected by the MEASure:SPECtrum:CONFig:FORMat and cannot exceed the maximum sample rate stated in the data sheet for the specific device.
MEASure:SPECtrum:CONFig:TRIGger configures the condition for requesting samples. Sample emission can be started by using SCPI commands (none) or by obtaining an external input signal (input,*), seeAppendix - Trigger.

Parent path: MEASure:SPECtrum:CONFig

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:COUNt`	returns the number of spectra returned from in-band query.	`<INTEGER>`: set the number of spectra returned from in-band query.
`:FORMat`	returns the format of the in-band query.	`<OUTPUT_FORMAT>`: set the format returned from in-band query.
`:PROCessing`	returns the applied processing steps for spectra returned from in-band query.	`<PROCESSING_STEP>`: set the processing steps for spectra returned from in-band query.
`:ROI`	returns the current region-of-interest (ROI).	`<INTEGER,INTEGER>`: set the first and last pixel for region of interest.
`:FREQuency`	returns the current sampling frequency.	`<FLOAT>`: set sampling frequency.
`:UNIT`	returns the unit of the frequency.	-
`:TRIGger`	returns the currently configured condition for starting a spectrum sample	`<TRIGGER>`: configure the condition for the start of the spectral emission

Example:

> MEASure:SPECtrum:CONFig:COUNT?
1
> MEASure:SPECtrum:CONFig:COUNT 10

> MEASure:SPECtrum:CONFig:COUNT?
10
> MEASure:SPECtrum:CONFig:FORMat?
human
> MEASure:SPECtrum:CONFig:FORMat base64_int16

> MEASure:SPECtrum:CONFig:FORMat?
base64_int16
> MEASure:SPECtrum:CONFig:PROCessing?
# no processing is enabled by default
> MEASure:SPECtrum:CONFig:PROCessing reference_light,average
# enables light_reference and averaging
> MEASure:SPECtrum:CONFig:PROCessing?
reference_light,average
> MEASure:SPECtrum:CONFig:ROI?
0,255
> MEASure:SPECtrum:CONFig:ROI 100,200

> MEASure:SPECtrum:CONFig:ROI?
100,200
> MEASure:SPECtrum:CONFig:FREQuency?
0
> MEASure:SPECtrum:CONFig:FREQuency 10

> MEASure:SPECtrum:CONFig:FREQuency?
10
> MEASure:SPECtrum:CONFig:FREQuency:UNIT?
Hz
> MEASure:SPECtrum:CONFig:TRIGger?
none
# The spectral emission  must be started using the respective SCPI command
> MEASure:SPECtrum:CONFig:TRIGger input,falling
# The spectral emission is started upon an incoming falling edge

`:AVERage:NUMBer` - Moving average number control

query and command

The MEASure:SPECtrum:CONFig:AVERage:NUMBer query and command provides access to the moving average number for spectrum averaging. The value applies only when the average flag is enabled in MEASure:SPECtrum:CONFig:PROCessing.

The configured number of averages determines, how many raw spectrum samples are consumed in order to produce a single averaged spectrum. A rolling averaging is applied. The special value 1 has the same effect as disabling averaging.

In addition to the base command :AVERage:NUMBer, additional sub commands are provided to inform about default average number as well as maximum and minimum values.

Parent path: MEASure:SPECtrum:CONFig

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:AVERage:NUMBer`	returns the current moving average number value	`<INTEGER>`: target average number
`:DEFault`	returns the default average number value	-
`:MAXimum`	returns the maximum allowed average number value	-
`:MINimum`	returns the minimum allowed average number value	-

Example:

> MEASure:SPECtrum:CONFig:AVERage:NUMBer?
1
> MEASure:SPECtrum:CONFig:AVERage:NUMBer 100

> MEASure:SPECtrum:CONFig:AVERage:NUMBer?
100
> MEASure:SPECtrum:CONFig:AVERage:NUMBer:DEFault?
1
> MEASure:SPECtrum:CONFig:AVERage:NUMBer:MAXimum?
1000000
> MEASure:SPECtrum:CONFig:AVERage:NUMBer:MINimum?
1
> MEASure:SPECtrum:CONFig:PROCessing average
# enables averaging for the in-band receive of spectral data

`:EXPosure:TIME` - Exposure time adjustment

query and command

The exposure time represents the duration to gather spectral information. Low values are typical for measurements with bright spectral sources to decrease the risk of truncation of spectral data. High values allow measurements of weak spectral sources.

Parent path: MEASure:SPECtrum:CONFig

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:EXPosure:TIME`	returns current exposure time	`<FLOAT>`: target exposure time
`:DEFault`	returns the default exposure time	-
`:MAXimum`	returns the maximum allowed exposure time	-
`:MINimum`	returns the minimum allowed exposure time	-
`:UNIT`	returns the current unit of the exposure time	-

Example:

> MEASure:SPECtrum:CONFig:EXPosure:TIME?
1.0e-6
> MEASure:SPECtrum:CONFig:EXPosure:TIME 2.3e-6

> MEASure:SPECtrum:CONFig:EXPosure:TIME?
2.3e-6
> MEASure:SPECtrum:CONFig:EXPosure:TIME:DEFault?
6.4e-6
> MEAsure:SPECtrum:CONFig:EXPosure:TIME:MINimum?
1.0e-7
> MEASure:SPECtrum:CONFig:EXPosure:TIME:MAXimum?
10.0
> MEASure:SPECtrum:CONFig:EXPosure:TIME:UNIT?
s

`:EMITter` - Out-of-band spectral emission

The MEASure:SPECtrum:EMITter path provides additional control of the out-of-band spectral emission.

A destination for the out-of-band spectra emission can be configured with MEASure:SPECtrum:EMITter:DESTination. The input must be a valid TCP or UDP uri, e.g. "udp://1.2.3.4:12345" (quotes are mandatory). The MEASure:SPECtrum:EMITter:RUN starts the spectral emission, if the MEASure:SPECtrum:CONFig:TRIGger is set to none. If the spectral emission should be triggered by some external signal (MEASure:SPECTrum:CONFig:TRIGger is set to input,*) setting MEASure:SPECtrum:EMITter:RUN to 1 prepares the spectral emission. The spectral emission is started once the input signal is detected.

Parent path: MEASure:SPECtrum:EMITter

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:DESTination`	returns the current destination for the emission of spectral data	`<STRING>`: uri of the destination for the emitted spectra
&nbsp`:RUN`	returns the current status	`<INTEGER>`: enables the out-of-band spectral emission

Example:

> MEASure:SPECtrum:CONFig:COUNt 10

> MEASure:SPECtrum:EMITter:DESTination "udp://192.168.4.23:8100"

> MEASure:SPECtrum:EMITter:DESTination?
"udp://192.168.4.23:8100"
> MEASure:SPECtrum:EMITTER:RUN 1
# upon receiving an input trigger signal, the emission of spectra to the destination starts
> MEASure:SPECtrum:EMITter:STATus?
busy
> MEASure:SPECtrum:EMITter:RUN?
0
> MEASure:SPECtrum:EMITter:STATus?
idle

`:STATus` - Status information for the out-of-band spectral emission

query only

MEASure:SPECtrum:EMITter:STATus? query provides details about the currently emitted spectra status (see appendix Emitter status. Logging messages and events occurring while spectral data is emitted to the destination are collected and available by querying MEASure:SPECtrum:EMITter:STATus:LOG? In addition, the number of emitted spectra since the last reconfiguration can be obtained from querying MEASure:SPECtrum:EMITter:STATus:ECOunt?. The currently achieved sample rate is provided by MEASure:SPECtrum:EMITter:STATus:RATE.

Parent path: MEASure:SPECtrum:EMITter

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:STATus`	returns the current status of the emission to the destination	-
`:ECOunt`	returns the number of emitted spectra since the last configuration change	-
`:LOG`	returns the last notable emitter events since the last configuration change	-
`:RATE`	returns the currently achieved sample rate since the last configuration change	-

Example:

> MEASure:SPECtrum:EMITter:DESTination "udp://192.168.4.23:8100"

> MEASure:SPECtrum:EMITter:STATus?
idle
> MEASure:SPECtrum:EMITter:CONFig:COUNt 10

> MEASure:SPECtrum:EMITter:RUN 1

> MEASure:SPECtrum:EMITter:STATus?
busy
> MEASure:SPECtrum:EMITter:STATus:ECOunt?
10
> MEASure:SPECtrum:EMITter:RUN?
0
> MEASure:SPECtrum:EMITter:STATus?
idle
> MEASure:SPECtrum:EMITter:STATus:LOG?
# some notable events

`:SCALe` - Custom spectra scaling

query and command

The MEASure:SPECtrum:SCALe query and command offers the option of applying a customized scaling to the spectra. If enabled (see MEASure:SPECtrum:CONFig:PROCessing), the provided factors are multiplied with the pixel intensities of the raw spectrum.

The MEASure:SPECtrum:SCALe can be enabled by passing the scale flag to MEASure:SPECtrum:CONFig:PROCessing.

A scaling vector containing only 1.0 is equal to not setting scale in the processing configuration (...:CONFig:PROCessing).

The default scale value is the sensitivity curve of the spectrometer (see DEVice:SPECtrometer:PIXels:SENSitivity?).

Parent path: MEASure:SPECtrum

SCPI String	Query `?`	Command `[<INPUT VALUE>]`
`:SCALe`	returns the current available scaling factors for each pixel	`<FLOAT,FLOAT,...>`: set scaling factors
`:DEFault`	returns the default scaling factors	-

Example:

> MEASure:SPECtrum:SCALe?
0.1,0.2,0.3,...,0.3,0.2
> MEASure:SPECtrum:SCALe 0.5,0.5,0.5,...,0.5,0.5

> MEASure:SPECtrum:SCALe?
0.5,0.5,0.5,...,0.5,0.5
> MEASure:SPECtrum:SCALe:DEFault?
0.000,0.010,0.020,...,0.030,0.020
> DEVice:SPECtrometer:PIXels:SENSitivity?
0.000,0.010,0.020,...,0.030,0.020
> MEASure:SPECtrum:REQuest:PROCessing scale
# enables scaling for in-band spectral retrieval
> MEASure:SPECtrum:REQuest:RAW?
10000.0,20000.0,30000.0,...,30000.0,20000.0
> MEASure:SPECtrum:SCALe?
0.5,0.5,0.5,...,0.5,0.5
> MEASure:SPECtrum:REQuest?
5000.0,10000.0,15000.0,...,15000.0,10000.0

MEASure - Measurement control

:SPECtrum - Spectral sample retrieval

:REFerence - Reference spectra handling

:DARK - Dark reference spectrum

:LIGHt - Light reference spectrum

:REQuest - In-band spectra retrieval

:CONFig - In-band and out-of-band spectral retrieval configuration

:AVERage:NUMBer - Moving average number control

:EXPosure:TIME - Exposure time adjustment

:EMITter - Out-of-band spectral emission

:STATus - Status information for the out-of-band spectral emission

:SCALe - Custom spectra scaling

`MEASure` - Measurement control

`:SPECtrum` - Spectral sample retrieval

`:REFerence` - Reference spectra handling

`:DARK` - Dark reference spectrum

`:LIGHt` - Light reference spectrum

`:REQuest` - In-band spectra retrieval

`:CONFig` - In-band and out-of-band spectral retrieval configuration

`:AVERage:NUMBer` - Moving average number control

`:EXPosure:TIME` - Exposure time adjustment

`:EMITter` - Out-of-band spectral emission

`:STATus` - Status information for the out-of-band spectral emission

`:SCALe` - Custom spectra scaling