DueDaq

Module for interacting with Arduino Due DAQ system.

This module provides classes and exceptions for data acquisition from an Arduino Due using the duq-daq firmware. It enables both actual data acquisition and simulation for testing purposes.

Usage

The primary class for interacting with the DAQ system is DueDaq. It handles communication with the Arduino Due device, starts and stops data acquisition, and retrieves the data collected. For testing without hardware, DueSerialSim can simulate data acquisition by generating mock data.

Examples:

Create a DueDaq instance with a simulated serial port

>>> from daqopen.duedaq import DueDaq
>>> my_daq = DueDaq(serial_port_name="SIM")
>>> my_daq.start_acquisition()
>>> data = my_daq.read_data()
>>> print(data)
[100, 100, 100]
>>> my_daq.stop_acquisition()

Classes:

Name	Description
`DueSerialSim`	Simulation Class for testing purpose.
`DueDaq`	Driver class for actual data acquisition.

Raises:

Type	Description
`DeviceNotFoundException`	Exception when the device could not be found by its VID and PID.
`DAQErrorException`	Exception when there occurs any other error relating the data acquisition.
`AcqNotRunningException`	Exception when data will be read without acquisition running.

`AcqNotRunningException`

Bases: Exception

Exception raised when data is attempted to be read without an active acquisition process.

This exception is raised if a read operation is attempted while the DAQ system is not currently acquiring data. It helps prevent operations on an inactive data stream.

`init(error_info)`

Exception raised when data is attempted to be read without an active acquisition process.

Parameters:

Name	Type	Description	Default
`error_info`	`str`	A description of the error encountered when attempting to read data.	required

`DAQErrorException`

Bases: Exception

Exception raised for errors related to the DAQ system.

This exception is raised during data acquisition if there are inconsistencies or errors such as frame number mismatches, corrupted data, or unexpected behavior.

`init(error_info)`

Exception raised for errors related to the DAQ system.

Parameters:

Name	Type	Description	Default
`error_info`	`str`	A description of the error encountered during data acquisition.	required

`DeviceNotFoundException`

Bases: Exception

Exception raised when the DAQ device cannot be found by its Vendor ID (VID) and Product ID (PID).

This exception is typically raised when attempting to initialize a connection to an Arduino Due DAQ system and the device is not detected on any serial port.

`init(device_name)`

Exception raised when the DAQ device cannot be found by its Vendor ID (VID) and Product ID (PID)

Parameters:

Name	Type	Description	Default
`device_name`	`str`	The name or identifier of the missing device.	required

`DueDaq`

Bases: object

Driver class for data acquisition from the Arduino Due DAQ system.

The DueDaq class interfaces with the Arduino Due running the duq-daq firmware. It handles starting and stopping data acquisition, reading and processing the data collected, and managing communication over the serial interface. Additionally, it supports simulated data acquisition for testing purposes.

Attributes:

Name	Type	Description
`MCLK`	`int`	MCU Clock Frequency.
`CONV_CYCLES_PER_SAMPLE`	`int`	Clock cycles per ADC conversion.
`MAX_BUFFER_SIZE`	`int`	Maximum DMA buffer size for ADC cyclic buffer in cumulative samples.
`MIN_BUFFER_SIZE`	`int`	Minimum DMA buffer size for ADC cyclic buffer in cumulative samples.
`MAX_BUFFER_DURATION`	`float`	Maximum time duration of the buffer for responsiveness.
`NUM_BYTES_PER_SAMPLE`	`int`	Number of bytes per data sample.
`NUM_BYTES_PKG_CNT`	`int`	Number of bytes for the package counter.
`START_PATTERN`	`bytearray`	Byte pattern marking the start of a data frame.
`FRAME_NUM_DT`	`dtype`	Data type for frame number, with little-endian byte order.
`FRAME_NUM_MAX`	`int`	Maximum value for the frame number.
`ADC_RANGE`	`list`	Range of the ADC values for normalization.
`CHANNEL_MAPPING`	`dict`	Mapping of channel names to their corresponding physical pins.
`CHANNEL_ORDER`	`list`	Order of the channels in the data package.

