explorepy

Main API

class explore.Explore

Bases: object

Mentalab Explore device

connect(device_name=None, mac_address=None)

Connects to the nearby device. If there are more than one device, the user is asked to choose one of them.

Parameters:

• device_name (str) – Device name(“Explore_XXXX”). Either mac address or name should be in the input
• mac_address (str) – The MAC address in format “XX:XX:XX:XX:XX:XX”

disconnect()

Disconnects from the device

acquire(duration=None)

Start getting data from the device

Parameters:duration (float) – duration of acquiring data (if None it streams data endlessly)

record_data(file_name, do_overwrite=False, duration=None, file_type='csv', block=False)

Records the data in real-time

Parameters:

• file_name (str) – Output file name
• do_overwrite (bool) – Overwrite if files exist already
• duration (float) – Duration of recording in seconds (if None records endlessly).
• file_type (str) – File type of the recorded file. Supported file types: ‘csv’, ‘edf’

stop_recording()

Stop recording

convert_bin(bin_file, out_dir='', file_type='edf', do_overwrite=False)

Convert a binary file to EDF or CSV file

Parameters:

• bin_file (str) – Path to the binary file recorded by Explore device
• out_dir (str) – Output directory path (must be relative path to the current working directory)
• file_type (str) – Output file type: ‘edf’ for EDF format and ‘csv’ for CSV format
• do_overwrite (bool) – Whether to overwrite an existing file

push2lsl(duration=None)

Push samples to two lsl streams (ExG and ORN streams)

Parameters:duration (float) – duration of data acquiring (if None it streams for one hour).

visualize(bp_freq=(1, 30), notch_freq=50)

Visualization of the signal in the dashboard

Parameters:

• bp_freq (tuple) – Bandpass filter cut-off frequencies (low_cutoff_freq, high_cutoff_freq), No bandpass filter
• if it is None.
• notch_freq (int) – Line frequency for notch filter (50 or 60 Hz), No notch filter if it is None

measure_imp()

Visualization of the electrode impedances

Parameters:notch_freq (int) – Notch frequency for filtering the line noise (50 or 60 Hz)

set_marker(code)

Sets a digital event marker while streaming

Parameters:code (int) – Marker code. It must be an integer larger than 7 (codes from 0 to 7 are reserved for hardware markers).

format_memory()

Format memory of the device

set_sampling_rate(sampling_rate)

Set sampling rate

Parameters:sampling_rate (int) – Desired sampling rate. Options: 250, 500, 1000

reset_soft()

Reset the device to the default settings

set_channels(channel_mask)

Set the channel mask of the device

The channels can be disabled/enabled by calling this function and passing an integer which represents the binary form of the mask. For example in a 4 channel device, if you want to disable channel 4, the adc mask should be b’0111’ (LSB is channel 1). The integer value of 0111 which is 7 must be given to this function

Parameters:channel_mask (int) – Integer representation of the binary channel mask

Examples

>>> from explorepy.explore import Explore
>>> explore = Explore()
>>> explore.connect(device_name='Explore_2FA2')
>>> explore.set_channels(channel_mask=7)  # disable channel 4 - mask:0111

disable_module(module_name)

Disable module

Parameters:module_name (str) – Module to be disabled (options: ‘ENV’, ‘ORN’, ‘EXG’)

Examples

>>> from explorepy.explore import Explore
>>> explore = Explore()
>>> explore.connect(device_name='Explore_2FA2')
>>> explore.disable_module('ORN')

enable_module(module_name)

Enable module

Parameters:module_name (str) – Module to be disabled (options: ‘ENV’, ‘ORN’, ‘EXG’)

Examples

>>> from explorepy.explore import Explore
>>> explore = Explore()
>>> explore.connect(device_name='Explore_2FA2')
>>> explore.enable_module('ORN')

calibrate_orn(do_overwrite=False)

Calibrate orientation module

This method calibrates orientation sensors in order to get the real physical orientation in addition to raw sensor data. While running this function you would need to move and rotate the device. This function will store calibration info in the configuration file which will be used later during streaming to calculate physical orientation from raw sensor data.

