This is the basic implementation of our FeatureIdentificationDevice (FID) spectrometer USB API as defined in ENG-0001. More...

Inheritance diagram for wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice:

[legend]

Collaboration diagram for wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice:

[legend]

Public Member Functions
	__init__ (self, device_id, message_queue=None, alert_queue=None)
	Instantiate a FeatureIdentificationDevice with from the given device_id.

	apply_edc (self, spectrum)
	Use optically black pixels for electrical dark correction (EDC).

	can_laser_fire (self)

	check_alert (self, s)

	clear_regions (self)

	connect (self, retries=0)
	Connect to the device and initialize basic settings.

	disconnect (self)

	generate_timeout_ms (self)

	get_actual_frames (self)

	get_actual_integration_time_us (self)

	get_ambient_temperature_degC (self)

	get_ambient_temperature_degC_arm (self)

	get_ambient_temperature_degC_gen15 (self)

	get_analog_input_value (self)

	get_analog_output_state (self)

	get_area_scan (self)

	get_area_scan_hamamatsu (self)

	get_area_scan_xs (self)

	get_battery_charging (self)

	get_battery_percentage (self)

	get_battery_register (self, int reg)

	get_battery_state_raw (self)
	Retrieves the raw battery reading and then caches it for 1 sec.

	get_ble_firmware_version (self)

	get_ccd_sensing_threshold (self)

	get_ccd_threshold_sensing_mode (self)

	get_dac (self, int dacIndex=0)

	get_detector_gain (self, bool update_session_eeprom=False)
	Read the device stored gain.

	get_detector_gain_odd (self, bool update_session_eeprom=False)

	get_detector_offset (self)

	get_detector_offset_odd (self)

	get_detector_tec_setpoint_degC (self)

	get_detector_tec_setpoint_raw (self)

	get_detector_temperature_degC (self, float raw=None)

	get_detector_temperature_raw (self)

	get_discretes_enabled (self)

	get_external_trigger_output (self)

	get_fan_enabled (self)

	get_fpga_configuration_register (self, str label="")

	get_fpga_firmware_version (self)

	get_high_gain_mode_enabled (self)

	get_integration_time_ms (self)

	get_lamp_enabled (self)

	get_laser_enabled (self)

	get_laser_interlock (self)
	laser interlock

	get_laser_power_attenuator (self)

	get_laser_tec_mode (self)
	The current opcode (0x85) seems to be actually returning GET_LASER_TEC_ENABLED, not GET_LASER_TEC_MODE.

	get_laser_temperature_degC (self, raw=None)
	Laser temperature conversion doesn't use EEPROM coeffs at all.

	get_laser_temperature_raw (self)

	get_laser_temperature_setpoint_raw (self)

	get_laser_warning_delay_sec (self)

	get_laser_watchdog_sec (self)

	get_line (self, trigger=True, auto_raman_params=None)
	legacy alias

	get_microcontroller_firmware_version (self)

	get_microcontroller_serial_number (self)

	get_mod_delay_us (self)

	get_mod_duration_us (self)

	get_mod_enabled (self)

	get_mod_linked_to_integration (self)

	get_mod_period_us (self)

	get_mod_width_us (self)

	get_opt_actual_integration_time (self)

	get_opt_area_scan (self)

	get_opt_cf_select (self)

	get_opt_data_header_tab (self)

	get_opt_has_laser (self)

	get_opt_horizontal_binning (self)

	get_opt_integration_time_resolution (self)

	get_opt_laser_control (self)
	Laser commands.

	get_poll_status (self)

	get_raman_delay_ms (self)

	get_raman_mode_enabled_NOT_USED (self)

	get_scans_to_average (self)

	get_secondary_adc_calibrated (self, float raw=None)

	get_secondary_adc_raw (self)

	get_selected_adc (self)

	get_selected_laser (self)

	get_sensor_line_length (self)

	get_shutter_enabled (self)

	get_spectrum (self, trigger=True, auto_raman_params=None)
	Send "acquire", then immediately read the bulk endpoint(s).

	get_strobe_enabled (self)
	a literal pass-through to get_laser_enabled()

	get_tec_enabled (self)

	get_trigger_delay (self)

	get_trigger_source (self)
	Read the trigger source setting from the device.

