PyQa40x-i2c 0.1.0__py3-none-any.whl

PyQa40x/__init__.py

@@ -0,0 +1,18 @@
+# __init__.py in PyQa40x
+
+from .analyzer import Analyzer
+from .analyzer_params import AnalyzerParams
+from .wave_sine import Wave, WaveSine
+from .registers import Registers
+from .control import Control
+from .stream import Stream
+from .series_plotter import SeriesPlotter
+from .freq_series_plotter import FreqSeriesPlotter
+
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+from .fft_processor import FFTProcessor
+from .sig_proc import SigProc
+from .helpers import *

PyQa40x/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

PyQa40x/analyzer.py

@@ -0,0 +1,322 @@
+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
+
+
+class Analyzer:
+    def __init__(self):
+        """
+        Initializes the Analyzer class.
+        """
+        self.params: AnalyzerParams | None = None
+        self.context: usb1.USBContext | None = None
+        self.device: usb1.USBDeviceHandle | None = None
+        self.registers: Registers | None = None
+        self.control: Control | None = None
+        self.stream: Stream | None = None
+        self.cal_data: dict | None = None
+        self.bt_device: BluetoothAudioDevice | None = None
+        self._cleanup_registered = False
+
+    def init(
+        self,
+        sample_rate: int = 48000,
+        max_input_level: int = 0,
+        max_output_level: int = 18,
+        pre_buf: int = 2048,
+        post_buf: int = 2048,
+        fft_size: int = 16384,
+        window_type: str = "boxcar",
+        amplitude_unit: str = "dbv",
+        distortion_unit: str = "db",
+        bt_device_name: str = "",
+    ) -> AnalyzerParams:
+        """
+        Initializes the analyzer hardware with the specified parameters.
+
+        Args:
+            sample_rate (int): The sample rate for the device. Default is 48000. Valid values are 48000, 96000, 192000.
+            max_input_level (int): Maximum input level in dBV. Valid values are 0, 6, 12, 18, 24, 30, 36, 42.
+            max_output_level (int): Maximum output level in dBV. Valid values are 18, 8, -2, -12.
+            pre_buf (int): Size of the pre-buffer.
+            post_buf (int): Size of the post-buffer.
+            fft_size (int): Size of the FFT.
+            window_type (str): Type of window function to apply to the signal before FFT.
+            amplitude_unit (str): Unit for amplitude measurements, default is "dbv".
+            distortion_unit (str): Unit for distortion measurements, default is "db".
+            bt_device_name (str): Name of the Bluetooth device to use. Default is empty.
+
+        Returns:
+            AnalyzerParams: A class instance containing the hardware and parameter settings.
+        """
+        self.params = AnalyzerParams(
+            sample_rate,
+            max_input_level,
+            max_output_level,
+            pre_buf,
+            post_buf,
+            fft_size,
+            window_type,
+        )
+        self.context = usb1.USBContext()
+        self.context.open()
+
+        # Attempt to open QA402 or QA403 device
+        self.device = self.context.openByVendorIDAndProductID(0x16C0, 0x4E37)  # QA402
+        if self.device is None:
+            self.device = self.context.openByVendorIDAndProductID(
+                0x16C0, 0x4E39
+            )  # QA403
+            if self.device is None:
+                raise SystemExit("No QA402/QA403 analyzer found")
+        self.device.resetDevice()
+        self.device.claimInterface(0)
+
+        self.registers = Registers(self.device)
+        self.control = Control(self.registers)
+        self.stream = Stream(self.context, self.device, self.registers)
+
+        # Load calibration data
+        self.cal_data = self.control.load_calibration()
+
+        # Set input/output levels and sample rate
+        self.control.set_input(max_input_level)
+        self.control.set_output(max_output_level)
+        self.control.set_samplerate(sample_rate)
+
+        # Initialize Bluetooth device if a name is provided
+        if bt_device_name:
+            self.bt_device = BluetoothAudioDevice(bt_device_name, sample_rate)
+            if self.bt_device.device_index is None:
+                raise SystemExit("Failed to connect to the specified Bluetooth device")
+
+        # Register cleanup function to be called on exit
+        if not self._cleanup_registered:
+            atexit.register(self.cleanup)
+            self._cleanup_registered = True
+
+        return self.params
+
+    def cleanup(self):
+        """
+        Releases the USB device interface and closes the context.
+        """
+        try:
+            if self.device:
+                self.device.releaseInterface(0)
+                self.device = None
+            if self.bt_device:
+                self.bt_device.close()
+                self.bt_device = None
+            if self.context:
+                self.context.close()
+                self.context = None
+        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]:
+        """
+        Sends DAC data to the device and receives ADC data.
+
+        Args:
+            left_wave (Wave): Wave instance with left channel DAC data.
+            right_wave (Wave): Wave instance with right channel DAC data.
+
+        Returns:
+            tuple[Wave, Wave]: Tuple containing Wave instances with left and right channel ADC data.
+        """
+        left_dac_data = left_wave.get_buffer()
+        right_dac_data = right_wave.get_buffer()
+
+        # On QA402 and QA403, outputs need to be swapped
+        left_dac_data, right_dac_data = right_dac_data, left_dac_data
+
+        left_peak = np.max(left_dac_data)
+
+        # 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
+        )
+
+        # 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
+
+        # 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)
+
+        # 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
+
+        self.stream.start()
+
+        # 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]
+
+        # 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
+
+        # 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
+        )
+
+        # 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)
+
+        # 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
+
+        # Ensure the buffer matches the expected shape. Is this needed?
+        expected_shape = (
+            self.params.pre_buf + self.params.fft_size + self.params.post_buf,
+        )
+        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)
+
+        return left_wave, right_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."""
+        BluetoothAudioDevice.list_audio_devices_by_sample_rate(target_sample_rate)
+
+    def capture(self, total_samples: int) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Captures ``total_samples`` samples from both ADC input channels without
+        playing anything on the DAC outputs.  Unlike ``send_receive()``, this
+        method:
+
+        * Starts the USB stream **once** for the entire capture — no stop/restart
+          between chunks, so no audio is ever lost mid-recording.
+        * Sends zero-filled DAC data (silence) only to satisfy the hardware
+          protocol; DAC output remains at 0 V throughout.
+        * Returns raw calibrated Volt arrays — **no pre/post guard samples are
+          discarded** and the length is exactly ``total_samples``.
+
+        Args:
+            total_samples (int): Number of samples to capture per channel.
+                At 48 kHz, 1 sample = 1/48000 s.  There is no upper limit
+                imposed by this method, but the host must have enough RAM to
+                hold the full recording (2 × total_samples × 8 bytes for
+                float64).
+
+        Returns:
+            tuple[np.ndarray, np.ndarray]: ``(left_volts, right_volts)`` —
+                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()
+        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)
+        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

PyQa40x/analyzer_params.py

@@ -0,0 +1,66 @@
+import scipy.signal # pip install scipy
+import numpy as np
+
+class AnalyzerParams:
+    def __init__(self, sample_rate: int = 192000, max_input_level: int = 0, max_output_level: int = 18, 
+                 pre_buf: int = 2048, post_buf: int = 2048, fft_size: int = 16384, window_type='boxcar'):
+        """
+        Initializes the AnalyzerParams class with default or specified parameters.
+
+        Args:
+            sample_rate (int): Sample rate for the hardware. Valid values are 48000, 96000, 192000.
+            max_input_level (int): Maximum input level in dBV. Valid values are 0, 6, 12, 18, 24, 30, 36, 42.
+            max_output_level (int): Maximum output level in dBV. Valid values are 18, 8, -2, -12.
+            pre_buf (int): Size of the pre-buffer.
+            post_buf (int): Size of the post-buffer.
+            fft_size (int): Size of the FFT.
+            window_type (str): Type of window function to apply to the signal before FFT.
+        """
+        self.sample_rate: int = sample_rate
+        self.max_input_level: int = max_input_level
+        self.max_output_level: int = max_output_level
+        self.pre_buf: int = pre_buf
+        self.post_buf: int = post_buf
+        self.fft_size: int = fft_size
+
+        self.window_type = window_type
+        self.window = scipy.signal.get_window(self.window_type, self.fft_size)
+        mean_w = np.mean(self.window)
+        self.ACF = 1 / mean_w
+        rms_w = np.sqrt(np.mean(self.window ** 2))
+        self.ECF = 1 / rms_w
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the AnalyzerParams instance.
+
+        Returns:
+            str: String representation of the parameters formatted as a table.
+        """
+        params = [
+            ("Sample Rate", f"{self.sample_rate} Hz"),
+            ("Max Input Level", f"{self.max_input_level} dBV"),
+            ("Max Output Level", f"{self.max_output_level} dBV"),
+            ("Pre Buffer", f"{self.pre_buf}"),
+            ("Post Buffer", f"{self.post_buf}"),
+            ("Buffer Size", f"{self.fft_size}"),
+            ("Duration", f"{self.fft_size/self.sample_rate:0.2f} sec"),
+            ("Window Type", f"{self.window_type}")
+        ]
+        
+        col_widths = [max(len(item[i]) for item in params) for i in range(2)]
+        col_widths[1] += 5  # Add padding
+
+        table = "===== ACQUISITION PARAMETERS =====\n"
+        rows = len(params)
+        cols = 3
+        
+        for row in range(0, rows, cols):
+            row_str = ""
+            for col in range(cols):
+                if row + col < rows:
+                    name, value = params[row + col]
+                    row_str += f"{name.ljust(col_widths[0])} : {value.ljust(col_widths[1])}   "
+            table += row_str.strip() + "\n"
+        
+        return table

