pypicosdk v0.2.23 (#4)

* Added 6000a FFT example

* added ps6000a stop

* Fixed autotrigger for 6000A devices

* Close_unit returned none

* Added conversions to docs

* Added timebase conversions

* Added timebased enums

* Added hatch target to project.toml

* Upversioned to 0.2.23

Author: JamesPicoTech

README.md

@@ -33,6 +33,6 @@ Once tested, try an [example script from github](https://github.com/JamesPicoTec
 - [PicoScope Support (Compatibility)](https://jamespicotech.github.io/pyPicoSDK/dev/current)
 
 ## Version Control
-pyPicoSDK: 0.2.22
+pyPicoSDK: 0.2.23
 
-Docs: 0.1.3
+Docs: 0.1.4

docs/docs/index.md

@@ -33,6 +33,6 @@ Once tested, try an [example script from github](https://github.com/JamesPicoTec
 - [PicoScope Support (Compatibility)](https://jamespicotech.github.io/pyPicoSDK/dev/current)
 
 ## Version Control
-pyPicoSDK: 0.2.22
+pyPicoSDK: 0.2.23
 
-Docs: 0.1.3
+Docs: 0.1.4

docs/docs/ref/conversions.md

@@ -0,0 +1,26 @@
+# PicoScope conversions
+These functions are general functions to convert data to another format.
+This is particularly useful for converting ADC data to mV or calculating 
+the needed timebase for your PicoScope.
+
+As the conversions talk to the PicoScope to retrieve the resolution and ADC limits,
+the PicoScope needs to be initialized using `scope.open_unit()` followed by the conversion.
+
+## Example
+```
+>>> import pypicosdk as psdk
+>>> scope = psdk.ps6000a()
+>>> scope.open_unit(resolution=psdk.RESOLUTION._8BIT)
+>>> scope.mv_to_adc(100, channel_range=psdk.RANGE.V1)
+3251
+>>> scope.close_unit()
+```
+
+## Reference
+::: pypicosdk.pypicosdk.PicoScopeBase
+    options:
+        filters:
+        - ".*_to_.*"
+        #- "!^_[^_]"
+        show_root_toc_entry: false
+        summary: true

docs/mkdocs.yml

@@ -9,6 +9,7 @@ nav:
     - Introduction: ref/introduction.md
     - PicoScope 6000 (A) Specific Functions: ref/ps6000a.md
     - PicoScope 5000 (A) Specific Functions: ref/ps5000a.md
+    - General Conversions: ref/conversions.md
     - General Constants: ref/constants.md
   - Development: 
     - Changelog: dev/changelog.md

examples/example_6000a_fft.py

@@ -0,0 +1,81 @@
+##################################################################
+# FFT example for a PicoScope 6000E.
+#
+# Description:
+#   This will convert the voltage data to the frequency domain and
+#   display it in pyplot
+#
+# Requirements: 
+# - PicoScope 6000E
+# - Python packages:
+#   pip install matplotlib scipy numpy pypicosdk
+#
+# Setup:
+#   - Connect 6000E SigGen (AWG) to Channel A of the oscilloscope
+#     using a BNC cable or probe
+#
+##################################################################
+
+import pypicosdk as psdk
+from matplotlib import pyplot as plt
+import numpy as np
+from scipy.fft import fft, fftfreq
+from scipy.signal import windows
+
+# Setup variables
+timebase = 3
+samples = 5_000_000
+channel_a = psdk.CHANNEL.A
+range = psdk.RANGE.V1
+threshold = 0
+
+# SigGen variables
+frequency = 1_000_000
+pk2pk = 0.8
+wave_type = psdk.WAVEFORM.SQUARE
+
+# Initialise PicoScope 6000
+scope = psdk.ps6000a()
+scope.open_unit()
+
+# Setup siggen
+scope.set_siggen(frequency, pk2pk, wave_type)
+
+# Setup channels and trigger
+scope.set_channel(channel=channel_a, range=range)
+scope.set_simple_trigger(channel=channel_a, threshold_mv=threshold)
+
+# Run the block capture
+channel_buffer, time_axis = scope.run_simple_block_capture(timebase, samples)
+
+# Finish with PicoScope
+scope.close_unit()
+
+# Take out data (converting ns time axis to s)
+v = np.array(channel_buffer[channel_a])
+t = np.array(time_axis) * 1E-9
+
+# Get sample rate
+dt = t[1] - t[0]
+
+# Create a window and apply to data
+window = windows.hann(samples)
+v_windowed = v * window
+
+# Create fft from data
+V_f = fft(v_windowed)
+freqs = fftfreq(samples, dt)
+
+# Remove negative frequency data
+positive_freqs = freqs[:samples//2]
+amplitudes = np.abs(V_f[:samples//2])
+
+# Plot data to pyplot
+plt.figure(figsize=(10, 4))
+plt.plot(positive_freqs / 1e6, amplitudes)  # Convert Hz to MHz
+plt.xlabel("Frequency (MHz)")
+plt.ylabel("Amplitude (mV)")
+plt.title("FFT of Voltage Signal")
+plt.grid(True)
+plt.tight_layout()
+plt.show()

examples/example_6000a_timebase.py

@@ -0,0 +1,20 @@
+"""
+Example to figure out the correct timebase value for a specific interval.
+"""
+from pypicosdk import ps6000a, CHANNEL, RANGE, SAMPLE_RATE, TIME_UNIT
+
+# Variables
+interval_s = 10E-9 # 10 us
+
+# Open PicoScope 6000
+scope = ps6000a()
+scope.open_unit()
+
+# Setup channels to make sure sample interval is accurate
+scope.set_channel(CHANNEL.A, RANGE.V1)
+scope.set_channel(CHANNEL.C, RANGE.mV100)
+
+# Return suggested timebase and actual sample interval 
+print(scope.sample_rate_to_timebase(100, unit=SAMPLE_RATE.MSPS))
+print(scope.interval_to_timebase(0.001, unit=TIME_UNIT.US))
+print(scope.get_nearest_sampling_interval(1E-9))

pypicosdk/constants.py

@@ -265,4 +265,17 @@ class POWER_SOURCE:
     """
     SUPPLY_CONNECTED = 0x00000119
     SUPPLY_NOT_CONNECTED = 0x0000011A
-    USB3_0_DEVICE_NON_USB3_0_PORT= 0x0000011E
+    USB3_0_DEVICE_NON_USB3_0_PORT= 0x0000011E
+
+class SAMPLE_RATE(IntEnum):
+    SPS = 1
+    KSPS = 1_000
+    MSPS = 1_000_000
+    GSPS = 1_000_000_000
+
+class TIME_UNIT(IntEnum):
+    PS = 1_000_000_000_000
+    NS = 1_000_000_000
+    US = 1_000_000
+    MS = 1_000
+    S = 1

pypicosdk/pypicosdk.py

@@ -123,7 +123,7 @@ def _open_unit(self, serial_number:int=None, resolution:RESOLUTION=0) -> None:
         )
         self.resolution = resolution
 
-    def close_unit(self) -> int:
+    def close_unit(self) -> None:
         """
         Closes the PicoScope device and releases the hardware handle.
 
@@ -135,6 +135,15 @@ def close_unit(self) -> int:
 
         self._get_attr_function('CloseUnit')(self.handle)
 
+    def stop(self) -> None: 
+        """
+        This function stops the scope device from sampling data
+        """
+        self._call_attr_function(
+            'Stop',
+            self.handle
+        )
+
     def is_ready(self) -> None:
         """
         Blocks execution until the PicoScope device is ready.
@@ -204,7 +213,7 @@ def _get_enabled_channel_flags(self) -> int:
             enabled_channel_byte += 2**channel
         return enabled_channel_byte
 
-    def get_nearest_sampling_interval(self, sample_rate:float) -> dict:
+    def get_nearest_sampling_interval(self, interval_s:float) -> dict:
         """
         This function returns the nearest possible sample interval to the requested 
         sample interval. It does not change the configuration of the oscilloscope.
@@ -213,18 +222,18 @@ def get_nearest_sampling_interval(self, sample_rate:float) -> dict:
         increase sample interval.
 
         Args:
-            sample_rate (float): Time value in seconds (s) you would like to obtain.
+            interval_s (float): Time value in seconds (s) you would like to obtain.
 
         Returns:
-            dict: Dictionary of suggested timebase and actual sample interval.
+            dict: Dictionary of suggested timebase and actual sample interval in seconds (s).
         """
         timebase = ctypes.c_uint32()
         time_interval = ctypes.c_double()
         self._call_attr_function(
             'NearestSampleIntervalStateless',
             self.handle,
             self._get_enabled_channel_flags(),
-            ctypes.c_double(sample_rate),
+            ctypes.c_double(interval_s),
             self.resolution,
             ctypes.byref(timebase),
             ctypes.byref(time_interval),
@@ -293,6 +302,39 @@ def _get_timebase_2(self, timebase: int, samples: int, segment:int=0):
         return {"Interval(ns)": time_interval_ns.value, 
                 "Samples":          max_samples.value}
 
+    def sample_rate_to_timebase(self, sample_rate:float, unit=SAMPLE_RATE.MSPS):
+        """
+        Converts sample rate to a PicoScope timebase value based on the 
+        attached PicoScope.
+
+        This function will return the closest possible timebase.
+        Use `get_nearest_sample_interval(interval_s)` to get the full timebase and 
+        actual interval achieved.
+
+        Args:
+            sample_rate (int): Desired sample rate 
+            unit (SAMPLE_RATE): unit of sample rate.
+        """
+        interval_s = 1 / (sample_rate * unit)
+        
+        return self.get_nearest_sampling_interval(interval_s)["timebase"]
+    
+    def interval_to_timebase(self, interval:float, unit=TIME_UNIT.S):
+        """
+        Converts a time interval (between samples) into a PicoScope timebase 
+        value based on the attached PicoScope.
+
+        This function will return the closest possible timebase.
+        Use `get_nearest_sample_interval(interval_s)` to get the full timebase and 
+        actual interval achieved.
+
+        Args:
+            interval (float): Desired time interval between samples
+            unit (TIME_UNIT, optional): Time unit of interval.
+        """
+        interval_s = interval / unit
+        return self.get_nearest_sampling_interval(interval_s)["timebase"]
+    
     def _get_adc_limits(self) -> tuple:
         """
         Gets the ADC limits for specified devices.
@@ -442,7 +484,7 @@ def _set_channel(self, channel, range, enabled=True, coupling=COUPLING.DC, offse
         )
         return self._error_handler(status)
 
-    def set_simple_trigger(self, channel, threshold_mv, enable=True, direction=TRIGGER_DIR.RISING, delay=0, auto_trigger_ms=3000):
+    def set_simple_trigger(self, channel, threshold_mv, enable=True, direction=TRIGGER_DIR.RISING, delay=0, auto_trigger=0):
         """
         Sets up a simple trigger from a specified channel and threshold in mV
 
@@ -452,7 +494,7 @@ def set_simple_trigger(self, channel, threshold_mv, enable=True, direction=TRIGG
             enable (bool, optional): Enables or disables the trigger. 
             direction (TRIGGER_DIR, optional): Trigger direction (e.g., TRIGGER_DIR.RISING, TRIGGER_DIR.FALLING). 
             delay (int, optional): Delay in samples after the trigger condition is met before starting capture. 
-            auto_trigger_ms (int, optional): Timeout in milliseconds after which data capture proceeds even if no trigger occurs. 
+            auto_trigger (int, optional): Timeout after which data capture proceeds even if no trigger occurs. 
         """
         threshold_adc = self.mv_to_adc(threshold_mv, self.range[channel])
         self._call_attr_function(
@@ -463,7 +505,7 @@ def set_simple_trigger(self, channel, threshold_mv, enable=True, direction=TRIGG
             threshold_adc,
             direction,
             delay,
-            auto_trigger_ms
+            auto_trigger
         )
 
     def set_data_buffer_for_enabled_channels():
@@ -747,6 +789,21 @@ def set_channel(self, channel:CHANNEL, range:RANGE, enabled=True, coupling:COUPL
             super()._set_channel_on(channel, range, coupling, offset, bandwidth)
         else:
             super()._set_channel_off(channel)
+
+    def set_simple_trigger(self, channel, threshold_mv, enable=True, direction=TRIGGER_DIR.RISING, delay=0, auto_trigger_ms=5_000):
+        """
+        Sets up a simple trigger from a specified channel and threshold in mV
+
+        Args:
+            channel (int): The input channel to apply the trigger to.
+            threshold_mv (float): Trigger threshold level in millivolts.
+            enable (bool, optional): Enables or disables the trigger. 
+            direction (TRIGGER_DIR, optional): Trigger direction (e.g., TRIGGER_DIR.RISING, TRIGGER_DIR.FALLING). 
+            delay (int, optional): Delay in samples after the trigger condition is met before starting capture. 
+            auto_trigger_ms (int, optional): Timeout in milliseconds after which data capture proceeds even if no trigger occurs. 
+        """
+        auto_trigger_us = auto_trigger_ms * 1000
+        return super().set_simple_trigger(channel, threshold_mv, enable, direction, delay, auto_trigger_us)
 
     def set_data_buffer(self, channel:CHANNEL, samples:int, segment:int=0, datatype:DATA_TYPE=DATA_TYPE.INT16_T, 
                         ratio_mode:RATIO_MODE=RATIO_MODE.RAW, action:ACTION=ACTION.CLEAR_ALL | ACTION.ADD) -> ctypes.Array:
@@ -870,6 +927,20 @@ def set_channel(self, channel, range, enabled=True, coupling=COUPLING.DC, offset
     def get_timebase(self, timebase, samples, segment=0):
         return super()._get_timebase_2(timebase, samples, segment)
 
+    def set_simple_trigger(self, channel, threshold_mv, enable=True, direction=TRIGGER_DIR.RISING, delay=0, auto_trigger_ms=5000):
+        """
+        Sets up a simple trigger from a specified channel and threshold in mV
+
+        Args:
+            channel (int): The input channel to apply the trigger to.
+            threshold_mv (float): Trigger threshold level in millivolts.
+            enable (bool, optional): Enables or disables the trigger. 
+            direction (TRIGGER_DIR, optional): Trigger direction (e.g., TRIGGER_DIR.RISING, TRIGGER_DIR.FALLING). 
+            delay (int, optional): Delay in samples after the trigger condition is met before starting capture. 
+            auto_trigger_ms (int, optional): Timeout in milliseconds after which data capture proceeds even if no trigger occurs. 
+        """
+        return super().set_simple_trigger(channel, threshold_mv, enable, direction, delay, auto_trigger_ms)
+    
     def set_data_buffer(self, channel, samples, segment=0, ratio_mode=0):
         return super()._set_data_buffer_ps5000a(channel, samples, segment, ratio_mode)
 

pypicosdk/version.py

@@ -1 +1 @@
-VERSION = "0.2.22"
+VERSION = "0.2.23"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypicosdk"
-version = "0.2.22"
+version = "0.2.23"
 description = "Modern Python wrapper for PicoSDK"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -31,3 +31,6 @@ pypicosdk = ["lib/**/*.dll"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["pypicosdk"]