SpectrometerResponse	get_upper_code (self, int wValue, int wIndex=0, int wLength=64, str label="", int msb_len=None, int lsb_len=None)

	get_vr_continuous_ccd (self)

	get_vr_num_frames (self)

	handle_requests (self, list[SpectrometerRequest] requests)

	has_linearity_coeffs (self)
	At least one linearity coeff is other than 0 or -1 (and no NaN).

	i2c_write (self, address, buf, label="")

	is_laser_firing (self)
	Check if the laser actually IS firing, independent of laser_enable or can_laser_fire.

	is_sensor_stable (self)

	queue_message (self, setting, value)
	If an upstream queue is defined, send the name-value pair.

	refresh_alerts (self)

	replace_session_eeprom (self, tuple[str, EEPROM] pair)
	Given a (serial_number, EEPROM) pair, replace this process's "session" EEPROM with the passed EEPROM.

	require_throwaway (self, flag)

	reset (self, *args)

	reset_area_scan_frame (self)

	reset_fpga (self)
	(end of laser commands)

	select_adc (self, int n)

	set_accessory_enable (self, bool flag)

	set_analog_output_mode (self, tuple[bool, int] value)

	set_analog_output_value (self, int value)

	set_area_scan_enable (self, flag)
	Historically, this opcode moved around a bit.

	set_area_scan_line_count (self, n)

	set_area_scan_line_interval (self, n)

	set_area_scan_line_step (self, n)

	set_detector_gain (self, float gain)
	Note that this is used for detector types, including:

	set_detector_gain_odd (self, float gain)

	set_detector_offset (self, int value)

	set_detector_offset_odd (self, int value)

	set_detector_roi (self, list[float] args, bool store=True)
	Note this only sends the ROI downstream to the spectrometer (and stores it in DetectorRegions).

	set_detector_tec_setpoint_degC (self, float degC)
	Attempt to set the CCD cooler setpoint.

	set_dfu_enable (self)
	Puts ARM-based spectrometers into Device Firmware Update (DFU) mode.

	set_fan_enable (self, bool flag)

	set_high_gain_mode_enable (self, bool flag)
	CF_SELECT is configured using bit 2 of the FPGA configuration register 0x12.

	set_integration_time_ms (self, float ms)
	Send the updated integration time in a control message to the device.

	set_lamp_enable (self, bool flag)

	set_laser_enable (self, bool flag)
	Turn the laser on or off.

	set_laser_power_attenuator (self, value)
	digital pot on 220250 Rev4A+

	set_laser_power_high_resolution (self, bool flag)
	Sets whether the PWM pulse period is 1000µs (high-resolution, default) or 100µs (low-resolution, legacy).

	set_laser_power_mW (self, int mW_in)

	set_laser_power_perc (self, float value_in, bool set_in_perc=True)

	set_laser_power_perc_immediate (self, float value)
	Sets laser power (modulated pulse width) which will be used next time the laser is turned on (or changed immediately, if the laser is already enabled).

	set_laser_power_require_modulation (self, bool flag)

	set_laser_tec_mode (self, mode)

	set_laser_temperature_setpoint_raw (self, int value)

	set_laser_warning_delay_sec (self, value)

	set_laser_watchdog_sec (self, sec)

	set_log_level (self, str s)

	set_mod_delay_us (self, float us)

	set_mod_duration_us_NOT_USED (self, float us)

	set_mod_enable (self, bool flag)

	set_mod_linked_to_integration (self, bool flag)

	set_mod_period_us (self, float us)

	set_mod_width_us (self, float us)

	set_onboard_scans_to_average (self, n)
	This is provided to let ENLIGHTEN turn off onboard averaging settings which might have been generated, and (deliberately) left in place after an Auto-Raman measurement.

	set_pixel_mode (self, float mode)

	set_raman_delay_ms (self, int ms)

	set_raman_mode_enable_NOT_USED (self, bool flag)
	Enable "Raman mode" (automatic laser) in the spectrometer firmware.

	set_selected_laser (self, int value)
	On spectrometers supporting two lasers, select the primary (0) or secondary (1).

	set_shutter_enable (self, bool flag)

	set_single_region (self, int n)
	This function uses the the multi-region feature to select just a single pre-configured region at a time.

	set_strobe_enable (self, bool flag)
	this is a synonym for _set_laser_enable_immediate(), but without side-effects

	set_tec_enable (self, bool flag)

	set_trigger_delay (self, float half_us)
	A confenurable delay from when an inbound trigger signal is received by the spectrometer, until the triggered acquisition actually starts.

	set_trigger_source (self, bool value)
	Set the source for incoming acquisition triggers.

	set_vertical_roi (self, roi)

	update_firmware_log (self)

	update_laser_watchdog (self)
	Automatically set the laser watchdog long enough to handle the current integration time, assuming we have to perform 6 throwaways on the sensor in case it went to sleep.

	update_session_eeprom (self, tuple[str, EEPROM] pair)
	Given a (serial_number, EEPROM) pair, update this process's "session" EEPROM with just the EDITABLE fields of the passed EEPROM.

	update_vertical_roi (self)

	write_eeprom (self)
	Actually store the current session EEPROM fields to the spectrometer.

Public Member Functions inherited from wasatch.InterfaceDevice.InterfaceDevice
	__init__ (self)
	Any class that communicates to a spectrometer should inherit this class.

Public Attributes
	alert_queue = alert_queue

	alerts = set()

bool	allow_default_gain_reset = True

list	area_scan_frame = [ [0] * self.settings.pixels() for line in range(self.settings.eeprom.actual_pixels_vertical) ]

bool	ccd_temperature_invalid = False

bool	connected = False

bool	connecting = False

	detector_tec_setpoint_degC = degC

bool	detector_tec_setpoint_has_been_set = False

	device = None

	device_id = device_id

	device_type

	eeprom_backup = None

list	extra_area_scan_data = []

bool	has_received_spectrum = False

	imx385 = IMX385()

bool	inject_random_errors = False

bool	laser_temperature_invalid = False

float	last_applied_laser_power = 0.0

	last_spectrum = None

	last_usb_timestamp = None

	message_queue = message_queue

float	next_applied_laser_power = None

	prev_pixels = None

bool	raise_exceptions = False

float	random_error_perc = 0.001

bool	retry_enabled = True

int	retry_max = 3

int	retry_ms = 5

	settings = SpectrometerSettings(device_id)

bool	shutdown_requested = False

Public Attributes inherited from wasatch.InterfaceDevice.InterfaceDevice
dict	process_f = {}

int	remaining_throwaways = 0

Protected Member Functions
	_apply_horizontal_binning (self, spectrum)

	_apply_linear_pixel_calibration (self, spectrum)

	_check_for_random_error (self)
	This function is provided to simulate random USB communication errors during regression testing, and is normally a no-op.

	_correct_bad_pixels (self, spectrum)
	If a spectrometer has bad_pixels configured in the EEPROM, then average over them in the driver.

	_correct_ingaas_gain_and_offset (self, list[float] spectrum)
	Until support for even/odd InGaAs gain and offset have been added to the firmware, apply the correction in software.

SpectrometerResponse	_get_code (self, int bRequest, int wValue=0, int wIndex=0, int wLength=64, str label="", int msb_len=None, int lsb_len=None)

	_init_process_funcs (self)
	Is it the expectation that all of these functions will return SpectrometerResponse?

	_post_connect (self)
	Perform additional setup after instantiating FID device.

	_read_eeprom (self)

	_read_fpga_compilation_options (self)

	_schedule_disconnect (self, exc)
	Something in the driver has caused it to request the controlling application to close the peripheral.

SpectrometerResponse	_send_code (self, int bRequest, int wValue=0, int wIndex=0, data_or_wLength=None, str label="", bool dry_run=False, bool retry_on_error=False, int success_result=0x00)

	_to40bit (self, val)
	Laser modulation and continuous-strobe commands take arguments in micro- seconds as 40-bit values, where the least-significant 16 bits are passed as wValue, the next-significant 16 as wIndex, and the most-significant as a single byte of payload.

	_wait_for_usb_available (self)
	Wait until any enforced USB packet intervals have elapsed.

Private Member Functions
	_set_laser_enable_immediate (self, bool flag)
	The user has requested to update the laser firing state (on or off), so apply the new laser state to the spectrometer immediately.

Detailed Description

This is the basic implementation of our FeatureIdentificationDevice (FID) spectrometer USB API as defined in ENG-0001.

This class is roughly comparable to Wasatch.NET's Spectrometer.cs.

This class is normally not accessed directly, but through the higher-level abstraction WasatchDevice.

See also

ENG-0001 ########################################################################## This class adopts the external device interface structure This invlovles receiving a request through the handle_request function A request is processed based on the key in the request The processing function passes the commands to the requested device Once it recevies a response from the connected device it then passes that back up the chain

                           Enlighten Request
                                   |
                            handle_requests
                                   |
                              -----------
                             |  |  |  |  | 
         { get_laser status, acquire, set_laser_watchdog, etc....}
                             |  |  |  |  | 
                              -----------
                                   |
                               _send_code

