API Reference

Complete API reference for SiFi Bridge Python package.

SifiBridge Class

The main class for interacting with SiFi devices.

Constructor

SifiBridge(publishers=None, use_lsl=False)

Create a SiFi Bridge instance.

Parameters:

publishers (str | list[str] | None): Additional data output destinations
- "csv://path/to/directory/" - Save to CSV files
- "tcp://ip:port" - Stream via TCP
- "udp://ip:port" - Stream via UDP
- Can provide multiple as a list: ["csv://./data/", "tcp://127.0.0.1:5000"]
use_lsl (bool): Enable Lab Streaming Layer (LSL) output

Example:

import sifi_bridge_py as sbp

# Basic instance (stdout only)
sb = sbp.SifiBridge()

# With CSV output
sb = sbp.SifiBridge(publishers="csv://./data/")

# Multiple outputs
sb = sbp.SifiBridge(publishers=["csv://./data/", "tcp://127.0.0.1:5000"])

# With LSL streaming
sb = sbp.SifiBridge(use_lsl=True)

info

The constructor automatically checks for a compatible sifibridge CLI executable and downloads it if necessary.

Connection Methods

connect()

connect(handle=None) -> bool

Connect to a SiFi device.

Parameters:

handle (DeviceType | str | None): Device to connect to
- None - Connect to any available device
- DeviceType enum - Connect by device name (e.g., DeviceType.BIOPOINT_V1_3)
- String - MAC address (Linux/Windows) or UUID (macOS)

Returns: True if connected, False otherwise

Raises: ConnectionError if Bluetooth is disabled

Examples:

# Connect to any device
sb.connect()

# Connect to specific device type
sb.connect(sbp.DeviceType.BIOPOINT_V1_3)

# Connect by MAC/UUID
sb.connect("XX:XX:XX:XX:XX:XX")

disconnect()

disconnect() -> bool

Disconnect from the active device.

Returns: Connection status (inverted - False means successfully disconnected)

list_devices()

list_devices(source) -> list[str]

List available devices.

Parameters:

source (ListSources | str): Source to list from
- ListSources.BLE - Bluetooth devices
- ListSources.SERIAL - Serial/USB devices
- ListSources.DEVICES - All virtual devices

Returns: List of device identifiers

Raises: ConnectionError if Bluetooth is disabled

Example:

# List Bluetooth devices
ble_devices = sb.list_devices(sbp.ListSources.BLE)
print(f"Found: {ble_devices}")

# List serial devices
serial_devices = sb.list_devices(sbp.ListSources.SERIAL)

show()

show() -> dict

Get information about the current device state.

Returns: Dictionary with device information including connection status, configuration, etc.

Example:

info = sb.show()
print(f"Connected: {info['connected']}")
print(f"Device: {info.get('device', 'None')}")

Sensor Configuration Methods

configure_sensors()

configure_sensors(ecg=False, emg=False, eda=False, imu=False, ppg=False) -> dict

Enable or disable multiple sensors at once.

Parameters:

ecg (bool): Enable ECG sensor
emg (bool): Enable EMG sensor
eda (bool): Enable EDA/BIOZ sensor
imu (bool): Enable IMU sensor
ppg (bool): Enable PPG sensor

Returns: Configuration response

Example:

# Enable ECG and IMU only
sb.configure_sensors(ecg=True, imu=True)

configure_ecg()

configure_ecg(
    state=True,
    fs=500,
    dc_notch=True,
    mains_notch=50,
    bandpass=True,
    flo=0.0,
    fhi=30.0
) -> dict

Configure ECG sensor parameters.

Parameters:

state (bool): Enable/disable sensor
fs (int): Sampling rate in Hz (250, 500, 1000)
dc_notch (bool): Enable DC offset removal filter
mains_notch (int | None): Mains notch filter (None=off, 50, 60)
bandpass (bool): Enable bandpass filter
flo (float): Lower cutoff frequency (Hz)
fhi (float): Higher cutoff frequency (Hz)

Returns: Configuration response

Example:

# Standard ECG configuration
sb.configure_ecg(
    state=True,
    fs=500,
    dc_notch=True,
    mains_notch=60,  # 60 Hz for North America
    bandpass=True,
    flo=0.5,
    fhi=40
)