Parameters:do_overwrite – to overwrite the calibration data if already exists or not

Bluetooth API

A module for bluetooth connection

class bt_client.BtClient(device_name=None, mac_address=None)

Bases: object

Responsible for Connecting and reconnecting explore devices via bluetooth

Initialize Bluetooth connection

Parameters:

• device_name (str) – Name of the device (either device_name or device address should be given)
• mac_address (str) – Devices MAC address

connect()

Connect to the device and return the socket

Returns:socket (bluetooth.socket)

reconnect()

Reconnect to the last used bluetooth socket.

This function reconnects to the the last bluetooth socket. If after 1 minute the connection doesn’t succeed, program will end.

disconnect()

Disconnect from the device

_find_mac_address()

_find_service()

read(n_bytes)

Read n_bytes from the socket

Parameters:n_bytes (int) – number of bytes to be read Returns:list of bytes

send(data)

Send data to the device

Parameters:data (bytearray) – Data to be sent

static _check_mac_address(device_name, mac_address)

Parser

Parser module

class parser.Parser(callback, mode='device')

Bases: object

Data parser class

Parameters:

• callback (function) – function to be called when new packet is received
• mode (str) – Parsing mode either from an Explore device or a binary file {‘device’, ‘file’}

start_streaming(device_name, mac_address)

Start streaming data from Explore device

stop_streaming()

Stop streaming data

start_reading(filename)

Open the binary file :Parameters: filename (str) – Binary file name

read_device_info(filename)

_stream(new_thread=True)

_stream_loop()

_generate_packet()

Reads and parses a package from a file or socket

Returns:packet object

static _parse_packet(pid, timestamp, bin_data)

Generates the packets according to the pid

Parameters:

• pid (int) – Packet ID
• timestamp (int) – Timestamp
• bin_data – Binary dat

Returns:

Packet

class parser.FileHandler(filename)

Bases: object

Binary file handler

Parameters:filename (str) – Binary file name

read(n_bytes)

Read n bytes from file :Parameters: n_bytes (int) – Number of bytes to be read

disconnect()

Close file

This module contains all packet classes of Mentalab Explore device

class packet.PACKET_ID

Bases: enum.IntEnum

Packet ID enum

ORN = 13

ENV = 19

TS = 27

DISCONNECT = 111

INFO = 99

EEG94 = 144

EEG98 = 146

EEG99S = 30

EEG99 = 62

EEG94R = 208

EEG98R = 210

CMDRCV = 192

CMDSTAT = 193

MARKER = 194

CALIBINFO = 195

class packet.Packet(timestamp, payload)

Bases: object

An abstract base class for Explore packet

Gets the timestamp and payload and initializes the packet object

Parameters:payload (bytearray) – a byte array including binary data and fletcher

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

__str__()

Print the data/info

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.EEG(timestamp, payload)

Bases: packet.Packet

EEG packet class

Gets the timestamp and payload and initializes the packet object

Parameters:payload (bytearray) – a byte array including binary data and fletcher

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

get_data(exg_fs=None)

get time vector and data

If exg_fs is given, it returns time vector and data. If exg_fs is not given, it returns the timestamp of the packet alongside with the data

get_impedances()

get electrode impedances

get_ptp()

Get peak to peak value

__str__()

Print the data/info

_check_fletcher(fletcher)

Checks if the fletcher is valid

_convert(bin_data)

Read the binary data and convert it to real values

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.EEG94(timestamp, payload)

Bases: packet.EEG

EEG packet for 4 channel device

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

get_data(exg_fs=None)

get time vector and data

If exg_fs is given, it returns time vector and data. If exg_fs is not given, it returns the timestamp of the packet alongside with the data

get_impedances()

get electrode impedances

get_ptp()

Get peak to peak value

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.EEG98(timestamp, payload)

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

get_data(exg_fs=None)

get time vector and data

If exg_fs is given, it returns time vector and data. If exg_fs is not given, it returns the timestamp of the packet alongside with the data

get_impedances()

get electrode impedances

get_ptp()

Get peak to peak value

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.EEG99s(timestamp, payload)

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

