pitaeeg package

Submodules

pitaeeg.exceptions module

Custom exceptions for PitaEEG sensor API.

This module defines exception classes used throughout the PitaEEG sensor library. All exceptions inherit from PitaEEGSensorError, allowing users to catch all sensor-related errors with a single exception handler.

exception pitaeeg.exceptions.InitializationError[source]

Bases: PitaEEGSensorError

Raised when sensor initialization fails.

This exception is raised during Sensor.__init__() when the native API’s Init function returns an error code, indicating that the sensor interface could not be properly initialized.

Common causes include: - Invalid serial port name or port not accessible - Port already in use by another application - Hardware communication failure - Invalid timeout parameters

exception pitaeeg.exceptions.LibraryNotFoundError[source]

Bases: PitaEEGSensorError

Raised when the native library cannot be found or loaded.

This exception is raised when the native C/C++ library required for sensor communication cannot be located in any of the search paths, or when loading the library fails due to platform-specific issues.

This typically occurs when: - The library file is not present in the expected locations - The library file is corrupted or incompatible with the current platform - Required system dependencies are missing

exception pitaeeg.exceptions.MeasurementError[source]

Bases: PitaEEGSensorError

Raised when measurement operation fails.

This exception is raised by various measurement-related methods when: - The sensor is not initialized or connected - Starting/stopping measurement fails - Receiving data fails - Getting sensor status, battery, version, or contact resistance fails

Methods that may raise this exception: - Sensor.start_measurement() - Sensor.receive_data() - Sensor.get_battery_remaining_time() - Sensor.get_version() - Sensor.get_state() - Sensor.get_contact_resistance()

exception pitaeeg.exceptions.PitaEEGSensorError[source]

Bases: Exception

Base exception for PitaEEG sensor API.

All exceptions raised by the PitaEEG sensor library inherit from this base class. This allows catching all sensor-related errors with a single exception handler.

Example

>>> try:
...     sensor = Sensor(port="COM3")
...     sensor.connect("HARU2-001")
... except PitaEEGSensorError as e:
...     print(f"Sensor error: {e}")
exception pitaeeg.exceptions.ScanError[source]

Bases: PitaEEGSensorError

Raised when device scanning fails.

This exception is raised by Sensor.scan_devices() when the scanning operation fails, such as when the startScan API call returns an error code.

Common causes include: - Sensor not initialized - Communication failure with USB receiver - Hardware malfunction

exception pitaeeg.exceptions.SensorConnectionError[source]

Bases: PitaEEGSensorError

Raised when device connection fails.

This exception is raised by Sensor.connect() when: - The device scan fails - The specified device name cannot be found within the timeout period - The connect_device API call returns an error code

Common causes include: - Device not powered on or out of range - Device name mismatch (check with Sensor.scan_devices()) - Device already connected to another application - Communication timeout

pitaeeg.sensor module

Core sensor API for PitaEEG sensor devices.

This module provides the main Sensor class for communicating with PitaEEG sensor devices via the native C/C++ API library. It handles device discovery, connection, measurement, and data acquisition operations.

class pitaeeg.sensor.Sensor(port, library_path=None, com_timeout=5000, scan_timeout=5000)[source]

Bases: object

PitaEEG sensor interface for device communication and data acquisition.

The Sensor class provides a high-level Python interface for communicating with PitaEEG sensor devices. It handles device discovery, connection, measurement control, and data reception through the native C/C++ API library.

The class supports context manager protocol for automatic resource cleanup. When used as a context manager, the sensor will automatically stop measurement, disconnect devices, and release resources when exiting the context.

Example

Basic usage:

sensor = Sensor(port="COM3", library_path="path/to/lib")
sensor.scan_devices(timeout=10)
sensor.connect("HARU2-001")
sensor.start_measurement()
for data in sensor.receive_data():
    print(data)
sensor.stop_measurement()
sensor.disconnect()
sensor.close()

Using as a context manager:

with Sensor(port="COM3") as sensor:
    devices = sensor.scan_devices()
    sensor.connect("HARU2-001")
    sensor.start_measurement()
    for data in sensor.receive_data():
        process_data(data)
close()[source]

Close the sensor interface and release resources.

This method attempts to safely stop measurement, disconnect the device, and terminate the sensor handle. All operations are best-effort and any internal errors are ignored. This function never raises exceptions.

Return type:

None