############################################################################

Constructor & Destructor Documentation

◆ init()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.__init__	(	self,
		device_id,
		message_queue = None,
		alert_queue = None )

Instantiate a FeatureIdentificationDevice with from the given device_id.

Parameters

device_id	[in] device ID ("USB:0x24aa:0x1000:1:24")
message_queue	[in] if provided, provides an outbound (from FID to WrapperWorker) queue for writing StatusMessage objects upstream
alert_queue	[in] if provided, accepts an inbound (from WrapperWorker to FID) queue for receiving AlertMessage objects

Member Function Documentation

◆ _apply_horizontal_binning()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._apply_horizontal_binning	(		self,
			spectrum )

protected

◆ _apply_linear_pixel_calibration()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._apply_linear_pixel_calibration	(		self,
			spectrum )

protected

◆ _check_for_random_error()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._check_for_random_error ( self )

protected

This function is provided to simulate random USB communication errors during regression testing, and is normally a no-op.

◆ _correct_bad_pixels()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._correct_bad_pixels	(		self,
			spectrum )

protected

If a spectrometer has bad_pixels configured in the EEPROM, then average over them in the driver.

Note this function modifies the passed array in-place, rather than returning a modified copy.

Note: assumes bad_pixels is previously sorted

◆ _correct_ingaas_gain_and_offset()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._correct_ingaas_gain_and_offset	(		self,
		list[float]	spectrum )

protected

Until support for even/odd InGaAs gain and offset have been added to the firmware, apply the correction in software.

◆ _get_code()

SpectrometerResponse wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._get_code	(		self,
		int	bRequest,
		int	wValue = 0,
		int	wIndex = 0,
		int	wLength = 64,
		str	label = "",
		int	msb_len = None,
		int	lsb_len = None )

protected

Note: weird that so few calls to this function override the default wLength

Todo: consider adding retry logic as well

◆ _init_process_funcs()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._init_process_funcs ( self )

protected

Is it the expectation that all of these functions will return SpectrometerResponse?

If so, that should be made explicit.

◆ _post_connect()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._post_connect ( self )

protected

Perform additional setup after instantiating FID device.

Split-out from physical / bus connect() to simplify MockSpectrometer.

◆ _read_eeprom()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._read_eeprom ( self )

protected

◆ _read_fpga_compilation_options()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._read_fpga_compilation_options ( self )

protected

◆ _schedule_disconnect()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._schedule_disconnect	(		self,
			exc )

protected

Something in the driver has caused it to request the controlling application to close the peripheral.

The next time WasatchDevice.acquire_data is called, it will pass a "poison pill" back up the response queue. Alternately, non-ENLIGHTEN callers can set "raise_exceptions" -> True for in-process exception-handling.

◆ _send_code()

SpectrometerResponse wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._send_code	(		self,
		int	bRequest,
		int	wValue = 0,
		int	wIndex = 0,
			data_or_wLength = None,
		str	label = "",
		bool	dry_run = False,
		bool	retry_on_error = False,
		int	success_result = 0x00 )

protected

◆ _set_laser_enable_immediate()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._set_laser_enable_immediate	(		self,
		bool	flag )

private

The user has requested to update the laser firing state (on or off), so apply the new laser state to the spectrometer immediately.