get_data(exg_fs=None)

get time vector and data

If exg_fs is given, it returns time vector and data. If exg_fs is not given, it returns the timestamp of the packet alongside with the data

get_impedances()

get electrode impedances

get_ptp()

Get peak to peak value

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.EEG99(timestamp, payload)

Bases: packet.EEG

EEG packet for 8 channel device

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

calculate_impedance(imp_calib_info)

calculate impedance with the help of impedance calibration info

Parameters:imp_calib_info (dict) – dictionary of impedance calibration info including slope, offset and noise level

get_data(exg_fs=None)

get time vector and data

If exg_fs is given, it returns time vector and data. If exg_fs is not given, it returns the timestamp of the packet alongside with the data

get_impedances()

get electrode impedances

get_ptp()

Get peak to peak value

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.Orientation(timestamp, payload)

Bases: packet.Packet

Orientation data packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

get_data(srate=None)

Get orientation timestamp and data

compute_angle(matrix=None)

Compute physical angle

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.Environment(timestamp, payload)

Bases: packet.Packet

Environment data packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

get_data()

Get environment data

static _volt_to_percent(voltage)

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.TimeStamp(timestamp, payload)

Bases: packet.Packet

Time stamp data packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.EventMarker(timestamp, payload)

Bases: packet.Packet

Marker packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

get_data(srate=None)

Get marker data :Parameters: srate – NOT USED. Only for compatibility purpose

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.Disconnect(timestamp, payload)

Bases: packet.Packet

Disconnect packet

_convert(bin_data)

Disconnect packet has no data

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.DeviceInfo(timestamp, payload)

Bases: packet.Packet

Device information packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

get_info()

Get device information as a dictionary

get_data()

Get firmware version

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.CommandRCV(timestamp, payload)

Bases: packet.Packet

Command Status packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.CommandStatus(timestamp, payload)

Bases: packet.Packet

Command Status packet

_convert(bin_data)

Read the binary data and convert it to real values

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

class packet.CalibrationInfo(timestamp, payload)

Bases: packet.Packet

Calibration Info packet

_convert(bin_data)

Read the binary data and convert it to real values

get_info()

Get calibration info

_check_fletcher(fletcher)

Checks if the fletcher is valid

static int24to32(bin_data)

Converts binary data to int32

Parameters:bin_data (list) – list of bytes with the structure of int24 Returns:np.ndarray of int values

Dashboard

class dashboard.dashboard.Dashboard(explore=None, mode='signal')

Bases: object

Explorepy dashboard class

Parameters:stream_processor (explorepy.stream_processor.StreamProcessor) – Stream processor object

start_server()

Start bokeh server

start_loop()

Start io loop and show the dashboard

exg_callback(packet)

Update ExG data in the visualization

Parameters:packet (explorepy.packet.EEG) – Received ExG packet

orn_callback(packet)

Update orientation data

Parameters:packet (explorepy.packet.Orientation) – Orientation packet

info_callback(packet)

Update device information in the dashboard

Parameters:packet (explorepy.packet.Environment) – Environment/DeviceInfo packet

marker_callback(packet)

Update markers :Parameters: packet (explorepy.packet.EventMarker) – Event marker packet

impedance_callback(packet)

Update impedances

Parameters:packet (explorepy.packet.EEG) – ExG packet

_update_fft()

Update spectral frequency analysis plot

_update_heart_rate()

Detect R-peaks and update the plot and heart rate

_change_scale(attr, old, new)

Change y-scale of ExG plot

_change_t_range(attr, old, new)

Change time range

_change_mode(attr, old, new)

Set EEG or ECG mode

_init_plots()

Initialize all plots in the dashboard

_init_controls()

Initialize all controls in the dashboard

_set_t_range(t_length)

Change time range of ExG and orientation plots

Additional tools

Some useful tools such as file recorder, heart rate estimation, etc. used in explorepy

tools.bt_scan()

“Scan for bluetooth devices Scans for available explore devices. Prints out MAC address and name of each found device

Args:

Returns:

tools.create_exg_recorder(filename, file_type, adc_mask, fs, do_overwrite)

