wasatch 2.3.24__tar.gz → 2.4.0__tar.gz

{wasatch-2.3.24 → wasatch-2.4.0}/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+_Note: in the following, FID = wasatch.FeatureInterfaceDevice_
+
+- 2026-05-27 2.4.0 (enlighten-4.2.2)
+    - InterfaceDevice
+        - This was a major change. The InterfaceDevice base class has existed for
+          years, but didn't contribute anything beyond handle_requests. I've 
+          moved message_queue and alert_queue up from WasatchDevice/FID so all 
+          InterfaceDevice subclasses can use that functionality directly.
+        - Also, the handle_requests([ SpectrometerRequest(cmd, args=[value]) ])[0]
+          syntax was neurose-inducing, so I've added convenience shortcuts for
+          handle_request(SpectrometerRequest) (singular), and handle_cmd(name[, value]).
+    - WasatchDevice
+        - deprecated command_queue (pending_commands)
+        - handle_requests now directly peeks into FID to see which commands can 
+          be handled by "the hardware layer," and processes those commands in 
+          real-time, accumulating the list of responses. This allows callers to 
+          use gettor methods like GET_LASER_WARNING_TIME_SEC and actually receive
+          the response value, which was previously impossible when such commands
+          were shoved onto the "pending command queue" (which offered no method 
+          for response delivery).
+    - FeatureInterfaceDevice
+        - deprecated SpectrumAndRow (legacy Area Scan design)
+        - removed handle_requests overload (not sure why this was there)
+        - added get_power_connection_state
+        - added periodic check for late-arriving attributes like ble_firmware_version
+        - enabled get_microcontroller_serial_number
+        - tweak laser password validation logic
+        - add default laser warning delay sec for old FW
+    - IDSDevice
+        - paired laser_device
+            - A key goal for this release was to allow IDSDevice "sensor 
+              control" objects to "pair" with WasatchDevice "laser control" 
+              objects, for the new case where an IDS sensor was being combined 
+              with a Wasatch laser driver to create a 2-device Raman spectrometer. 
+            - Note that once "paired," they essentially merge EEPROMs (starting
+              with whatever WasatchDevice loaded from USB, then folding-in 
+              whatever IDSDevice found in JSON).
+            - In this first implementation, I chose to connect the two (make one 
+              device "discoverable" by the other) through WasatchDeviceWrapper. 
+              That created a weird import loop and maybe was higher than it 
+              needed to be. I may refactor this later so they're discoverable / 
+              joined at the InterfaceDevice level itself, which resolves the loop
+              and makes the pair usable without WasatchDeviceWrapper (a class 
+              essentially designed by and for ENLIGHTEN).
+        - Part of the point of the above was to support a subtype of Auto-Raman,
+          tentatively called Auto-Collection, which skips the integ/gain 
+          optimization and goes straight for averaging dark-collected Raman
+          within a measurement window.
+    - EEPROM
+        - A third key goal of this release was to support all the new EEPROM fields
+          added from Rev18 to Rev19 of ENG-0034, including:
+            - startup_laser_tec_setpoint
+            - light_source_type
+            - assembly_revision (and AssemblyRevision)
+            - feature_mask_xs
+            - max_battery_temp_deg_c
+            - max_laser_temp_deg_c
+            - acc_state
+            - acc_state_gpio1
+            - acc_state_gpio2
+            - acc_cont_strobe_count
+            - acc_cont_strobe_delay_us
+            - acc_cont_strobe_period_us
+            - acc_cont_strobe_width_us
+            - pixel_correction_type
+        - deprecated baud_rate, linearity_coeffs
+        - made EEPROM subclasses JSON serializable (hopefully)
+        - fixed EEPROM.pack for binary types ("*") for our growing set of "binary" 
+          (marshalled) fields
+        - moved further into using the new un/pack_field functions, automatically
+          pulling offset/size/type from eeprom_fields table
+        - revisited user_text / user_data relationship
+        - consolidating backup location when writing EEPROM (can probably just 
+          get rid of this)
+    - BLEDevice
+        - added laser PWM
+    - AndorDevice
+        - renamed "shutter_enable" (whatever that meant) to "shutter_open"
+    - SpectrometerResponse
+        - deprecated progress and incomplete
+    - starting to consider Safe Mode
 - 2026-04-18 2.3.24
     - add avg_resolution to IDSDevice EEPROM
     - change XS attenuator default from 127 to 40