configure_emg()

configure_emg(
    state=True,
    fs=2000,
    dc_notch=True,
    mains_notch=50,
    bandpass=True,
    flo=20.0,
    fhi=450.0
) -> dict

Configure EMG sensor parameters.

Parameters:

state (bool): Enable/disable sensor
fs (int): Sampling rate in Hz (1000, 2000)
dc_notch (bool): Enable DC offset removal filter
mains_notch (int | None): Mains notch filter (None=off, 50, 60)
bandpass (bool): Enable bandpass filter
flo (float): Lower cutoff frequency (Hz)
fhi (float): Higher cutoff frequency (Hz)

Returns: Configuration response

Example:

# High-frequency EMG recording
sb.configure_emg(
    state=True,
    fs=2000,
    bandpass=True,
    flo=20,
    fhi=500
)

configure_eda()

configure_eda(
    state=True,
    fs=50,
    dc_notch=True,
    mains_notch=50,
    bandpass=True,
    flo=0.0,
    fhi=5.0,
    freq=0
) -> dict

Configure EDA/BIOZ sensor parameters.

Parameters:

state (bool): Enable/disable sensor
fs (int): Sampling rate in Hz (50, 100)
dc_notch (bool): Enable DC offset removal filter
mains_notch (int | None): Mains notch filter (None=off, 50, 60)
bandpass (bool): Enable bandpass filter
flo (float): Lower cutoff frequency (Hz)
fhi (float): Higher cutoff frequency (Hz)
freq (int): Excitation signal frequency (0 for DC measurement)

Returns: Configuration response

warning

Enabling BIOZ (freq > 0) and ECG/EMG simultaneously may cause interference.

Example:

# EDA measurement
sb.configure_eda(state=True, fs=50, freq=0)

# BIOZ measurement
sb.configure_eda(state=True, fs=100, freq=50000)  # 50 kHz excitation

configure_ppg()

configure_ppg(
    state=True,
    fs=100,
    ir=9,
    red=9,
    green=9,
    blue=9,
    sens=PpgSensitivity.MEDIUM,
    avg=1
) -> dict

Configure PPG sensor parameters.

Parameters:

state (bool): Enable/disable sensor
fs (int): Sampling rate in Hz (50, 100, 200, 400, 800, 1000, 1600, 3200)
ir (int): IR LED current in mA (1-50)
red (int): Red LED current in mA (1-50)
green (int): Green LED current in mA (1-50)
blue (int): Blue LED current in mA (1-50)
sens (PpgSensitivity): Light sensor sensitivity
avg (int): Signal averaging factor

Returns: Configuration response

Example:

# PPG for heart rate monitoring
sb.configure_ppg(
    state=True,
    fs=100,
    ir=25,
    red=25,
    sens=sbp.PpgSensitivity.HIGH,
    avg=2
)

configure_imu()

configure_imu(
    state=True,
    fs=100,
    accel_range=2,
    gyro_range=16
) -> dict

Configure IMU sensor parameters.

Parameters:

state (bool): Enable/disable sensor
fs (int): Sampling rate in Hz (50, 100, 200, 400, 800, 1000, 1600, 3200)
accel_range (int): Accelerometer range in ±G
gyro_range (int): Gyroscope range in ±dps

Returns: Configuration response

Example:

# IMU for motion tracking
sb.configure_imu(
    state=True,
    fs=200,
    accel_range=4,
    gyro_range=500
)

Device Configuration Methods

set_filters()

set_filters(enable) -> dict

Enable or disable onboard filtering for all sensors.

Parameters:

enable (bool): True to enable filters, False to disable

Returns: Configuration response

set_ble_power()

set_ble_power(power) -> dict

Set Bluetooth transmission power.

Parameters:

power (BleTxPower | str): Power level (LOW, MEDIUM, HIGH)

Returns: Configuration response

Example:

# Increase range and stability
sb.set_ble_power(sbp.BleTxPower.HIGH)

set_memory_mode()

set_memory_mode(memory_config) -> dict

Configure device memory mode.

Parameters:

