feat: Add a helper function to register USBTMC connection information…

… for devices that don't currently have USBTMC support in tm_devices.

Also updated constants and modules to cause the documentation to be rendered in a more usable way.

CHANGELOG.md

@@ -21,11 +21,14 @@ Things to be included in the next release go here.
 ### Added
 
 - Added a config option (`default_visa_timeout`) to specify the default VISA timeout for all initial VISA device connections.
+- Added a new function, `register_additional_usbtmc_mapping()`, to enable users to add USBTMC connection information for devices that don't have native support for USBTMC connections in `tm_devices` yet.
 
 ### Changed
 
 - Switched all workflows to use the new [`tektronix/python-package-ci-cd`](https://github.com/tektronix/python-package-ci-cd) reusable workflows.
 - Reduced the out-of-the box `default_visa_timeout` value from 30 seconds to 5 seconds.
+- _**SEMI-BREAKING CHANGE**_: Changed the `USB_MODEL_ID_LOOKUP` constant to use `SupportedModels` as keys instead of values to make the documentation clearer.
+- _**SEMI-BREAKING CHANGE**_: Changed the `DEVICE_DRIVER_MODEL_MAPPING` constant to use `SupportedModels` as keys instead of values to make the documentation clearer.
 
 ---
 

examples/miscellaneous/custom_device_driver_support.py

@@ -2,7 +2,7 @@
 
 from typing import Tuple, Union
 
-from tm_devices import DeviceManager
+from tm_devices import DeviceManager, register_additional_usbtmc_mapping
 from tm_devices.drivers import MSO5
 from tm_devices.drivers.pi.pi_device import PIDevice
 from tm_devices.drivers.pi.scopes.scope import Scope
@@ -74,11 +74,16 @@ def custom_device_method(self, value: int) -> None:
 }
 
 
+# To enable USBTMC connection support for a device without native USBTMC support in tm_devices,
+# simply register the USBTMC connection information for the device's model series.
+register_additional_usbtmc_mapping("CustomModelSeries", model_id="0x0000", vendor_id="0x0000")
+
+
 with DeviceManager(external_device_drivers=CUSTOM_DEVICE_DRIVERS) as device_manager:
     # Add a scope that is currently supported by the package
     mso5: MSO5 = device_manager.add_scope("192.168.0.1")
-    # Add the custom scope
-    custom_scope: CustomScope = device_manager.add_scope("192.168.0.2")
+    # Add the custom scope with a USB connection after registering the USBTMC mapping above
+    custom_scope: CustomScope = device_manager.add_scope("MODEL-SERIAL", connection_type="USB")
     # Add the custom device that is a device type not officially supported
     # NOTE: If using a config file or environment variable to define a device that is unsupported,
     #       the `device_type` key must be set to "UNSUPPORTED".

src/tm_devices/__init__.py

@@ -20,6 +20,7 @@
     SYSTEM_DEFAULT_VISA_BACKEND,
 )
 from tm_devices.helpers.enums import SupportedModels
+from tm_devices.helpers.functions import register_additional_usbtmc_mapping
 
 # Read version from installed package.
 __version__ = version(PACKAGE_NAME)
@@ -28,6 +29,7 @@
     "DeviceManager",
     "print_available_visa_devices",
     "PYVISA_PY_BACKEND",
+    "register_additional_usbtmc_mapping",
     "SupportedModels",
     "SYSTEM_DEFAULT_VISA_BACKEND",
 ]

src/tm_devices/device_manager.py

@@ -20,6 +20,11 @@
 from tm_devices.drivers.api.rest_api.margin_testers.margin_tester import MarginTester
 from tm_devices.drivers.api.rest_api.rest_api_device import RESTAPIDevice
 from tm_devices.drivers.device import Device
+
+# noinspection PyProtectedMember
+from tm_devices.drivers.device_driver_mapping import (
+    _DEVICE_DRIVER_MODEL_STR_MAPPING,  # pyright: ignore[reportPrivateUsage]
+)
 from tm_devices.drivers.pi.data_acquisition_systems.data_acquisition_system import (
     DataAcquisitionSystem,
 )