{wasatch-2.3.24 → wasatch-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wasatch
-Version: 2.3.24
+Version: 2.4.0
 Summary: Application-level driver for Wasatch Photonics spectrometers
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown

{wasatch-2.3.24 → wasatch-2.4.0}/WasatchShell/wasatch-shell.py

@@ -105,7 +105,7 @@ class WasatchShell:
                 "get_selected_adc",                         # SR
                 "get_selected_laser",                       # SR
                 "get_sensor_line_length",                   # SR
-                "get_shutter_enabled",                      # SR
+                "get_shutter_open",                         # SR
                 "get_strobe_enabled",                       # SR
                 "get_tec_enabled",                          # SR
                 "get_trigger_delay",                        # SR
@@ -146,7 +146,7 @@ class WasatchShell:
                                                
         set_fan_enable                         - takes bool argument
         set_lamp_enable                        - takes bool argument
-        set_shutter_enable                     - takes bool argument
+        set_shutter_open                       - takes bool argument
         set_strobe_enable                      - takes bool argument
         set_mod_enable                         - takes bool argument
         set_mod_period_us                      - takes int argument
@@ -394,8 +394,8 @@ class WasatchShell:
                             self.device.change_setting("lamp_enable", self.read_bool())
                             self.display(1)
 
-                        elif command == "set_shutter_enable":
-                            self.device.change_setting("shutter_enable", self.read_bool())
+                        elif command == "set_shutter_open":
+                            self.device.change_setting("shutter_open", self.read_bool())
                             self.display(1)
 
                         elif command == "set_strobe_enable":

{wasatch-2.3.24 → wasatch-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wasatch"
-version = "2.3.24"
+version = "2.4.0"
 description= "Application-level driver for Wasatch Photonics spectrometers"
 requires-python = ">=3.9"
 readme = "README.md"

{wasatch-2.3.24 → wasatch-2.4.0}/wasatch/AbstractUSBDevice.py

@@ -1,5 +1,7 @@
-
 class AbstractUSBDevice:
+    """
+    This is NOT an InterfaceDevice. This is used by MockUSBDevice and RealUSBDevice.
+    """
 
     def __init__(self):
         pass
@@ -26,4 +28,4 @@ class AbstractUSBDevice:
         pass
 
     def send_code(self):
-        pass
+        pass

wasatch-2.4.0/wasatch/AccessoryConnector.py

@@ -0,0 +1,75 @@
+
+
+class GPIOState:
+    MODE_FUNCTION                   = 0
+    MODE_MANUAL                     = 1
+
+    DIR_INPUT                       = 0
+    DIR_OUTPUT                      = 1
+
+    GPIO_FUNCTION_DISABLED          = 0
+
+    GPIO1_FUNCTION_EXT_TRIGGER      = 1
+    GPIO1_FUNCTION_LASER_OVERRIDE   = 2
+
+    GPIO2_FUNCTION_CONT_STROBE      = 1
+    GPIO2_FUNCTION_DATA_READY       = 2
+    GPIO2_FUNCTION_LASER_MIRROR     = 3
+    GPIO2_FUNCTION_LASER_ERROR      = 4
+
+    def __init__(self, num):
+        self.num = num
+        self.mode = GPIOState.MODE_FUNCTION
+        self.dir = GPIOState.DIR_INPUT
+        self.function = GPIOState.GPIO_FUNCTION_DISABLED
+        self.value = 0
+
+    def serialize(self):
+        mask = 0x00
+        mask |= 0x01 if self.mode == self.MODE_MANUAL else 0
+        mask |= 0x02 if self.dir == self.DIR_OUTPUT else 0
+        if self.dir == self.DIR_OUTPUT:
+            mask |= 0x04 if self.value else 0
+        # bit 3 reserved
+        mask |= (self.function << 4)
+
+    def deserialize(self, mask):
+        self.mode = mask & 0x01
+        self.dir = mask & 0x02
+        if self.dir == self.DIR_INPUT:
+            self.value = mask & 0x04
+        self.function = (mask >> 4) & 0xf
+
+    def __repr__(self):
+        return f"GPIO{self.num}< mode {self.mode}, dir {self.dir}, func {self.function}, value {self.value} >"
+
+class AccessoryConnector:
+
+    def __init__(self):
+        self.acc_gpio_enabled = False
+        self.acc_5v_enabled = False
+        self.acc_5v_good = False # read-only
+
+        self.state_gpio1 = GPIOState(1)
+        self.state_gpio2 = GPIOState(2)
+
+        self.strobe_period_us = None
+        self.strobe_width_us = None
+        self.strobe_delay_us = None
+        self.strobe_count = None
+
+    def serialize_acc_state(self):
+        mask = 0x0000
+        mask |= 0x0001 if self.acc_gpio_enabled else 0
+        mask |= 0x0002 if self.acc_5v_enabled else 0
+        # acc_5v_good read-only
+        # bits 3-15 reserved
+        return mask
+
+    def deserialize_acc_state(self, mask):
+        self.acc_gpio_enabled   = 0 != mask & 0x01
+        self.acc_5v_enabled     = 0 != mask & 0x02
+        self.acc_5v_good        = 0 != mask & 0x04 # read-only
+
+    def __repr__(self):
+        return f"AccessoryConnector < gpio_enabled {self.acc_gpio_enabled}, 5v_enabled {self.acc_5v_enabled}, 5v_good {self.acc_5v_good}"

{wasatch-2.3.24 → wasatch-2.4.0}/wasatch/AndorDevice.py

@@ -24,28 +24,6 @@ class AndorDevice(InterfaceDevice):
 
     @todo have check_result return a SpectrometerResponse 
     @todo try to auto-detect whether x-axis needs inverted via DLL.GetImageFlip()
-
-    ##########################################################################
-    This class adopts the external device interface structure.
-    This involves 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 receives a response from the connected device it then passes that
-    back up the chain.
-    @verbatim
-                               Enlighten Request
-                                       |
-                                handle_requests
-                                       |
-                                  -----------
-                                 |  |  |  |  |  
-             { get_laser status, acquire, set_laser_watchdog, etc....}
-                                 |  |  |  |  |  
-                                  -----------
-                                       |
-                         {self.driver.some_andor_sdk_call}
-    @endverbatim
-    ############################################################################
     """
 
     SUCCESS = 20002             #!< see load_error_codes()
@@ -55,29 +33,15 @@ class AndorDevice(InterfaceDevice):
     DRIVER_NOT_INSTALLED = False
 
     def __init__(self, device_id, message_queue=None, alert_queue=None):
-        # if passed a string representation of a DeviceID, deserialize it
-        super().__init__()
+        super().__init__(device_id=device_id, message_queue=message_queue, alert_queue=alert_queue)
 
         if self.DRIVER_NOT_INSTALLED:
             raise InterfaceDeviceClassUnavailable("Andor driver not installed")
 
-        if type(device_id) is str:
-            device_id = DeviceID(label=device_id)
-
-        self.device_id      = device_id
-        self.message_queue  = message_queue
-        self.alert_queue    = alert_queue
-
         self.load_error_codes()
 
         self.connected = False
 
-        # Receives ENLIGHTEN's 'change settings' commands in the spectrometer
-        # process. 
-        self.command_queue = []
-
-        self.immediate_mode = False
-
         # An AndorDevice has-a SpectrometerSettings, which has-a EEPROM, which 
         # has-a MultiWavelengthCalibration
         self.settings = SpectrometerSettings(self.device_id)
@@ -179,40 +143,39 @@ class AndorDevice(InterfaceDevice):
         except:
             log.error(f"failed to enqueue StatusMessage {msg}", exc_info=1)
 
-    def not_implemented(self):
+    def not_implemented(self, arg):
         pass
 
     def _init_process_funcs(self):
         process_f = {}
 
-        process_f["connect"]                    = self.connect
-        process_f["acquire_data"]               = self.acquire_data
-        process_f["set_shutter_enable"]         = self.set_shutter_enable
-        process_f["set_integration_time_ms"]    = self.set_integration_time_ms
-        process_f["get_serial_number"]          = self.get_serial_number
-        process_f["init_tec_setpoint"]          = self.init_tec_setpoint
-        process_f["set_tec_setpoint"]           = self.set_tec_setpoint
-        process_f["init_detector_area"]         = self.init_detector_area
-        process_f["scans_to_average"]           = self.set_scans_to_average
-        process_f["high_gain_mode_enable"]      = self.high_gain_mode_enable
-        process_f["save_config"]                = self.save_config
+        # setting and function have same name
+        for fn_name in [
+                "connect",
+                "acquire_data",
+                "set_shutter_open",
+                "set_integration_time_ms",
+                "get_serial_number",
+                "init_tec_setpoint",
+                "set_tec_setpoint",
+                "init_detector_area",
+                "scans_to_average",
+                "high_gain_mode_enable",
+                "save_config",
+                "set_vertical_binning",
+                "set_ingaas_correction_enable",
+                "set_etalon_correction_enable" ]:
+            process_f[fn_name] = getattr(self, fn_name)
+
+        # setting and function have different names
+        process_f["integration_time_ms"]        = self.set_integration_time_ms
+        process_f["fan_enable"]                 = self.set_fan_enable
+        process_f["shutter_open"]               = self.set_shutter_open
+        process_f["detector_tec_enable"]        = self.set_detector_tec_enable
+        process_f["detector_tec_setpoint_degC"] = self.set_tec_setpoint
         process_f["vertical_binning"]           = self.set_vertical_binning
         process_f["take_one_request"]           = self.set_take_one_request
 
-        process_f["reset_scan_averaging"]       = self.not_implemented
-        process_f["heartbeat"]                  = lambda x: None
-
-        ##################################################################
-        # What follows is the old init-lambdas that are squashed into process_f
-        # Long term, the upstream requests should be changed to match the new format
-        # This is an easy fix for the time being to make things behave
-        ##################################################################
-        process_f["integration_time_ms"]        = lambda x: self.set_integration_time_ms(x)
-        process_f["fan_enable"]                 = lambda x: self.set_fan_enable(bool(x))
-        process_f["shutter_enable"]             = lambda x: self.set_shutter_enable(bool(x))
-        process_f["detector_tec_enable"]        = lambda x: self.toggle_tec(bool(x))
-        process_f["detector_tec_setpoint_degC"] = lambda x: self.set_tec_setpoint(int(round(x)))
-
         return process_f
 
     def high_gain_mode_enable(self, enabled):
@@ -227,9 +190,13 @@ class AndorDevice(InterfaceDevice):
             log.debug(f"for {enabled} setting gain to {self.gain_options[0]}")
             return
 
-    def set_fan_enable(self, x):
-        self.check_result(self.driver.SetFanMode(int(x)), f"Andor Fan On {x}")
-        return SpectrometerResponse()
+    def set_fan_enable(self, flag):
+        flag = True if flag else False
+        try:
+            self.check_result(self.driver.SetFanMode(int(x)), f"Andor Fan On {x}")
+        except:
+            return SpectrometerResponse(False)
+        return SpectrometerResponse(True)
 
     def _get_default_data_dir(self):
         if os.name == "nt":
@@ -271,6 +238,12 @@ class AndorDevice(InterfaceDevice):
         if not spectrum.any():
             self._queue_message("marquee_error", "Andor camera is saturated")
 
+        if self.settings.ingaas_correction:
+            spectrum = self.settings.ingaas_correction.apply(spectrum)
+
+        if self.settings.etalon_correction:
+            spectrum = self.settings.etalon_correction.apply(spectrum)
+
         # log.debug(f"_get_spectrum_raw: returning spectrum {spectrum}")
         return spectrum
 
@@ -389,13 +362,29 @@ class AndorDevice(InterfaceDevice):
             return self.temperature_cache_value
 
     def _close_ex_shutter(self):
+        # SetShutterEx(typ, internalMode, closingTimeMS, openingTimeMS, externalMode)
+        # where:
+        # - typ: 
+        #       0 = output TTL LOW to open shutter
+        #       1 = output TTL HIGH to open shutter
+        #
+        # - mode:
+        #       0 = Fully Auto
+        #       1 = Permanently Open
+        #       2 = Permanently Closed
+        #       3 = UNDEFINED
+        #       4 = Open for FVB series
+        #       5 = Open for any series
+
+        # set TTL HIGH="open", internalMode PermanentlyOpen, externalMode PermanentlyClosed
         self.check_result(self.driver.SetShutterEx(1, 1, self.SHUTTER_SPEED_MS, self.SHUTTER_SPEED_MS, 2), "SetShutterEx(2)")
-        self.settings.state.shutter_enabled = False
+        self.settings.state.shutter_open = False
         return SpectrometerResponse(True)
 
     def _open_ex_shutter(self):
+        # set TTL HIGH="open", internalMode PermanentlyOpen, externalMode PermanentlyOpen
         self.check_result(self.driver.SetShutterEx(1, 1, self.SHUTTER_SPEED_MS, self.SHUTTER_SPEED_MS, 1), "SetShutterEx(1)")
-        self.settings.state.shutter_enabled = True
+        self.settings.state.shutter_open = True
         return SpectrometerResponse(True)
 
     ###############################################################
@@ -461,8 +450,9 @@ class AndorDevice(InterfaceDevice):
         self.init_detector_speed() # step 12+13
 
         # step 14
+        # set internal shutter to PermanentlyOpen, external shutter to Automatic
         self.check_result(self.driver.SetShutterEx(1, 1, self.SHUTTER_SPEED_MS, self.SHUTTER_SPEED_MS, 0), "SetShutterEx(fully automatic external with internal always open)")
-        self.settings.state.shutter_enabled = True
+        self.settings.state.shutter_open = True 
 
         # step 15
         self.set_integration_time_ms(self.settings.eeprom.startup_integration_time_ms)
@@ -560,8 +550,9 @@ class AndorDevice(InterfaceDevice):
         """
         Loads configuration from file `self.config_file` and populates `self.settings.eeprom` with members.
         """
-        f = open(self.config_file,)
-        self.config_values = dict(json.load(f))
+        with open(self.config_file) as f:
+            self.config_values = json.load(f)
+
         log.debug(f"loaded {self.config_file}: {self.config_values}")
 
         # handle wp_ prefixes
@@ -570,6 +561,7 @@ class AndorDevice(InterfaceDevice):
                 self.settings.eeprom.multi_wavelength_calibration.set(v, self.config_values[k])
 
         # same spelling
+        # consider just using self.settings.eeprom.fields.keys()
         for k in [ 'model', 
                    'stubbed', 
                    'detector', 
@@ -597,17 +589,20 @@ class AndorDevice(InterfaceDevice):
         if 'startup_temp_degC' in self.config_values:
             self.set_tec_setpoint(self.settings.eeprom.startup_temp_degC)
 
+        # pick up Pixel Corrections like EtalonCorrection, InGaAsCorrection etc
+        self.settings.augment_from_json_data(data)
+
     def acquire_data(self):
         # handle TakeOneRequest.take_dark
         dark_reading = None
         tor = self.take_one_request
         log.debug(f"acquire_data: tor {tor}")
         if tor and tor.take_dark:
-            self.set_shutter_enable(True)
+            self.set_shutter_open(False)
             dark_reading = self._take_one_averaged_reading()
-            if dark is None:
+            if dark_reading is None:
                 return SpectrometerResponse(False, error_msg="failed to collect dark")
-            self.set_shutter_enable(False)
+            self.set_shutter_open(True)
 
         # get spectrum (potentially averaged)
         reading = self._take_one_averaged_reading()
@@ -647,8 +642,8 @@ class AndorDevice(InterfaceDevice):
         log.debug(f"acquire_data: reading {reading}")
         return SpectrometerResponse(data=reading)
 
-    def set_shutter_enable(self, enable):
-        if enable:
+    def set_shutter_open(self, flag):
+        if flag:
             return self._open_ex_shutter()
         else:
             return self._close_ex_shutter()
@@ -696,16 +691,17 @@ class AndorDevice(InterfaceDevice):
 
         return SpectrometerResponse(True)
 
-    def toggle_tec(self, toggle_state):
-        c_toggle = c_int(toggle_state)
-        self.tec_enabled = c_toggle.value
-        if self.tec_enabled:
+    def set_detector_tec_enable(self, flag):
+        flag = True if flag else False
+        self.tec_enabled = flag
+        if flag:
             self.check_result(self.driver.CoolerON(), "CoolerON")
         else:
             self.check_result(self.driver.CoolerOFF(), "CoolerOFF")
         return SpectrometerResponse(True)
 
     def set_tec_setpoint(self, set_temp):
+        set_temp = int(round(set_temp, 0))
         if set_temp < self.settings.eeprom.min_temp_degC or set_temp > self.settings.eeprom.max_temp_degC:
             log.error(f"requested temp of {set_temp}, but it is outside range ({self.settings.eeprom.min_temp_degC}C, {self.settings.eeprom.max_temp_degC}C)")
             return
@@ -776,6 +772,14 @@ class AndorDevice(InterfaceDevice):
         log.debug(f"set AD channel {ADnumber} with horizontal speed {HSnumber} ({STemp})")
         return SpectrometerResponse(True)
 
+    def set_ingaas_correction_enable(self, flag):
+        if self.settings.ingaas_correction:
+            self.settings.ingaas_correction.enable = flag
+            
+    def set_etalon_correction_enable(self, flag):
+        if self.settings.etalon_correction:
+            self.settings.etalon_correction.enable = flag
+
     def set_scans_to_average(self, value):
         value = int(value)
 

wasatch-2.4.0/wasatch/AssemblyRevision.py

@@ -0,0 +1,56 @@
+import json
+from . import utils
+
+class AssemblyRevision(dict):
+    """
+    Making this a standalone class because might end up using from both FID (USB)
+    and BLEDevice.
+    """
+    def __init__(self, data=None):
+        dict.__init__(self) # https://stackoverflow.com/a/31207881
+        self.partnumber = None
+        self.variant = None
+        self.revision = None
+
+        if isinstance(data, str):
+            data = utils.hex_string_to_data(data)
+
+        self.parse_data(data)
+
+    def parse_data(self, data):
+        """
+        This is based on the data structure defined in ENG-0120 Rev 10.
+        """
+        if data is None or len(data) != 6:
+            log.error(f"parse_data: invalid length {data}")
+            return
+
+        self.partnumber = (data[0] << 8) + data[1] + 140_000
+        self.variant    = (data[2] << 8) + data[3]
+        self.revision   = (data[4] << 8) + data[5]
+
+    def serialize(self):
+        """ probably a simpler way to do this with struct """
+        buf = [ 0 ] * 6
+        if self.partnumber:
+            n = self.partnumber - 140_000
+            buf[0] = (n >> 8) & 0xff
+            buf[1] = n & 0xff
+        if self.variant:
+            n = self.variant
+            buf[2] = (n >> 8) & 0xff
+            buf[3] = n & 0xff
+        if self.revision:
+            n = self.revision
+            buf[4] = (n >> 8) & 0xff
+            buf[5] = n & 0xff
+
+    def __repr__(self):
+        s = ""
+        if self.partnumber and self.partnumber != 140_000:
+            s += f"{self.partnumber}"
+            if self.variant:
+                s += f"-{self.variant}"
+            if self.revision:
+                s += f" Rev{self.revision}"
+        return s