Because the ability to immediately disable a laser is a safety-related feature (noting that truly safety-critical capabilities should be implemented in hardware, and generally can't be robustly achieved through Python scripts), this function takes the unusual step of looping over multiple attempts to set the laser state until either the command succeeds, or 3 consecutive failures have occured.

This behavior was added after a developmental, unreleased prototype was found to occasionally drop USB packets, and was therefore susceptible to inadvertently failing to disable the laser upon command.

(as callers are recommended to use set_laser_enable)

Parameters

flag	(Input) whether the laser should be on (true) or off (false)

Returns: true if new state was successfully applied

◆ _to40bit()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._to40bit	(		self,
			val )

protected

Laser modulation and continuous-strobe commands take arguments in micro- seconds as 40-bit values, where the least-significant 16 bits are passed as wValue, the next-significant 16 as wIndex, and the most-significant as a single byte of payload.

This function takes an unsigned integral value (presumably microseconds) and returns a tuple of wValue, wIndex and a buffer to pass as payload.

◆ _wait_for_usb_available()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice._wait_for_usb_available ( self )

protected

Wait until any enforced USB packet intervals have elapsed.

This does nothing in most cases - the function is normally a no-op. However, if the application has defined min/max_usb_interval_ms (say (20, 50ms), then pick a random delay in the defined window (e.g. 37ms) and sleep until it has been at least that long since the last USB exchange. The purpose of this function was to wring-out some early ARM micro- controllers with apparent timing issues under high-speed USB 2.0, to see if communications issues disappeared if we enforced a communication latency from the software side.

◆ apply_edc()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.apply_edc	(		self,
			spectrum )

Use optically black pixels for electrical dark correction (EDC).

IMX385LQR-C datasheet (p8)

Pixels    Count Description
0-3       4     OB side ignored area                <-- using this
4-7       4     Effective pixel side ignored area
8-15      8     Effective margin for color processing
16-1935   1920  Recording pixel area
1936-1944 9     Effective margin for color processing
1945-1948 4     Effective pixel side ignored area
1949-1951 3     Dummy

Note: that this is called BEFORE horizontal binning, so should still work even with BIN_4X2

Todo: we might want to make buffer length configurable, either in spectra or by time (consider 10ms vs 1sec integration time)

◆ can_laser_fire()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.can_laser_fire ( self )

Note: only works on FX2-based spectrometers with FW >= 10.0.0.11

Returns: True if there is a laser and either the interlock is closed (in firing position), or there is no readable interlock

◆ check_alert()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.check_alert	(		self,
			s )

◆ clear_regions()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.clear_regions ( self )

◆ connect()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.connect	(		self,
			retries = 0 )

Connect to the device and initialize basic settings.

Warning: this causes a problem in non-blocking mode (WasatchDeviceWrapper) on MacOS

◆ disconnect()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.disconnect ( self )

◆ generate_timeout_ms()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.generate_timeout_ms ( self )

◆ get_actual_frames()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_actual_frames ( self )

◆ get_actual_integration_time_us()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_actual_integration_time_us ( self )

◆ get_ambient_temperature_degC()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_ambient_temperature_degC ( self )

◆ get_ambient_temperature_degC_arm()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_ambient_temperature_degC_arm ( self )

◆ get_ambient_temperature_degC_gen15()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_ambient_temperature_degC_gen15 ( self )

See also: https://www.nxp.com/docs/en/data-sheet/LM75B.pdf

◆ get_analog_input_value()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_analog_input_value ( self )

◆ get_analog_output_state()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_analog_output_state ( self )

◆ get_area_scan()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_area_scan ( self )

Returns: Reading(spectrum, AreaScanImage(data=nd_array))

It's important to understand that Hamamatsu and XS area scan features are architected differently in several respects.

Hamamatsu Area Scan

Full-frame Hamamatsu area scans are collected and returned in a single blocking call. This is possible because:

the frame is only 69 lines (6% of a 1080p image)
FX2-based 110008 boards use 480 mbps High-Speed USB (40x faster than 12 mbps Full-Speed)
CCDs are more sensitive as CMOS, allowing shorter integration times
Hamamatsu sensors don't have the 32ms min per-frame LVDS transfer time
Hamamatsu sensors allow vertical shifting and horizontal-readout to be delayed by the FPGA until the previous line has been pushed to the FX2, allowing every line in a frame to be sequentially read and pushed (vs IMX385 free-running frame times forcing one line/frame)
the FX2 internally generates subsequent ACQUIRE signals to the FPGA after each line has been read-out from the USB buffers to host, reducing the number of EP0 control messages

Due to the above, the Hamamatsu area scan can be executed much faster than an IMX385 area scan, and is considered fast enough to "block" on the full frame.

Therefore, a single blocking call to get_area_scan_hamamatsu() will return a complete area scan frame in roughly the following time:

INTEG_MS + TICK_US x LINES x (PIXELS + 1)

where: INTEG_MS is current integration time LINES is 69 for most Hamamatsu CCDs (128 for C0) PIXELS is 1044 or 2068 as appropriate (physical, not active) TICK_US is 2µs or 4µs as appropriate (depends on clock speed at which FPGA 'ticks' the CCD)

"PIXELS + 1" represents the 1 tick required for each line's vertical shift, plus PIXELS ticks for the horizontal read-out.

XS Area Scan

In contrast, as long as our IMX385 sensor is controlled in "main mode," via Spartan6 with no additional DDR memory, over LVDS, the XS image scan must be read line-by-line, where each line requires a separate full-frame acquisition (32ms minimum latency).

Therefore, a full area scan of a 1080p detector would take AT LEAST 32ms x 1080 lines = 35sec just for LVDS readout to the FPGA. The 1080 ACQUIRE commands would stretch that out further. Over 12mbps Full-Speed USB, the entire process comes to something like 2.5 MINUTES operationally.

Therefore, a blocking call to get_area_scan_xs() will return ASINGLE LINE of an ONGOING area scan. This allows ENLIGHTEN to appear "responsive" during the area scan process, updating its graphical area scan image in real-time as each line is received.

To further speed the process, the XS FPGA will only return lines within the configured vertical ROI, so if a vertical ROI of (300, 500) is config- ured, the area scan image will only comprise 200 lines rather than the full 1080.

Also, since each call to this function will only return a single line, and the FPGA will automatically "roll-over" the current line index after coming to the configured stop_line (returning to the configured start_line), this function does not have a concept of "stopping" or "finishing" a frame; subsequent calls will just keep sending out additional lines, until the spectrometer is taken out of area scan mode.

◆ get_area_scan_hamamatsu()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_area_scan_hamamatsu ( self )

Returns: Reading(spectrum, AreaScanImage(data=nd_array))

◆ get_area_scan_xs()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_area_scan_xs ( self )

Returns: Reading(spectrum, AreaScanImage(data=nd_array))

◆ get_battery_charging()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_battery_charging ( self )

◆ get_battery_percentage()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_battery_percentage ( self )

◆ get_battery_register()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_battery_register	(		self,
		int	reg )

◆ get_battery_state_raw()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_battery_state_raw ( self )

Retrieves the raw battery reading and then caches it for 1 sec.

◆ get_ble_firmware_version()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_ble_firmware_version ( self )

◆ get_ccd_sensing_threshold()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_ccd_sensing_threshold ( self )

◆ get_ccd_threshold_sensing_mode()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_ccd_threshold_sensing_mode ( self )

◆ get_dac()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_dac	(		self,
		int	dacIndex = 0 )

◆ get_detector_gain()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_detector_gain	(		self,
		bool	update_session_eeprom = False )

Read the device stored gain.

Convert from binary "half-precision" float.

1st byte (LSB) is binary encoded: bit 0 = 1/2, bit 1 = 1/4, bit 2 = 1/8 etc.
2nd byte (MSB) is the integral part to the left of the decimal E.g., 231 dec == 0x01e7 == 1.90234375

◆ get_detector_gain_odd()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_detector_gain_odd	(		self,
		bool	update_session_eeprom = False )

◆ get_detector_offset()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_detector_offset ( self )

◆ get_detector_offset_odd()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_detector_offset_odd ( self )

◆ get_detector_tec_setpoint_degC()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_detector_tec_setpoint_degC ( self )

◆ get_detector_tec_setpoint_raw()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_detector_tec_setpoint_raw ( self )

◆ get_detector_temperature_degC()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_detector_temperature_degC	(		self,
		float	raw = None )

◆ get_detector_temperature_raw()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_detector_temperature_raw ( self )

Note: big-endian, reverse of get_laser_temperature_raw

◆ get_discretes_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_discretes_enabled ( self )

Todo: find out opcode

◆ get_external_trigger_output()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_external_trigger_output ( self )

◆ get_fan_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_fan_enabled ( self )

◆ get_fpga_configuration_register()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_fpga_configuration_register	(		self,
		str	label = "" )

◆ get_fpga_firmware_version()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_fpga_firmware_version ( self )

◆ get_high_gain_mode_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_high_gain_mode_enabled ( self )

◆ get_integration_time_ms()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_integration_time_ms ( self )

◆ get_lamp_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_lamp_enabled ( self )

◆ get_laser_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_enabled ( self )

◆ get_laser_interlock()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_interlock ( self )

laser interlock

Legacy wrapper over can_laser_fire.

◆ get_laser_power_attenuator()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_power_attenuator ( self )

◆ get_laser_tec_mode()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_tec_mode ( self )

The current opcode (0x85) seems to be actually returning GET_LASER_TEC_ENABLED, not GET_LASER_TEC_MODE.

◆ get_laser_temperature_degC()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_temperature_degC	(		self,
			raw = None )

Laser temperature conversion doesn't use EEPROM coeffs at all.

IPS

Some Wasatch SML products use an IPS Wavelength-Stabilized TO-56 laser, which internally uses a Betatherm 10K3CG3 thermistor.

See also: https://www.ipslasers.com/data-sheets/SM-TO-56-Data-Sheet-IPS.pdf

The official IPS conversion from thermistor resistance (in ohms) to degC is:

1 / (   C1
      + C2 * ln(ohms)
      + C3 * pow(ln(ohms), 3)
    )
- 273.15

Where: C1 = 0.00113
       C2 = 0.000234
       C3 = 8.78e-8

That said, on XS the IPS thermistor then goes through a MAX1978ETM-T TEC IC which buffers the thermistor voltage. This requires the additional empirically-determined static conversion captured below.

Regrettably, the laser thermistor voltage on 110280 boards overflows the ADC range, so we don't currently have valid laser temperature read-out with those PCBs.

Ondax MML

On MML units using the Ondax OEM Module, the cable to the 220060 does not seem to pass-through the thermistor pin, so we don't have laser temperature read-out on those, either. (Nor photodiode...)

RealLight

RealLight SML thermistors use the following resistance and beta:

Thermistor Rt (kΩ / β(25°C)): 10±5% / 3450

Therefore you can convert the raw thermistor ADC reading to degrees Celsius:

Convert raw ADC to voltage:

voltage = 2.5 * raw / 4096
Convert voltage to resistance (assuming 2.5v reference)

resistance = 21450.0 * voltage / (2.5 - voltage)
Convert resistance to Kelvin:

1/T = (1/T0) + (1/β) * ln(R/R0) 1 = T((1/T0) + (1/β) * ln(R/10)) T = 1/((1/T0) + (1/β) * ln(R/10))

Where:

T: is the temperature in Kelvin T0: is a reference temperature (usually 25°C or 298.15K) β: is the beta value of the thermistor (a constant indicating the relationship between resistance and temperature) R: is the measured resistance of the thermistor R0: is the resistance of the thermistor at the reference temperature T0

Kelvin = 1/((1/298.15) + (1/3450) * ln(resistance/10))

Convert Kelvin to degrees Celsius:

degC = Kelvin - 273.15

Parameters

raw	the value read from the thermistor's 12-bit ADC (can be uint12 or SpectrometerResponse)

◆ get_laser_temperature_raw()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_temperature_raw ( self )

Note: little-endian, reverse of get_detector_temperature_raw

◆ get_laser_temperature_setpoint_raw()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_temperature_setpoint_raw ( self )

Note: never used, provided for OEM

◆ get_laser_warning_delay_sec()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_warning_delay_sec ( self )

◆ get_laser_watchdog_sec()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_laser_watchdog_sec ( self )

◆ get_line()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_line	(	self,
		trigger = True,
		auto_raman_params = None )

legacy alias

◆ get_microcontroller_firmware_version()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_microcontroller_firmware_version ( self )

◆ get_microcontroller_serial_number()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_microcontroller_serial_number ( self )

◆ get_mod_delay_us()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_mod_delay_us ( self )

◆ get_mod_duration_us()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_mod_duration_us ( self )

◆ get_mod_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_mod_enabled ( self )

◆ get_mod_linked_to_integration()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_mod_linked_to_integration ( self )

◆ get_mod_period_us()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_mod_period_us ( self )

◆ get_mod_width_us()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_mod_width_us ( self )

◆ get_opt_actual_integration_time()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_opt_actual_integration_time ( self )

◆ get_opt_area_scan()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_opt_area_scan ( self )

◆ get_opt_cf_select()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_opt_cf_select ( self )

◆ get_opt_data_header_tab()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_opt_data_header_tab ( self )

◆ get_opt_has_laser()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_opt_has_laser ( self )

◆ get_opt_horizontal_binning()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_opt_horizontal_binning ( self )

◆ get_opt_integration_time_resolution()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_opt_integration_time_resolution ( self )

◆ get_opt_laser_control()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_opt_laser_control ( self )

Laser commands.

◆ get_poll_status()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_poll_status ( self )

◆ get_raman_delay_ms()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_raman_delay_ms ( self )

◆ get_raman_mode_enabled_NOT_USED()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_raman_mode_enabled_NOT_USED ( self )

Note: not called by ENLIGHTEN

Warning: conflicts with GET_SELECTED_LASER

◆ get_scans_to_average()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_scans_to_average ( self )

◆ get_secondary_adc_calibrated()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_secondary_adc_calibrated	(		self,
		float	raw = None )

◆ get_secondary_adc_raw()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_secondary_adc_raw ( self )

◆ get_selected_adc()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_selected_adc ( self )

◆ get_selected_laser()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_selected_laser ( self )

◆ get_sensor_line_length()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_sensor_line_length ( self )

◆ get_shutter_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_shutter_enabled ( self )

◆ get_spectrum()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_spectrum	(	self,
		trigger = True,
		auto_raman_params = None )

Send "acquire", then immediately read the bulk endpoint(s).

Probably the most important method in this class.

Parameters

trigger	(Input) send an initial ACQUIRE
auto_raman_params	(Input) if present, use VR_ACQUIRE_AUTO_RAMAN rather than the usual VR_ACQUIRE_CCD

Returns: tuple of (spectrum[], area_scan_row_count) for success; None when it times-out while waiting for an external trigger (interpret as, "didn't find any fish this time, try again in a bit"); False (bool) when it times-out or encounters an exception when NOT in external-triggered mode

Exceptions

exception on timeout (unless external triggering enabled)

◆ get_strobe_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_strobe_enabled ( self )

a literal pass-through to get_laser_enabled()

◆ get_tec_enabled()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_tec_enabled ( self )

◆ get_trigger_delay()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_trigger_delay ( self )

◆ get_trigger_source()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_trigger_source ( self )

Read the trigger source setting from the device.

0 = internal
1 = external

Use caution when interpreting the larger behavior of the device as ARM and FX2 implementations differ as of 2017-08-02

Note: never called by ENLIGHTEN - provided for OEMs

◆ get_upper_code()

SpectrometerResponse wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_upper_code	(		self,
		int	wValue,
		int	wIndex = 0,
		int	wLength = 64,
		str	label = "",
		int	msb_len = None,
		int	lsb_len = None )

◆ get_vr_continuous_ccd()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_vr_continuous_ccd ( self )

◆ get_vr_num_frames()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.get_vr_num_frames ( self )

◆ handle_requests()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.handle_requests	(		self,
		list[SpectrometerRequest]	requests )

Todo: consider making 'requests' an object, and dynamically checking to see if it is a single SpectrometerRequest or a list[SpectrometerRequest]; if the former, only return a single SpectrometerResponse.

Reimplemented from wasatch.InterfaceDevice.InterfaceDevice.

◆ has_linearity_coeffs()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.has_linearity_coeffs ( self )

At least one linearity coeff is other than 0 or -1 (and no NaN).

Public because used by wasatch-shell.

◆ i2c_write()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.i2c_write	(	self,
		address,
		buf,
		label = "" )

◆ is_laser_firing()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.is_laser_firing ( self )

Check if the laser actually IS firing, independent of laser_enable or can_laser_fire.

Returns: SpectrometerResponse

◆ is_sensor_stable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.is_sensor_stable ( self )

◆ queue_message()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.queue_message	(	self,
		setting,
		value )

If an upstream queue is defined, send the name-value pair.

Does nothing if the caller hasn't provided a queue.

"setting" is application (caller) dependent, but ENLIGHTEN currently uses "marquee_info" and "marquee_error".

◆ refresh_alerts()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.refresh_alerts ( self )

◆ replace_session_eeprom()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.replace_session_eeprom	(		self,
		tuple[str, EEPROM]	pair )

Given a (serial_number, EEPROM) pair, replace this process's "session" EEPROM with the passed EEPROM.

◆ require_throwaway()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.require_throwaway	(		self,
			flag )

◆ reset()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.reset	(		self,
		*	args )

◆ reset_area_scan_frame()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.reset_area_scan_frame ( self )

◆ reset_fpga()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.reset_fpga ( self )

(end of laser commands)

◆ select_adc()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.select_adc	(		self,
		int	n )

◆ set_accessory_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_accessory_enable	(		self,
		bool	flag )

Todo: change opcode (conflicts with GET_DETECTOR_START_LINE)

◆ set_analog_output_mode()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_analog_output_mode	(		self,
		tuple[bool, int]	value )

Parameters

value (Input) tuple of (bool enable, int mode)

◆ set_analog_output_value()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_analog_output_value	(		self,
		int	value )

◆ set_area_scan_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_area_scan_enable	(		self,
			flag )

Historically, this opcode moved around a bit.

It is currently 0xeb, which conflicts with CF_SELECT). At one point it was 0xe9, which conflicted with LASER_RAMP_ENABLE.

◆ set_area_scan_line_count()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_area_scan_line_count	(		self,
			n )

◆ set_area_scan_line_interval()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_area_scan_line_interval	(		self,
			n )

◆ set_area_scan_line_step()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_area_scan_line_step	(		self,
			n )

◆ set_detector_gain()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_detector_gain	(		self,
		float	gain )

Note that this is used for detector types, including:

Hamamatsu silicon (S16010-*, S16011-*, etc)
Hamamatsu InGaAs (G9214 etc)
Sony IMX (IMX385 etc)

It is important to understand that the UNIT of this value changes between Hamamatsu and IMX detectors, but the DATATYPE does not.

Reasonable gain levels for Hamamatsu are a floating-point scalar, literally used to scale (gain) the signal, and are usually in the range (0.8 .. 1.2) or thereabouts.

Reasonable levels for IMX sensors are in dB and vary by detector, but are usually in the range (0.0 .. 31.0), with exactly 0.1dB precision. The spectrometer's FW will round to the nearest setting (1.23 will be rounded to 1.2). IMX sensors switch from "analog gain" to "digital gain" above a given threshold...on the IMX123, analog gain is 0.0 - 31.0, and digital is 31.1 - 72.0 (I think).

See also: https://wasatchphotonics.com/api/Wasatch.NET/class_wasatch_n_e_t_1_1_funky_float.html

Todo: we should probably track runtime hardware gain in SpectrometerState, not EEPROM

◆ set_detector_gain_odd()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_detector_gain_odd	(		self,
		float	gain )

◆ set_detector_offset()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_detector_offset	(		self,
		int	value )

◆ set_detector_offset_odd()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_detector_offset_odd	(		self,
		int	value )

◆ set_detector_roi()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_detector_roi	(		self,
		list[float]	args,
		bool	store = True )

Note this only sends the ROI downstream to the spectrometer (and stores it in DetectorRegions).

If you want to update the wavecal and store the "selected" region index, use set_region() instead (which calls this).

You should use set_region() if you are selecting one of the standard regions already configured on the EEPROM. You should use set_detector_roi() if you're making ad-hoc ROIs which aren't configured on the EEPROM.

Parameters

args	either a DetectorROI or a tuple of (region, y0, y1, x0, x1)

◆ set_detector_tec_setpoint_degC()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_detector_tec_setpoint_degC	(		self,
		float	degC )

Attempt to set the CCD cooler setpoint.

Verify that it is within an acceptable range. Ideally this is to prevent condensation and other issues. This value is a default and is hugely dependent on the environmental conditions.

◆ set_dfu_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_dfu_enable ( self )

Puts ARM-based spectrometers into Device Firmware Update (DFU) mode.

Warning: reflashing spectrometer firmware without specific instruction and support from Wasatch Photonics will void your warranty

◆ set_fan_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_fan_enable	(		self,
		bool	flag )

◆ set_high_gain_mode_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_high_gain_mode_enable	(		self,
		bool	flag )

CF_SELECT is configured using bit 2 of the FPGA configuration register 0x12.

This bit can be set using vendor commands 0xeb to SET and 0xec to GET. Note that the set command is expecting a 5-byte unsigned value, the highest byte of which we pass as part of an 8-byte buffer. Not sure why.

◆ set_integration_time_ms()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_integration_time_ms	(		self,
		float	ms )

Send the updated integration time in a control message to the device.

Warning: disabled EEPROM range-checking by customer request; range limits in EEPROM are defined as 16-bit values, while integration time is actually a 24-bit value, such that the EEPROM is artificially limiting our range.

Todo: SiG needs to wait 20ms + 8 frames for stabilization.

◆ set_lamp_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_lamp_enable	(		self,
		bool	flag )

◆ set_laser_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_enable	(		self,
		bool	flag )

Turn the laser on or off.

If laser power hasn't yet been externally configured, applies the default of full-power. The new state will be applied immediately.

Parameters

flag	(Input) bool (True turns laser on, False turns laser off)

Returns: whether the new state was applied

◆ set_laser_power_attenuator()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_power_attenuator	(		self,
			value )

digital pot on 220250 Rev4A+

◆ set_laser_power_high_resolution()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_power_high_resolution	(		self,
		bool	flag )

Sets whether the PWM pulse period is 1000µs (high-resolution, default) or 100µs (low-resolution, legacy).

Parameters

flag	(Input) True for 1000µs PWM period (high-resolution, default), False for 100µs (low-resolution)

Laser power is controlled via PWM (Pulse Width Modulation), essentially a square wave whose "duty cycle" (high vs low), expressed as a percentage, represents the amount of time the laser is actually firing. If the duty cycle is 33%, the laser will be firing 1/3 of the time, representing approximately one-third of "full power".

(It's not "exactly" one-third because the laser needs a moment to stablize when energized, and that "start-up" instability is increased when you're constantly pulsing the laser on-and-off.)

This function is used to determine the LENGTH (period) of that PWM square wave. Because the laser's PWM parameters are all specified in microseconds (µs), a longer period allows greater precision (resolution) in specifying the duty cycle.

Historically, Wasatch spectrometers used a PWM period of 100µs, meaning the pulse width (time each wave was high) could only be set from 1-99µs, giving an essential laser power resolution of 1%. That behavior can be restored by setting this value False.

More recently, we've increased the default PWM pulse period to 1000µs (1ms). Since the pulse width is still set in µs, that allows an effective laser power resolution of 0.1%. This is the new default, and can be explicitly requested by setting this value to True.

Warning: Note that this function is provided for cases where the laser power is set as a percentage. When setting laser power through milliWatts, using the onboard laser power calibration, it is important to use the same resolution as was in effect when the calibration was generated. All Wasatch laser power calibrations are generated in "high-resolution," so this function SHOULD NOT be set "False" (low-res) if setting laser power in mW.

◆ set_laser_power_mW()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_power_mW	(		self,
		int	mW_in )

◆ set_laser_power_perc()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_power_perc	(		self,
		float	value_in,
		bool	set_in_perc = True )

Todo: support floating-point value, as we have a 12-bit ADC and can provide a bit more precision than 100 discrete steps (goal to support 0.1 - .125% resolution)

◆ set_laser_power_perc_immediate()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_power_perc_immediate	(		self,
		float	value )

Sets laser power (modulated pulse width) which will be used next time the laser is turned on (or changed immediately, if the laser is already enabled).

Laser power is determined by a combination of the pulse width, period and modulation being enabled. There are many combinations of these values that will produce a given percentage of the total laser power through pulse width modulation. There is no 'get laser power' control message on the device.

Some of the goals of Enlighten are for it to be stable, and a reason we have sales. During spectrometer builds, it was discovered that the laser power settings were not implemented. During the implementation process, it was discovered that the laser modulation, pulse period and pulse width commands do not conform to specification. Where you can set integration time 100 ms with the command:

device.ctrl_transfer(bmRequestType=device_to_host, bRequest=0xDB, wValue=100, wIndex=0, data_or_wLength=0)

The laser pulse period must be set where the wValue and data_or_wLength parameters are equal. So if you wanted a pulse period of 100, you must specify the value in both places:

... wValue=100, data_or_wLength=100) ...