tools.create_orn_recorder(filename, file_type, do_overwrite)

tools.create_marker_recorder(filename, do_overwrite)

class tools.HeartRateEstimator(fs=250, smoothing_win=20)

Bases: object

Real-time heart Rate Estimator class This class provides the tools for heart rate estimation. It basically detects R-peaks in ECG signal using the method explained in Hamilton 2002 [2].

Parameters:

• fs (int) – Sampling frequency
• smoothing_win (int) – Length of smoothing window

References

[1] Hamilton, P. S. (2002). Open source ECG analysis software documentation. Computers in cardiology, 2002.

[2] Hamilton, P. S., & Tompkins, W. J. (1986). Quantitative investigation of QRS detection rules using the MIT/BIH arrhythmia database. IEEE transactions on biomedical engineering.

average_noise_peak

average_qrs_peak

decision_threshold

average_rr_interval

heart_rate

_push_r_peak(val, time)

_push_noise_peak(val, peak_idx, peak_time)

estimate(ecg_sig, time_vector)

Detection of R-peaks

Parameters:

• time_vector (np.array) – One-dimensional time vector
• ecg_sig (np.array) – One-dimensional ECG signal

Returns:

List of detected peaks indices

check_missing_peak(peak_time, peak_idx, detected_peaks_idx, ecg_sig, time_vector)

class tools.FileRecorder(filename, ch_label, fs, ch_unit, ch_min=None, ch_max=None, device_name='Explore', file_type='edf', do_overwrite=False)

Bases: object

Explorepy file recorder class.

This class can write ExG, orientation and environment data into (separated) EDF+ files. It can write data while streaming from Explore device. The incoming data will be stored in a buffer and after it reached fs samples, it writes the buffer in EDF file.

Attributes:

Parameters:

• filename (str) – File name
• ch_label (list) – List of channel labels.
• fs (int) – Sampling rate (must be identical for all channels)
• ch_unit (list) – List of channels unit (e.g. ‘uV’, ‘mG’, ‘s’, etc.)
• ch_min (list) – List of minimum value of each channel. Only needed in edf mode (can be None in csv mode)
• ch_max (list) – List of maximum value of each channel. Only needed in edf mode (can be None in csv mode)
• device_name (str) – Recording device name
• file_type (str) – File type. current options: ‘edf’ and ‘csv’.
• do_overwrite (bool) – Overwrite file if a file with the same name exists already.

fs

Sampling frequency

_create_edf(do_overwrite)

_create_csv(do_overwrite)

stop()

Stop recording

_init_edf_channels()

write_data(packet)

writes data to the file

Notes

If file type is set to EDF, this function writes each 1 seconds of data. If the input is less than 1 second, it will be buffered in the memory and it will be written in the file when enough data is in the buffer.

Parameters:packet (explorepy.packet.Packet) – ExG or Orientation packet

set_marker(packet)

Writes a marker event in the file

Parameters:packet (explorepy.packet.EventMarker) – Event marker packet

class tools.LslServer(device_info)

Bases: object

Class for LabStreamingLayer integration

push_exg(packet)

Push data to ExG outlet

Parameters:packet (explorepy.packet.EEG) – ExG packet

push_orn(packet)

Push data to orientation outlet

Parameters:packet (explorepy.packet.Orientation) – Orientation packet

push_marker(packet)

Push data to marker outlet

Parameters:packet (explorepy.packet.EventMarker) – Event marker packet

class tools.ImpedanceMeasurement(device_info, calib_param, notch_freq)

Bases: object

Impedance measurement class

Parameters:

• device_info (dict) – Device information dictionary
• calib_param (dict) – Calibration parameters dictionary
• notch_freq (int) – Line frequency (for notch filter)

_add_filters()

measure_imp(packet)

Compute electrode impedances

Parameters:

• self
• packet

Returns:

packet

class tools.PhysicalOrientation

Bases: object

Movement sensors modules

calculate(packet)

_get_rest_orn(packet)

read_calibre_data(device_name)

_map(packet)

static init_dir()

static calibrate(cache_dir, device_name)

static check_calibre_data(device_name)