Updated Documentation to include usage of PyVISA and tm_devices along with TekHSI.

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 `PyVISA` and `tm_devices`.
+- Updated documentation requirements.
+
 ---
 
 ## v0.1.1 (2024-09-11)

docs/additional_examples_and_pseudo_code/access_data.py

@@ -0,0 +1,10 @@
+from tm_data_types import AnalogWaveform
+
+from tekhsi import TekHSIConnect
+
+with TekHSIConnect("192.168.0.1:5000") as connection:
+    # Request access to data
+    with connection.access_data():
+        # Access granted
+        ch1: AnalogWaveform = connection.get_data("ch1")
+        ch3: AnalogWaveform = connection.get_data("ch3")

docs/additional_examples_and_pseudo_code/acq_filters.py

@@ -0,0 +1,31 @@
+from typing import Dict
+
+from tekhsi import WaveformHeader
+
+
+def any_horizontal_change(
+    previous_header: Dict[str, WaveformHeader],
+    current_header: Dict[str, WaveformHeader],
+) -> bool:
+    """Acq acceptance filter that accepts only acqs with changes to horizontal settings.
+
+    Args:
+        previous_header (dict[str, WaveformHeader]): Previous header dictionary.
+        current_header (dict[str, WaveformHeader]): Current header dictionary.
+
+    Returns:
+        True if the acquisition is accepted, False otherwise.
+    """
+    for key, cur in current_header.items():
+        if key not in previous_header:
+            return True
+        prev = previous_header[key]
+        if prev is None and cur is not None:
+            return True
+        if prev is not None and (
+            prev.noofsamples != cur.noofsamples
+            or prev.horizontalspacing != cur.horizontalspacing
+            or prev.horizontalzeroindex != cur.horizontalzeroindex
+        ):
+            return True
+    return False

docs/additional_examples_and_pseudo_code/active_symbols.py

@@ -0,0 +1,4 @@
+from tekhsi import TekHSIConnect
+
+with TekHSIConnect("192.168.0.1:5000") as connection:
+    print(connection.activesymbols)

docs/additional_examples_and_pseudo_code/analog_waveform_usage.py

@@ -0,0 +1,25 @@
+import matplotlib.pyplot as plt
+
+from tm_data_types import AnalogWaveform
+
+from tekhsi import TekHSIConnect
+
+with TekHSIConnect("192.168.0.1:5000") as connection:
+    # Get one data set to setup plot
+    with connection.access_data():
+        waveform: AnalogWaveform = connection.get_data("ch1")
+
+    # Data converted into vertical units
+    # This is the usual way to access the data
+    vd = waveform.normalized_vertical_values
+
+    # Horizontal Times - returns an array of times
+    # that corresponds to the time at each index in
+    # vertical array
+    hd = waveform.normalized_horizontal_values
+
+    # Simple Plot Example
+    _, ax = plt.subplots()
+    ax.plot(hd, vd)
+    ax.set(xlabel=waveform.x_axis_units, ylabel=waveform.y_axis_units, title="Simple Plot")
+    plt.show()

docs/additional_examples_and_pseudo_code/blocking_methods.py

@@ -0,0 +1,10 @@
+from tm_data_types import AnalogWaveform, DigitalWaveform, IQWaveform
+
+from tekhsi import AcqWaitOn, TekHSIConnect
+
+with TekHSIConnect("192.168.0.1:5000") as connection:
+    with connection.access_data(AcqWaitOn.NewData):
+        ch1: AnalogWaveform = connection.get_data("ch1")
+        ch3: AnalogWaveform = connection.get_data("ch3")
+        ch1_iq: IQWaveform = connection.get_data("ch1_iq")
+        ch4_dall: DigitalWaveform = connection.get_data("ch4_DAll")

docs/additional_examples_and_pseudo_code/digital_waveform_usage.py