Note

  • If measurement is active, it will be stopped.

  • If a device is connected, it will be disconnected.

  • If a handle is present, it will be terminated.

  • If any step fails, the error is silently ignored.

connect(device_name, scan_timeout=10.0)[source]

Connect to a specific device.

Scans for devices and connects to the device matching the specified name. This method must be called before starting measurements. Use scan_devices() to discover available device names.

Return type:

None

Parameters:

  • device_name (str) – Name of the device to connect to (e.g., “HARU2-001”). This should match one of the device names returned by scan_devices().

  • scan_timeout (float) – Maximum time to wait for the device to be found in seconds. Defaults to 10.0 seconds.

Raises:

SensorConnectionError – If the sensor is not initialized, device scanning fails, the device is not found, or connection fails.

disconnect()[source]

Disconnect from the EEG device.

If a measurement is active, it will be stopped first. After disconnecting, the internal connection state is cleared.

Return type:

None

Note

This method does not raise exceptions directly. If the sensor was never connected (i.e., _connected_device is None), this method does nothing.

get_battery_remaining_time()[source]

Get remaining battery time.

Retrieves the estimated remaining battery time from the connected sensor device. The returned value represents the estimated remaining battery time in minutes.

Return type:

float

Returns:

Remaining battery time in minutes.

Return type:

float

Raises:

MeasurementError – If the sensor is not initialized or if the operation fails.

get_contact_resistance()[source]

Get electrode contact resistance data.

Retrieves the electrical contact resistance measurements for each electrode from the connected sensor device. Contact resistance is a measure of the electrical impedance between the electrode and the skin. Lower resistance values indicate better electrode contact.

Return type:

ContactResistance

Returns:

Structure containing raw resistance values

(ChZ, ChR, ChL). The values are expressed in ohms (Ω). Lower values (typically < 10 kΩ) indicate good contact.

Return type:

ContactResistance

Raises:

MeasurementError – If the sensor is not initialized or the native API call fails.

Note

High resistance values (> 50 kΩ) may indicate poor electrode contact and can result in increased noise or signal artifacts in the EEG data.

get_state()[source]

Get the current sensor state and error code.

Retrieves the current operating state and error status from the connected sensor device. This information can be used to diagnose device issues and monitor measurement status.

Return type:

tuple[int, int]

Returns:

A tuple (state, error) where:

Sensor State (SENSOR_STATE) Represents the operating status of the EEG device:

  • INITIAL (0): Initial state

  • WAIT_CONNECT (1): Waiting for device connection

  • IDLE (2): Waiting to start measurement

  • MEASURE (3): Measuring via wireless mode

  • STORE (4): Measuring in storage mode

  • ERR (0x80 / 128): Error state flag

Multiple states may be combined using a logical OR.

Sensor Error (SENSOR_ERROR) Represents abnormal conditions detected by the device:

  • ELECTRODE_NOT_CONNECTED (0x01): Electrode sheet not connected

  • AFE_COMM_ERROR (0x02): Hardware communication error ※

  • BLE_IC_COMM_ERROR_CMD (0x03): BLE IC command communication error ※

  • BLE_IC_COMM_ERROR_DATA (0x04): BLE IC data communication error ※

  • CHARGE_ERROR (0x05): Charging-related hardware error ※

  • BATTERY_REMAINING_ERROR (0x06): Battery remaining below 5%

  • STORAGE_ERROR (0x07): Failed to save data to storage

  • BLE_COMM_ERROR (0x08): BLE communication hardware error ※

  • USB_COMM_ERROR (0x09): USB communication hardware error ※

  • ERROR_END (0x0A): General hardware error flag ※

※ If this error occurs, please contact PGV support.

Return type:

tuple[int, int]

Raises:

MeasurementError – If the sensor is not initialized or the API call fails.

get_version()[source]

Get sensor firmware version.

Retrieves the firmware version from the connected sensor device. The version is returned as a floating-point number.

Return type:

float

Returns:

Firmware version value from the device.

Return type:

float

Raises:

MeasurementError – If the sensor is not initialized or the native API call fails.

property is_connected: bool

Check if a device is currently connected.

Returns:

True if a device is connected, False otherwise.

Return type:

bool

property is_measuring: bool

Check if measurement is currently active.

Returns:

True if measurement is active, False otherwise.

Return type:

bool

receive_data()[source]

Receive data from the sensor.

This method returns a generator that yields EEG data packets as they become available from the sensor. The generator will continue to yield data until measurement is stopped via stop_measurement().

