docs: added example illustrating usage of pyvisa and tm_devices

CHANGELOG.md

@@ -18,6 +18,11 @@ Valid subsections within a version are:
 
 Things to be included in the next release go here.
 
+### Added
+
+- Updated documentation to include examples illustrating usage of `PyISA` and `tm_devices`.
+- Updated documentation requirements.
+
 ---
 
 ## v0.1.1 (2024-09-11)

docs/basic_usage.md

@@ -335,3 +335,75 @@ TekHSI is compatible with PyVISA. You can mix PyVISA with TekHSI. This has some
     to take little or no time.
 3. TekHSI requires much less code that the normal processing of curve commands.
 4. The waveform output from TekHSI is easy to use with file readers/writers that allow this data to be quickly exported using the [tm_data_types](https://github.com/tektronix/tm_data_types) module.
+
+```python
+"""An example script demonstrating the command & control using PyVISA and retrieving waveform data from a single channel using TekHSI."""
+
+import pyvisa
+
+from tm_data_types import AnalogWaveform
+from tekhsi import TekHSIConnect
+
+addr = "192.168.0.1"  # Replace with the IP address of your instrument
+
+rm = pyvisa.ResourceManager("@py")
+
+# write command to instrument sample using pyvisa
+visa_scope = rm.open_resource(f"TCPIP0::{addr}::INSTR")
+
+sample_query = visa_scope.query("*IDN?")
+print(sample_query)
+# Make the waveform display OFF
+visa_scope.write("DISplay:WAVEform OFF")
+# Set the Horizontal mode to Manual
+visa_scope.write("HOR:MODE MAN")
+# Set the horizontal Record Length
+visa_scope.write("HOR:MODE:RECO 2500")
+
+# time.sleep(2) # Optional delay
+# Connect to instrument via TekHSI, select channel 1
+with TekHSIConnect(f"{addr}:5000", ["ch1"]) as connect:
+    # Save data from 10 acquisitions
+    for i in range(10):
+        with connect.access_data():
+            waveform: AnalogWaveform = connect.get_data("ch1")
+            print(f"{waveform.source_name}_{i}:{waveform.record_length}")
+
+visa_scope.write("DISplay:WAVEform ON")
+
+# close visa connection
+rm.close()
+```
+
+#### `tm_devices` can be used along with TekHSI
+
+```python
+"""An example script demonstrating the command & control using tm_devices and retrieving waveform data from a single channel using TekHSI."""
+
+from tm_data_types import AnalogWaveform
+from tm_devices import DeviceManager
+from tm_devices.drivers import MSO6B
+
+from tekhsi import TekHSIConnect
+
+addr = "192.168.0.1"  # Replace with the IP address of your instrument
+
+with DeviceManager(verbose=True) as device_manager:
+    scope: MSO6B = device_manager.add_scope(f"{addr}")
+    idn_response = scope.commands.idn.query()
+    print(idn_response)
+    scope.commands.display.waveform.write("OFF")
+    scope.commands.horizontal.mode.write("OFF")
+    scope.commands.horizontal.mode.recordlength.write("2500")
+
+    # time.sleep(2) # Optional delay
+    # Connect to instrument via TekHSI, select channel 1
+    with TekHSIConnect(f"{scope.ip_address}:5000", ["ch1"]) as connect:
+        # Save data from 10 acquisitions
+        for i in range(10):
+            with connect.access_data():
+                waveform: AnalogWaveform = connect.get_data("ch1")
+                print(f"{waveform.source_name}_{i}:{waveform.record_length}")
+
+    scope.commands.display.waveform.write("ON")
+```

docs/requirements.txt

@@ -39,6 +39,7 @@ platformdirs==4.3.2 ; python_version >= "3.8" and python_version < "4.0"
 pygments==2.18.0 ; python_version >= "3.8" and python_version < "4.0"
 pymdown-extensions==10.9 ; python_version >= "3.8" and python_version < "4.0"
 python-dateutil==2.9.0.post0 ; python_version >= "3.8" and python_version < "4.0"
+pyvisa==1.14.1 ; python_version >= "3.8" and python_version < "4.0"
 pyyaml==6.0.2 ; python_version >= "3.8" and python_version < "4.0"
 pyyaml-env-tag==0.1 ; python_version >= "3.8" and python_version < "4.0"
 requests==2.32.3 ; python_version >= "3.8" and python_version < "4.0"
@@ -47,6 +48,7 @@ six==1.16.0 ; python_version >= "3.8" and python_version < "4.0"
 soupsieve==2.6 ; python_version >= "3.8" and python_version < "4.0"
 symspellpy==6.7.8 ; python_version >= "3.8" and python_version < "4.0"
 termcolor==2.4.0 ; python_version >= "3.8" and python_version < "4.0"
+tm_devices==2.3.0 ; python_version >= "3.8" and python_version < "4.0"
 tomli==2.0.1 ; python_version >= "3.8" and python_version < "4.0"
 typing-extensions==4.12.2 ; python_version >= "3.8" and python_version < "3.11"
 urllib3==2.2.2 ; python_version >= "3.8" and python_version < "4.0"

examples/custom_filter.py

@@ -1,6 +1,6 @@
 """A script to connect to a scope, apply a custom filter to waveform data, and save to files."""
 
-from typing import Dict, List
+from typing import Dict
 
 from tm_data_types import AnalogWaveform, write_file
 
@@ -9,7 +9,9 @@
 addr = "192.168.0.1"  # Replace with the IP address of your instrument
 
 
-def custom_filter(previous_header: Dict[WaveformHeader], current_header: List[WaveformHeader]):
+def custom_filter(
+    previous_header: Dict[str, WaveformHeader], current_header: Dict[str, WaveformHeader]
+):
     """A custom criterion for deciding when to consider an acquisition for acceptance."""
     for key, cur in current_header.items():
         if key not in previous_header: