microspeclib.simple module (dev-kit API commands)

class microspeclib.simple.MicroSpecSimpleInterface(serial_number=None, device=None, timeout=2.0, retry_timeout=0.001, emulation=False, *args, **kwargs)
autoExposure(**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

SensorAutoExposure

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

captureFrame(**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

SensorCaptureFrame

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

getAutoExposeConfig(**kwargs)

Retrieve the current auto-expose configuration.

Returns

  • status

  • max_tries

  • start_pixel

  • stop_pixel

  • target

  • target_tolerance

  • max_exposure

Return type

SensorGetAutoExposeConfig

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
getBridgeLED(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, or LEDRed

Parameters

led_num (int) – Valid input: 0

Returns

  • status

  • led_setting

Return type

BridgeGetBridgeLED

Example

>>> from microspeclib.simple import MicroSpecSimpleInterface
>>> kit = MicroSpecSimpleInterface()
>>> print(kit.getBridgeLED(led_num=0))
BridgeGetBridgeLED(status=0, led_setting=1)
getExposure(**kwargs)

Retrieve the spectrometer integration time (exposure time).

Returns

  • status

  • cycles

Return type

SensorGetExposure

See also

setExposure()

getSensorConfig(**kwargs)

Retrieve the spectrometer configuration.

Returns

  • status

  • binning

  • gain

  • row_bitmap

Return type

SensorGetSensorConfig

getSensorLED(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, or LEDRed.

Parameters

led_num (int) –

  • Valid range: 0, 1

Returns

  • status

  • led_setting

Return type

SensorGetSensorLED

null(**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

BridgeNull

Example

>>> from microspeclib.simple import MicroSpecSimpleInterface
>>> kit = MicroSpecSimpleInterface()
>>> print(kit.null())
BridgeNull()
setAutoExposeConfig(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 if autoExposure() failed beacuse it hit max_tries, see the iterations attribute in the reply.

  • 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

SensorSetAutoExposeConfig

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)

setBridgeLED(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
  • led_num (int) –

    • Valid range: 0 (there is only one LED)

  • led_setting (int) –

Returns

  • status

Return type

BridgeSetBridgeLED

setExposure(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

SensorSetExposure

setSensorConfig(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

SensorSetSensorConfig

setSensorLED(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
  • led_num (int) –

    • Valid range: 0, 1

  • led_setting (int) –

Returns

  • status

Return type

SensorSetSensorLED