Each yielded ReceiveData2 object contains: - EEG channel data (3 channels for HARU2) - Battery level percentage - Data repair/correction flag

Return type:

Generator[ReceiveData2, None, None]

Note

This method blocks until data is available. To stop receiving data, call stop_measurement() from another thread or use a timeout mechanism.

Yields:

ReceiveData2 –

Received data structure containing EEG measurements

and sensor status information.

Raises:

MeasurementError – If the sensor is not initialized or measurement is not started.

Example

>>> sensor.start_measurement()
>>> for data in sensor.receive_data():
...     print(f"Channels: {data.data}, Battery: {data.batlevel}%")
...     if some_condition:
...         sensor.stop_measurement()
...         break
scan_devices(timeout=10.0)[source]

Scan for available devices.

Initiates a device scan operation to discover PitaEEG sensors that are within communication range. The scan continues until devices are found or the timeout expires. The scan will stop early if devices are found before the timeout.

Return type:

list[dict[str, str]]

Parameters:

timeout (float) – Maximum time to wait for devices in seconds. Defaults to 10.0 seconds.

Returns:

List of dictionaries containing device information.

Each dictionary contains: - name (str): Device name (e.g., “HARU2-001”) - id (str): Device ID as a hexadecimal string

Return type:

list[dict[str, str]]

Raises:

ScanError – If the sensor is not initialized or scanning fails.

start_measurement()[source]

Start EEG measurement.

Starts measurement using all available channels. This method must be called after a device has been connected via connect(). After starting measurement, data can be received using receive_data().

The returned device time represents the timestamp from the sensor device when measurement began, allowing synchronization with the device clock.

Return type:

int

Returns:

Device time in milliseconds since epoch (Unix timestamp * 1000).

This timestamp represents when the sensor device started measurement and can be used for time synchronization with other data streams.

Return type:

int

Raises:

MeasurementError – If the sensor is not initialized, no device is connected, or starting measurement fails.

stop_measurement()[source]

Stop ongoing EEG measurement.

Stops measurement only if the device is initialized and currently measuring. If no measurement is active, this function does nothing.

Return type:

None

Note

This method does not raise exceptions directly, but subsequent API calls depending on measurement state may fail if measurement was never started.

pitaeeg.types module

Data types and structures for PitaEEG sensor API.

This module defines ctypes structures and constants used for communication with the PitaEEG sensor native API library.

class pitaeeg.types.ContactResistance[source]

Bases: Structure

Contact resistance values for each EEG channel.

Contains the electrical contact resistance measurements for each electrode. Contact resistance is a measure of the electrical impedance between the electrode and the skin. Lower resistance values indicate better electrode contact with the skin, which generally leads to higher quality EEG signals.

This structure is returned by Sensor.get_contact_resistance() to provide real-time feedback on electrode contact quality.

ChZ

Contact resistance for the Z channel (ground/reference) in ohms (Ω). Lower values (typically < 10 kΩ) indicate good contact.

Type:

float

ChR

Contact resistance for the R channel (right hemisphere) in ohms (Ω). Lower values (typically < 10 kΩ) indicate good contact.

Type:

float

ChL

Contact resistance for the L channel (left hemisphere) in ohms (Ω). Lower values (typically < 10 kΩ) indicate good contact.

Type:

float

Note

High resistance values (> 50 kΩ) may indicate poor electrode contact and can result in increased noise or signal artifacts in the EEG data.

ChL

Structure/Union member

ChR

Structure/Union member

ChZ

Structure/Union member

class pitaeeg.types.DeviceInfo[source]

Bases: Structure

Device information structure.

Contains identifying information for a PitaEEG sensor device discovered during scanning operations. This structure is used internally for device connection and identification.

deviceid

Device ID as an array of bytes (8 bytes). Typically represented as a hexadecimal string when displayed to users.

Type:

bytes

devicename

Device name as a null-terminated C string (24 bytes max). Contains the human-readable device name (e.g., “HARU2-001”).

Type:

bytes

deviceid

Structure/Union member

devicename

Structure/Union member

pitaeeg.types.HARU2_CH_NUM = 3

Number of EEG channels for HARU2 sensor model (int).

pitaeeg.types.MAX_CH = 8

Maximum number of EEG channels supported (int).

pitaeeg.types.MAX_DEVICEADDR_LEN = 8

Maximum length of device address in bytes (int).

pitaeeg.types.MAX_DEVICENAME_LEN = 24

Maximum length of device name in bytes (int).

class pitaeeg.types.ReceiveData2[source]

Bases: Structure

Received data structure for HARU2 sensor.

Contains EEG measurement data received from the sensor device during active measurement. This structure is yielded by the Sensor.receive_data() generator.

data

Array of EEG channel data values (3 channels for HARU2). Each value represents the measured voltage in microvolts (µV). The array length matches HARU2_CH_NUM.

Type:

list[float]

batlevel

Battery level percentage ranging from 0.0 to 100.0. Indicates the current charge level of the sensor device.

Type:

float

isRepair

Repair flag indicating data correction status. Value of 0 indicates normal data, 1 indicates that data correction algorithms were applied to compensate for signal quality issues.

Type:

int

batlevel

Structure/Union member

data

Structure/Union member

isRepair

Structure/Union member

class pitaeeg.types.SensorParam[source]

Bases: Structure

Sensor parameter structure.

Contains configuration parameters for sensor measurement channels. This structure is used to specify which EEG channels should be enabled during measurement operations.

usech

Array indicating which channels to use (8 bytes). Each byte represents a channel usage flag where 0 indicates the channel is unused and 1 indicates the channel is used. The array length matches MAX_CH.

Type:

bytes

reserve

Reserved field for future use (32 bytes). This field should be set to zero and is reserved for future API extensions.

Type:

bytes

reserve

Structure/Union member

usech

Structure/Union member

class pitaeeg.types.TimesetParam[source]

Bases: Structure

Timeout parameters for communication and scanning.

This structure is used to configure timeout values for serial communication and device scanning operations when initializing the sensor interface.

com_timeout

Communication timeout in milliseconds. Determines how long to wait for responses during serial communication.

Type:

int

scan_timeout

Device scanning timeout in milliseconds. Determines how long to wait for devices to respond during scanning operations.

Type:

int

com_timeout

Structure/Union member

scan_timeout

Structure/Union member

Module contents

PitaEEG Sensor Library for Python.

This package provides a Python interface for communicating with PitaEEG sensor devices. It enables device discovery, connection, measurement, and data acquisition through a high-level API.

The main entry point is the Sensor class, which manages the connection to a sensor device and provides methods for scanning devices, connecting, starting/stopping measurements, and receiving EEG data.

The library is designed to work with LabStreamingLayer (LSL) for real-time data streaming and synchronization with other neuroscience tools.

Example

Basic usage of the Sensor class:

from pitaeeg import Sensor

# Create and initialize sensor
sensor = Sensor(port="COM3")

# Scan for available devices
devices = sensor.scan_devices(timeout=10.0)

# Connect to a specific device
sensor.connect("HARU2-001")

# Start measurement
device_time = sensor.start_measurement()

# Receive data
for data in sensor.receive_data():
    print(f"Channels: {data.data}, Battery: {data.batlevel}%")

# Clean up
sensor.stop_measurement()
sensor.disconnect()
sensor.close()

Using as a context manager:

with Sensor(port="COM3") as sensor:
    devices = sensor.scan_devices()
    sensor.connect("HARU2-001")
    sensor.start_measurement()
    for data in sensor.receive_data():
        process_data(data)

Note

This library requires the native PitaEEG API library to function. The library file must be placed in the appropriate platform-specific directory (libs/macos/arm64/, libs/linux/, libs/windows/) or provided via the library_path parameter.

See also

  • Sensor: Main sensor interface class

  • pitaeeg.types.DeviceInfo: Device information structure

  • pitaeeg.types.ReceiveData2: EEG data structure

  • pitaeeg.types.ContactResistance: Contact resistance measurements

class pitaeeg.ContactResistance[source]

Bases: Structure

Contact resistance values for each EEG channel.

Contains the electrical contact resistance measurements for each electrode. Contact resistance is a measure of the electrical impedance between the electrode and the skin. Lower resistance values indicate better electrode contact with the skin, which generally leads to higher quality EEG signals.

This structure is returned by Sensor.get_contact_resistance() to provide real-time feedback on electrode contact quality.

ChZ

Contact resistance for the Z channel (ground/reference) in ohms (Ω). Lower values (typically < 10 kΩ) indicate good contact.

Type:

float

ChR

Contact resistance for the R channel (right hemisphere) in ohms (Ω). Lower values (typically < 10 kΩ) indicate good contact.

Type:

float

ChL