@@ -0,0 +1,25 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+from tm_data_types import DigitalWaveform
+
+from tekhsi import TekHSIConnect
+
+with TekHSIConnect("192.168.0.1:5000") as connection:
+    # Get one data set to setup plot
+    with connection.access_data():
+        waveform: DigitalWaveform = connection.get_data("ch4_DAll")
+
+    # Digital retrieval of bit 3 in the digital array
+    vd = waveform.get_nth_bitstream(3).astype(np.float32)
+
+    # Horizontal Times - returns an array of times
+    # that corresponds to the time at each index in
+    # vertical array
+    hd = waveform.normalized_horizontal_values
+
+    # Simple Plot Example
+    _, ax = plt.subplots()
+    ax.plot(hd, vd)
+    ax.set(xlabel=waveform.x_axis_units, ylabel=waveform.y_axis_units, title="Simple Plot")
+    plt.show()

docs/additional_examples_and_pseudo_code/iq_waveform_usage.py

@@ -0,0 +1,24 @@
+import matplotlib.pyplot as plt
+
+from tm_data_types import IQWaveform
+
+from tekhsi import TekHSIConnect
+
+with TekHSIConnect("169.254.3.12:5000") as connection:
+    # Get one data set to setup plot
+    with connection.access_data():
+        waveform: IQWaveform = connection.get_data("ch1_iq")
+
+    # IQ Data Access (Complex Array)
+    iq_data = waveform.normalized_vertical_values
+
+    # Simple Plot Example
+    _, ax = plt.subplots()
+    ax.specgram(
+        iq_data,
+        NFFT=int(waveform.meta_info.iq_fft_length),
+        Fc=waveform.meta_info.iq_center_frequency,
+        Fs=waveform.meta_info.iq_sample_rate,
+    )
+    ax.set_title("Spectrogram")
+    plt.show()

docs/additional_examples_and_pseudo_code/pyvisa_usage.py

@@ -0,0 +1,37 @@
+"""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
+visa_scope.close()

docs/additional_examples_and_pseudo_code/supported_data_types.py

@@ -0,0 +1,24 @@
+import numpy as np
+
+from tm_data_types import AnalogWaveform, DigitalWaveform, IQWaveform, read_file
+
+data = read_file("Test.wfm")
+
+# currently wfm files can be of three flavors
+# AnalogWaveform, IQWaveform, or DigitalWaveform
+# each can be explicitly checked for as follows.
+if isinstance(data, AnalogWaveform):
+    wfm: AnalogWaveform = data
+    # returns the sampled values in vertical units
+    vd = wfm.normalized_vertical_values
+    y_axis = wfm.y_axis_units
+elif isinstance(data, IQWaveform):
+    wfm: IQWaveform = data
+    # Returns the real portion of the iq data for plotting.
+    # Note that 'normalized_vertical_values' is a complex array.
+    vd = wfm.normalized_vertical_values.real
+    y_axis = wfm.y_axis_units
+elif isinstance(data, DigitalWaveform):
+    wfm: DigitalWaveform = data
+    # Returns bit 3 as a float stream for plotting.
+    vd = wfm.get_nth_bitstream(3).astype(np.float32)

docs/additional_examples_and_pseudo_code/tm_devices_usage.py

@@ -0,0 +1,32 @@
+"""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)
+    # Make the waveform display OFF
+    scope.commands.display.waveform.write("OFF")
+    # Set the Horizontal mode to Manual
+    scope.commands.horizontal.mode.write("OFF")
+    # Set the horizontal Record Length
+    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}")
+
+    # Make the waveform display ON
+    scope.commands.display.waveform.write("ON")

docs/additional_examples_and_pseudo_code/wait_on_new_data.py

@@ -0,0 +1,5 @@
+from tekhsi import AcqWaitOn, TekHSIConnect
+
+with TekHSIConnect("192.168.0.1:5000") as connection:
+    with connection.access_data(AcqWaitOn.NewData):
+        ...

docs/additional_examples_and_pseudo_code/wait_on_next_acq.py

@@ -0,0 +1,5 @@
+from tekhsi import AcqWaitOn, TekHSIConnect
+
+with TekHSIConnect("192.168.0.1:5000") as connection:
+    with connection.access_data(AcqWaitOn.NextAcq):
+        ...

docs/additional_examples_and_pseudo_code/wait_on_time.py

@@ -0,0 +1,5 @@
+from tekhsi import AcqWaitOn, TekHSIConnect
+
+with TekHSIConnect("192.168.0.1:5000") as connection:
+    with connection.access_data(AcqWaitOn.Time, after=0.5):
+        ...