memory_config (MemoryMode | str): Memory mode
- MemoryMode.STREAMING - Only stream via BLE
- MemoryMode.DEVICE - Only save to device memory
- MemoryMode.BOTH - Stream and save

Returns: Configuration response

info

SiFiBand does not support onboard memory.

Example:

# Record to device memory only
sb.set_memory_mode(sbp.MemoryMode.DEVICE)

set_low_latency_mode()

set_low_latency_mode(on) -> dict

Enable low-latency data mode (if supported by device).

Parameters:

on (bool): True for low-latency mode

Returns: Configuration response

set_stealth_mode()

set_stealth_mode(enable) -> dict

Enable stealth mode (disables LEDs during acquisition).

Parameters:

enable (bool): True to enable stealth mode

Returns: Configuration response

Example:

# Disable LEDs for sleep study
sb.set_stealth_mode(True)

set_motor_intensity()

set_motor_intensity(level) -> dict

Set vibration motor intensity.

Parameters:

level (int): Intensity level (1-10, where 10 is maximum)

Returns: Configuration response

Raises: ValueError if level not in range 1-10

Data Acquisition Methods

start()

start() -> bool

Start data acquisition.

Returns: True if command sent successfully

Raises: ConnectionError if device not connected

stop()

stop() -> bool

Stop data acquisition.

Returns: True if command sent successfully

info

Allow ~1 second for the command to reach the device before destroying the SifiBridge instance.

get_data()

get_data(timeout=None) -> dict

Wait for any data packet.

Parameters:

timeout (float | None): Timeout in seconds (None = block indefinitely)

Returns: Data packet as dictionary (empty dict if timeout)

Example:

# Block until packet arrives
packet = sb.get_data()

# Wait up to 2 seconds
packet = sb.get_data(timeout=2.0)
if packet:
    print(f"Got {packet['packet_type']}")

get_data_with_key()

get_data_with_key(keys) -> dict

Wait for a packet containing specific key(s).

Parameters:

keys (str | list[str]): Key or keys to wait for

Returns: Packet containing the requested key(s)

Example:

# Wait for packet with 'timestamp'
packet = sb.get_data_with_key("timestamp")

# Wait for nested keys
packet = sb.get_data_with_key(["data", "ecg"])

get_ecg()

get_ecg() -> dict

Wait for an ECG data packet.

Returns: ECG packet dictionary

get_emg()

get_emg() -> dict

Wait for an EMG data packet.

Returns: EMG packet dictionary

get_eda()

get_eda() -> dict

Wait for an EDA/BIOZ data packet.

Returns: EDA packet dictionary

get_imu()

get_imu() -> dict

Wait for an IMU data packet.

Returns: IMU packet dictionary

get_ppg()

get_ppg() -> dict

Wait for a PPG data packet.

Returns: PPG packet dictionary

get_temperature()

get_temperature() -> dict

Wait for a temperature data packet.

Returns: Temperature packet dictionary

Memory Management Methods

start_memory_download()

start_memory_download() -> int

Start downloading data from device memory.

Returns: Number of kilobytes to download

Raises:

ConnectionError if device not connected
TypeError if device doesn't support memory download

Example:

kb = sb.start_memory_download()
print(f"Downloading {kb} kB...")

while True:
    packet = sb.get_data()
    if sb.is_memory_download_completed(packet):
        break
    # Process memory packet...

is_memory_download_completed()

is_memory_download_completed(packet) -> bool

Check if a packet indicates memory download completion.

Parameters:

packet (dict): Data packet to check

Returns: True if download complete

Device Control Methods

send_command()

send_command(command) -> bool

Send a command to the device.

Parameters:

command (DeviceCommand | str): Command to send

Returns: True if command sent successfully

Example:

# Control LEDs
sb.send_command(sbp.DeviceCommand.OPEN_LED_1)
sb.send_command(sbp.DeviceCommand.CLOSE_LED_1)

# Motor control
sb.send_command(sbp.DeviceCommand.START_MOTOR)
time.sleep(1)
sb.send_command(sbp.DeviceCommand.STOP_MOTOR)

# Power management
sb.send_command(sbp.DeviceCommand.POWER_OFF)