Contact resistance for the L channel (left hemisphere) in ohms (Ω). Lower values (typically < 10 kΩ) indicate good contact.

Type:

float

Note

High resistance values (> 50 kΩ) may indicate poor electrode contact and can result in increased noise or signal artifacts in the EEG data.

ChL

Structure/Union member

ChR

Structure/Union member

ChZ

Structure/Union member

class pitaeeg.DeviceInfo[source]

Bases: Structure

Device information structure.

Contains identifying information for a PitaEEG sensor device discovered during scanning operations. This structure is used internally for device connection and identification.

deviceid

Device ID as an array of bytes (8 bytes). Typically represented as a hexadecimal string when displayed to users.

Type:

bytes

devicename

Device name as a null-terminated C string (24 bytes max). Contains the human-readable device name (e.g., “HARU2-001”).

Type:

bytes

deviceid

Structure/Union member

devicename

Structure/Union member

exception pitaeeg.InitializationError[source]

Bases: PitaEEGSensorError

Raised when sensor initialization fails.

This exception is raised during Sensor.__init__() when the native API’s Init function returns an error code, indicating that the sensor interface could not be properly initialized.

Common causes include: - Invalid serial port name or port not accessible - Port already in use by another application - Hardware communication failure - Invalid timeout parameters

exception pitaeeg.LibraryNotFoundError[source]

Bases: PitaEEGSensorError

Raised when the native library cannot be found or loaded.

This exception is raised when the native C/C++ library required for sensor communication cannot be located in any of the search paths, or when loading the library fails due to platform-specific issues.

This typically occurs when: - The library file is not present in the expected locations - The library file is corrupted or incompatible with the current platform - Required system dependencies are missing

exception pitaeeg.MeasurementError[source]

Bases: PitaEEGSensorError

Raised when measurement operation fails.

This exception is raised by various measurement-related methods when: - The sensor is not initialized or connected - Starting/stopping measurement fails - Receiving data fails - Getting sensor status, battery, version, or contact resistance fails

Methods that may raise this exception: - Sensor.start_measurement() - Sensor.receive_data() - Sensor.get_battery_remaining_time() - Sensor.get_version() - Sensor.get_state() - Sensor.get_contact_resistance()

exception pitaeeg.PitaEEGSensorError[source]

Bases: Exception

Base exception for PitaEEG sensor API.

All exceptions raised by the PitaEEG sensor library inherit from this base class. This allows catching all sensor-related errors with a single exception handler.

Example

>>> try:
...     sensor = Sensor(port="COM3")
...     sensor.connect("HARU2-001")
... except PitaEEGSensorError as e:
...     print(f"Sensor error: {e}")
class pitaeeg.ReceiveData2[source]

Bases: Structure

Received data structure for HARU2 sensor.

Contains EEG measurement data received from the sensor device during active measurement. This structure is yielded by the Sensor.receive_data() generator.

data

Array of EEG channel data values (3 channels for HARU2). Each value represents the measured voltage in microvolts (µV). The array length matches HARU2_CH_NUM.

Type:

list[float]

batlevel

Battery level percentage ranging from 0.0 to 100.0. Indicates the current charge level of the sensor device.

Type:

float

isRepair

Repair flag indicating data correction status. Value of 0 indicates normal data, 1 indicates that data correction algorithms were applied to compensate for signal quality issues.

Type:

int

batlevel

Structure/Union member

data

Structure/Union member

isRepair

Structure/Union member

exception pitaeeg.ScanError[source]

Bases: PitaEEGSensorError

Raised when device scanning fails.

This exception is raised by Sensor.scan_devices() when the scanning operation fails, such as when the startScan API call returns an error code.

Common causes include: - Sensor not initialized - Communication failure with USB receiver - Hardware malfunction

class pitaeeg.Sensor(port, library_path=None, com_timeout=5000, scan_timeout=5000)[source]

Bases: object

PitaEEG sensor interface for device communication and data acquisition.

The Sensor class provides a high-level Python interface for communicating with PitaEEG sensor devices. It handles device discovery, connection, measurement control, and data reception through the native C/C++ API library.

The class supports context manager protocol for automatic resource cleanup. When used as a context manager, the sensor will automatically stop measurement, disconnect devices, and release resources when exiting the context.

Example

Basic usage:

sensor = Sensor(port="COM3", library_path="path/to/lib")
sensor.scan_devices(timeout=10)
sensor.connect("HARU2-001")
sensor.start_measurement()
for data in sensor.receive_data():
    print(data)