PyQa40x/bluetooth.py

@@ -0,0 +1,134 @@
+import pyaudio # pip install pyaudio
+import threading
+import numpy as np
+from PyQa40x.wave import Wave
+
+class BluetoothAudioDevice:
+    def __init__(self, device_name: str, sample_rate: int, debug: bool = False):
+        """
+        Initializes the BluetoothAudioDevice.
+
+        Args:
+            device_name (str): Name of the target Bluetooth audio device.
+            sample_rate (int): Sample rate for playback.
+            debug (bool): If True, print detailed debug information. Default is False.
+        """
+        self.device_name = device_name
+        self.sample_rate = sample_rate
+        self.debug = debug
+        self.device_index = None
+        self.p = pyaudio.PyAudio()
+
+        # Attempt to find and open the device
+        self.device_index = self._find_device()
+        if self.device_index is None:
+            print(f"Failed to open audio device '{self.device_name}' with the required sample rate {self.sample_rate} Hz.")
+
+    def _find_device(self):
+        """Find and return the index of the target audio device if it supports the required sample rate."""
+        target_device_index = None
+        if self.debug:
+            print("Enumerating audio devices...\n")
+
+        for i in range(self.p.get_device_count()):
+            info = self.p.get_device_info_by_index(i)
+            if self.debug:
+                print(f"Device {i}: {info['name']}")
+            
+            if self.device_name in info['name']:
+                if self.debug:
+                    print(f"  Checking device '{info['name']}' for sample rate {self.sample_rate} Hz...")
+                try:
+                    # Attempt to open a stream to check if the sample rate is supported
+                    stream = self.p.open(format=pyaudio.paFloat32,
+                                         channels=2,
+                                         rate=self.sample_rate,
+                                         output=True,
+                                         output_device_index=i)
+                    stream.close()
+                    if self.debug:
+                        print(f"  -> Device {i} supports the required sample rate.")
+                    if target_device_index is None:
+                        target_device_index = i
+                except Exception as e:
+                    if self.debug:
+                        print(f"  -> Device {i} does not support the required sample rate. ({str(e)})")
+        return target_device_index
+
+    def play_wave_background(self, left_wave: Wave, right_wave: Wave):
+        """Play left and right Wave objects in the background."""
+        if self.device_index is None:
+            print("No valid audio device found. Cannot play wave.")
+            return None
+        
+        # Start playing the wave in a separate thread
+        thread = threading.Thread(target=self._play_wave, args=(left_wave, right_wave, self.sample_rate, self.device_index))
+        thread.start()
+        return thread
+
+    def _play_wave(self, left_wave: Wave, right_wave: Wave, sample_rate: int, device_index: int):
+        """Play a stereo Wave object."""
+        stream = self.p.open(format=pyaudio.paFloat32,
+                             channels=2,  # Stereo playback
+                             rate=sample_rate,
+                             output=True,
+                             output_device_index=device_index)
+
+        actual_sample_rate = stream._rate
+        if self.debug:
+            print(f"Requested Sample Rate: {sample_rate}")
+            print(f"Actual Sample Rate: {actual_sample_rate}")
+
+        # Get buffers for left and right waves
+        left_buffer = left_wave.get_buffer().astype(np.float32)
+        right_buffer = right_wave.get_buffer().astype(np.float32)
+
+        # Ensure both buffers are the same length
+        min_length = min(len(left_buffer), len(right_buffer))
+        left_buffer = left_buffer[:min_length]
+        right_buffer = right_buffer[:min_length]
+
+        # Interleave left and right buffers for stereo output
+        interleaved = np.empty((min_length * 2,), dtype=np.float32)
+        interleaved[0::2] = left_buffer
+        interleaved[1::2] = right_buffer
+
+        # Convert wave data to float32 format and play
+        stream.write(interleaved.tobytes())
+        stream.stop_stream()
+        stream.close()
+
+    def close(self):
+        """Terminate the PyAudio instance."""
+        self.p.terminate()
+
+    @staticmethod
+    def list_audio_devices():
+        """List all available audio devices by name."""
+        p = pyaudio.PyAudio()
+        print("Available audio devices:\n")
+        for i in range(p.get_device_count()):
+            info = p.get_device_info_by_index(i)
+            print(f"Device {i}: {info['name']}")
+        p.terminate()
+
+    @staticmethod
+    def list_audio_devices_by_sample_rate(target_sample_rate: int):
+        """List all available audio devices that support a specific sample rate."""
+        p = pyaudio.PyAudio()
+        print(f"Audio devices supporting {target_sample_rate} Hz sample rate:\n")
+        for i in range(p.get_device_count()):
+            info = p.get_device_info_by_index(i)
+            try:
+                # Check if the device supports the specified sample rate
+                stream = p.open(format=pyaudio.paFloat32,
+                                channels=2,  # Check for stereo support
+                                rate=target_sample_rate,
+                                output=True,
+                                output_device_index=i)
+                stream.close()
+                print(f"Device {i}: {info['name']} supports {target_sample_rate} Hz")
+            except Exception:
+                # Device does not support the specified sample rate
+                continue
+        p.terminate()