Parameters:

Name	Type	Description	Default
`channels`	`list[str]`	List of channels to be acquired.	`['A0']`
`reset_pin`	`int`	GPIO pin number for hardware reset (default: None).	`None`
`serial_port_name`	`str`	Name of the serial port for communication. Use `"SIM"` for simulation mode.	`''`
`samplerate`	`float`	Desired sampling rate for acquisition per channel (may not be guaranteed).	`50000.0`
`differential`	`bool`	Enable or disable differential mode for the analog input.	`False`
`gain`	`str \| DueDaqGain`	Set the input amplification of the integrated stage.	`SGL_1X`
`offset_enabled`	`bool`	Enable or disable offset removal before amplification (only for single-ended).	`False`
`extend_to_int16`	`bool`	Expand the data to 16-bit range and perform crosstalk compensation (experimental).	`False`
`realtime_sim`	`bool`	Enable or disable realtime mode during simulation	`True`

Methods:

Name	Description
`start_acquisition`	Starts the data acquisition process.
`stop_acquisition`	Stops the data acquisition process.
`hard_reset`	Performs a hardware reset of the DAQ system using the specified reset pin.
`read_data`	Reads and processes a block of data from the DAQ system.

Examples:

>>> from daqopen.duedaq import DueDaq
>>> my_daq = DueDaq(serial_port_name="SIM")
>>> my_daq.start_acquisition()
>>> data = my_daq.read_data()
>>> print(data)
>>> my_daq.stop_acquisition()

Raises:

Type	Description
`DeviceNotFoundException`	If the DAQ device is not found.
`DAQErrorException`	For errors during data acquisition, such as frame number mismatches.
`AcqNotRunningException`	If trying to read data without an active acquisition process.

`init(channels=['A0'], reset_pin=None, serial_port_name='', samplerate=50000.0, differential=False, gain=DueDaqGain.SGL_1X, offset_enabled=False, extend_to_int16=False, realtime_sim=True)`

Initialize the DueDaq instance for data acquisition.

Sets up the necessary configurations for either real or simulated data acquisition. It calculates the ADC prescaler, sets up channels, and initializes the serial communication with either the real Arduino Due hardware or the DueSerialSim simulator.

Parameters:

Name	Type	Description	Default
`channels`	`list[str]`	List of channels to be acquired.	`['A0']`
`reset_pin`	`int`	GPIO pin number for hardware reset (default: None).	`None`
`serial_port_name`	`str`	Name of the serial port for communication. Use `"SIM"` for simulation mode.	`''`
`samplerate`	`float`	Desired sampling rate for acquisition per channel (cannot be guaranteed).	`50000.0`
`differential`	`bool`	Enable or disable differential mode for the analog input.	`False`
`gain`	`str \| DueDaqGain`	Gain of ADC input amplifier (e.g., single-ended 1x, 2x, etc.).	`SGL_1X`
`offset_enabled`	`bool`	Whether to remove offset before amplification (single-ended mode only).	`False`
`extend_to_int16`	`bool`	Expand data to 16-bit range and perform crosstalk compensation (experimental).	`False`
`realtime_sim`	`bool`	Enable or disable realtime mode during simulation	`True`

Notes

If serial_port_name is "SIM", the DueSerialSim class will be used for simulated data acquisition.
For hardware reset on a Raspberry Pi using reset_pin, ensure that the RPi.GPIO library is installed.

`hard_reset()`

Perform a hardware reset of the DAQ system.

Uses the specified reset_pin (if configured) to reset the Arduino Due hardware. This is only applicable when running on a Raspberry Pi with the RPi.GPIO library installed.

Actions

Drives the reset pin low for 1 second, then high again to reset the hardware.
Reinitializes the DAQ board after the reset.