sensor.stop_measurement()
sensor.disconnect()
sensor.close()

Using as a context manager:

with Sensor(port="COM3") as sensor:
    devices = sensor.scan_devices()
    sensor.connect("HARU2-001")
    sensor.start_measurement()
    for data in sensor.receive_data():
        process_data(data)
close()[source]

Close the sensor interface and release resources.

This method attempts to safely stop measurement, disconnect the device, and terminate the sensor handle. All operations are best-effort and any internal errors are ignored. This function never raises exceptions.

Return type:

None

Note

  • If measurement is active, it will be stopped.

  • If a device is connected, it will be disconnected.

  • If a handle is present, it will be terminated.

  • If any step fails, the error is silently ignored.

connect(device_name, scan_timeout=10.0)[source]

Connect to a specific device.

Scans for devices and connects to the device matching the specified name. This method must be called before starting measurements. Use scan_devices() to discover available device names.

Return type:

None

Parameters:

  • device_name (str) – Name of the device to connect to (e.g., “HARU2-001”). This should match one of the device names returned by scan_devices().

  • scan_timeout (float) – Maximum time to wait for the device to be found in seconds. Defaults to 10.0 seconds.

Raises:

SensorConnectionError – If the sensor is not initialized, device scanning fails, the device is not found, or connection fails.

disconnect()[source]

Disconnect from the EEG device.

If a measurement is active, it will be stopped first. After disconnecting, the internal connection state is cleared.

Return type:

None

Note

This method does not raise exceptions directly. If the sensor was never connected (i.e., _connected_device is None), this method does nothing.

get_battery_remaining_time()[source]

Get remaining battery time.

Retrieves the estimated remaining battery time from the connected sensor device. The returned value represents the estimated remaining battery time in minutes.

Return type:

float

Returns:

Remaining battery time in minutes.

Return type:

float

Raises:

MeasurementError – If the sensor is not initialized or if the operation fails.

get_contact_resistance()[source]

Get electrode contact resistance data.

Retrieves the electrical contact resistance measurements for each electrode from the connected sensor device. Contact resistance is a measure of the electrical impedance between the electrode and the skin. Lower resistance values indicate better electrode contact.

Return type:

ContactResistance

Returns:

Structure containing raw resistance values

(ChZ, ChR, ChL). The values are expressed in ohms (Ω). Lower values (typically < 10 kΩ) indicate good contact.

Return type:

ContactResistance

Raises:

MeasurementError – If the sensor is not initialized or the native API call fails.

Note

High resistance values (> 50 kΩ) may indicate poor electrode contact and can result in increased noise or signal artifacts in the EEG data.

get_state()[source]

Get the current sensor state and error code.

Retrieves the current operating state and error status from the connected sensor device. This information can be used to diagnose device issues and monitor measurement status.

Return type:

tuple[int, int]

Returns:

A tuple (state, error) where:

Sensor State (SENSOR_STATE) Represents the operating status of the EEG device:

  • INITIAL (0): Initial state

  • WAIT_CONNECT (1): Waiting for device connection

  • IDLE (2): Waiting to start measurement

  • MEASURE (3): Measuring via wireless mode

  • STORE (4): Measuring in storage mode

  • ERR (0x80 / 128): Error state flag

Multiple states may be combined using a logical OR.

Sensor Error (SENSOR_ERROR) Represents abnormal conditions detected by the device:

  • ELECTRODE_NOT_CONNECTED (0x01): Electrode sheet not connected

  • AFE_COMM_ERROR (0x02): Hardware communication error ※

  • BLE_IC_COMM_ERROR_CMD (0x03): BLE IC command communication error ※

  • BLE_IC_COMM_ERROR_DATA (0x04): BLE IC data communication error ※

  • CHARGE_ERROR (0x05): Charging-related hardware error ※

  • BATTERY_REMAINING_ERROR (0x06): Battery remaining below 5%

  • STORAGE_ERROR (0x07): Failed to save data to storage

  • BLE_COMM_ERROR (0x08): BLE communication hardware error ※

  • USB_COMM_ERROR (0x09): USB communication hardware error ※

  • ERROR_END (0x0A): General hardware error flag ※

※ If this error occurs, please contact PGV support.

Return type:

tuple[int, int]

Raises:

MeasurementError – If the sensor is not initialized or the API call fails.

