Mark devices behind generic serial converters and skip auto-probing them

Problem: Many instruments sit behind a stock FTDI 0x0403:0x6001 cable
(FieldMaster, oscilloscope, Echo, IntelliDrive), so they all share the same
VID/PID. DeviceManager could not tell them apart and, on every FTDI cable
plugged in, tried initializeDevice() on each candidate class -- sending
arbitrary protocol bytes to an unknown instrument (the same kind of blind
probing that can wedge a device).

Solution: add PhysicalDevice.usesGenericSerialConverter (default False). When
set, vidpids() expands to every generic converter vendor (FTDI/Prolific/
CP210x/CH34x) with the product id wildcarded, sourced from
SerialPort.genericSerialConverterVendors (single source of truth), and
isCompatibleWith treats a None product id in a pair as a wildcard. So such a
device is discoverable behind any generic cable, not just FTDI, and is
identified by serial number rather than VID/PID. DeviceManager gains
candidateClassesForAutoDiscovery(), which drops generic-converter classes so
they are never auto-probed; they are constructed explicitly instead.

FieldMaster, oscilloscope, Echo and IntelliDrive are flagged generic;
DebugFieldMasterDevice keeps its own fake identity (flag False), and
Thorlabs (custom-EEPROM FTDI PID 0xfaf0) stays a specific, unique identity.
connectedUSBDevices omits the product id from usb.core.find when it is None so
VID-only matching works end to end. Adds testGenericSerialConverter.py
(hardware-free).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dccote

hardwarelibrary/devicemanager.py

@@ -207,13 +207,23 @@ def stopMonitoring(self):
         else:
             raise RuntimeError("No monitoring loop running")
 
+    @classmethod
+    def candidateClassesForAutoDiscovery(cls, idVendor, idProduct):
+        """Device classes matching a plugged-in USB device that are safe to
+        instantiate automatically. Classes behind a generic serial converter are
+        excluded: their VID/PID identifies only the cable, so several instruments
+        share it and auto-probing them would send arbitrary protocol bytes to an
+        unknown device. Those must be constructed explicitly instead."""
+        candidates = utils.getCandidateDeviceClasses(PhysicalDevice, idVendor, idProduct)
+        return [aClass for aClass in candidates if not aClass.usesGenericSerialConverter]
+
     def usbDeviceConnected(self, usbDevice):
         descriptor = USBDeviceDescriptor.fromUSBDevice(usbDevice)
         NotificationCenter().postNotification(DeviceManagerNotification.usbDeviceDidConnect, notifyingObject=self, userInfo=descriptor)
         if descriptor not in self.usbDeviceDescriptors:
             self.usbDeviceDescriptors.append(descriptor)
 
-        candidates = utils.getCandidateDeviceClasses(PhysicalDevice, descriptor.idVendor, descriptor.idProduct)
+        candidates = self.candidateClassesForAutoDiscovery(descriptor.idVendor, descriptor.idProduct)
         for candidateClass in candidates:
             # This may throw if incompat:
             #                 deviceInstanceible

hardwarelibrary/echodevice.py

@@ -14,6 +14,7 @@
 class EchoDevice(PhysicalDevice):
     classIdProduct = 0x6001
     classIdVendor = 0x0403