This in turn implies that the legacy firmware has a long masked issue when reading the value to update from the data_or_wLength parameter instead of the wValue field. This is only accurate for the laser modulation related functions.

This is backed up by the Dash v3 StrokerControl DLL implementation. It was discovered that the StrokerControl DLL sets the wValue and data or wLength parameters to the same value at every control message write.

The exciting takeaway here is that Enlighten is stable enough. Turning the laser on with the data or wLength parameter not set correctly will cause a hardware failure and complete device lockup requiring a power cycle.

fid: CRITICAL Hardware Failure FID Send Code Problem with ctrl transfer: [Errno None] 11

Unlike Dash which may lockup and require killing the application, Enlighten does not lock up. The Enlighten code base has now been used to unmask an issue that has been lurking with our legacy firmware for close to 6 years. We've detected this out of specification area of the code before it can adversely impact a customer. """

As long as laser power is modulated using a period of 100us, with a necessarily-integral pulse width of 1-99us, then it's not physically possible to support fractional power levels.

Todo: talk to Jason about changing modulation PERIOD to longer value (200us? 400? 1000?), OR whether pulse WIDTH can be in smaller unit (500ns? 100ns?)

◆ set_laser_power_require_modulation()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_power_require_modulation	(		self,
		bool	flag )

◆ set_laser_tec_mode()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_tec_mode	(		self,
			mode )