Multi-Device Management

create_device()

create_device(name, select=True) -> dict

Create a new virtual device manager.

Parameters:

name (str): Device name (no spaces allowed)
select (bool): Whether to select this device after creation

Returns: Response dictionary

Raises: ValueError if name contains spaces

select_device()

select_device(name) -> dict

Switch to a different virtual device.

Parameters:

name (str): Name of device to select

Returns: Response dictionary

delete_device()

delete_device(name) -> str

Delete a virtual device manager.

Parameters:

name (str): Name of device to delete

Returns: Name of newly active device

Enumerations

DeviceType

Supported device types for connection.

class DeviceType(Enum):
    BIOPOINT_V1_1 = "BioPoint_v1_1"
    BIOPOINT_V1_2 = "BioPoint_v1_2"
    BIOPOINT_V1_3 = "BioPoint_v1_3"
    SIFIBAND = "SiFiBand"

DeviceCommand

Commands that can be sent to devices.

class DeviceCommand(Enum):
    START_ACQUISITION = "start-acquisition"
    STOP_ACQUISITION = "stop-acquisition"
    SET_BLE_POWER = "set-ble-power"
    SET_ONBOARD_FILTERING = "set-filtering"
    ERASE_ONBOARD_MEMORY = "erase-memory"
    DOWNLOAD_ONBOARD_MEMORY = "download-memory"
    START_STATUS_UPDATE = "start-status-update"
    STOP_STATUS_UPDATE = "stop-status-update"
    OPEN_LED_1 = "open-led1"
    OPEN_LED_2 = "open-led2"
    CLOSE_LED_1 = "close-led1"
    CLOSE_LED_2 = "close-led2"
    START_MOTOR = "start-motor"
    STOP_MOTOR = "stop-motor"
    POWER_OFF = "power-off"
    POWER_DEEP_SLEEP = "deep-sleep"
    SET_PPG_CURRENTS = "set-ppg-currents"
    SET_PPG_SENSITIVITY = "set-ppg-sensitivity"
    SET_EMG_MAINS_NOTCH = "set-emg-mains-notch"
    SET_EDA_FREQUENCY = "set-eda-freq"
    SET_EDA_GAIN = "set-eda-gain"
    DOWNLOAD_MEMORY_SERIAL = "download-memory-serial"

PacketType

Data packet types.

class PacketType(Enum):
    ECG = "ecg"
    EMG = "emg"
    EMG_ARMBAND = "emg_armband"
    EDA = "eda"
    IMU = "imu"
    PPG = "ppg"
    STATUS = "status"
    MEMORY = "memory"
    TEMPERATURE = "temperature"
    START_TIME = "start_time"
    LOW_LATENCY = "low_latency"

PacketStatus

Packet status values.

class PacketStatus(Enum):
    OK = "ok"
    LOST_DATA = "lost_data"
    RECORDING = "recording"
    MEMORY_DOWNLOAD_COMPLETED = "memory_download_completed"
    MEMORY_ERASED = "memory_erased"
    INVALID = "invalid"

SensorChannel

Sensor channel names for accessing data.

class SensorChannel(Enum):
    ECG = "ecg"
    EMG = "emg"
    EMG_ARMBAND = ("emg0", "emg1", "emg2", "emg3", "emg4", "emg5", "emg6", "emg7")
    EDA = "eda"
    IMU = ("qw", "qx", "qy", "qz", "ax", "ay", "az")
    PPG = ("ir", "r", "g", "b")
    TEMPERATURE = "temperature"

Example:

packet = sb.get_imu()
imu_data = packet['data']

# Access specific IMU channels
qw = imu_data[sbp.SensorChannel.IMU.value[0]]  # Quaternion W
ax = imu_data[sbp.SensorChannel.IMU.value[4]]  # Accel X

BleTxPower

Bluetooth transmission power levels.