@@ -1260,15 +1265,12 @@ def __create_device(
             SystemError: Indicates something went wrong when creating the device.
             AssertionError: Indicates something went wrong when creating the device.
         """
-        # pylint: disable=import-outside-toplevel
-        from tm_devices.drivers import DEVICE_DRIVER_MODEL_MAPPING
-
         if self._external_device_drivers is not None:
             device_drivers: Mapping[str, Type[Device]] = MappingProxyType(
-                {**self._external_device_drivers, **DEVICE_DRIVER_MODEL_MAPPING}
+                {**self._external_device_drivers, **_DEVICE_DRIVER_MODEL_STR_MAPPING}
             )
         else:
-            device_drivers = DEVICE_DRIVER_MODEL_MAPPING
+            device_drivers = _DEVICE_DRIVER_MODEL_STR_MAPPING
 
         alias_string = f' "{device_config.alias}"' if device_config.alias else ""
         if device_config.device_type == DeviceTypes.UNSUPPORTED:

src/tm_devices/drivers/__init__.py

@@ -109,7 +109,7 @@
 from tm_devices.drivers.pi.systems_switches.ss3706a import SS3706A
 from tm_devices.drivers.api.rest_api.margin_testers.tmt4 import TMT4
 
-# TODO: remove this function after TekScopeSW is fully removed
+# TODO: deprecation: remove this function after TekScopeSW is fully removed
 if not ("--doctest-modules" in sys.argv and sys.argv[-1] == "src"):  # pragma: no cover
 
     def __getattr__(name: str) -> Any:

src/tm_devices/drivers/device_driver_mapping.py

@@ -105,120 +105,136 @@
 from tm_devices.drivers.pi.systems_switches.ss3706a import SS3706A
 from tm_devices.helpers.enums import SupportedModels
 
-DEVICE_DRIVER_MODEL_MAPPING: Mapping[str, Type[Device]] = MappingProxyType(
+# IMPORTANT: Any additions to this class which support a USBTMC connection need to be added to the
+# tm_devices.helpers.constants_and_dataclasses.USB_MODEL_ID_LOOKUP constant as well.
+DEVICE_DRIVER_MODEL_MAPPING: Mapping[SupportedModels, Type[Device]] = MappingProxyType(
     {
         # AFGs
-        SupportedModels.AFG3K.value: AFG3K,
-        SupportedModels.AFG3KB.value: AFG3KB,
-        SupportedModels.AFG3KC.value: AFG3KC,
-        SupportedModels.AFG31K.value: AFG31K,
+        SupportedModels.AFG3K: AFG3K,
+        SupportedModels.AFG3KB: AFG3KB,
+        SupportedModels.AFG3KC: AFG3KC,
+        SupportedModels.AFG31K: AFG31K,
         # AWGs
-        SupportedModels.AWG5200.value: AWG5200,
-        SupportedModels.AWG5K.value: AWG5K,
-        SupportedModels.AWG5KB.value: AWG5KB,
-        SupportedModels.AWG5KC.value: AWG5KC,
-        SupportedModels.AWG7K.value: AWG7K,
-        SupportedModels.AWG7KB.value: AWG7KB,
-        SupportedModels.AWG7KC.value: AWG7KC,
-        SupportedModels.AWG70KA.value: AWG70KA,
-        SupportedModels.AWG70KB.value: AWG70KB,
+        SupportedModels.AWG5200: AWG5200,
+        SupportedModels.AWG5K: AWG5K,
+        SupportedModels.AWG5KB: AWG5KB,
+        SupportedModels.AWG5KC: AWG5KC,
+        SupportedModels.AWG7K: AWG7K,
+        SupportedModels.AWG7KB: AWG7KB,
+        SupportedModels.AWG7KC: AWG7KC,
+        SupportedModels.AWG70KA: AWG70KA,
+        SupportedModels.AWG70KB: AWG70KB,
         # Scopes
-        SupportedModels.DPO5K.value: DPO5K,
-        SupportedModels.DPO5KB.value: DPO5KB,
-        SupportedModels.DPO7K.value: DPO7K,
-        SupportedModels.DPO7KC.value: DPO7KC,
-        SupportedModels.DPO70K.value: DPO70K,
-        SupportedModels.DPO70KC.value: DPO70KC,
-        SupportedModels.DPO70KD.value: DPO70KD,
-        SupportedModels.DPO70KDX.value: DPO70KDX,
-        SupportedModels.DPO70KSX.value: DPO70KSX,
-        SupportedModels.DSA70K.value: DSA70K,
-        SupportedModels.DSA70KC.value: DSA70KC,
-        SupportedModels.DSA70KD.value: DSA70KD,
-        SupportedModels.LPD6.value: LPD6,
-        SupportedModels.MSO2K.value: MSO2K,
-        SupportedModels.MSO2KB.value: MSO2KB,
-        SupportedModels.DPO2K.value: DPO2K,
-        SupportedModels.DPO2KB.value: DPO2KB,
-        SupportedModels.MDO3.value: MDO3,
-        SupportedModels.MDO3K.value: MDO3K,
-        SupportedModels.MDO4K.value: MDO4K,
-        SupportedModels.MDO4KB.value: MDO4KB,
-        SupportedModels.MDO4KC.value: MDO4KC,
-        SupportedModels.MSO4K.value: MSO4K,
-        SupportedModels.MSO4KB.value: MSO4KB,
-        SupportedModels.DPO4K.value: DPO4K,
-        SupportedModels.DPO4KB.value: DPO4KB,
-        SupportedModels.MSO2.value: MSO2,
-        SupportedModels.MSO4.value: MSO4,
-        SupportedModels.MSO4B.value: MSO4B,
-        SupportedModels.MSO5.value: MSO5,
-        SupportedModels.MSO5B.value: MSO5B,
-        SupportedModels.MSO5LP.value: MSO5LP,
-        SupportedModels.MSO6.value: MSO6,
-        SupportedModels.MSO6B.value: MSO6B,
-        SupportedModels.MSO5K.value: MSO5K,
-        SupportedModels.MSO5KB.value: MSO5KB,
-        SupportedModels.MSO70K.value: MSO70K,
-        SupportedModels.MSO70KC.value: MSO70KC,
-        SupportedModels.MSO70KDX.value: MSO70KDX,
-        SupportedModels.TEKSCOPEPC.value: TekScopePC,
-        SupportedModels.TSOVU.value: TSOVu,
+        SupportedModels.DPO5K: DPO5K,
+        SupportedModels.DPO5KB: DPO5KB,
+        SupportedModels.DPO7K: DPO7K,
+        SupportedModels.DPO7KC: DPO7KC,
+        SupportedModels.DPO70K: DPO70K,
+        SupportedModels.DPO70KC: DPO70KC,
+        SupportedModels.DPO70KD: DPO70KD,
+        SupportedModels.DPO70KDX: DPO70KDX,
+        SupportedModels.DPO70KSX: DPO70KSX,
+        SupportedModels.DSA70K: DSA70K,
+        SupportedModels.DSA70KC: DSA70KC,
+        SupportedModels.DSA70KD: DSA70KD,
+        SupportedModels.LPD6: LPD6,
+        SupportedModels.MSO2K: MSO2K,
+        SupportedModels.MSO2KB: MSO2KB,
+        SupportedModels.DPO2K: DPO2K,
+        SupportedModels.DPO2KB: DPO2KB,
+        SupportedModels.MDO3: MDO3,
+        SupportedModels.MDO3K: MDO3K,
+        SupportedModels.MDO4K: MDO4K,
+        SupportedModels.MDO4KB: MDO4KB,
+        SupportedModels.MDO4KC: MDO4KC,
+        SupportedModels.MSO4K: MSO4K,
+        SupportedModels.MSO4KB: MSO4KB,
+        SupportedModels.DPO4K: DPO4K,
+        SupportedModels.DPO4KB: DPO4KB,
+        SupportedModels.MSO2: MSO2,
+        SupportedModels.MSO4: MSO4,
+        SupportedModels.MSO4B: MSO4B,
+        SupportedModels.MSO5: MSO5,
+        SupportedModels.MSO5B: MSO5B,
+        SupportedModels.MSO5LP: MSO5LP,
+        SupportedModels.MSO6: MSO6,
+        SupportedModels.MSO6B: MSO6B,
+        SupportedModels.MSO5K: MSO5K,
+        SupportedModels.MSO5KB: MSO5KB,
+        SupportedModels.MSO70K: MSO70K,
+        SupportedModels.MSO70KC: MSO70KC,
+        SupportedModels.MSO70KDX: MSO70KDX,
+        SupportedModels.TEKSCOPEPC: TekScopePC,
+        SupportedModels.TSOVU: TSOVu,
         # Margin Testers
-        SupportedModels.TMT4.value: TMT4,
+        SupportedModels.TMT4: TMT4,
         # Source Measure Units
-        SupportedModels.SMU2400.value: SMU2400,
-        SupportedModels.SMU2401.value: SMU2401,
-        SupportedModels.SMU2410.value: SMU2410,
-        SupportedModels.SMU2450.value: SMU2450,
-        SupportedModels.SMU2460.value: SMU2460,
-        SupportedModels.SMU2461.value: SMU2461,
-        SupportedModels.SMU2470.value: SMU2470,
-        SupportedModels.SMU2601B.value: SMU2601B,
-        SupportedModels.SMU2601B_PULSE.value: SMU2601BPulse,
-        SupportedModels.SMU2602B.value: SMU2602B,
-        SupportedModels.SMU2604B.value: SMU2604B,
-        SupportedModels.SMU2606B.value: SMU2606B,
-        SupportedModels.SMU2611B.value: SMU2611B,
-        SupportedModels.SMU2612B.value: SMU2612B,
-        SupportedModels.SMU2614B.value: SMU2614B,
-        SupportedModels.SMU2634B.value: SMU2634B,
-        SupportedModels.SMU2635B.value: SMU2635B,
-        SupportedModels.SMU2636B.value: SMU2636B,
-        SupportedModels.SMU2651A.value: SMU2651A,
-        SupportedModels.SMU2657A.value: SMU2657A,
-        SupportedModels.SMU2601A.value: SMU2601A,
-        SupportedModels.SMU2602A.value: SMU2602A,
-        SupportedModels.SMU2604A.value: SMU2604A,
-        SupportedModels.SMU2611A.value: SMU2611A,
-        SupportedModels.SMU2612A.value: SMU2612A,
-        SupportedModels.SMU2614A.value: SMU2614A,
-        SupportedModels.SMU2634A.value: SMU2634A,
-        SupportedModels.SMU2635A.value: SMU2635A,
-        SupportedModels.SMU2636A.value: SMU2636A,
-        SupportedModels.SMU6430.value: SMU6430,
-        SupportedModels.SMU6514.value: SMU6514,
-        SupportedModels.SMU6517B.value: SMU6517B,
+        SupportedModels.SMU2400: SMU2400,
+        SupportedModels.SMU2401: SMU2401,
+        SupportedModels.SMU2410: SMU2410,
+        SupportedModels.SMU2450: SMU2450,
+        SupportedModels.SMU2460: SMU2460,
+        SupportedModels.SMU2461: SMU2461,
+        SupportedModels.SMU2470: SMU2470,
+        SupportedModels.SMU2601B: SMU2601B,
+        SupportedModels.SMU2601B_PULSE: SMU2601BPulse,
+        SupportedModels.SMU2602B: SMU2602B,
+        SupportedModels.SMU2604B: SMU2604B,
+        SupportedModels.SMU2606B: SMU2606B,
+        SupportedModels.SMU2611B: SMU2611B,
+        SupportedModels.SMU2612B: SMU2612B,
+        SupportedModels.SMU2614B: SMU2614B,
+        SupportedModels.SMU2634B: SMU2634B,
+        SupportedModels.SMU2635B: SMU2635B,
+        SupportedModels.SMU2636B: SMU2636B,
+        SupportedModels.SMU2651A: SMU2651A,
+        SupportedModels.SMU2657A: SMU2657A,
+        SupportedModels.SMU2601A: SMU2601A,
+        SupportedModels.SMU2602A: SMU2602A,
+        SupportedModels.SMU2604A: SMU2604A,
+        SupportedModels.SMU2611A: SMU2611A,
+        SupportedModels.SMU2612A: SMU2612A,
+        SupportedModels.SMU2614A: SMU2614A,
+        SupportedModels.SMU2634A: SMU2634A,
+        SupportedModels.SMU2635A: SMU2635A,
+        SupportedModels.SMU2636A: SMU2636A,
+        SupportedModels.SMU6430: SMU6430,
+        SupportedModels.SMU6514: SMU6514,
+        SupportedModels.SMU6517B: SMU6517B,
         # Power Supplies
-        SupportedModels.PSU2200.value: PSU2200,
-        SupportedModels.PSU2220.value: PSU2220,
-        SupportedModels.PSU2230.value: PSU2230,
-        SupportedModels.PSU2231.value: PSU2231,
-        SupportedModels.PSU2231A.value: PSU2231A,
-        SupportedModels.PSU2280.value: PSU2280,
-        SupportedModels.PSU2281.value: PSU2281,
+        SupportedModels.PSU2200: PSU2200,
+        SupportedModels.PSU2220: PSU2220,
+        SupportedModels.PSU2230: PSU2230,
+        SupportedModels.PSU2231: PSU2231,
+        SupportedModels.PSU2231A: PSU2231A,
+        SupportedModels.PSU2280: PSU2280,
+        SupportedModels.PSU2281: PSU2281,
         # Digital Multimeters
-        SupportedModels.DMM6500.value: DMM6500,
-        SupportedModels.DMM7510.value: DMM7510,
-        SupportedModels.DMM7512.value: DMM7512,
+        SupportedModels.DMM6500: DMM6500,
+        SupportedModels.DMM7510: DMM7510,
+        SupportedModels.DMM7512: DMM7512,
         # Data Acquisition System
-        SupportedModels.DAQ6510.value: DAQ6510,
+        SupportedModels.DAQ6510: DAQ6510,
         # Systems Switches
-        SupportedModels.SS3706A.value: SS3706A,
+        SupportedModels.SS3706A: SS3706A,
     }
 )
 """A mapping of device model series names to their device driver objects.
 
 Any additions to this class which support a USBTMC connection need to be added to
 the [`tm_devices.helpers.constants_and_dataclasses.USB_MODEL_ID_LOOKUP`][] constant as well.
+
+!!! danger "Deprecated"
+    This mapping is deprecated since it is only used internally by the
+    [`DeviceManager`][tm_devices.DeviceManager].
 """
+
+####################################################################################################
+# Private Attributes
+####################################################################################################
+# TODO: deprecation: Move the contents of DEVICE_DRIVER_MODEL_MAPPING into this attribute,
+#  remove the old DEVICE_DRIVER_MODEL_MAPPING constant, and make this entire module (file) private
+#  in the next major release
+_DEVICE_DRIVER_MODEL_STR_MAPPING: "Mapping[str, Type[Device]]" = MappingProxyType(
+    {key.value: value for key, value in DEVICE_DRIVER_MODEL_MAPPING.items()}
+)

src/tm_devices/drivers/pi/_base_afg_source_channel.py → src/tm_devices/drivers/pi/base_afg_source_channel.py

@@ -3,7 +3,7 @@
 from abc import abstractmethod
 from typing import Literal
 
-from tm_devices.drivers.pi._base_source_channel import BaseSourceChannel
+from tm_devices.drivers.pi.base_source_channel import BaseSourceChannel
 from tm_devices.drivers.pi.pi_device import PIDevice
 from tm_devices.helpers.enums import SignalGeneratorFunctionBase
 

src/tm_devices/drivers/pi/scopes/tekscope/tekscope.py

@@ -41,7 +41,7 @@
 )
 from tm_devices.driver_mixins.usb_drives_mixin import USBDrivesMixin
 from tm_devices.drivers.device import family_base_class
-from tm_devices.drivers.pi._base_afg_source_channel import BaseAFGSourceChannel
+from tm_devices.drivers.pi.base_afg_source_channel import BaseAFGSourceChannel
 from tm_devices.drivers.pi.scopes.scope import Scope
 from tm_devices.helpers import DeviceConfigEntry, LoadImpedanceAFG
 

src/tm_devices/drivers/pi/scopes/tekscope/tekscopesw.py

@@ -1,5 +1,5 @@
 """TekScopePC device driver module."""
-# TODO: rename file after TekScopeSW is fully removed
+# TODO: deprecation: rename file after TekScopeSW is fully removed
 
 import pyvisa as visa
 

src/tm_devices/drivers/pi/signal_generators/afgs/afg.py

@@ -13,7 +13,7 @@
     SourceDeviceConstants,
 )
 from tm_devices.drivers.device import family_base_class
-from tm_devices.drivers.pi._base_afg_source_channel import BaseAFGSourceChannel
+from tm_devices.drivers.pi.base_afg_source_channel import BaseAFGSourceChannel
 from tm_devices.drivers.pi.signal_generators.signal_generator import SignalGenerator
 from tm_devices.helpers import DeviceTypes, LoadImpedanceAFG
 

src/tm_devices/drivers/pi/signal_generators/awgs/awg.py

@@ -12,7 +12,7 @@
     SourceDeviceConstants,
 )
 from tm_devices.drivers.device import family_base_class
-from tm_devices.drivers.pi._base_source_channel import BaseSourceChannel
+from tm_devices.drivers.pi.base_source_channel import BaseSourceChannel
 from tm_devices.drivers.pi.signal_generators.signal_generator import SignalGenerator
 from tm_devices.helpers import DeviceTypes, LoadImpedanceAFG
 

src/tm_devices/helpers/__init__.py

@@ -35,6 +35,7 @@
     get_visa_backend,
     ping_address,
     print_with_timestamp,
+    register_additional_usbtmc_mapping,
     sanitize_enum,
 )
 from tm_devices.helpers.read_only_cached_property import ReadOnlyCachedProperty
@@ -62,6 +63,7 @@
     "ping_address",
     "print_with_timestamp",
     "PYVISA_PY_BACKEND",
+    "register_additional_usbtmc_mapping",
     "sanitize_enum",
     "SerialConfig",
     "Singleton",