◆ set_laser_temperature_setpoint_raw()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_temperature_setpoint_raw	(		self,
		int	value )

◆ set_laser_warning_delay_sec()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_warning_delay_sec	(		self,
			value )

◆ set_laser_watchdog_sec()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_laser_watchdog_sec	(		self,
			sec )

◆ set_log_level()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_log_level	(		self,
		str	s )

◆ set_mod_delay_us()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_mod_delay_us	(		self,
		float	us )

◆ set_mod_duration_us_NOT_USED()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_mod_duration_us_NOT_USED	(		self,
		float	us )

◆ set_mod_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_mod_enable	(		self,
		bool	flag )

◆ set_mod_linked_to_integration()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_mod_linked_to_integration	(		self,
		bool	flag )

◆ set_mod_period_us()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_mod_period_us	(		self,
		float	us )

◆ set_mod_width_us()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_mod_width_us	(		self,
		float	us )

◆ set_onboard_scans_to_average()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_onboard_scans_to_average	(		self,
			n )

This is provided to let ENLIGHTEN turn off onboard averaging settings which might have been generated, and (deliberately) left in place after an Auto-Raman measurement.

◆ set_pixel_mode()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_pixel_mode	(		self,
		float	mode )

Parameters

mode	integral value 0-3

mode  ADC (AD)   Pixel Width (OD)
b00   10-bit     10-bit
b01   10-bit     12-bit
b10   12-bit     10-bit
b11   12-bit     12-bit

