Constants¶

Names for common constants used by the API.

Example

>>> import microspec as usp
>>> usp.GREEN
1

See the complete list of constants.

View the microspec.constants unit tests (source code) for examples using constants.

Use constants instead of hard-coded numbers¶

Calls using these constants should refer to them by the names defined here instead of hard-coding the values in application code. For example:

kit.setBridgeLED(led_setting=usp.GREEN) # <-- Do this.
kit.setBridgeLED(led_setting=1)         # <-- NOT this!

Constants in microspec match microspeclib¶

List constants in microspeclib:

>>> import microspeclib.datatypes.types as dtypes
>>> dtypes.__all__
['StatusOK', 'StatusError', ...]

These constants are defined in the globals object in the JSON API config file.

Example

microspec OK equals microspeclib StatusOK:

>>> usp.OK == dtypes.StatusOK
True

The tests in microspec.tests.test_constants.TestConsistent_with_microspeclib checks if the constants in the API are consistent with the JSON config file.

list of constants¶

microspec.constants.ALL_ROWS = 31¶

Use all five rows of pixels.

Pixel height is divided into five rows. Using all five rows, the pixels are 312.5µm tall. This is the recommended and default configuration.

row_bitmap=31 means “all five rows” because 31 in binary is 0001 1111:

>>> 0b00011111
31

Similarly, row_bitmap=7 means only use rows 1, 2, and 3:

>>> 0b00000111
7

Type:	int

microspec.constants.BINNING_OFF = 0¶

Pixels are not binned.

There are 784 pixels with 7.8µm pitch. The first 14 are optically black.

See also

BINNING_ON

Type:	int

microspec.constants.BINNING_ON = 1¶

Pixels are binned.

There are 392 pixels with 15.6µm pitch. The first 7 are optically black. This is the recommended and default configuration.

See also

BINNING_OFF

Type:	int

microspec.constants.ERROR = 1¶

The dev-kit failed to execute the command.

status=='ERROR' indicates that serial communication succeeded, but the dev-kit firmware did not understand the command or its parameters. If status=='ERROR', the other response attributes are not valid. For example, if reading exposure time and status=='ERROR', the exposure time values are meaningless.

Application code (code using the API) does not need to check for status=='ERROR': it does not occur when using the API.

When testing commands at the REPL, status=='ERROR' is useful for identifying invalid command parameters. For example, 42 is invalid for led_num in getBridgeLED(led_num=42).

There are two other possible reasons for status=='ERROR', but these cannot be replicated at the REPL when using the microspec API:

the command ID itself is invalid

the host computer sent a valid command ID and valid parameter values, but the bytes were corrupted (in a way that did not cause serial communication to fail)

See also

OK

Type:	int

microspec.constants.GAIN1X = 1¶

Pixel analog voltage gain is 1x.

This is the recommended and default configuration.

Type:	int

microspec.constants.GAIN2_5X = 37¶

Pixel analog voltage gain is 2.5x.

Type:	int

microspec.constants.GAIN4X = 4¶

Pixel analog voltage gain is 4x.

Type:	int

microspec.constants.GAIN5X = 5¶

Pixel analog voltage gain is 5x.

Type:	int

microspec.constants.GAVE_UP = 0¶

Auto-expose did not hit the target signal range.

Type:	int

microspec.constants.GREEN = 1¶

LED is ON and GREEN.

See also

OFF, RED

Type:	int

microspec.constants.HIT_TARGET = 1¶

Auto-expose hit the target signal range.

Type:	int

microspec.constants.MAX_CYCLES = 65500¶

Longest exposure time (integration time).

Type:	int

microspec.constants.MIN_CYCLES = 1¶

Shortest exposure time (integration time).

Type:	int

microspec.constants.OFF = 0¶

LED is OFF.

See also

GREEN, RED

Type:	int

microspec.constants.OK = 0¶

The dev-kit successfully executed the command.

status=='OK' most of the time. Application code usually does not check status because the commands check status internally and issue a warning or raise an exception if status is not OK.

Applications should check status if receiving a UserWarning that the command timed out. Specific commands and replies discuss application use cases where status=='TIMEOUT' is known to occur and how to handle such cases.

See also

ERROR

Type:	int

microspec.constants.RED = 2¶

LED is ON and RED.

See also

OFF, GREEN

Type:	int

microspec.constants.binning_dict = {0: 'BINNING_OFF', 1: 'BINNING_ON'}¶

microspec.constants.gain_dict = {1: 'GAIN1X', 4: 'GAIN4X', 5: 'GAIN5X', 37: 'GAIN2_5X'}¶

microspec.constants.led_dict = {0: 'OFF', 1: 'GREEN', 2: 'RED'}¶

microspec.constants.row_dict = {31: 'ALL_ROWS'}¶

microspec.constants.status_dict = {0: 'OK', 1: 'ERROR'}¶

microspec.constants.success_dict = {0: 'GAVE_UP', 1: 'HIT_TARGET'}¶