Appendix

Mnemonics

Spectral output format

Spektralwerk Core supports four different spectral output formats in order to reduce the required bandwidth.

Format Description Size of spectrum (256 Pixels) in bytes
human human readable float values 2560
base64_float base64 encoded float values 1372
base64_int16 base64 encoded integer values 686
cobs_int16 cobs encoded integer values 515

base64_* is commonly used to transfer binary data in a text-based context. The maximum possible sample rate can be achieved with the cobs-int16.

Processing steps

Spektralwerk Core can return already processed values. Both channels, MEASure:SPECtrum:REQuest (in-band) and MEASure:SPECtrum:EMITter (out-of-band) are affected by the processing steps listed in MEASure:SPECtrum:CONFig:PROCessing endpoint. Possible processing steps are:

  • average -- Several spectra are collected and the rolling average of the spectra is returned. The number of spectra used for averaging can be adjusted with MEASure:SPECtrum:CONFig:AVERage:NUMBer. If average is not applied, each spectrum is returned individually. Each spectrum is also returned individually if MEASure:SPECtrum:CONFig:AVERage:NUMBer is set to 1 while average is set to true, because a rolling average of size 1 is equivalent to the individual spectrum.
  • reference_dark -- The dark reference spectrum (MEASure:SPECtrum:REFerence:DARK) is subtracted from the spectrum. If no dark reference is stored, adding the reference_dark flag does not alter the outgoing spectrum. The reference_dark flag can be used to subtract noise from the signal.
  • reference_light -- The spectrum is subtracted from the light reference spectrum (MEASure:SPECtrum:REFerence:LIGHt). If no light reference is stored, adding the reference_light flag does not alter the outgoing spectrum.
  • scale -- A user-defined scaling (MEASure:SPECtrum:SCALe) is applied to the outgoing spectra. The default scaling spectrum represents the sensitivity curve of the spectrometer (DEVice:SPECtrometer:PIXels:SENSitivity).

Emitter status

Requesting the current emitter status (MEASure:SPECtrum:EMITter:STATus?) will return brief status information:

  • busy - The out-of-band emission of spectral data is running
  • idle - The out-of-band emission of spectral data is waiting for a start signal

Trigger edges

The spectral sampling can be triggered by external signals (see MEASure:SPECtrum:CONFig:TRIGger for more details). Spektralwerk Core will trigger a spectral sample depending on the detected edge. Possible values for the edges are:

  • input -- A spectrum emission is triggered every time a rising edge is detected on the input line (default). This is equivalent to input:rising.
  • input,rising -- A spectrum emission is triggered when a rising edge is detected on the input line.
  • input,falling -- A spectrum emission is triggered when a falling edge is detected on the input line.
  • input,both -- A spectrum emission is triggered whenever an edge is detected on the input line.
  • none -- Start spectrum sampling without waiting for external signals.

Trigger output source

  • manual -- Allows the manual control of the output line via SCPI commands.
  • sampling -- The output line remains active throughout the sampling process, making this mode ideal for controlling a shutter.

Indicator status

The behavior of the status indicator LED can be changed by passing one of the following keywords to CONTrol:INDicator:STATus. Changes on the LED will not be kept upon rebooting.

  • on -- The status LED is switched on.
  • off -- The status LED is switched off and no status information will be provided by the LED.
  • auto -- The status LED is switched on and status information is provided by color and blinking frequency (default).

Example

The Spektralwerk Core can be used in various use-cases, depending on the users needs. Some of the most common use-cases are provided.

In-band use-cases

The term in-band is used to describe the case where spectra are returned as a direct response within the existing SCPI connection.

Requesting a finite number of spectra

The interactive (in-band) SCPI connection is used to request a finite number of spectra and receive it immediately. The connection is closed afterwards and new requests can be sent to the Spektralwerk. 

# Configure the number of requested spectra, e.g. 3 spectra.
> MEASure:SPECtrum:CONFig:COUNt 3

> MEASure:SPECtrum:CONFig:TRIGger none

> MEASure:SPECtrum:REQuest?
12.23,34343,46576,36433,13492,...;...;...
> *IDN?
Silicann Systems,spektralwerk-core,1234567890,1.2.4

The query MEASure:SPECtrum:REQuest:RAW? can be used to obtain a single raw spectrum.

Requesting an infinite stream of spectra

The interactive (in-band) connection is used to start an infinite stream of spectra using the request channel. The communication is kept alive. To stop the stream, the client must close the connection.

This might be useful to obtain a live preview of the currently measured spectra.

# Configure an infinite stream of spectra.
> MEASure:SPECtrum:CONFig:COUNt 0

> MEASure:SPECtrum:CONFig:TRIGger none

