force_sequence example added

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
 

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)

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)