get_version()[source]

Get sensor firmware version.

Retrieves the firmware version from the connected sensor device. The version is returned as a floating-point number.

Return type:

float

Returns:

Firmware version value from the device.

Return type:

float

Raises:

MeasurementError – If the sensor is not initialized or the native API call fails.

property is_connected: bool

Check if a device is currently connected.

Returns:

True if a device is connected, False otherwise.

Return type:

bool

property is_measuring: bool

Check if measurement is currently active.

Returns:

True if measurement is active, False otherwise.

Return type:

bool

receive_data()[source]

Receive data from the sensor.

This method returns a generator that yields EEG data packets as they become available from the sensor. The generator will continue to yield data until measurement is stopped via stop_measurement().

Each yielded ReceiveData2 object contains: - EEG channel data (3 channels for HARU2) - Battery level percentage - Data repair/correction flag

Return type:

Generator[ReceiveData2, None, None]

Note

This method blocks until data is available. To stop receiving data, call stop_measurement() from another thread or use a timeout mechanism.

Yields:

ReceiveData2 –

Received data structure containing EEG measurements

and sensor status information.

Raises:

MeasurementError – If the sensor is not initialized or measurement is not started.

Example

>>> sensor.start_measurement()
>>> for data in sensor.receive_data():
...     print(f"Channels: {data.data}, Battery: {data.batlevel}%")
...     if some_condition:
...         sensor.stop_measurement()
...         break
scan_devices(timeout=10.0)[source]

Scan for available devices.

Initiates a device scan operation to discover PitaEEG sensors that are within communication range. The scan continues until devices are found or the timeout expires. The scan will stop early if devices are found before the timeout.

Return type:

list[dict[str, str]]

Parameters:

timeout (float) – Maximum time to wait for devices in seconds. Defaults to 10.0 seconds.

Returns:

List of dictionaries containing device information.

Each dictionary contains: - name (str): Device name (e.g., “HARU2-001”) - id (str): Device ID as a hexadecimal string

Return type:

list[dict[str, str]]

Raises:

ScanError – If the sensor is not initialized or scanning fails.

start_measurement()[source]

Start EEG measurement.

Starts measurement using all available channels. This method must be called after a device has been connected via connect(). After starting measurement, data can be received using receive_data().

The returned device time represents the timestamp from the sensor device when measurement began, allowing synchronization with the device clock.

Return type:

int

Returns:

Device time in milliseconds since epoch (Unix timestamp * 1000).

This timestamp represents when the sensor device started measurement and can be used for time synchronization with other data streams.

Return type:

int

Raises:

MeasurementError – If the sensor is not initialized, no device is connected, or starting measurement fails.

stop_measurement()[source]

Stop ongoing EEG measurement.

Stops measurement only if the device is initialized and currently measuring. If no measurement is active, this function does nothing.

Return type:

None

Note

This method does not raise exceptions directly, but subsequent API calls depending on measurement state may fail if measurement was never started.

exception pitaeeg.SensorConnectionError[source]

Bases: PitaEEGSensorError

Raised when device connection fails.

This exception is raised by Sensor.connect() when: - The device scan fails - The specified device name cannot be found within the timeout period - The connect_device API call returns an error code

Common causes include: - Device not powered on or out of range - Device name mismatch (check with Sensor.scan_devices()) - Device already connected to another application - Communication timeout

class pitaeeg.SensorParam[source]

Bases: Structure

Sensor parameter structure.

Contains configuration parameters for sensor measurement channels. This structure is used to specify which EEG channels should be enabled during measurement operations.

usech

Array indicating which channels to use (8 bytes). Each byte represents a channel usage flag where 0 indicates the channel is unused and 1 indicates the channel is used. The array length matches MAX_CH.

Type:

bytes

reserve

Reserved field for future use (32 bytes). This field should be set to zero and is reserved for future API extensions.

Type:

bytes

reserve

Structure/Union member

usech

Structure/Union member

class pitaeeg.TimesetParam[source]

Bases: Structure

Timeout parameters for communication and scanning.

This structure is used to configure timeout values for serial communication and device scanning operations when initializing the sensor interface.

com_timeout

Communication timeout in milliseconds. Determines how long to wait for responses during serial communication.

Type:

int

scan_timeout

Device scanning timeout in milliseconds. Determines how long to wait for devices to respond during scanning operations.

Type:

int

com_timeout

Structure/Union member

scan_timeout

Structure/Union member