◆ set_raman_delay_ms()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_raman_delay_ms	(		self,
		int	ms )

◆ set_raman_mode_enable_NOT_USED()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_raman_mode_enable_NOT_USED	(		self,
		bool	flag )

Enable "Raman mode" (automatic laser) in the spectrometer firmware.

◆ set_selected_laser()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_selected_laser	(		self,
		int	value )

On spectrometers supporting two lasers, select the primary (0) or secondary (1).

Laser Enable, laser power etc should all then affect the currently-selected laser.

Warning: conflicts with GET_RAMAN_MODE_ENABLE

◆ set_shutter_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_shutter_enable	(		self,
		bool	flag )

◆ set_single_region()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_single_region	(		self,
		int	n )

This function uses the the multi-region feature to select just a single pre-configured region at a time.

Whichever region is selected, that region's parameters are written to "region 0" of the spectrometer, and the global wavecal is updated to use that region's calibration.

Todo: consider clear_region() function to restore physical ROI to (0, active_vertical_pixels, 0, active_horizontal_pixels) (leave wavecal alone?)

◆ set_strobe_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_strobe_enable	(		self,
		bool	flag )

this is a synonym for _set_laser_enable_immediate(), but without side-effects

◆ set_tec_enable()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_tec_enable	(		self,
		bool	flag )

Todo: rename set_detector_tec_enable

◆ set_trigger_delay()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_trigger_delay	(		self,
		float	half_us )

A confenurable delay from when an inbound trigger signal is received by the spectrometer, until the triggered acquisition actually starts.