+    usesGenericSerialConverter = True
     commands = {
         "ECHO1": TextCommand(name="ECHO1", requestEncoder="someText", replyDecoder="someText"),
         "ECHO2": TextCommand(name="ECHO2", requestEncoder="someOtherText", replyDecoder="someOtherText"),

hardwarelibrary/motion/intellidrivedevice.py

@@ -22,6 +22,7 @@ class State(Enum):
 class IntellidriveDevice(RotationDevice):
     classIdVendor = 0x0403
     classIdProduct = 0x6001
+    usesGenericSerialConverter = True
 
     commands = {
         "SET_REGISTER": TextCommand(name="SET_REGISTER",

hardwarelibrary/oscilloscope/oscilloscopedevice.py

@@ -26,6 +26,7 @@ def __init__(self, code, msg, esr, stb, underlyingErrors=None):
 class OscilloscopeDevice(PhysicalDevice):
     classIdVendor = 0x0403
     classIdProduct = 0x6001
+    usesGenericSerialConverter = True
 
     def __init__(self, serialNumber:str = None, idProduct = 0x6001, idVendor = 0x0403):
         super().__init__(serialNumber, idProduct=self.classIdProduct, idVendor=self.classIdVendor)

hardwarelibrary/physicaldevice.py

@@ -38,6 +38,14 @@ class NotInitialized(Exception):
     classIdProduct = None
     commands = None
 
+    # True when classIdVendor/classIdProduct are those of a generic, off-the-shelf
+    # USB/RS-232 converter (a stock FTDI/Prolific/CP210x/CH34x cable) rather than
+    # the instrument's own identity. Such a device shares its VID/PID with every
+    # other instrument behind the same cable model, so it cannot be identified by
+    # VID/PID alone: it matches any generic converter (see vidpids) and must be
+    # disambiguated by serial number, and DeviceManager will not auto-probe it.
+    usesGenericSerialConverter = False
+
     def __init__(self, serialNumber:str, idProduct:int, idVendor:int):
         if serialNumber == "*" or serialNumber is None:
             serialNumber = ".*"
@@ -65,13 +73,22 @@ def __init__(self, serialNumber:str, idProduct:int, idVendor:int):
 
     @classmethod
     def vidpids(cls):
+        if cls.usesGenericSerialConverter:
+            # Identity is not in the VID/PID: match any generic converter chip,
+            # PID wildcarded (None). Local import avoids a physicaldevice <->
+            # communication import cycle.
+            from hardwarelibrary.communication.serialport import SerialPort
+            return [(idVendor, None) for idVendor in SerialPort.genericSerialConverterVendors]
         return [(cls.classIdVendor, cls.classIdProduct)]
 
     @classmethod
     def isCompatibleWith(cls, serialNumber, idProduct, idVendor):
         for compatibleIdVendor, compatibleIdProduct in cls.vidpids():
-            if idVendor == compatibleIdVendor and idProduct == compatibleIdProduct:
-                return True
+            if idVendor == compatibleIdVendor:
+                # A None product id in the pair is a wildcard: it matches any
+                # product behind that vendor (used for generic converters).
+                if compatibleIdProduct is None or idProduct == compatibleIdProduct:
+                    return True
 
         return False
 

hardwarelibrary/powermeters/fieldmasterdevice.py

@@ -43,6 +43,7 @@ class FieldMasterDevice(PowerMeterDevice):
 
     classIdVendor = 0x0403
     classIdProduct = 0x6001
+    usesGenericSerialConverter = True
 
     def __init__(self, serialNumber: str = None, idProduct: int = 0x6001,
                  idVendor: int = 0x0403, portPath: str = None,
@@ -152,6 +153,7 @@ class DebugFieldMasterDevice(FieldMasterDevice):
 
     classIdVendor = 0xFFFF
     classIdProduct = 0xFFF1
+    usesGenericSerialConverter = False   # debug device has its own fake identity
 
     def __init__(self, serialNumber='debug'):
         PhysicalDevice.__init__(self, serialNumber=serialNumber,

hardwarelibrary/tests/testGenericSerialConverter.py

@@ -0,0 +1,73 @@
+import env
+import unittest
+
+from hardwarelibrary.physicaldevice import PhysicalDevice
+from hardwarelibrary.communication.serialport import SerialPort
+from hardwarelibrary.powermeters import (
+    FieldMasterDevice, DebugFieldMasterDevice, IntegraDevice,
+)
+from hardwarelibrary.devicemanager import DeviceManager
+import hardwarelibrary.utils as utils
+
+
+class TestGenericConverterFlag(unittest.TestCase):
+    def testFieldMasterIsGeneric(self):
+        self.assertTrue(FieldMasterDevice.usesGenericSerialConverter)
+
+    def testDebugFieldMasterIsNotGeneric(self):
+        self.assertFalse(DebugFieldMasterDevice.usesGenericSerialConverter)
+
+    def testIntegraIsNotGeneric(self):
+        self.assertFalse(IntegraDevice.usesGenericSerialConverter)
+
+    def testBaseDefaultIsNotGeneric(self):
+        self.assertFalse(PhysicalDevice.usesGenericSerialConverter)
+
+
+class TestGenericConverterVidpids(unittest.TestCase):
+    def testGenericExpandsToAllConverterVendors(self):
+        expected = [(idVendor, None) for idVendor in SerialPort.genericSerialConverterVendors]
+        self.assertEqual(FieldMasterDevice.vidpids(), expected)
+
+    def testNonGenericKeepsSinglePair(self):
+        self.assertEqual(IntegraDevice.vidpids(), [(0x1ad5, 0x0300)])
+
+    def testDebugKeepsItsOwnPair(self):
+        self.assertEqual(DebugFieldMasterDevice.vidpids(), [(0xFFFF, 0xFFF1)])
+
+
+class TestGenericConverterCompatibility(unittest.TestCase):
+    def testMatchesAnyGenericConverterVendorWithAnyProduct(self):
+        # Same instrument behind FTDI, Prolific, or CP210x cables (different PIDs)
+        self.assertTrue(FieldMasterDevice.isCompatibleWith("*", 0x6001, 0x0403))
+        self.assertTrue(FieldMasterDevice.isCompatibleWith("*", 0x2303, 0x067b))
+        self.assertTrue(FieldMasterDevice.isCompatibleWith("*", 0xEA60, 0x10c4))
+
+    def testRejectsUnknownVendor(self):
+        self.assertFalse(FieldMasterDevice.isCompatibleWith("*", 0x0001, 0x9999))
+
+    def testNonGenericStillRequiresExactProduct(self):
+        self.assertTrue(IntegraDevice.isCompatibleWith("*", 0x0300, 0x1ad5))
+        self.assertFalse(IntegraDevice.isCompatibleWith("*", 0x9999, 0x1ad5))
+        # No wildcard leak: a None product must not match a concrete pair.
+        self.assertFalse(IntegraDevice.isCompatibleWith("*", None, 0x1ad5))
+
+    def testDebugFieldMasterStillConstructs(self):
+        device = DebugFieldMasterDevice()  # would raise if the flag broke its vidpids
+        self.assertEqual(device.idVendor, 0xFFFF)
+        self.assertEqual(device.idProduct, 0xFFF1)
+
+
+class TestAutoDiscoveryGuard(unittest.TestCase):
+    def testGenericClassesMatchButAreExcludedFromAutoDiscovery(self):
+        candidates = utils.getCandidateDeviceClasses(PhysicalDevice, 0x0403, 0x6001)
+        self.assertIn(FieldMasterDevice, candidates)  # it does match the FTDI cable
+
+        discoverable = DeviceManager.candidateClassesForAutoDiscovery(0x0403, 0x6001)
+        self.assertNotIn(FieldMasterDevice, discoverable)  # ...but is not auto-probed
+        for aClass in discoverable:
+            self.assertFalse(aClass.usesGenericSerialConverter)
+
+
+if __name__ == "__main__":
+    unittest.main()

hardwarelibrary/utils.py

@@ -77,7 +77,12 @@ def connectedUSBDevices(vidpids = None, serialNumberPattern=None):
     devices = []
     if vidpids is not None:
         for (idVendor, idProduct) in vidpids:
-            devices.extend(list(usb.core.find(find_all=True, idVendor=idVendor, idProduct=idProduct)))
+            if idProduct is None:
+                # A None product id means "any product from this vendor". pyusb's
+                # find matches on equality, so idProduct must be omitted, not None.
+                devices.extend(list(usb.core.find(find_all=True, idVendor=idVendor)))
+            else:
+                devices.extend(list(usb.core.find(find_all=True, idVendor=idVendor, idProduct=idProduct)))
     else:
         devices.extend(list(usb.core.find(find_all=True)))