`read_data()`

Read and process a block of data from the DAQ system.

Reads the current frame into the internal buffer, detects and corrects any spikes in the data, and performs necessary adjustments like expanding to 16-bit values and reducing crosstalk.

Returns:

Type	Description
`ndarray`	The processed data array with dimensions (NUM_SAMPLES, NUM_CH).

`start_acquisition()`

Start the data acquisition process.

Sends the "START" command to the DAQ system to begin data acquisition. It waits for the start of a data frame to synchronize the system, then sets the acquisition state to "running".

Actions

Resets the input buffer.
Waits for the first data frame to ensure proper synchronization.
Changes the acquisition state to "running".

`stop_acquisition()`

Stop the data acquisition process.

Sends the "STOP" command to the DAQ system to stop data acquisition and clears the input buffer. The state is then set to "stopped".

`DueDaqGain`

Bases: Enum

Enumeration for GAIN Setting

Attributes:

Name	Type	Description
`SGL_1X`	`int`	Single Ended Mode Gain = 1x
`SGL_2X`	`int`	Single Ended Mode Gain = 2x
`SGL_4X`	`int`	Single Ended Mode Gain = 4x
`DIFF_05X`	`int`	Differential Mode Gain = 0.5x
`DIFF_1X`	`int`	Differential Mode Gain = 1x
`DIFF_2X`	`int`	Differential Mode Gain = 2x

`DueSerialSim`

Bases: object

A simulation class for Arduino Due Data Acquisition (DAQ) system.

DueSerialSim is designed to simulate data acquisition from an Arduino Due for testing purposes. It generates mock data packets that mimic the behavior of the real DAQ system, allowing for software testing without the need for actual hardware.

Attributes:

Name	Type	Description
`MCLK`	`int`	MCU Clock Frequency.
`CONV_CYCLES_PER_SAMPLE`	`int`	Clock Cycles per conversion.
`MAX_BUFFER_SIZE`	`int`	Maximum DMA buffer size for ADC cyclic buffer in cumulative samples.
`MIN_BUFFER_SIZE`	`int`	Minimum DMA buffer size for ADC cyclic buffer in cumulative samples.
`NUM_BYTES_PER_SAMPLE`	`int`	Number of bytes per data sample.
`NUM_BYTES_PKG_CNT`	`int`	Number of bytes in the package counter.
`START_PATTERN`	`bytearray`	Byte pattern marking the start of a data frame.
`FRAME_NUM_DT`	`dtype`	Data type for frame number, with little-endian byte order.
`FRAME_NUM_MAX`	`int`	Maximum value for the frame number.
`ADC_RANGE`	`list`	Range of the ADC values for normalization.
`CHANNEL_MAPPING`	`dict`	Mapping of channel names to their corresponding physical pins.
`CHANNEL_ORDER`	`list`	Order of the channels in data package.

Parameters:

Name	Type	Description	Default
`realtime`	`bool`	Enable or disable the real-time simulation.	`True`

Methods:

Name	Description
`write`	Simulates writing commands to the DAQ system (e.g., "START", "STOP", "SETMODE").
`read`	Reads a specified length of data from the simulated DAQ system.
`readinto`	Reads data directly into the provided buffer.
`reset_input_buffer`	Resets the internal read buffer.

Notes

Please do not use this class directly, instead use the DueDaq with serial_port_name = "SIM"

`init(realtime=True)`

Initialize the DueSerialSim instance for simulating data acquisition.

This constructor sets up the simulation environment for the Arduino Due DAQ system. It initializes the internal state, prepares the simulated data signals, and sets up the delay between data packet generations if realtime is enabled.

Parameters:

Name	Type	Description	Default
`realtime`	`bool`	Enable or disable the realtime simulation. If True, timing will simulate the behavior of the real board. Otherwise, the simulation runs as fast as possible.	`True`

Attributes:

Name	Type	Description
`response_data`		Placeholder for response data, initialized as an empty byte string.
`_frame_number`		Counter to keep track of the frame number.
`_actual_state`		Current state of the simulator, either "started" or "stopped".
`_read_buffer`		Buffer to store generated frames for reading.
`_is_differential`		Boolean flag indicating whether differential mode is enabled.
`_gain_value`		Gain value used in signal simulation, range 0-3.
`_offset_enabled`		Boolean flag indicating whether offset is enabled in the ADC.
`_adc_prescal`		ADC prescaler value, affecting the sampling rate.
`_adc_cher`		ADC channel enable register, storing active channel bits.
`_channels`		List of active ADC channels based on `_adc_cher`.
`_buffer_size`		Size of the buffer for data samples.
`_samplerate`		Calculated sample rate for the simulation.
`_samples_per_block_channel`		Number of samples per block per channel.
`_signal_buffer`		Buffer storing the simulated signal for all active channels.

`read(length=0)`

Simulate reading data from the DAQ system.

This method retrieves a specified amount of data from the internal read buffer. If the buffer is empty and the simulation is in the "started" state, a new frame is generated.

Parameters:

Name	Type	Description	Default
`length`	`int`	The number of bytes to read from the buffer. If there is not enough data, a new frame is generated if the DAQ is running.	`0`

Returns:

Name	Type	Description
`bytes`	`bytes`	A byte string containing the requested data from the buffer. If the buffer contains less data than requested, it returns whatever is available.

`readinto(buffer=0)`

Simulate reading data into an existing buffer.

This method fills the provided buffer with data from the internal read buffer. If the simulation is in the "started" state, a new data frame is generated. If data already exists in the buffer when a new frame is generated, a warning is logged.

Parameters:

Name	Type	Description	Default
`buffer`	`bytearray`	A bytearray that will be filled with the simulated data.	`0`

Actions

The internal read buffer is filled with the generated frame.
The provided buffer is then populated with this data.

`reset_input_buffer()`

Reset the internal read buffer of the simulator.

This method clears the current content of the _read_buffer, ensuring that no previously generated frames remain in the buffer.

It can be used to reset the state when switching between different commands or tests.

`write(data)`

Simulate writing commands to the DAQ system and handle the setup accordingly.

This method processes various commands sent to the DAQ system and adjusts the internal state of the simulator based on the command.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	A byte string containing the command to be processed.	required

Actions

The appropriate internal attributes (e.g., _is_differential, _gain_value, _adc_prescal) are updated based on the command.
The method recalculates ADC parameters and regenerates the fake ADC configuration after any change in settings by calling _setup_fake_adc.

DueDaq

Usage

AcqNotRunningException

__init__(error_info)

DAQErrorException

__init__(error_info)

DeviceNotFoundException

__init__(device_name)

DueDaq

__init__(channels=['A0'], reset_pin=None, serial_port_name='', samplerate=50000.0, differential=False, gain=DueDaqGain.SGL_1X, offset_enabled=False, extend_to_int16=False, realtime_sim=True)

hard_reset()

read_data()

start_acquisition()

stop_acquisition()

DueDaqGain

DueSerialSim

__init__(realtime=True)

read(length=0)

readinto(buffer=0)

reset_input_buffer()

write(data)

`AcqNotRunningException`

`init(error_info)`

`DAQErrorException`

`init(error_info)`

`DeviceNotFoundException`

`init(device_name)`

`DueDaq`

`init(channels=['A0'], reset_pin=None, serial_port_name='', samplerate=50000.0, differential=False, gain=DueDaqGain.SGL_1X, offset_enabled=False, extend_to_int16=False, realtime_sim=True)`

`hard_reset()`

`read_data()`

`start_acquisition()`

`stop_acquisition()`

`DueDaqGain`

`DueSerialSim`

`init(realtime=True)`

`read(length=0)`

`readinto(buffer=0)`

`reset_input_buffer()`

`write(data)`