> MEASure:SPECtrum:REQuest?
12.23,34343,46576,36433,13492,...;...;... ...
# The SCPI connection returns an infinite stream of spectra and cannot be used for any
# other communication anymore. The client has to close the connection.

Trigger a finite number of spectra

An input signal is used to trigger a finite number of spectra. Therefore the input signal must be connected to the Spektralwerk. Once the respective signal is detected, the configured amount of spectra are returned. As long as the connection is kept open by the client, an incoming signal will trigger the in-band emission of the finite number of spectra. The request remains active until the client closes the connection.

# Configure the number of requested spectra, e.g. 7 spectra in a row on incoming
# signals.
> MEASure:SPECtrum:CONFig:COUNt 7

> MEASure:SPECtrum:CONFig:TRIGger input,falling
# The `...:REQuest?` endpoint will obtain the spectra once the input signal is detected.
> MEASure:SPECtrum:REQuest?
# A single spectrum is emitted every time a correct input signal is detected.
12.23,34343,46576,36433,13492,...;...;...

Trigger an infinite stream of spectra

Similar to the above example, an input signal triggers the emission of an infinite stream of spectra. Additional input signals after the first one will not have any effect, the stream will persist. The client has to close the connection to stop the spectral emission.

# Configure the number of requested spectra.
> MEASure:SPECtrum:CONFig:COUNt 0

> MEASure:SPECtrum:CONFig:TRIGger input,falling
# The `...:REQuest?` endpoint will obtain the spectra once the input signal is detected.
> MEASure:SPECtrum:REQuest?
# An infinite stream is emitted and will not be affected by additional input signals.
# The request remains active until the client closes the connection.
12.23,34343,46576,36433,13492,...;...;...

Out-of-band use-cases

Unlike in-band transmission, the spectral data is sent to a predefined destination rather than through the SCPI channel

Requesting a finite number of spectra

A finite number of spectra is requested and sent to a destination using TCP or UDP protocol. No further spectra will be emitted. 

# Configure the number of requested spectra, e.g. send 2 spectra.
> MEASure:SPECtrum:CONFig:COUNt 2

> MEASure:SPECtrum:CONFig:TRIGger none

> MEASure:SPECtrum:EMITter:DESTination "udp://1.2.3.4:8000"

> MEASure:SPECtrum:EMITter:RUN 1
# Two spectra are transmitted as udp datagrams to the destination.
> MEASure:SPECtrum:EMITter:RUN?
0

Requesting an infinite stream of spectra

Spectrum sampling is started with the SCPI request MEASure:SPECtrum:EMITter:RUN 1. This starts an infinite stream of spectra data being sent to the configured destination. The stream can be stopped with the SCPI request MEASure:SPECtrum:EMITter:RUN 0.

# Configure an infinite stream of spectra.
> MEASure:SPECtrum:CONFig:COUNt 0

> MEASure:SPECtrum:CONFig:TRIGger none

> MEASure:SPECtrum:EMITter:DESTination "udp://1.2.3.4:8000"
# Start an infinite stream to the destination.
> MEASure:SPECtrum:EMITter:RUN 1

> MEASure:SPECtrum:EMITter:RUN 0

Trigger a finite number of spectra

An external input signal is used to trigger the emission of a single spectrum to a defined destination. Each incoming correct signal will return a single spectrum as long as emission is not stopped.

# Configure the number of requested spectra, e.g. send 6 spectra upon each incoming
# signal.
> MEASure:SPECtrum:CONFig:COUNt 6

> MEASure:SPECtrum:CONFig:TRIGger input,falling

> MEASure:SPECtrum:EMITter:DESTination "udp://1.2.3.4:8000"

> MEASure:SPECtrum:EMITter:RUN 1
# 6 spectra in a row are emitted once the correct input signal is detected.
> MEASure:SPECtrum:EMITter:RUN?
1
# The emission of 6 spectra will be triggered upon each incoming correct signal.
# The emission must be stopped explicitly.
> MEASure:SPECtrum:EMITter:RUN 0

Trigger an infinite stream of spectra

Similar to the above example the emission to a destination is started if the correct input signal is received. Instead of emitting a single spectrum, an infinite stream of spectra is emitted and is not affected by additional incoming signals any more. The emission must be stopped by sending MEASure:SPECtrum:EMITter:RUN 0.

# Configure the number of requested spectra.
 > MEASure:SPECtrum:CONFig:COUNt 0

> MEASure:SPECtrum:CONFig:TRIGger input,falling

> MEASure:SPECtrum:EMITter:DESTination "udp://1.2.3.4:8000"

> MEASure:SPECtrum:EMITter:RUN 1
# An infinite stream of spectra is emitted to the destination once the correct input
# signal is detected. Additional incoming signals are ignored.
# The emission must be stopped explicitly.
> MEASure:SPECtrum:EMITter:RUN 0

References