PyQa40x-i2c 0.1.2__tar.gz → 0.2.0__tar.gz

{pyqa40x_i2c-0.1.2 → pyqa40x_i2c-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyQa40x-i2c
-Version: 0.1.2
+Version: 0.2.0
 Summary: A Python library for the QA40x audio analyser (int2code fork)
 Maintainer-email: Hubert Stepniewski <hubert.stepniewski@int2code.com>
 License: MIT License

{pyqa40x_i2c-0.1.2 → pyqa40x_i2c-0.2.0}/RELEASE_NOTES.md

@@ -1,3 +1,7 @@
+### 0.2.0
+
+[MINOR] Add endless audio capturing 
+
 ### 0.1.2
 
 [PATCH] Fix usb teardown deadlock.

{pyqa40x_i2c-0.1.2 → pyqa40x_i2c-0.2.0}/src/PyQa40x/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.2'
-__version_tuple__ = version_tuple = (0, 1, 2)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
-__commit_id__ = commit_id = 'g1bd064f6c'
+__commit_id__ = commit_id = 'g6a5ba3357'

{pyqa40x_i2c-0.1.2 → pyqa40x_i2c-0.2.0}/src/PyQa40x/analyzer.py

@@ -1,21 +1,24 @@
+import threading
+import logging
+
 import numpy as np
 import usb1  # pip install libusb1
-import struct
 import atexit
-import scipy.signal  # pip install scipy
 
 from PyQa40x.registers import Registers
 from PyQa40x.control import Control
 from PyQa40x.stream import Stream
-from PyQa40x.wave_sine import Wave
-from PyQa40x.fft_processor import FFTProcessor
-from PyQa40x.sig_proc import SigProc
 from PyQa40x.helpers import *
 from PyQa40x.analyzer_params import AnalyzerParams
 from PyQa40x.bluetooth import BluetoothAudioDevice
 
+logger = logging.getLogger(__name__)
+
 
 class Analyzer:
+
+    CAPTURE_CHUNK_BYTES = Stream.TRANSFER_BYTES  # bytes per USB transfer
+
     def __init__(self):
         """
         Initializes the Analyzer class.
@@ -29,6 +32,9 @@ class Analyzer:
         self.cal_data: dict | None = None
         self.bt_device: BluetoothAudioDevice | None = None
         self._cleanup_registered = False
+        self._capturing: bool = False
+        self._dac_writer: threading.Thread | None = None  # set in start_capture()
+        self._dac_writer_error: Exception | None = None  # error from DAC writer thread
 
     def init(
         self,
@@ -139,126 +145,137 @@ class Analyzer:
         except Exception as e:
             print(f"An error occurred during cleanup: {e}")
 
-    def send_receive(self, left_wave: Wave, right_wave: Wave) -> tuple[Wave, Wave]:
+    @staticmethod
+    def list_audio_devices_by_sample_rate(target_sample_rate: int):
+        """
+        List all available audio devices that support a specific sample rate
+        by calling the method from BluetoothAudioDevice.
         """
-        Sends DAC data to the device and receives ADC data.
+        BluetoothAudioDevice.list_audio_devices_by_sample_rate(target_sample_rate)
+
+    def _convert_adc_bytes_to_volts(
+        self, raw_bytes: bytearray, n_samples: int
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Convert interleaved int32 ADC bytes to calibrated Volt arrays.
 
         Args:
-            left_wave (Wave): Wave instance with left channel DAC data.
-            right_wave (Wave): Wave instance with right channel DAC data.
+            raw_bytes (bytearray): Interleaved little-endian int32 stereo ADC data.
+            n_samples (int): Samples per channel to return.
 
         Returns:
-            tuple[Wave, Wave]: Tuple containing Wave instances with left and right channel ADC data.
+            tuple[np.ndarray, np.ndarray]: (left_volts, right_volts), float64.
         """
-        left_dac_data = left_wave.get_buffer()
-        right_dac_data = right_wave.get_buffer()
+        # Reads the raw bytes and treat every 4 bytes as one signed 32‑bit integer
+        # [L0, R0, L1, R1, L2, R2, …]
+        interleaved = np.frombuffer(raw_bytes, dtype=np.int32)
 
-        # On QA402 and QA403, outputs need to be swapped
-        left_dac_data, right_dac_data = right_dac_data, left_dac_data
+        # Split interleaved int32 array into left and right channels
+        left_int = interleaved[0::2][:n_samples]
+        right_int = interleaved[1::2][:n_samples]
 
-        left_peak = np.max(left_dac_data)
+        # Convert int32 → float64 and normalise to range +-1
+        max_int_value = 2**31 - 1
+        left_f = left_int.astype(np.float64) / max_int_value
+        right_f = right_int.astype(np.float64) / max_int_value
 
-        # Get calibration factors for outgoing data
-        cal_dac_left, cal_dac_right = self.control.get_dac_cal(
-            self.cal_data, self.params.max_output_level
+        # Factor for computing the voltage that corresponds to digital full scale
+        dbfs_correction = 10 ** ((self.params.max_input_level - 6) / 20)
+        # Stored QA40x calibration factors for the current input level.
+        cal_adc_left, cal_adc_right = self.control.get_adc_cal(
+            self.cal_data, self.params.max_input_level
         )
 
-        # Convert to dBFS. Note the 3 dB adjustment--dBFS is peak, while dBV is RMS
-        dac_dbfs_adjustment = 10 ** -((self.params.max_output_level + 3) / 20)
-
-        # Apply calibration and dBFS scaling
-        left_dac_data = left_dac_data * dac_dbfs_adjustment * cal_dac_left
-        right_dac_data = right_dac_data * dac_dbfs_adjustment * cal_dac_right
-
-        # Convert incoming doubles to float
-        left_dac_data_float = left_dac_data.astype(np.float32)
-        right_dac_data_float = right_dac_data.astype(np.float32)
-
-        # Interleave the left and right channels
-        interleaved_dac_data = np.empty(
-            (left_dac_data_float.size + right_dac_data_float.size,), dtype=np.float32
-        )
-        interleaved_dac_data[0::2] = left_dac_data_float
-        interleaved_dac_data[1::2] = right_dac_data_float
+        # Apply ADC calibration and dBFS → Volts conversion
+        left_volts = left_f * cal_adc_left * dbfs_correction
+        right_volts = right_f * cal_adc_right * dbfs_correction
 
-        # Convert to bytes, multiplying by max int value
-        max_int_value = 2**31 - 1
-        interleaved_dac_data = (interleaved_dac_data * max_int_value).astype(np.int32)
+        return left_volts, right_volts
 
-        # Pack the data into chunks of 16k bytes
-        chunk_size = 16384  # 16k bytes
-        num_ints_per_chunk = chunk_size // 4  # 32-bit ints, so 4 bytes per int
-        total_chunks = len(interleaved_dac_data) // num_ints_per_chunk
+    def start_capture(self) -> None:
+        """
+        Starts a continuous capture of ADC data in a background thread.
+        The captured data can be retrieved later using the `read_capture` method.
+        """
+        if self._capturing:
+            raise RuntimeError("Capture is already in progress.")
 
+        self._capturing = True
+        self._dac_writer_error = None
         self.stream.start()
+        self._dac_writer = threading.Thread(
+            target=self._dac_writer_loop, name="qa40x-dac-writer-thread", daemon=True
+        )
+        self._dac_writer.start()
+
+    def _dac_writer_loop(self) -> None:
+        """Continuously submit zero-DAC / ADC-read transfer pairs while capturing."""
+        while self._capturing and self.stream.running:
+            try:
+                self.stream.write_zeros(self.CAPTURE_CHUNK_BYTES)
+            except Exception as exc:  # pylint: disable=broad-except
+                # Racing with stop() is expected; a real failure while we still
+                # expect to run is recorded in the post-loop reconciliation below.
+                if self._capturing and self.stream.running:
+                    self._dac_writer_error = exc
+                    logger.error("DAC writer failed; stopping capture.", exc_info=exc)
+                break
+
+        # If the loop ended but we never asked to stop, the stream halted
+        # underneath us (error or ADC overflow): record it and clear _capturing so
+        # the analyzer isn't wedged "capturing" behind a dead writer thread.
+        if self._capturing:
+            self._capturing = False
+            if self._dac_writer_error is None:
+                self._dac_writer_error = self.stream.overflow_error or RuntimeError(
+                    "Stream stopped unexpectedly during capture."
+                )
+
+    def read_capture(self, n_samples: int) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Return the next `n_samples` samples per channel as Volt arrays.
 
-        # Play wave on Bluetooth if available
-        bt_thread = None
-        if self.bt_device:
-            # Play both left and right waves on Bluetooth
-            bt_thread = self.bt_device.play_wave_background(left_wave, right_wave)
-
-        try:
-            for i in range(total_chunks):
-                chunk = interleaved_dac_data[
-                    i * num_ints_per_chunk : (i + 1) * num_ints_per_chunk
-                ]
-                buffer = struct.pack("<%di" % len(chunk), *chunk)
-                self.stream.write(buffer)
-        finally:
-            self.stream.stop()
-
-        # Collect ADC data. This is bytes
-        interleaved_adc_data = self.stream.collect_remaining_adc_data()
-
-        # Wait for the Bluetooth thread to finish after processing
-        if bt_thread:
-            bt_thread.join()
-
-        # Convert collected ADC data back to int
-        interleaved_adc_data = np.frombuffer(interleaved_adc_data, dtype=np.int32)
-
-        # Separate interleaved ADC data into left and right channels. This is int
-        left_adc_data_int = interleaved_adc_data[0::2]
-        right_adc_data_int = interleaved_adc_data[1::2]
+        Blocks until the samples are available. Consecutive calls return
+        contiguous audio (no gap) because the stream is never stopped between
+        reads. Returns fewer than `n_samples` only if the capture is stopping.
 
-        # Convert left and right channels back to double
-        left_adc_data = left_adc_data_int.astype(np.float64) / max_int_value
-        right_adc_data = right_adc_data_int.astype(np.float64) / max_int_value
+        Args:
+            n_samples (int): Samples per channel to return.
 
-        # Get calibration factors for incoming data
-        cal_adc_left, cal_adc_right = self.control.get_adc_cal(
-            self.cal_data, self.params.max_input_level
-        )
+        Returns:
+            tuple[np.ndarray, np.ndarray]: (left_volts, right_volts), float64.
 
-        # Convert from dBFS to dBV. Note the 6 dB factor--the ADC is differential
-        adc_dbfs_correction = 10 ** ((self.params.max_input_level - 6) / 20)
+        Raises:
+            RuntimeError: If the DAC writer thread failed during capture.
+            AdcOverflowError: If capture data was not read fast enough.
+        """
+        if self._dac_writer_error is not None:
+            raise RuntimeError(
+                "DAC writer thread encountered an error during capture."
+            ) from self._dac_writer_error
 
-        # Apply calibration and dBFS scaling
-        left_adc_data = left_adc_data * cal_adc_left * adc_dbfs_correction
-        right_adc_data = right_adc_data * cal_adc_right * adc_dbfs_correction
+        need_bytes = n_samples * 8  # 2 channels x int32
 
-        # Ensure the buffer matches the expected shape. Is this needed?
-        expected_shape = (
-            self.params.pre_buf + self.params.fft_size + self.params.post_buf,
+        raw = self.stream.consume_adc(
+            need_bytes, should_keep_waiting=lambda: self._capturing
         )
-        if left_adc_data.shape[0] != expected_shape[0]:
-            left_adc_data = np.resize(left_adc_data, expected_shape)
-        if right_adc_data.shape[0] != expected_shape[0]:
-            right_adc_data = np.resize(right_adc_data, expected_shape)
-
-        # Create instances of Wave with the full buffers
-        left_wave = Wave(self.params)
-        right_wave = Wave(self.params)
-        left_wave.set_buffer(left_adc_data)
-        right_wave.set_buffer(right_adc_data)
+        got_samples = len(raw) // 8
+        return self._convert_adc_bytes_to_volts(raw, got_samples)
 
-        return left_wave, right_wave
+    def stop_capture(self) -> None:
+        """
+        Stop the continuous capture: end the feeder thread and stop the stream.
 
-    @staticmethod
-    def list_audio_devices_by_sample_rate(target_sample_rate: int):
-        """List all available audio devices that support a specific sample rate by calling the method from BluetoothAudioDevice."""
-        BluetoothAudioDevice.list_audio_devices_by_sample_rate(target_sample_rate)
+        Order matters: clearing `_capturing` and stopping the stream releases a
+        dac writer blocked on the dacQueue (stop() cancels transfers and drains the
+        queue), after which the dac writer observes `_capturing == False` and exits.
+        """
+        if not self._capturing:
+            return
+        self._capturing = False
+        self.stream.stop()
+        if self._dac_writer is not None:
+            self._dac_writer.join(timeout=5.0)
 
     def capture(self, total_samples: int) -> tuple[np.ndarray, np.ndarray]:
         """
@@ -285,51 +302,10 @@ class Analyzer:
                 two float64 arrays each of length ``total_samples``, values
                 in Volts (calibrated, same scale as ``send_receive()``).
         """
-        chunk_bytes = 16384  # 16 kB per USB transfer
-        bytes_per_stereo_sample = 8  # 2 × int32
-        need_bytes = total_samples * bytes_per_stereo_sample
-
-        # Number of DAC write / ADC read pairs needed to cover need_bytes.
-        # Each pair transfers chunk_bytes ADC bytes.
-        n_chunks = -(-need_bytes // chunk_bytes)  # ceiling division
-
-        max_int_value = 2**31 - 1
-
-        # -- single stream start ------------------------------------------------
-        self.stream.start()
+        # A fixed-length capture is just a continuous capture read once: start
+        # the gapless stream, read exactly total_samples, then stop.
+        self.start_capture()
         try:
-            # Submit all zero-DAC / ADC-read pairs up front so the USB host
-            # controller can pipeline them; no stop/restart in the middle.
-            for _ in range(n_chunks):
-                self.stream.write_zeros(chunk_bytes)
-
-            # Block until we have exactly the bytes we need
-            raw_bytes = self.stream.collect_adc_exact(need_bytes)
+            return self.read_capture(total_samples)
         finally:
-            self.stream.stop()
-        # -- stream stopped -----------------------------------------------------
-
-        # Deserialise interleaved int32 ADC data
-        interleaved = np.frombuffer(raw_bytes, dtype=np.int32)
-
-        left_int = interleaved[0::2]
-        right_int = interleaved[1::2]
-
-        # Trim to exact length (collect_adc_exact already trims, but be safe)
-        left_int = left_int[:total_samples]
-        right_int = right_int[:total_samples]
-
-        # Convert int32 → float64 in the range ±1
-        left_f = left_int.astype(np.float64) / max_int_value
-        right_f = right_int.astype(np.float64) / max_int_value
-
-        # Apply ADC calibration and dBFS → Volts conversion
-        cal_adc_left, cal_adc_right = self.control.get_adc_cal(
-            self.cal_data, self.params.max_input_level
-        )
-        adc_dbfs_correction = 10 ** ((self.params.max_input_level - 6) / 20)
-
-        left_volts = left_f * cal_adc_left * adc_dbfs_correction
-        right_volts = right_f * cal_adc_right * adc_dbfs_correction
-
-        return left_volts, right_volts
+            self.stop_capture()

pyqa40x_i2c-0.2.0/src/PyQa40x/stream.py

@@ -0,0 +1,253 @@
+import threading
+import queue
+import usb1
+import logging
+from typing import Callable
+
+from PyQa40x.registers import Registers
+
+logger = logging.getLogger(__name__)
+
+
+class AdcOverflowError(RuntimeError):
+    """
+    Raised when the ADC receive buffer exceeds its high-water mark.
+
+    The capture pipeline requires the consumer to read captured data
+    continuously (see ``consume_adc``).  If the consumer falls behind, the
+    receive buffer grows without bound toward OOM.  Rather than leak memory,
+    the stream treats this as a hard error: the worker thread latches it and
+    ``consume_adc`` re-raises it on the consumer's thread.
+    """
+
+
+class Stream:
+    """
+    Class to manage buffer streaming, with event worker thread.
+    """
+
+    TRANSFER_TIMEOUT_MS = 1000  # Timeout for USB transfers in milliseconds
+    TRANSFER_BYTES = 16384  # 16 kB per USB bulk transfer (hardware chunk size)
+    # cap on unread ADC data before overflow
+    MAX_BUFFERED_BYTES = 256 * 1024 * 1024
+
+    def __init__(
+        self,
+        context: usb1.USBContext,
+        device: usb1.USBDeviceHandle,
+        registers: Registers,
+    ) -> None:
+        """
+        Initialize the Stream.
+
+        Args:
+            context (usb1.USBContext): The USB context.
+            device (usb1.USBDeviceHandle): The USB device handle.
+            registers (Registers): The Registers instance for control writes.
+        """
+        self.context = context
+        self.device = device
+        self.registers = registers
+        self.endpoint_read = usb1.ENDPOINT_IN | 0x02  # EP2 in
+        self.endpoint_write = usb1.ENDPOINT_OUT | 0x02  # EP2 out
+        self.dacQueue = queue.Queue(
+            maxsize=5
+        )  # Max. 5 overlapping buffers in flight, block on more
+        self.adcQueue = queue.Queue()  # Unlimited queue for received data buffers
+        self.transfer_helper = usb1.USBTransferHelper()  # Use the callback dispatcher
+        # Handle COMPLETED transfers normally; also handle ERROR/TIMED_OUT/CANCELLED
+        # so the queues are always drained and dacQueue.put() never deadlocks.
+        for status in (
+            usb1.TRANSFER_COMPLETED,
+            usb1.TRANSFER_ERROR,
+            usb1.TRANSFER_TIMED_OUT,
+            usb1.TRANSFER_CANCELLED,
+            usb1.TRANSFER_STALL,
+            usb1.TRANSFER_NO_DEVICE,
+            usb1.TRANSFER_OVERFLOW,
+        ):
+            self.transfer_helper.setEventCallback(status, self.callback)
+        self.thread: threading.Thread | None = None
+        self.running = False
+        # In-flight transfers, keyed by identity; pruned in callback, bulk-cancelled in stop.
+        self._pending_transfers: set = set()
+        # raised to break the worker out of stuck queues
+        self._force_stop = threading.Event()
+        self._transfer_lock = threading.Lock()  # protects _pending_transfers
+        self._epoch = 0  # session counter; stale-session callbacks are ignored
+        self._adc_data = queue.Queue()  # received ADC data, one chunk per item
+        self._adc_data_carry = bytearray()  # leftover ADC bytes between consume_adc calls
+        # latched, raised by consume_adc
+        self._overflow_error: AdcOverflowError | None = None
+        self._max_queued_chunks = self.MAX_BUFFERED_BYTES // self.TRANSFER_BYTES
+
+    @property
+    def overflow_error(self) -> "AdcOverflowError | None":
+        """Latched ADC overflow error, or None if the buffer never overran."""
+        return self._overflow_error
+
+    def start(self) -> None:
+        """
+        Start streaming and spawn the worker thread.
+        """
+        self._force_stop.clear()
+        self._epoch += 1  # new session; callbacks from prior sessions are ignored
+        self.thread = threading.Thread(target=self.worker, daemon=True)
+        self.running = True
+        self.thread.start()
+        self._adc_data = queue.Queue()  # Reset the ADC data queue
+        self._adc_data_carry = bytearray()  # Reset the carry buffer
+        self._overflow_error = None  # Reset the overflow error
+        self.registers.write(8, 0x05)  # Start streaming
+
+    def stop(self) -> None:
+        """
+        Stop streaming and end the worker thread.
+
+        Sets ``running`` to False and cancels in-flight USB transfers so their
+        callbacks fire and drain the queues, which allows the worker loop to
+        exit naturally.  If the worker has not exited within 5 seconds (e.g.
+        because a USB cancellation is slow), ``_force_stop`` is set so the
+        worker breaks unconditionally after its current
+        ``handleEventsTimeout(0.1)`` call (≤ 100 ms), and we give it one
+        further second to join before proceeding.
+        """
+        # Cancel any in-flight transfers so their callbacks fire and drain the queues,
+        # allowing the worker thread to exit its loop. The lock ensure no transfer is added
+        # to the list while we are cancelling.
+        with self._transfer_lock:
+            self.running = False
+            for transfer in self._pending_transfers:
+                try:
+                    transfer.cancel()
+                except Exception:  # pylint: disable=broad-except
+                    pass
+            self._pending_transfers.clear()
+
+        if self.thread is not None and self.thread.is_alive():
+            self.thread.join(timeout=5.0)
+            if self.thread.is_alive():
+                # Worker is stuck (slow USB cancellation).  Force it out so
+                # context.close() does not deadlock.
+                self._force_stop.set()
+                self.thread.join(timeout=1.0)
+        self.registers.write(8, 0x00)  # Stop streaming
+
+    def worker(self) -> None:
+        """
+        Event loop for the asynchronous transfers.
+
+        Runs until *both* conditions are true:
+        * ``running`` is False (``stop()`` has been called), and
+        * both USB queues are empty (all callbacks have fired).
+
+        An early exit is also triggered by ``_force_stop`` (set by ``stop()``
+        when the normal join times out) so that ``context.close()`` is never
+        called while this thread is still inside ``handleEventsTimeout``.
+        """
+        while self.running or not (
+            self.dacQueue.empty() and self.adcQueue.empty()
+        ):  # Play until the last
+            if self._force_stop.is_set():
+                break
+            # 100 ms timeout prevents blocking forever
+            self.context.handleEventsTimeout(0.1)
+
+    def callback(self, transfer: usb1.USBTransfer) -> None:
+        """
+        Handle a completed transfer (runs on the worker thread).
+
+        On a completed ADC read, buffer the bytes; if the receive queue passes
+        its limit, latch an AdcOverflowError and stop so consume_adc can raise it.
+
+        Args:
+            transfer (usb1.USBTransfer): The USB transfer that has completed.
+        """
+        current = transfer.getUserData() == self._epoch  # ignore stale-session data
+        if transfer.getEndpoint() == self.endpoint_read:
+            if current and transfer.getStatus() == usb1.TRANSFER_COMPLETED:
+                if self._overflow_error is None:
+                    # Copy: the transfer buffer is freed once we prune the transfer.
+                    self._adc_data.put(bytes(transfer.getBuffer()))
+                if self._adc_data.qsize() > self._max_queued_chunks:
+                    self._overflow_error = AdcOverflowError(
+                        "ADC receive queue exceeded high-water mark "
+                        f"({self._adc_data.qsize()} chunks); consumer not "
+                        "reading capture fast enough."
+                    )
+                    self.running = False  # unwind feeder + worker
+                    logger.error(str(self._overflow_error))
+            self.adcQueue.get_nowait()  # Always drain the queue
+        else:
+            self.dacQueue.get_nowait()  # Always drain the queue
+
+        # Prune this finished transfer so _pending_transfers stays bounded during
+        # a long capture; discard() is a no-op if stop() already cleared it.
+        with self._transfer_lock:
+            self._pending_transfers.discard(transfer)
+
+    def write(self, buffer: bytes) -> None:
+        """Submit one DAC playback buffer and one matching ADC read transfer."""
+        with self._transfer_lock:
+            if not self.running:
+                raise RuntimeError(
+                    "Stream is not running; call start() first.")
+            dac = self.device.getTransfer()
+            dac.setBulk(self.endpoint_write, buffer, self.transfer_helper,
+                        self._epoch, self.TRANSFER_TIMEOUT_MS)
+            dac.submit()
+            self._pending_transfers.add(dac)
+            read = self.device.getTransfer()
+            read.setBulk(self.endpoint_read, len(buffer), self.transfer_helper,
+                         self._epoch, self.TRANSFER_TIMEOUT_MS)
+            read.submit()
+            self._pending_transfers.add(read)
+        self.dacQueue.put(dac)
+        self.adcQueue.put(read)
+
+    def write_zeros(self, chunk_bytes: int = TRANSFER_BYTES) -> None:
+        """Feed the ADC pipeline with a zero DAC buffer (continuous capture)."""
+        self.write(bytes(chunk_bytes))
+
+    def consume_adc(
+        self,
+        need_bytes: int,
+        should_keep_waiting: Callable[[], bool] | None = None,
+        poll_s: float = 0.005,
+    ) -> bytearray:
+        """
+        Block until `need_bytes` of ADC data are available, then remove and
+        return exactly that many bytes from the front of the receive buffer.
+
+        Args:
+            need_bytes (int): Number of bytes to consume.
+            should_keep_waiting (Callable[[], bool] | None): Polled each iteration;
+                when it returns False, stop waiting and return what is available.
+            poll_s (float): Poll interval in seconds.
+
+        Returns:
+            bytearray: Up to `need_bytes` of ADC data (fewer only on early stop).
+
+        Raises:
+            AdcOverflowError: If the receive buffer exceeded its limit because
+                captured data was not read fast enough.
+        """
+        while len(self._adc_data_carry) < need_bytes:
+            if self._overflow_error is not None:
+                raise self._overflow_error
+            if should_keep_waiting is not None and not should_keep_waiting():
+                break
+            if not self.running and self._adc_data.empty():
+                break  # stream stopped and no more data will arrive, return what we have
+            try:
+                chunk = self._adc_data.get(timeout=poll_s)
+                self._adc_data_carry.extend(chunk)
+            except queue.Empty:
+                continue  # No new data yet, loop and check conditions again
+
+        if self._overflow_error is not None:
+            raise self._overflow_error
+        take_bytes_count = min(need_bytes, len(self._adc_data_carry))
+        out_bytes = self._adc_data_carry[:take_bytes_count]
+        del self._adc_data_carry[:take_bytes_count]
+        return out_bytes

{pyqa40x_i2c-0.1.2 → pyqa40x_i2c-0.2.0}/src/PyQa40x_i2c.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyQa40x-i2c
-Version: 0.1.2
+Version: 0.2.0
 Summary: A Python library for the QA40x audio analyser (int2code fork)
 Maintainer-email: Hubert Stepniewski <hubert.stepniewski@int2code.com>
 License: MIT License

{pyqa40x_i2c-0.1.2 → pyqa40x_i2c-0.2.0}/src/PyQa40x_i2c.egg-info/SOURCES.txt

@@ -55,6 +55,8 @@ src/PyQa40x_i2c.egg-info/PKG-INFO
 src/PyQa40x_i2c.egg-info/SOURCES.txt
 src/PyQa40x_i2c.egg-info/dependency_links.txt
 src/PyQa40x_i2c.egg-info/requires.txt
+src/PyQa40x_i2c.egg-info/scm_file_list.json
+src/PyQa40x_i2c.egg-info/scm_version.json
 src/PyQa40x_i2c.egg-info/top_level.txt
 tests/__init__.py
 tests/test_template.py

pyqa40x_i2c-0.2.0/src/PyQa40x_i2c.egg-info/scm_file_list.json

@@ -0,0 +1,58 @@
+{
+  "files": [
+    ".gitignore",
+    "README.md",
+    ".pylint_ignore",
+    "requirements-test.txt",
+    "requirements.txt",
+    "requirements-dev.txt",
+    "tox.ini",
+    "pyproject.toml",
+    "MANIFEST.in",
+    "RELEASE_NOTES.md",
+    "LICENSE",
+    "src/PyQa40x/wave.py",
+    "src/PyQa40x/math_general.py",
+    "src/PyQa40x/fft_processor.py",
+    "src/PyQa40x/wave_sine.py",
+    "src/PyQa40x/freq_series_plotter.py",
+    "src/PyQa40x/analyzer_params.py",
+    "src/PyQa40x/sig_proc.py",
+    "src/PyQa40x/control.py",
+    "src/PyQa40x/math_sines.py",
+    "src/PyQa40x/analyzer.py",
+    "src/PyQa40x/helpers.py",
+    "src/PyQa40x/registers.py",
+    "src/PyQa40x/cross_correlation.py",
+    "src/PyQa40x/series_plotter.py",
+    "src/PyQa40x/math_windows.py",
+    "src/PyQa40x/bluetooth.py",
+    "src/PyQa40x/math_energy.py",
+    "src/PyQa40x/math_chirp.py",
+    "src/PyQa40x/wave_chirp.py",
+    "src/PyQa40x/__init__.py",
+    "src/PyQa40x/stream.py",
+    "src/PyQa40x.egg-info/requires.txt",
+    "src/PyQa40x.egg-info/SOURCES.txt",
+    "src/PyQa40x.egg-info/top_level.txt",
+    "src/PyQa40x.egg-info/dependency_links.txt",
+    "src/PyQa40x.egg-info/PKG-INFO",
+    ".github/workflows/unit_tests.yml",
+    ".github/workflows/code_checker.yml",
+    ".github/workflows/publish_package.yml",
+    "_ci/is_dev_version.sh",
+    "LibTest/PyQa40x_cross_correlation.py",
+    "LibTest/PyQa40x_acoustic_chirp_spl_bt.py",
+    "LibTest/PyQa40x_acoustic_dbspl.py",
+    "LibTest/PyQa40x_freq_response_with_mask.py",
+    "LibTest/PyQa40x_pinknoise.py",
+    "LibTest/PyQa40x_acoustic_energy_decay_bt.py",
+    "LibTest/mask_phase.txt",
+    "LibTest/PyQa40x_coherent_averaging.py",
+    "LibTest/PyQa40x_thdn.py",
+    "LibTest/FirstPrinciples.py",
+    "LibTest/mask_freq.txt",
+    "tests/test_template.py",
+    "tests/__init__.py"
+  ]
+}

pyqa40x_i2c-0.2.0/src/PyQa40x_i2c.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.2.0",
+  "distance": 0,
+  "node": "g6a5ba3357cf07c1d160ef5f122265823f2560ec9",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-16"
+}

pyqa40x_i2c-0.1.2/src/PyQa40x/stream.py

@@ -1,208 +0,0 @@
-import threading
-import queue
-import time
-import usb1
-import numpy as np
-
-
-class Stream:
-    """
-    Class to manage buffer streaming, with event worker thread.
-    """
-
-    def __init__(self, context, device, registers):
-        """
-        Initializes the Stream class.
-
-        Args:
-            context (usb1.USBContext): The USB context.
-            device (usb1.USBDeviceHandle): The USB device handle.
-            registers (Registers): An instance of the Registers class.
-        """
-        self.context = context
-        self.device = device
-        self.registers = registers
-        self.endpoint_read = usb1.ENDPOINT_IN | 0x02  # EP2 in
-        self.endpoint_write = usb1.ENDPOINT_OUT | 0x02  # EP2 out
-        self.dacQueue = queue.Queue(
-            maxsize=5
-        )  # Max. 5 overlapping buffers in flight, block on more
-        self.adcQueue = queue.Queue()  # Unlimited queue for received data buffers
-        self.transfer_helper = usb1.USBTransferHelper()  # Use the callback dispatcher
-        # Handle COMPLETED transfers normally; also handle ERROR/TIMED_OUT/CANCELLED
-        # so the queues are always drained and dacQueue.put() never deadlocks.
-        for status in (
-            usb1.TRANSFER_COMPLETED,
-            usb1.TRANSFER_ERROR,
-            usb1.TRANSFER_TIMED_OUT,
-            usb1.TRANSFER_CANCELLED,
-            usb1.TRANSFER_STALL,
-            usb1.TRANSFER_NO_DEVICE,
-            usb1.TRANSFER_OVERFLOW,
-        ):
-            self.transfer_helper.setEventCallback(status, self.callback)
-        # self.received_data = bytearray()  # Collection of received data bytes
-        self.thread = None
-        self.running = False
-        self._pending_transfers = []  # track all submitted transfers for cancellation
-        self._force_stop = (
-            threading.Event()
-        )  # raised to break the worker out of stuck queues
-
-    def start(self):
-        """
-        Starts the streaming and spawns the worker thread.
-        """
-        self._force_stop.clear()
-        self.thread = threading.Thread(target=self.worker, daemon=True)
-        self.running = True
-        self.thread.start()
-        self.received_data = bytearray()
-        self.registers.write(8, 0x05)  # Start streaming
-
-    def stop(self):
-        """
-        Stops the streaming and ends the worker thread.
-
-        Sets ``running`` to False and cancels in-flight USB transfers so their
-        callbacks fire and drain the queues, which allows the worker loop to
-        exit naturally.  If the worker has not exited within 5 seconds (e.g.
-        because a USB cancellation is slow), ``_force_stop`` is set so the
-        worker breaks unconditionally after its current
-        ``handleEventsTimeout(0.1)`` call (≤ 100 ms), and we give it one
-        further second to join before proceeding.
-        """
-        self.running = False
-        # Cancel any in-flight transfers so their callbacks fire and drain the queues,
-        # allowing the worker thread to exit its loop.
-        for t in self._pending_transfers:
-            try:
-                t.cancel()
-            except Exception:
-                pass
-        self._pending_transfers.clear()
-        if self.thread is not None and self.thread.is_alive():
-            self.thread.join(timeout=5.0)
-            if self.thread.is_alive():
-                # Worker is stuck (slow USB cancellation).  Force it out so
-                # context.close() does not deadlock.
-                self._force_stop.set()
-                self.thread.join(timeout=1.0)
-        self.registers.write(8, 0x00)  # Stop streaming
-
-    def write(self, buffer):
-        """
-        Adds a buffer to the playback queue.
-
-        Args:
-            buffer (bytes): The data buffer to be written.
-        """
-        transfer = self.device.getTransfer()
-        transfer.setBulk(self.endpoint_write, buffer, self.transfer_helper, None, 1000)
-        transfer.submit()  # Asynchronous transfer
-        self._pending_transfers.append(transfer)
-        self.dacQueue.put(transfer)  # It doesn't matter what we put in here
-
-        # Submit a USB bulk transfer to read
-        read_transfer = self.device.getTransfer()
-        read_transfer.setBulk(
-            self.endpoint_read, 16384, self.transfer_helper, None, 1000
-        )
-        read_transfer.submit()  # Asynchronous transfer
-        self._pending_transfers.append(read_transfer)
-        self.adcQueue.put(read_transfer)  # It doesn't matter what we put in here
-
-    def worker(self):
-        """
-        Event loop for the asynchronous transfers.
-
-        Runs until *both* conditions are true:
-        * ``running`` is False (``stop()`` has been called), and
-        * both USB queues are empty (all callbacks have fired).
-
-        An early exit is also triggered by ``_force_stop`` (set by ``stop()``
-        when the normal join times out) so that ``context.close()`` is never
-        called while this thread is still inside ``handleEventsTimeout``.
-        """
-        while self.running or not (
-            self.dacQueue.empty() and self.adcQueue.empty()
-        ):  # Play until the last
-            if self._force_stop.is_set():
-                break
-            self.context.handleEventsTimeout(
-                0.1
-            )  # 100 ms timeout prevents blocking forever
-
-    def callback(self, transfer):
-        """
-        Callback of the worker thread to handle completed transfers.
-
-        Args:
-            transfer (usb1.USBTransfer): The USB transfer that has completed.
-        """
-        if transfer.getEndpoint() == self.endpoint_read:
-            if transfer.getStatus() == usb1.TRANSFER_COMPLETED:
-                self.received_data.extend(
-                    transfer.getBuffer()
-                )  # Collect received data bytes
-            self.adcQueue.get_nowait()  # Always drain the queue
-        else:
-            self.dacQueue.get_nowait()  # Always drain the queue
-
-    def collect_remaining_adc_data(self):
-        """
-        Waits for all remaining ADC transfers to complete and returns the collected data.
-
-        Returns:
-            bytearray: The collected ADC data.
-        """
-        while not self.adcQueue.empty():
-            time.sleep(0.01)
-
-        return self.received_data
-
-    def write_zeros(self, chunk_bytes: int = 16384):
-        """
-        Sends a zero-filled DAC buffer of `chunk_bytes` bytes and queues one
-        matching ADC read transfer.  Functionally identical to write() but
-        generates the zero payload internally so no DAC Wave is needed.
-
-        Args:
-            chunk_bytes (int): Number of bytes per transfer (must be a multiple
-                of 4).  Defaults to 16384 (16 kB) to match the hardware chunk
-                size used by write().
-        """
-        zeros = bytes(chunk_bytes)
-
-        dac_transfer = self.device.getTransfer()
-        dac_transfer.setBulk(
-            self.endpoint_write, zeros, self.transfer_helper, None, 1000
-        )
-        dac_transfer.submit()
-        self._pending_transfers.append(dac_transfer)
-        self.dacQueue.put(dac_transfer)
-
-        read_transfer = self.device.getTransfer()
-        read_transfer.setBulk(
-            self.endpoint_read, chunk_bytes, self.transfer_helper, None, 1000
-        )
-        read_transfer.submit()
-        self._pending_transfers.append(read_transfer)
-        self.adcQueue.put(read_transfer)
-
-    def collect_adc_exact(self, n_bytes: int) -> bytearray:
-        """
-        Blocks until at least `n_bytes` of ADC data have been collected, then
-        returns exactly `n_bytes` (any excess is discarded).  The stream must
-        have been started with start() and all required write_zeros() calls
-        must have been submitted before calling this.
-
-        Args:
-            n_bytes (int): Exact number of bytes to return.
-
-        Returns:
-            bytearray: Exactly n_bytes of calibrated ADC data.
-        """
-        while len(self.received_data) < n_bytes:
-            time.sleep(0.01)
-        return bytearray(self.received_data[:n_bytes])