microspeclib.datatypes.command module¶
-
class
microspeclib.datatypes.command.
CommandAutoExposure
(*args, **kwargs)¶ Auto-expose the spectrometer.
Tell dev-kit firmware to adjust spectrometer exposure time until peak signal strength hits the auto-expose target.
- Returns
status
success
iterations
- Return type
Example
>>> from microspeclib.simple import MicroSpecSimpleInterface >>> kit = MicroSpecSimpleInterface() >>> reply = kit.autoExposure() >>> print(reply.success) 1 >>> print(reply.iterations) 3
See also
setAutoExposeConfig
configure auto-expose parameters
getExposure
get the new exposure time after the auto-expose
-
class
microspeclib.datatypes.command.
CommandCaptureFrame
(*args, **kwargs)¶ Retrieve one frame of spectrometer data.
Expose the pixels at the current integration time (exposure time). Return an array of counts (signal strength) at each pixel.
- Returns
status
num_pixels
pixels
- Return type
Example
>>> from microspeclib.simple import MicroSpecSimpleInterface >>> kit = MicroSpecSimpleInterface() >>> print(kit.captureFrame()) SensorCaptureFrame(status=0, num_pixels=392, pixels=[7904, 8295, ...
See also
autoExposure
set optimal exposure time before capturing a frame
setExposure
manually set exposure time before capturing a frame
-
class
microspeclib.datatypes.command.
CommandGetAutoExposeConfig
(*args, **kwargs)¶ Retrieve the current auto-expose configuration.
- Returns
status
max_tries
start_pixel
stop_pixel
target
target_tolerance
max_exposure
- Return type
Example
>>> from microspeclib.simple import MicroSpecSimpleInterface >>> kit = MicroSpecSimpleInterface() >>> reply = kit.getAutoExposeConfig() >>> print(reply.max_tries) 12 >>> print(reply.start_pixel) 7 >>> print(reply.stop_pixel) 392 >>> print(reply.target) 46420 >>> print(reply.target_tolerance) 3277
See also
setAutoExposeConfig
-
class
microspeclib.datatypes.command.
CommandGetBridgeLED
(*args, led_num=None, **kwargs)¶ Retrieve the state of the LED on the Bridge board.
The Bridge board is the top PCB in the dev-kit. There is only one LED on the Bridge.
The state is either:
LEDOff
,LEDGreen
, orLEDRed
- Parameters
led_num (int) – Valid input: 0
- Returns
status
led_setting
- Return type
Example
>>> from microspeclib.simple import MicroSpecSimpleInterface >>> kit = MicroSpecSimpleInterface() >>> print(kit.getBridgeLED(led_num=0)) BridgeGetBridgeLED(status=0, led_setting=1)
-
class
microspeclib.datatypes.command.
CommandGetExposure
(*args, **kwargs)¶ Retrieve the spectrometer integration time (exposure time).
- Returns
status
cycles
- Return type
See also
setExposure
-
class
microspeclib.datatypes.command.
CommandGetSensorConfig
(*args, **kwargs)¶ Retrieve the spectrometer configuration.
- Returns
status
binning
gain
row_bitmap
- Return type
-
class
microspeclib.datatypes.command.
CommandGetSensorLED
(*args, led_num=None, **kwargs)¶ Retrieve the state of an LED on the Sensor board.
The Sensor board is the bottom PCB in the dev-kit. There are two LEDs on the Sensor.
The state is either:
LEDOff
,LEDGreen
, orLEDRed
.- Parameters
led_num (int) –
Valid range: 0, 1
- Returns
status
led_setting
- Return type
-
class
microspeclib.datatypes.command.
CommandNull
(*args, **kwargs)¶ Send Null to flush serial communication.
The Null command is a loopback request: the dev-kit ignores Null and does not send a reply, but the API returns empty object
BridgeNull
.Call
null()
to flush the serial line in case of desynchronization. This is a way to synchronize serial communication with the dev-kit without exiting the application.- Returns
empty object (no API attributes, not even status)
- Return type
Example
>>> from microspeclib.simple import MicroSpecSimpleInterface >>> kit = MicroSpecSimpleInterface() >>> print(kit.null()) BridgeNull()
-
class
microspeclib.datatypes.command.
CommandReset
(*args, **kwargs)¶ NOT IMPLEMENTED. Future: Resets the hardware and replies when the reset is complete.
- Returns
status
- Return type
-
class
microspeclib.datatypes.command.
CommandSetAutoExposeConfig
(*args, max_tries=None, start_pixel=None, stop_pixel=None, target=None, target_tolerance=None, max_exposure=None, **kwargs)¶ Set the auto-expose configuration.
The application should set start_pixel and stop_pixel to match the pixel range in the spectrometer wavelength calibration data. Chromation recommends using the default power-on values for target and target_tolerance.
- Parameters
max_tries (int) –
Maximum number of exposures to try before auto-expose gives up.
Valid range: 1-255
Default (after dev-kit power-on): 12
If max_tries is 0:
reply status is
StatusError
auto-expose configuration is not changed
The auto-expose algorithm usually terminates after a couple of tries, usually less than max_tries. The precise value of max_tries is not important as long as it is big enough for auto-expose to hit the target. max_tries is a safeguard against the auto-expose algorithm oscillating forever.
Adjusting max_tries is useful when troubleshooting why
autoExposure()
fails. To determine ifautoExposure()
failed beacuse it hit max_tries, see the iterations attribute in thereply
.start_pixel (int) –
Auto-expose ignores pixels below start_pixel when finding the peak counts.
Valid range: 7-392 (14-784 with pixel binning off)
Default (after dev-kit power-on): 7
Recommended start_pixel is the lowest pixel number in the pixel-to-wavelength map.
If start_pixel is outside the allowed range, reply status is
StatusError
and the auto-expose configuration is not changed.stop_pixel (int) –
Auto-expose ignores pixels above stop_pixel when finding the peak counts.
Valid range: 7-392 (14-784 with pixel binning off),
stop_pixel must be >= start_pixel
Default (after dev-kit power-on): 7
Recommended stop_pixel is the highest pixel number in the pixel-to-wavelength map.
If stop_pixel is outside the allowed range, reply status is
StatusError
and the auto-expose configuration is not changed.target (int) –
Target peak-counts for exposure gain calculation.
Valid range: 4500-65535
Default (after dev-kit power-on): 46420
If target is outside the allowed range, reply status is
StatusError
and the auto-expose configuration is not changed.Note
The lowest allowed target is 4500 counts, not 0 counts.
4500 counts is chosen as the lowest allowed target to ensure that the signal is at least above the dark background.
This is a conservative over-estimate on the dark background. Chromation ships the dev-kits with the dark background trimmed to approximately 1000 counts.
target_tolerance (int) –
Auto-expose is finished when the peak counts lands within target +/- target_tolerance.
Valid range: 0-65535
Default (after dev-kit power-on): 3277
If the combination of target and target_tolerance results in target ranges extending below 4500 counts or above 65535 counts, auto-expose ignores the target_tolerance and clamps the target range at these boundaries.
max_exposure (int) –
The maximum integration time (exposure time) auto-expose is allowed to try. Auto-expose gives up if the exposure time is max_exposure and the peak counts is below the target range.
Valid range: 5-65535 (0.1ms to 1.3s)
Default (after dev-kit power-on): 10000 (200ms)
The default is only 200ms, while the maximum integration time is 1.3s. There is nothing significant about 200ms. It is a compromise between detecting weak optical signals while keeping the wait time reasonably short.
Warning
There is a known bug in the dev-kit firmware that occassionally sets max_exposure to 4112 (82.24ms), regardless of the actual value sent in the
setAutoExposeConfig()
command.
- Returns
status
- Return type
Notes
The default auto-expose configuration is optimized for the design specifications of the spectrometer readout circuit on the Sensor board.
The dev-kit uses a 16-bit ADC to convert pixel voltages to counts. The signal strength, therefore, is in units of counts in the range 0-65535.
The default values for target and target_tolerance guarantee that auto-expose, if it hits the target counts range, chooses an exposure time that is within the linear range of the spectrometer chip output.
target: 46420 counts
target_tolerance: 3277 counts
3277 counts is a +/-5% of 65535, the full-scale counts. This large tolerance helps the auto-expose algorithm settle within a few iterations.
The largest peak considered to be within target, therefore, is 49697 counts.
49697 counts is the top of the guaranteed linear range of output values for the spectrometer chip when used with the dev-kit.
49697 counts is based on:
dev-kit specifications:
16-bit ADC
1.8V ADC voltage reference
3.3V power supply for the spectrometer chip
spectrometer chip configuration:
binning on
gain 1x
all rows active (i.e., use full pixel height)
-
class
microspeclib.datatypes.command.
CommandSetBridgeLED
(*args, led_num=None, led_setting=None, **kwargs)¶ Set the state of the LED on the Bridge board.
The Bridge board is the top PCB in the dev-kit.
- Parameters
- Returns
status
- Return type
-
class
microspeclib.datatypes.command.
CommandSetExposure
(*args, cycles=None, **kwargs)¶ Set spectrometer integration time (exposure time).
- Parameters
cycles (int) –
Exposure time in units of 20µs cycles. For example, a 1ms exposure time is 50 cycles.
Valid range: 5-65535 (0.1ms to 1.3s)
Default (after dev-kit power-on): 50 (1ms)
- Returns
status
- Return type
-
class
microspeclib.datatypes.command.
CommandSetSensorConfig
(*args, binning=None, gain=None, row_bitmap=None, **kwargs)¶ Configure the photodiode array in the spectrometer chip.
- Parameters
binning (int) –
Connect adjacent pixels to double pixel width.
- 0: OFF
With binning off there are 784 pixels with 7.8µm pitch.
- 1: ON
With binning on there are 392 pixels with 15.6µm pitch.
Default (after dev-kit power-on): 1 (binning ON)
gain (int) –
The spectrometer chip has an internal analog gain. The gain setting applies to all pixels.
row_bitmap (int) –
Each pixel is 312.5µm tall and this height is divided into 5 sub-pixels which can be enabled/disabled. Use all 5 rows of sub-pixels with a binary bitmap of 5 1’s, i.e. 0001 1111 or 0x1F. Use only the first three rows with 0000 0111. Any combination of rows is permitted.
Default (after dev-kit power-on): 0x1F (0001 1111)
- Returns
status
- Return type
-
class
microspeclib.datatypes.command.
CommandSetSensorLED
(*args, led_num=None, led_setting=None, **kwargs)¶ Set the state of an LED on the Sensor board.
The Sensor board is the bottom PCB in the dev-kit. There are two LEDs on the Sensor.
- Parameters
- Returns
status
- Return type
-
class
microspeclib.datatypes.command.
CommandVerify
(*args, **kwargs)¶ NOT IMPLEMENTED. Future: Verifies running status of the hardware.
- Returns
status
- Return type
-
microspeclib.datatypes.command.
getCommandByID
(cid)¶
-
microspeclib.datatypes.command.
getCommandByName
(name)¶