interface

This module implements the main interface class for PicoQuake device.

AcquisitionData dataclass

Data class for storing the complete acquisition result, including IMU samples, device information, and acquisition configuration.

Attributes:

• samples (list[IMUSample]) –

  List of IMU samples.

• device (DeviceInfo) –

  Device information.

• config (Config) –

  Acquisition configuration.

• start_time (datetime) –

  Start time of the acquisition.

• skipped_samples (int) –

  Number of skipped samples due to acquisition issues.

• csv_path (Optional[str]) –

  Path to the CSV file containing the data. Used if the data was loaded from a file.

• duration (float) –

  Duration of the acquisition in seconds.

• num_samples (int) –

  Number of samples in the acquisition.

• integrity (bool) –

  Whether the acquisition has integrity (no skipped samples).

Methods:

• to_csv –

  Write the data to a CSV file.

• from_csv –

  Load the data from a CSV file.

from_csv(path) classmethod

Load the data from a CSV file.

Parameters:

• path (str) –

  Path to the CSV file.

Returns:

• AcquisitionData ( AcquisitionData ) –

  Data loaded from the CSV file.

Raises:

• ValueError –

  If an error occurs while parsing the CSV file.

re_centre(index)

Re-centre the data around a specific index.

Parameters:

• index (int) –

  The index to re-centre the data around.

to_csv(path)

Write the data to a CSV file.

Parameters:

• filename –

  Path to the CSV file.

AcquisitionDataCorrupted

Bases: Exception

Raised when acquisition data is corrupted.

AcquisitionIncomplete

Bases: Exception

Raised when acquisition is incomplete.

ConfigEnum

Bases: Enum

Base class for configuration enums. Each member has two elements: an index and a parameter value. Parameter value can be either an integer or a float.

Attributes:

• index (int) –

  Index of the member.

• param_value (Union[float, int]) –

  Parameter value of the member.

Methods:

• from_index –

  Return member with specified index.

• from_param_value –

  Return member with specified parameter value.

• find_closest –

  Return member with parameter value closest to specified value.

find_closest(value) classmethod

Return member with parameter value closest to specified value.

from_index(index) classmethod

Return member with specified index.

from_param_value(value, tolerance=1e-05) classmethod

Return member with specified parameter value.

ConnectionError

Bases: Exception

Raised when connection to the device fails.

DeviceError

Bases: Exception

Raised when connected device returns an error.

Attributes:

• error_code (int) –

  The error code returned by the device.

DeviceNotFound

Bases: Exception

Raised when device with specified short ID is not found.

HandshakeError

Bases: Exception

Raised when handshake with the device fails.

IMUSample dataclass

Data class for storing a single IMU sample.

Attributes:

• count (int) –

  Sample count.

• acc_x (float) –

  Accelerometer X value.

• acc_y (float) –

  Accelerometer Y value.

• acc_z (float) –

  Accelerometer Z value.

• gyro_x (float) –

  Gyroscope X value.

• gyro_y (float) –

  Gyroscope Y value.

• gyro_z (float) –

  Gyroscope Z value.

PicoQuake

PicoQuake interface class

Attributes:

• device_info (Optional[DeviceInfo]) –

  The device information.

• config (Config) –

  The current configuration of the device.

Methods:

• configure –

  Configures the device with specified parameters.

• configure_approx –

  Configures the device with approximated parameters.

• stop –

  Stops the device.

• acquire –

  Acquires data for a specified duration.

• start_continuos –

  Starts the device in continuos mode.

• stop_continuos –

  Stops the device in continuos mode.

• read_last –

  Reads the last sample received in continuos mode.

config: Config = Config(SampleRate.hz_100, Filter.hz_42, AccRange.g_4, GyroRange.dps_1000) instance-attribute

The current configuration of the device.

device_info: Optional[DeviceInfo] = None instance-attribute

The device information.

__init__(short_id=None, port=None)

Initializes the device.

Specify short_id written on the device label to find the device automatically. Alternatively, specify the port to which the device is connected.

Parameters:

• short_id (Optional[str], default: None ) –

  A 4-character string used to identify the device. Written on the device label.

• port (Optional[str], default: None ) –

  The port to which the device is connected.

Raises:

• ValueError –

  If neither short_id nor port are provided, or if short_id is not a 4-character string.

• DeviceNotFound –

  If device with short_id is not found.

acquire(seconds=0, n_samples=0)

Starts data acquisition of a specified duration. Duration can be specified in seconds or number of samples.

Parameters:

• seconds (float, default: 0 ) –

  The duration of the acquisition in seconds.

• n_samples (int, default: 0 ) –

  The number of samples to acquire.

Returns:

• Tuple[AcquisitionData, Optional[Exception]] –

  A tuple containing the acquisition data and an exception if any occurred.

Raises:

• ValueError –

  If both seconds and n_samples are specified, if neither seconds nor n_samples are specified, or if seconds or n_samples are negative.

• ConnectionError –

  If the acquisition times out or if not all samples are received. Incomplete data is still saved.

configure(sample_rate, filter_hz, acc_range, gyro_range)

Configures PicoQuake with acquisition parameters. Parameters are selected from enums with available values.

Parameters:

• sample_rate (SampleRate) –

  The sample rate in Hz.

• filter_hz (Filter) –

  The filter frequency in Hz.

• acc_range (AccRange) –

  The accelerometer range in g.

• gyro_range (GyroRange) –

  The gyroscope range in dps.

configure_approx(sample_rate, filter_hz, acc_range, gyro_range)

Configures PicoQuake with acquisition parameters. Parameters are approximated to the closest available values.

Parameters:

• sample_rate (float) –

  The sample rate in Hz.

• filter_hz (float) –

  The filter frequency in Hz.

• acc_range (float) –

  The accelerometer range in g.

• gyro_range (float) –

  The gyroscope range in dps.

read(num=1, timeout=None)

Reads the specified number of samples received in continuos mode. Samples are returned in the same order as they were received. If timeout is None, blocks until the specified number of samples are received.

Parameters:

• num (int, default: 1 ) –

  The number of samples to read.

• timeout (Optional[float], default: None ) –

  The maximum time to wait for the samples.

Returns:

• List[IMUSample] –

  List of samples. Might be less than num if timeout is set.

Raises:

• RuntimeError –

  If continuos mode is not started.

read_last(timeout=None)

Reads the last sample received in continuos mode. If timeout is None, blocks until a sample is received.

Parameters:

• timeout (Optional[float], default: None ) –

  The maximum time to wait for the sample.

Returns:

• Optional[IMUSample] –

  The latest sample received.

Raises:

• RuntimeError –

  If continuos mode is not started.

reboot_to_bootsel()

Reboots the device to BOOTSEL mode.

start_continuos()

Starts the device in continuos mode. Samples can be read using read_last().

stop()

Stops the device. Disconnects from the device and stops the acquisition.

stop_continuos()

Stops the device in continuos mode.

trigger(rms_threshold, pre_seconds, post_seconds, source='accel', axis='xyz', rms_window=1.0, on_trigger=None)

Triggers the device to start sampling when the RMS value exceeds the threshold.

Parameters:

• rms_threshold (float) –

  The RMS threshold in g.

• pre_seconds (float) –

  The duration before the trigger in seconds.

• post_seconds (float) –

  The duration after the trigger in seconds.

• source (str, default: 'accel' ) –

  The source of the RMS value, either "accel" or "gyro".

• axis (str, default: 'xyz' ) –

  The axis or combination of axes to calculate the RMS value.

• rms_window (float, default: 1.0 ) –

  The window length in seconds to calculate the RMS value.

• on_trigger (Optional[Callable[[float], None]], default: None ) –

  A callback function to call when the trigger is activated. The RMS value is passed as an argument.

Returns:

• Tuple[AcquisitionData, Optional[Exception]] –

  A tuple containing the acquisition data and an exception if any occurred.

deque_get_last_n(data, n)

Get the last n elements from a deque. Does not remove the elements from the deque.

Args: data: Deque with data. n: Number of elements to get.

Returns: List with the last n elements from the deque. If n is greater than the length of the deque, all elements are returned.

deque_slice(dq, start, end=None)

Return a slice from the deque. Behaves like the list slice method.

Args: dq: The deque to slice. start: The starting index of the slice. end : The ending index of the slice.

Returns: deque: A deque containing the specified slice.

detrend(data)

Remove the trend from a list of values.

Args: data: List of values.

Returns: List with the trend removed.

get_unique_filename(path)

Returns a unique filename by appending a sequential number if the file already exists.

Parameters:

• path (str) –

  The path to the original file.

Returns:

• –

  A unique filename.

imu_rms(samples, axes, de_trend=False)

Calculate the root mean square of the acceleration and angular velocity components for the specified axes.

Args: samples: List of IMU samples. axes: String with the axes to calculate the RMS values. Must be a combination of 'x', 'y', and 'z'. de_trend: If True, remove the trend from the data.

Returns: Tuple of the root mean square of the acceleration and angular velocity.

mean(data)

Calculate the mean of a list of values.

Args: data: List of values.

Returns: The mean of the values.

rms(data, de_trend=False)

Calculate the root mean square of a list of values.

data: List of values or a tuple of lists of values. If a tuple is provided, the squares of the values in each list are summed. de_trend: If True, remove the trend from the data.

Returns: The root mean square of the values.

running_rms(data, window_size, de_trend=False)

Calculate the running root mean square of a list of values.

Args: data: List of values. window_size: Size of the window for the running RMS calculation. de_trend: If True, remove the trend from the data.

Returns: List with the running root mean square of the values.