Added Streaming class and documentation (#62)

* Added get_streaming_latest_values()

* Updated run_streaming() to cast samples to int

* Updated base.py
 - Removed un-needed errors

* Added streaming.py example

* Added streaming examples

* Added streaming

Added the following:
 - Basic streaming example. No display till finish. - streaming.py
 - Streaming using threading - streaming_threading.py
 - Streaming with live plot - streaming_plot_animation.py

* Fixed display limit

* Removed redundant lines

* Update streaming_plot_animation.py

Restructured streaming class example

* Updated streaming_plot_animation.py
- Removed need for np_list & renamed  np_array

* Added streaming.py to package

* Edited streaming examples to use StreamingScope class

* Renamed and removed streaming examples

* Added docStrings and types to streaming.py functions

* Incorrect mkdocs plugin switched

* Fixed missing type annotation

* Fixed duplication of functions

* Added streaming to docs

* Fixed a potentially broken link

* Removed timebase from examples

---------

Co-authored-by: Jamackey <31521142+Jamackey@users.noreply.github.com>

Author: JamesPicoTech

build-tools/requirements.txt

@@ -6,7 +6,7 @@ matplotlib
 
 mkdocs >= 1.6
 mkdocstrings-python >= 1.16
-mkdocs-autorefs >= 1.4
+include-markdown-plugin >= 7.1.6
 
 build
 pytest

docs/docs/ref/ps6000a/channel.md

@@ -9,6 +9,7 @@
         - "channel"
         - "!trigger"
         - "!buffer"
+        - "!siggen"
         - "!_to_"
         - "!^_"
         show_root_toc_entry: false

docs/docs/ref/ps6000a/digital.md

@@ -4,6 +4,7 @@
         filters:
         - "!.*"
         - "digital"
+        - "!trigger"
         - "!^_"
         show_root_toc_entry: false
         summary: true

docs/docs/ref/ps6000a/trigger.md

@@ -4,6 +4,7 @@
         filters:
         - "!.*"
         - "trigger"
+        - "!siggen"
         - "!^_"
         show_root_toc_entry: false
         summary: true

docs/docs/ref/streaming.md

@@ -0,0 +1,15 @@
+# Streaming
+Streaming in a PicoScope is a great tool for monitoring a waveform for a long period of time
+without the delay between block captures. Though this method of capture is fairly limited in 
+sample rate and usability in comparison to a `block capture` and especially `rapid block capture`.
+
+## Using Streaming in pyPicoSDK
+Streaming is implemented in this package as a class to take advantage of the benefits offered by an object-oriented approach.
+For a quick start-up use the [example code](https://github.com/JamesPicoTech/pyPicoSDK/blob/main/examples/streaming) and alter it to your application.
+
+## Methods & Functions
+Below are the included public methods for streaming:
+::: pypicosdk.streaming.StreamingScope
+    options:
+        show_root_toc_entry: true
+        summary: true

docs/mkdocs.yml

@@ -21,6 +21,7 @@ nav:
       - ref/ps6000a/retrieval.md
     - General Conversions: ref/conversions.md
     - General Constants: ref/constants.md
+    - ref/streaming.md
   - Development: 
     - Changelog: dev/changelog.md
     - Current Support: dev/current.md

examples/streaming/streaming.py

@@ -0,0 +1,36 @@
+import pypicosdk as psdk
+from pypicosdk.streaming import StreamingScope
+from matplotlib import pyplot as plt
+import numpy as np
+
+# Capture configuration
+samples = int(1E9)
+streaming_samples = 250
+interval = 4
+unit = psdk.TIME_UNIT.NS
+pico_unit = psdk.PICO_TIME_UNIT.NS
+channel = psdk.CHANNEL.A
+
+def setup_scope():
+    scope = psdk.ps6000a()
+    scope.open_unit()
+    scope.set_siggen(frequency=100, pk2pk=1.6, wave_type=psdk.WAVEFORM.TRIANGLE)
+    scope.set_channel(channel=psdk.CHANNEL.A, range=psdk.RANGE.V1)
+    scope.set_simple_trigger(channel=psdk.CHANNEL.A, threshold_mv=0)
+    return scope
+
+def main():
+    scope = setup_scope()
+    stream = StreamingScope(scope)
+    stream.config_streaming(channel, samples, interval, pico_unit, max_buffer_size=None)
+
+    stream.run_streaming_for_samples(5000000)
+
+    scope.close_unit()
+
+    plt.plot(stream.buffer_array)
+    plt.show()
+
+
+if __name__ == '__main__':
+    main()

examples/streaming/streaming_live_plot.py

@@ -0,0 +1,75 @@
+"""
+Note: RACE CONDITION!
+The data retrieved from get_streaming data *NEEDS* to be 
+    larger than the captured data. 
+    If it's smaller, the live plot will lag behind the data. 
+    If it's larger, the streaming will ignore the empty buffers.
+
+Threading: 
+    The main streaming is handled in a thread while loop.
+    This is so that the matplotlib animation can be the main loop,
+    so the frame update interval doesn't control the retrieval of data
+    removing any race condition from the animation.
+"""
+
+
+import pypicosdk as psdk
+from pypicosdk.streaming import StreamingScope
+from matplotlib import pyplot as plt
+from matplotlib.animation import FuncAnimation
+import numpy as np
+import threading
+import time
+
+# Capture configuration
+samples = int(1E9)
+streaming_samples = 250
+interval = 20
+display_samples = 1000
+pico_unit = psdk.PICO_TIME_UNIT.NS
+channel = psdk.CHANNEL.A
+
+
+fig = plt.figure() 
+axis = plt.axes(xlim =(0, display_samples), 
+                ylim =(-32000, 32000)) 
+x = np.arange(display_samples)  # Predefined x-data of length 10
+line, = axis.plot(x, np.zeros_like(x), lw=2)  # Initialize with zeros
+
+
+def setup_scope():
+    scope = psdk.ps6000a()
+    scope.open_unit()
+    scope.set_siggen(frequency=1_000_000, pk2pk=1.6, wave_type=psdk.WAVEFORM.TRIANGLE)
+    scope.set_channel(channel=psdk.CHANNEL.A, range=psdk.RANGE.V1)
+    scope.set_simple_trigger(channel=psdk.CHANNEL.A, threshold_mv=0)
+    return scope
+
+def streaming_thread(stream:StreamingScope):
+    stream.run_streaming_while()
+
+def animate(frame, stream:StreamingScope):
+    data = stream.buffer_array
+    line.set_ydata(data)
+    return line,
+
+def main():
+    stop = False
+    scope = setup_scope()
+    stream = StreamingScope(scope)
+    stream.config_streaming(channel, samples, interval, pico_unit, display_samples)
+
+    th = threading.Thread(target=streaming_thread, args=[stream])
+    th.start()
+
+    anim = FuncAnimation(fig, animate, frames=500, fargs=(stream, ), interval=20, blit=True)
+    plt.show()
+
+    stream.stop()
+    th.join()
+
+    scope.close_unit()
+
+
+if __name__ == '__main__':
+    main()

pypicosdk/base.py

@@ -162,11 +162,6 @@ def _error_handler(self, status: int) -> None:
             # raise an exception as callers may poll until data is ready.
             if status == 407:  # PICO_WAITING_FOR_DATA_BUFFERS
                 return
-            # Streaming related status codes indicate no new data is ready.
-            # These should not be treated as fatal errors and simply signal
-            # the caller to try again later.
-            if status in [28672, 28673, 28674]:
-                return
             self.close_unit()
             raise PicoSDKException(error_code)
         return
@@ -716,8 +711,8 @@ def get_values_bulk_async(
         to_segment_index: int,
         down_sample_ratio: int,
         down_sample_ratio_mode: int,
-        lp_data_ready,
-        p_parameter,
+        lp_data_ready:ctypes.POINTER,
+        p_parameter:ctypes.POINTER,
     ) -> None:
         """Begin asynchronous retrieval of values from multiple segments.
 
@@ -1863,8 +1858,8 @@ def run_streaming(
             self.handle,
             ctypes.byref(c_sample_interval),
             time_units,
-            max_pre_trigger_samples,
-            max_post_trigger_samples,
+            int(max_pre_trigger_samples),
+            int(max_post_trigger_samples),
             auto_stop,
             ratio,
             ratio_mode,
@@ -1928,6 +1923,36 @@ def get_values(self, samples, start_index=0, segment=0, ratio=0, ratio_mode=RATI
         self.is_over_range()
         return total_samples.value
 
+    def get_streaming_latest_values(
+        self,
+        channel,
+        ratio_mode,
+        data_type
+    ):
+        info = PICO_STREAMING_DATA_INFO(
+            channel_ = channel,
+            mode_ = ratio_mode,
+            type_ = data_type,
+        )
+        trigger = PICO_STREAMING_DATA_TRIGGER_INFO()
+
+        status = self._call_attr_function(
+            "GetStreamingLatestValues",
+            self.handle,
+            ctypes.byref(info),
+            1,
+            ctypes.byref(trigger)
+        )
+        return {
+            'status': status,
+            'no of samples': info.noOfSamples_,
+            'Buffer index': info.bufferIndex_,
+            'start index': info.startIndex_,
+            'overflowed?': info.overflow_,
+            'triggered at': trigger.triggerAt_,
+            'triggered?': trigger.triggered_,
+            'auto stopped?': trigger.autoStop_,
+        }
 
     def is_over_range(self) -> list:
         """