CLI reference

Overview

The SiFi Bridge REPL (Read-Eval-Print Loop) provides an interactive interface for managing and controlling SiFi Labs devices. It supports command chaining with semicolons and outputs responses in JSON format (use the -p/--pretty flag for pretty-printed JSON).

At any point in the REPL, use help [command] to show a command's help message, including its options and value ranges.

Starting the REPL

# Start the REPL (default mode)
./sifibridge

# Start the REPL with pretty-printed JSON output
./sifibridge --pretty

Working with devices

A device session is created by connect, which both opens the BLE (or serial) link and registers the device internally, keyed by its stable BLE id. When several devices are connected, select switches which one subsequent commands target, and many commands accept an --all flag to act on every connected device at once. disconnect closes the link and removes the session.

Targeting devices

Commands that act on hardware accept two optional targeting flags. Without either, the command applies to the active device (see select).

--all - apply to every connected device
--devices <HANDLE[,HANDLE...]> - apply to a specific subset, as a comma-separated list of device ids or local names

# Active device only
> start

# Every connected device
> start --all

# A named subset
> start --devices left_arm_bp,right_arm_bp

These flags are accepted by configure (on the configure command itself, before the subcommand), start, stop, event, led, motor, status-update, erase-memory and power-off.

Command chaining

Multiple commands can be chained on a single line, separated by semicolons:

> connect; info; start

Device and session commands

list

List devices from a given source.

Usage:

list <FROM>

Arguments:

<FROM> - Source to list from:
- ble - Scan for Bluetooth Low Energy devices
- serial - List serial ports
- devices - List currently connected device sessions

connect

