diff --git a/docs/basic_usage.md b/docs/basic_usage.md index 4833996..9d991c7 100644 --- a/docs/basic_usage.md +++ b/docs/basic_usage.md @@ -106,6 +106,17 @@ synchronization using start and `*OPC?`. # fmt: off --8<-- "src/tekhsi/tek_hsi_connect.py:any_horizontal_change" ``` +## Transmitting an acquisition made before connecting +There are cases in which you might want to connect and transfer waveforms that you have already acquired on the scope. + +To do this, we provide the [`force_sequence()`][tekhsi.TekHSIConnect.force_sequence] method. + +It is important to note that this is provided for the specific case when you establish the HSI connection AFTER acquiring the data. + +```python +# fmt: off +--8<-- "examples/force_sequence.py" +``` ## Mixing TekHSI and PyVISA diff --git a/examples/force_sequence.py b/examples/force_sequence.py new file mode 100644 index 0000000..e1ecae4 --- /dev/null +++ b/examples/force_sequence.py @@ -0,0 +1,16 @@ +"""A script demonstrating a way to use force_sequence to save a wfm locally.""" + +from tm_data_types import AnalogWaveform, write_file +from tekhsi import TekHSIConnect + +addr = "192.168.0.1" # Replace with the IP address of your instrument + +# Connect to instrument +with TekHSIConnect(f"{addr}:5000") as connect: + # Save a single acquisition that was made prior to connecting + connect.force_sequence() + with connect.access_data(): + wfm: AnalogWaveform = connect.get_data("ch1") + + # Save the waveform to a file + write_file(f"{wfm.source_name}.csv", wfm) diff --git a/src/tekhsi/tek_hsi_connect.py b/src/tekhsi/tek_hsi_connect.py index ca54b29..81695d9 100644 --- a/src/tekhsi/tek_hsi_connect.py +++ b/src/tekhsi/tek_hsi_connect.py @@ -489,11 +489,24 @@ def done_with_data(self) -> None: self._done_with_data_release_lock() def force_sequence(self) -> None: - """force_sequence asks the instrument to please give us access. + """Ask the instrument to give us access to the already acquired data. - to the current acquisition data. This is useful when connecting to a stopped instrument to + This is useful when connecting to a stopped instrument to get access to the currently available data. Otherwise, the API will wait until the next acquisition. + + Examples: + >>> from tm_data_types import AnalogWaveform, write_file + >>> from tekhsi import TekHSIConnect + + >>> addr = "192.168.0.1" # Replace with the IP address of your instrument + >>> with TekHSIConnect(f"{addr}:5000") as connect: + ... # Save a single acquisition that was made prior to connecting + ... connect.force_sequence() + ... with connect.access_data(): + ... wfm: AnalogWaveform = connect.get_data("ch1") + ... write_file(f"{wfm.source_name}.csv", wfm) + """ _logger.debug("force_sequence") request = ConnectRequest(name=self.clientname)