class BleTxPower(Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

MemoryMode

Device memory configuration modes.

class MemoryMode(Enum):
    STREAMING = "streaming"  # Stream via BLE only
    DEVICE = "device"        # Save to device memory only
    BOTH = "both"            # Stream and save

PpgSensitivity

PPG sensor light sensitivity levels.

class PpgSensitivity(Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    MAX = "max"

ListSources

Sources for device listing.

class ListSources(Enum):
    BLE = "ble"          # Bluetooth devices
    SERIAL = "serial"    # Serial/USB devices
    DEVICES = "devices"  # Virtual device managers

Data Packet Structure

All sensor data packets follow this structure:

{
    'id': str,              # Device identifier
    'packet_type': str,     # One of PacketType values
    'timestamp': float,     # Unix timestamp
    'status': str,          # One of PacketStatus values
    'data': dict,           # Sensor-specific data
}

ECG Packet

{
    'packet_type': 'ecg',
    'data': {
        'ecg': [float, ...]  # Array of voltage values
    }
}

EMG Packet

{
    'packet_type': 'emg',
    'data': {
        'emg': [float, ...]  # Array of voltage values
    }
}

EDA Packet

{
    'packet_type': 'eda',
    'data': {
        'eda': [float, ...]  # Array of conductance/impedance values
    }
}

IMU Packet

{
    'packet_type': 'imu',
    'data': {
        'qw': [float, ...],  # Quaternion W
        'qx': [float, ...],  # Quaternion X
        'qy': [float, ...],  # Quaternion Y
        'qz': [float, ...],  # Quaternion Z
        'ax': [float, ...],  # Acceleration X (g)
        'ay': [float, ...],  # Acceleration Y (g)
        'az': [float, ...]   # Acceleration Z (g)
    }
}

PPG Packet

{
    'packet_type': 'ppg',
    'data': {
        'ir': [float, ...],     # IR channel
        'r': [float, ...],      # Red channel
        'g': [float, ...],      # Green channel
        'b': [float, ...]       # Blue channel
    }
}

Temperature Packet

{
    'packet_type': 'temperature',
    'data': {
        'temperature': [float, ...]  # Temperature in °C
    }
}

SifiBridge Class​

Constructor​

Connection Methods​

connect()​

disconnect()​

list_devices()​

show()​

Sensor Configuration Methods​

configure_sensors()​

configure_ecg()​

configure_emg()​

configure_eda()​

configure_ppg()​

configure_imu()​

Device Configuration Methods​

set_filters()​

set_ble_power()​

set_memory_mode()​

set_low_latency_mode()​

set_stealth_mode()​

set_motor_intensity()​

Data Acquisition Methods​

start()​

stop()​

get_data()​

get_data_with_key()​

get_ecg()​

get_emg()​

get_eda()​

get_imu()​

get_ppg()​

get_temperature()​

Memory Management Methods​

start_memory_download()​

is_memory_download_completed()​

Device Control Methods​

send_command()​

Multi-Device Management​

create_device()​

select_device()​

delete_device()​

Enumerations​

DeviceType​

DeviceCommand​

PacketType​

PacketStatus​

SensorChannel​

BleTxPower​

MemoryMode​

PpgSensitivity​

ListSources​

Data Packet Structure​

ECG Packet​

EMG Packet​

EDA Packet​

IMU Packet​

PPG Packet​

Temperature Packet​

SifiBridge Class

Constructor

Connection Methods

connect()

disconnect()

list_devices()

show()

Sensor Configuration Methods

configure_sensors()

configure_ecg()

configure_emg()

configure_eda()

configure_ppg()

configure_imu()

Device Configuration Methods

set_filters()

set_ble_power()

set_memory_mode()

set_low_latency_mode()

set_stealth_mode()

set_motor_intensity()

Data Acquisition Methods

start()

stop()

get_data()

get_data_with_key()

get_ecg()

get_emg()

get_eda()

get_imu()

get_ppg()

get_temperature()

Memory Management Methods

start_memory_download()

is_memory_download_completed()

Device Control Methods

send_command()

Multi-Device Management

create_device()

select_device()

delete_device()

Enumerations

DeviceType

DeviceCommand

PacketType

PacketStatus

SensorChannel

BleTxPower

MemoryMode

PpgSensitivity

ListSources

Data Packet Structure

ECG Packet

EMG Packet

EDA Packet

IMU Packet

PPG Packet

Temperature Packet