Connect to a device. On success a new session is created (keyed by the device's stable BLE id) and selected as the active device.

Usage:

connect [HANDLE]

Arguments:

[HANDLE] (optional) - Connection handle:
- Empty: auto-connect to the first matching device
- BLE device name (e.g. BioPoint)
- Windows/Linux: BLE MAC address (e.g. 00:11:22:33:44:55)
- macOS: BLE UUID (e.g. 00001122-3344-5566-7788-99AABBCCDDEE)

Examples:

# Auto-connect to first available device
> connect

# Connect by device name
> connect my_bp

# Connect by MAC address (Windows/Linux)
> connect 00:11:22:33:44:55

disconnect

Disconnect from a device and remove its session. With no argument, disconnects the active device. After disconnection, the next remaining device (if any) becomes active.

Buffered acquisitions for the device are retained — use buffer clear to drop them.

Usage:

disconnect [HANDLE]

Arguments:

[HANDLE] (optional) - Device id or BLE local name. Defaults to the active device.

select

Select which device subsequent commands target. The argument can be the device id (BLE MAC/UUID) or the device's local name. If multiple devices share a name, the id must be used to disambiguate.

Usage:

select <HANDLE>

Arguments:

<HANDLE> - Device id or local name

rename

Rename the current device.

Usage:

rename [OPTIONS] [NAME]

Arguments:

[NAME] (optional) - New device name

Options:

--reset - Reset the device's name to its factory default

Examples:

> rename right_arm_bp
> rename --reset

Custom name constraints

Custom names are limited to 14 characters and must be valid ASCII.

info

Print device information for the current device, including its complete configuration, as JSON.

Usage:

info

Configuration commands

configure

Configure the current device, all devices when --all is set, or a specific subset with --devices. The configure command has subcommands for each sensor and device-level setting.

Usage:

configure [--all] [--devices <HANDLE[,HANDLE...]>] <COMMAND>

Subcommands: sensors, ecg, emg, eda, ppg, imu, filtering, temperature, high-gain, memory, low-latency, ble-power, night.

Use help configure <subcommand> for the exact options and value ranges of each.

configure sensors

Enable or disable which sensors are active. This is how sensors are turned on and off — the per-sensor subcommands below adjust settings but do not change the on/off state.

Usage:

configure sensors [OPTIONS]

Options (each takes off or on; omitted sensors keep their current state):

--ecg <ECG>
--emg <EMG>
--eda <EDA>
--imu <IMU>
--ppg <PPG>

Example:

configure sensors --ecg on --ppg on --imu off

configure ecg

Configure the ECG (Electrocardiography) sensor.

Usage:

configure ecg [OPTIONS]

Options:

--fs <FS> - Sampling rate in Hz (250, 500, 1000, 2000)
--dc-notch <DC_NOTCH> - Enable DC notch (off, on)
--mains-notch <MAINS_NOTCH> - Enable mains notch (off, 50, 60)
--bandpass <BANDPASS> - Enable bandpass filter (off, on)
--bandpass-low <BANDPASS_LOW> - Bandpass lower cutoff frequency (Hz)
--bandpass-high <BANDPASS_HIGH> - Bandpass higher cutoff frequency (Hz)

Example:

configure ecg --fs 250 --mains-notch 60 --bandpass on --bandpass-low 0.5 --bandpass-high 40

configure emg

Configure the EMG (Electromyography) sensor.

Usage:

configure emg [OPTIONS]

Options:

--fs <FS> - Sampling rate in Hz (500, 1000, 1600, 2000)
--dc-notch <DC_NOTCH> - Enable DC notch (off, on)
--mains-notch <MAINS_NOTCH> - Enable mains notch (off, 50, 60)
--bandpass <BANDPASS> - Enable bandpass filter (off, on)
--bandpass-low <BANDPASS_LOW> - Bandpass lower cutoff frequency (Hz)
--bandpass-high <BANDPASS_HIGH> - Bandpass higher cutoff frequency (Hz)

Example:

configure emg --fs 1000 --bandpass on --bandpass-low 20 --bandpass-high 450

configure eda

Configure the EDA/BIOZ (Electrodermal Activity / Bioimpedance) sensor.

Usage:

configure eda [OPTIONS]

Options:

--fs <FS> - Sampling rate in Hz (5, 25, 50, 100)
--dc-notch <DC_NOTCH> - Enable DC notch (off, on)
--mains-notch <MAINS_NOTCH> - Enable mains notch (off, 50, 60)
--bandpass <BANDPASS> - Enable bandpass filter (off, on)
--bandpass-low <BANDPASS_LOW> - Bandpass lower cutoff frequency (Hz)
--bandpass-high <BANDPASS_HIGH> - Bandpass higher cutoff frequency (Hz)
--freq <FREQ> - Signal frequency in Hz (0 for DC)

Example:

configure eda --fs 50 --freq 0

configure ppg

Configure the PPG (Photoplethysmography) sensor.

Usage:

configure ppg [OPTIONS]

Options:

--sps <SPS> - Raw AFE sample rate in Hz (50, 100, 200, 400, 800). The effective output rate is this divided by --avg, and is reported live in each packet's sample_rate.
--led-ir <LED_IR> - IR LED current in mA
--led-red <LED_RED> - Red LED current in mA
--led-green <LED_GREEN> - Green LED current in mA
--led-blue <LED_BLUE> - Blue LED current in mA
--sens <SENS> - Sensor sensitivity (low, medium, high, max)
--avg <AVG> - Signal averaging factor (1, 2, 4, 8, 16, 32)

Example:

configure ppg --sps 400 --led-ir 9 --led-red 9 --sens high --avg 4

configure imu

Configure the IMU (Inertial Measurement Unit).

Usage:

configure imu [OPTIONS]

Options:

--fs <FS> - Sampling rate in Hz (25, 50, 100, 200)
--acc-range <ACC_RANGE> - Accelerometer range in g (8, 16)

Example:

configure imu --fs 100 --acc-range 8

Gyroscope range removed in 2.0

--gyro-range was removed in SiFi Bridge 2.0. The IMU still streams orientation (qw, qx, qy, qz) alongside acceleration (ax, ay, az); only the gyroscope full-scale option is gone.

configure memory

Set the memory mode. Data can be stored in the device's internal memory and/or streamed over BLE to the host.

Usage:

configure memory <MODE>

Arguments:

<MODE>:
- streaming - Stream data over BLE to the host only
- device - Store data in device memory only
- both - Stream and store simultaneously

Note: SiFiBand only supports streaming.

Example:

configure memory streaming

Other configure subcommands

configure filtering <off|on> - Enable on-board filtering
configure temperature --fs <0.1|1|2|10> - Configure the temperature sensor
configure high-gain <off|on> - Enable high gain on the ECG and EMG ADC
configure low-latency <off|on> - Pack data from multiple sensors into a single BLE packet for minimal per-sensor latency.
configure ble-power <low|medium|high> - Set BLE transmission power level
configure night <off|on> - Disable LEDs during an acquisition (e.g. for sleep studies)

Use help configure <subcommand> for details on each.

Low latency mode

Low latency mode is enabled by default.

In this mode, the device packs its BLE buffer with data from all sensors, thereby reducing the per-sensor latency. As a consequence, there is a ~10% BLE bandwidth overhead.

With low latency disabled, each sensor fills a dedicated buffer independently. Thus, sensors with a low sampling rate take a long time to fill the buffer, such that the perceived latency can be very high. This can still be useful to reduce the BLE bandwidth by about 10%.

Acquisition commands

start

Start data acquisition.

Usage:

start [OPTIONS]

Options:

--all - Start acquisition on all connected devices
--devices <HANDLE[,HANDLE...]> - Apply to specific devices
--set-default - Set the current configuration as the device default

Examples:

> start
> start --all --set-default

Setting a default configuration

--set-default sets the current configuration as the device's default when starting an acquisition with the on-device button.

For instance, you can set a default configuration, and all subsequent button-initiated acquisitions will use that same configuration.

stop

Stop data acquisition.

Usage:

stop [OPTIONS]

Options:

--all - Stop acquisition on all connected devices
--devices <HANDLE[,HANDLE...]> - Apply to specific devices

event

Generate a software event, inserting an event marker into the data stream.

Usage:

event [OPTIONS]

Options:

--all - Apply to all connected devices
--devices <HANDLE[,HANDLE...]> - Apply to specific devices

status-update

Start or stop periodic device status updates. When on, the device emits status packets (battery level, used memory, device state) roughly once per second alongside the sensor streams. See Data output for the packet shape.

Usage:

status-update [OPTIONS] <STATE>

Arguments:

<STATE> - Status update state (off, on)

Options:

--all - Apply to all connected devices
--devices <HANDLE[,HANDLE...]> - Apply to specific devices

Example:

> status-update on

Memory and data buffers

erase-memory

Erase the recordings stored in the device's on-board memory.

Usage:

erase-memory [OPTIONS]

Options:

--format - Fully format the flash instead of only erasing the stored recordings. Takes longer, but leaves the memory completely clear.
--all - Apply to all connected devices
--devices <HANDLE[,HANDLE...]> - Apply to specific devices

Examples:

# Erase stored recordings
> erase-memory

# Full format
> erase-memory --format

Erasing is irreversible

Download anything you still need with download-memory before erasing.

download-memory

Download data stored in the device's on-board memory into Sifi Bridge's buffers. Use buffer export afterwards to save the data to disk. Acquiring on-board recordings requires a memory mode of device or both (see configure memory).

Usage:

download-memory [--serial <SERIAL>]

Options:

--serial <SERIAL> - Serial port to use for the download (e.g. /dev/ttyACM0). Downloading over serial is significantly faster than BLE. If omitted, the download happens over BLE.

Examples:

# Download over BLE
> download-memory

# Download over serial
> download-memory --serial /dev/ttyACM0

buffer

Manage the data buffers that hold acquisitions for real-time access, querying, and export. Streamed data is buffered automatically; on-board recordings are buffered by download-memory. See Buffering for how buffers are filled, kept, and cleared.

Usage:

buffer <COMMAND>

Subcommands: pull, info, clear, list, export.

Across the buffer subcommands, a device is addressed by its --handle (the device id or local name), and an acquisition by its --id. When --id is omitted, commands default to the latest acquisition.

buffer pull

Pull sensor data out of a buffered acquisition.

buffer pull --sensor <SENSOR> [OPTIONS]

Options:

-s, --sensor <SENSOR> (required) - Sensor type(s) to pull; repeat to pull several at once (ecg, emg, emg_armband, eda, imu, ppg, temperature, event)
--handle <HANDLE> - Device handle (id or local name)
--id <ID> - Acquisition ID (defaults to the latest acquisition)
--last-seconds <LAST_SECONDS> - Return only the last N seconds of data
--from <FROM> - Start of time range, in seconds since recording start
--to <TO> - End of time range, in seconds since recording start

buffer info

Get acquisition details, including device configuration.

buffer info [--handle <HANDLE>] [--id <ID>]

buffer list

List acquisitions and their status.

buffer list [--handle <HANDLE>]

Options:

--handle <HANDLE> - Device handle to filter by (if not specified, lists all)

buffer clear

Clear buffered data.

buffer clear [OPTIONS]

Options:

--handle <HANDLE> - Device handle whose acquisitions should all be cleared
--id <ID> - Acquisition ID to clear
--all - Clear all buffered data

buffer export

Export buffered acquisitions to disk.

buffer export --format <FORMAT> [OPTIONS]

Options:

--format <FORMAT> (required) - Output format (csv, hdf5)
--handle <HANDLE> - Device handle to export
--dir <DIR> - Output directory (defaults to the current directory, ./)

Example:

> buffer export --dir export/directory --format hdf5

See Export data to file for the difference between the hdf5 and csv formats.

Firmware

dfu

Update device firmware using a DFU (Device Firmware Update) package. The device will be rebooted and sifibridge will attempt reconnecting to it after the update.

Usage:

dfu [OPTIONS] <DFU_PACKAGE>

Arguments:

<DFU_PACKAGE> - Path to the DFU zip package

Options:

--handle <HANDLE> - Connection handle (defaults to the currently selected device)
-r, --resume - Resume a previously interrupted DFU process

Example:

> dfu /path/to/firmware.zip

DFU can also be run without entering the REPL, as a top-level subcommand. Note that this form takes the device handle as a positional argument rather than --handle:

./sifibridge dfu <HANDLE> <PATH>

# For example
./sifibridge dfu BioPoint_EF05 ./firmware.zip

What to do if DFU failed

If DFU fails, you can wait about a minute. The device will reboot into its normal operating mode. You can then retry doing the DFU.

Other commands

led

Turn a device LED on or off.

Usage:

led [OPTIONS] --state <STATE> <INDEX>

Arguments:

<INDEX> - LED index (1 or 2)

Options:

--state <STATE> (required) - LED state (off, on)
--all - Apply to all connected devices
--devices <HANDLE[,HANDLE...]> - Apply to specific devices

Example:

> led 1 --state on

motor

Control the vibration motor. Set the intensity, change the run state, or both — at least one of --intensity/--state is required. The motor only vibrates while its run state is on, and the intensity you set persists until changed.

Usage:

motor [OPTIONS] <--intensity <INTENSITY>|--state <STATE>>

Options:

--intensity <INTENSITY> - Vibration intensity (0–10)
--state <STATE> - Motor run state (off, on)
--all - Apply to all connected devices
--devices <HANDLE[,HANDLE...]> - Apply to specific devices

Example:

# Set intensity and start the motor in one command
> motor --intensity 5 --state on
# Stop it
> motor --state off

power-off

Power off the device.

Usage:

power-off [OPTIONS]

Options:

--all - Apply to all connected devices
--devices <HANDLE[,HANDLE...]> - Apply to specific devices

Example:

> power-off
{
  "power_off": {
    "id": "BP_7A1F",
    "name": "my_bp",
    "device": "BioPoint",
    "connected": false
  }
}

The response reports "connected": false: powering the device off also ends its BLE session, so the device is gone from list ble immediately afterwards and no further commands can target it.

Waking up the device

Connect the device via USB to power it back on.

Utility commands

help

Display help for the REPL or a specific command, including options and value ranges.

help [COMMAND]

Examples:

> help
> help connect
> help configure ecg

quit

Exit the REPL. You can also use Ctrl+C or Ctrl+D.

quit

Invocation options

sifibridge is normally started in REPL mode, but it accepts top-level options and subcommands.

Options:

# Pretty-print JSON output
./sifibridge --pretty

# Bind a TCP port for input (remote control)
./sifibridge --tcp-in 127.0.0.1:5000

# Stream sensor data to TCP subscribers
./sifibridge --tcp-out 192.168.1.100:8080

# Send sensor data to a UDP port
./sifibridge --udp-out 192.168.1.100:9000

# Send sensor data to Lab Streaming Layer
./sifibridge --lsl

# Disable sending data to stdout
./sifibridge --no-stdout-data

# Increase / decrease logging verbosity
./sifibridge -v
./sifibridge -q

Subcommands:

repl - Read-Eval-Print Loop mode (the default when no subcommand is given)
dfu - Update device firmware over BLE
completion - Generate shell completion scripts
schema - Export JSON schemas for documentation

JSON response format

All commands return JSON responses. With --pretty, responses are pretty-printed.

Each response is wrapped in a single key named after the command, in snake_case — so erase-memory answers under erase_memory, status-update under status_update, and buffer clear under buffer_clear. Inside the wrapper, commands that act on a device echo its state (id, name, device, connected), plus any command-specific payload:

> erase-memory
{
  "erase_memory": {
    "id": "BP_7A1F",
    "name": "my_bp",
    "device": "BioPoint",
    "connected": true
  }
}

Errors are returned under an error key instead:

{ "error": { "message": "Failed to connect: could not find device" } }

Note that the Python wrapper returns the unwrapped payload — rename_device() gives you the inner object directly, not {"rename": {...}}.

See the Quick start for annotated response examples, and Data output for the streamed data packet format.

Overview​

Starting the REPL​

Working with devices​

Targeting devices​

Command chaining​

Device and session commands​

list​

connect​

disconnect​

select​

rename​

info​

Configuration commands​

configure​

configure sensors​

configure ecg​

configure emg​

configure eda​

configure ppg​

configure imu​

configure memory​

Other configure subcommands​

Acquisition commands​

start​

stop​

event​

status-update​

Memory and data buffers​

erase-memory​

download-memory​

buffer​

buffer pull​

buffer info​

buffer list​

buffer clear​

buffer export​

Firmware​

dfu​

Other commands​

led​

motor​

power-off​

Utility commands​

help​

quit​

Invocation options​

JSON response format​

Overview

Starting the REPL

Working with devices

Targeting devices

Command chaining

Device and session commands

list

connect

disconnect

select

rename

info

Configuration commands

configure

configure sensors

configure ecg

configure emg

configure eda

configure ppg

configure imu

configure memory

Other configure subcommands

Acquisition commands

start

stop

event

status-update

Memory and data buffers

erase-memory

download-memory

buffer

buffer pull

buffer info

buffer list

buffer clear

buffer export

Firmware

dfu

Other commands

led

motor

power-off

Utility commands

help

quit

Invocation options

JSON response format