Default value is 0us.

Unit is in 0.5 microseconds (500ns), so value of 25 would represent 12.5us.

Value is 24bit, so max value is 16777216 (8.388608 sec).

Like triggering, only currently supported on ARM.

◆ set_trigger_source()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_trigger_source	(		self,
		bool	value )

Set the source for incoming acquisition triggers.

Parameters

value either 0 for "internal" or 1 for "external" With internal triggering (the default), the spectrometer expects the USB host to explicitly send a START_ACQUISITION (ACQUIRE) opcode to begin each integration. In external triggering, the spectrometer waits for the rising edge on a signal connected to a pin on the OEM accessory connector. Technically on ARM, the microcontroller is continuously monitoring both the external pin and listening for internal software opcodes. On the FX2 you need to explicitly place the microcontroller into external triggering mode to avail the feature.

◆ set_vertical_roi()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.set_vertical_roi	(		self,
			roi )

◆ update_firmware_log()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.update_firmware_log ( self )

◆ update_laser_watchdog()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.update_laser_watchdog ( self )

Automatically set the laser watchdog long enough to handle the current integration time, assuming we have to perform 6 throwaways on the sensor in case it went to sleep.

Note: we are not currently using this function

◆ update_session_eeprom()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.update_session_eeprom	(		self,
		tuple[str, EEPROM]	pair )

Given a (serial_number, EEPROM) pair, update this process's "session" EEPROM with just the EDITABLE fields of the passed EEPROM.

◆ update_vertical_roi()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.update_vertical_roi ( self )

◆ write_eeprom()

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.write_eeprom ( self )

Actually store the current session EEPROM fields to the spectrometer.

Member Data Documentation

◆ alert_queue

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.alert_queue = alert_queue

◆ alerts

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.alerts = set()

◆ allow_default_gain_reset

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.allow_default_gain_reset = True

◆ area_scan_frame

list wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.area_scan_frame = [ [0] * self.settings.pixels() for line in range(self.settings.eeprom.actual_pixels_vertical) ]

◆ ccd_temperature_invalid

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.ccd_temperature_invalid = False

◆ connected

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.connected = False

◆ connecting

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.connecting = False

◆ detector_tec_setpoint_degC

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.detector_tec_setpoint_degC = degC

◆ detector_tec_setpoint_has_been_set

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.detector_tec_setpoint_has_been_set = False

◆ device

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.device = None

◆ device_id

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.device_id = device_id

◆ device_type

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.device_type

Initial value:

=  MockUSBDevice(device_id.name,
                                             device_id.directory,
                                             device_id.overrides,
                                             device_id.spectra_options)

◆ eeprom_backup

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.eeprom_backup = None

◆ extra_area_scan_data

list wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.extra_area_scan_data = []

◆ has_received_spectrum

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.has_received_spectrum = False

◆ imx385

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.imx385 = IMX385()

◆ inject_random_errors

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.inject_random_errors = False

◆ laser_temperature_invalid

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.laser_temperature_invalid = False

◆ last_applied_laser_power

float wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.last_applied_laser_power = 0.0

◆ last_spectrum

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.last_spectrum = None

◆ last_usb_timestamp

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.last_usb_timestamp = None

◆ message_queue

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.message_queue = message_queue

◆ next_applied_laser_power

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.next_applied_laser_power = None

◆ prev_pixels

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.prev_pixels = None

◆ raise_exceptions

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.raise_exceptions = False

◆ random_error_perc

float wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.random_error_perc = 0.001

◆ retry_enabled

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.retry_enabled = True

◆ retry_max

int wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.retry_max = 3

◆ retry_ms

int wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.retry_ms = 5

◆ settings

wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.settings = SpectrometerSettings(device_id)

◆ shutdown_requested

bool wasatch.FeatureIdentificationDevice.FeatureIdentificationDevice.shutdown_requested = False

The documentation for this class was generated from the following file:

/Users/mzieg/work/code/Wasatch.PY/wasatch/FeatureIdentificationDevice.py

Public Member Functions

Public Attributes

Protected Member Functions

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ _apply_horizontal_binning()

◆ _apply_linear_pixel_calibration()

◆ _check_for_random_error()

◆ _correct_bad_pixels()

◆ _correct_ingaas_gain_and_offset()

◆ _get_code()

◆ _init_process_funcs()

◆ _post_connect()

◆ _read_eeprom()

◆ _read_fpga_compilation_options()

◆ _schedule_disconnect()

◆ _send_code()

◆ _set_laser_enable_immediate()

◆ _to40bit()

◆ _wait_for_usb_available()

◆ apply_edc()

◆ can_laser_fire()

◆ check_alert()

◆ clear_regions()

◆ connect()

◆ disconnect()

◆ generate_timeout_ms()

◆ get_actual_frames()

◆ get_actual_integration_time_us()

◆ get_ambient_temperature_degC()

◆ get_ambient_temperature_degC_arm()

◆ get_ambient_temperature_degC_gen15()

◆ get_analog_input_value()

◆ get_analog_output_state()

◆ get_area_scan()

◆ get_area_scan_hamamatsu()

◆ get_area_scan_xs()

◆ get_battery_charging()

◆ get_battery_percentage()

◆ get_battery_register()

◆ get_battery_state_raw()

◆ get_ble_firmware_version()

◆ get_ccd_sensing_threshold()

◆ get_ccd_threshold_sensing_mode()

◆ get_dac()

◆ get_detector_gain()

◆ get_detector_gain_odd()

◆ get_detector_offset()

◆ get_detector_offset_odd()

◆ get_detector_tec_setpoint_degC()

◆ get_detector_tec_setpoint_raw()

◆ get_detector_temperature_degC()

◆ get_detector_temperature_raw()

◆ get_discretes_enabled()

◆ get_external_trigger_output()

◆ get_fan_enabled()

◆ get_fpga_configuration_register()

◆ get_fpga_firmware_version()

◆ get_high_gain_mode_enabled()

◆ get_integration_time_ms()

◆ get_lamp_enabled()

◆ get_laser_enabled()

◆ get_laser_interlock()

◆ get_laser_power_attenuator()

◆ get_laser_tec_mode()

◆ get_laser_temperature_degC()

◆ get_laser_temperature_raw()

◆ get_laser_temperature_setpoint_raw()

◆ get_laser_warning_delay_sec()

◆ get_laser_watchdog_sec()

◆ get_line()

◆ get_microcontroller_firmware_version()

◆ get_microcontroller_serial_number()

◆ get_mod_delay_us()

◆ get_mod_duration_us()

◆ get_mod_enabled()

◆ get_mod_linked_to_integration()

◆ init()