Quick start
Get up and running with SiFi Bridge in 5 minutes. This guide walks through the typical workflow: connecting to and managing your device, configuring sensors, and collecting and exporting data. To do this, we use the interactive REPL, the most common way to use SiFi Bridge.
It covers only the commands you need for typical use cases. For the complete command set, see the CLI Reference.
Starting the REPL
Launch the SiFi Bridge interactive shell:
$ sifibridge
>
As indicated by the prompt (>), you're now in the REPL (Read-Eval-Print Loop) where you can type commands interactively.
SiFi Bridge outputs responses in JSON format. For easier reading, use the --pretty flag:
sifibridge --pretty
>
SiFi Bridge includes logging to help debug issues, which are enabled to different levels with the -v flag:
- Omitting the flag still prints Error logs.
-v: Print logs down to Warning level.-vv: Print logs down to Info level. This is usually the sweet spot to debug issues.-vvv: Print logs down to Debug level. Watch out! this is extremely verbose.
sifibridge -vv
[2026-06-26T16:30:46Z INFO sifibridge::buffering::service] StreamingService started
> connect
[2026-06-26T16:32:52Z INFO sifibridge::transport::ble] Using BLE adapter: Adapter { session: BluetoothSession, adapter: AdapterId { object_path: Path("/org/bluez/hci0\0") } }
[2026-06-26T16:33:08Z INFO sifibridge::transport::ble] Services discovered
[2026-06-26T16:33:08Z INFO sifibridge::transport::ble] Subscribed to notifications
[2026-06-26T16:33:08Z INFO sifibridge::transport::ble] Found SiFi service data: BP_7A1F
Subcommand help
Every subcommand is documented within sifibridge itself:
> help
SiFi Bridge ...
...snip...
Commands:
select: Select a device
...snip...
> help configure sensors
Usage: configure sensors [OPTIONS]
Options:
--ecg <ECG> ECG state [possible values: off, on]
--emg <EMG> EMG state [possible values: off, on]
--eda <EDA> EDA/BIOZ state [possible values: off, on]
--imu <IMU> IMU state [possible values: off, on]
--ppg <PPG> PPG state [possible values: off, on]
-h, --help Print help
List devices
Discover available SiFi devices via Bluetooth:
> list ble
{
"list": {
"devices": [
{
"name": "my_bp",
"id": "BP_7A1F"
},
]
}
}
You can also list devices from other sources with list serial or list devices:
> list serial
{
"list": {
"devices": [
"/dev/ttyACM0",
]
}
}
list ble outputs a list of dictionaries with the keys "name" and "id", while list serial and list devices output plain lists (see example above).
Connect to a device
sifibridge can auto-connect to the first SiFi device it finds, or you can specify the device to which you want to connect either via its name, device ID, or its MAC address (UUID on macOS):
> connect -> auto-connect
> connect my_bp -> device name
> connect BP_7A1F -> device ID
> connect C2:EC:EF:30:0D:10 -> MAC address / UUID
{
"id": "BP_7A1F",
"name": "my_bp",
"device": "BioPoint"
"connected": true
}
You will notice that the device has different fields: id, name, device. Here is their meaning:
id: An identifier to uniquely identify the device. It is either the device ID, e.g.BP_7A1F, or the BLE MAC address, for exampleC2:EC:EF:30:0D:10name: The device's name, which can be changed (see Rename a device).device: The device type. EitherBioPointorSiFiBand.
These fields are reused throughout sifibridge's messages and follow this convention.
Rename a device
Once connected, you can rename your device at any time.
> rename right_arm_bp
{
"rename": {
"id": "BP_7A1F",
"name": "right_arm_bp",
"device": "BioPoint",
"connected": true
}
}
Make sure your custom name respects the following:
- The maximum length is 14 characters.
- The name must consist of valid ASCII characters.
You can also reset the name to the factory default:
> rename --reset
{
"rename": {
"id": "BP_7A1F",
"name": "BioPoint_7A1F",
"device": "BioPoint",
"connected": true
}
}
For the changes to be reflected, you may need to reconnect to the device. Bluetooth stacks typically cache information about devices such as the BLE local name. Nevertheless, sifibridge eagerly changes the name internally.
Get device information
View detailed information about the connected device:
> info
{
"info": {
"id": "BP_7A1F",
"name": "my_bp",
"device": "BioPoint",
"connected": true,
"device": {
--- snip ---
}
}
}
The info command outputs the complete device configuration in JSON format.
Configure the device
Before starting an acquisition, configure which sensors are active and where their data goes. Use help configure to list every configurable aspect. Typically, you will start with configure sensors to configure which sensors are enabled and then configure each sensor invidually with configure <sensor>. Any parameter you don't set keeps SiFi Bridge's default configuration.
Select active sensors
Enable or disable individual sensors. Each takes on or off:
> configure sensors --emg on --imu off --ppg off
The available sensors are --ecg, --emg, --eda, --imu, and --ppg. Omitted sensors keep their current state. Each sensor also has its own subcommand (configure ecg, configure ppg, …) for finer settings such as sampling rate and filtering — see help configure <sensor>.
Adjust sensor settings
Once a sensor is enabled, tune it with its own subcommand. For example, to record EMG at 2000 Hz with a 20–450 Hz bandpass filter:
> configure emg --fs 2000 --bandpass on --bandpass-low 20 --bandpass-high 450
Each subcommand only changes the options you pass; everything else keeps its current value. Run help configure emg for the full list of EMG options and their accepted values.
Choose where data goes
The memory mode controls whether data is streamed to the host, stored on the device, or both:
> configure memory <mode>
Where <mode> is one of:
streaming— data is streamed over BLE to the host as it is acquired (and buffered, ready to export).device— data is stored in the device's on-board memory only. Retrieve it later withdownload-memory.both— stream and store simultaneously.
SiFiBand only supports streaming.
When recording to on-board memory, use the Data bandwidth and recording time calculator to estimate how long the device can record before its memory fills up.
Start collecting data
Begin acquiring data from your device:
> start
{
"start": {
"id": "BP_7A1F",
"name": "BioPoint_v1_3",
"device": "BioPoint",
"connected": true
}
}
{
"device": "BioPoint",
"id": "BP_7A1F",
"name": "BioPoint_v1_3",
"mac": "C2:EC:EF:30:0D:10",
"packet_type": "start_time",
"status": "ok",
"timestamp": 1781363548.881,
"timestamps": [
1781363548.881
],
"data": {
"hour": [
11.0
],
"year": [
2026.0
],
"second": [
28.0
],
"start_time": [
1781363548.0
],
"minute": [
12.0
],
"month": [
6.0
],
"day": [
13.0
]
}
}
SiFi Bridge returns:
- The Start response acknowledge to the input handler (stdin or TCP)
- The Start Time data packet to the output handler (stdout, TCP or UDP)
As acquisition continues, sensor data packets are streamed to the output handler. By default these go to stdout; they can also be sent to Lab Streaming Layer, TCP, or UDP — see the Data output reference for the packet format and streaming options.
Starting an acquisition while another is ongoing will start a new acquisition. In other words:
> start
---snip---
> start
is equivalent to:
> start
--- snip ---
> stop
> start
Stop data collection
Stop the data acquisition:
> stop
{
"stop": {
"id": "BP_7A1F",
"name": "BioPoint_v1_3",
"device": "BioPoint",
"connected": true
}
}
Disconnect from a device
Close the connection:
> disconnect
{
"disconnect": {
"id": "BP_7A1F",
"name": "BioPoint_v1_3",
"device": "BioPoint",
"connected": false
}
}
Disconnecting does not stop an ongoing acquisition — by design. The device keeps recording on its own, so you can drop the BLE connection whenever keeping it live is impractical and reconnect later to stop the acquisition and retrieve the data.
A sleep study is a typical example: a clinician installs, configures, and starts the acquisition in-clinic, sends the patient home for the night, then reconnects the next morning to stop the recording and download the data for analysis.
Export data to file
Sifi Bridge can export data from its buffering subsystem to disk. Streamed data is saved to these buffers automatically as it arrives, so it is ready to export at any time. Data stored in the device's on-board memory must first be downloaded into the buffers (see below).
Download from device memory (optional)
This step is only required to export recordings stored in the device's on-board memory.
Streamed data is already buffered and can be exported directly — skip ahead to Export the buffer to disk.
> download-memory [--serial <port>]
This may take up to a few hours depending on the amount of data stored on the device. Passing --serial with a serial port (e.g. --serial /dev/ttyACM0) downloads over that port, which is significantly faster than Bluetooth.
Data is only written to on-board memory when the device's memory mode is set to device or both. See Configure the device.
Export the buffer to disk
> buffer export [--handle HANDLE] [--dir path/to/dir] --format <FORMAT>
Where <FORMAT> is either:
hdf5— the recommended format. A single HDF5 file holds an entire recording along with its metadata, storing recording-level and per-sensor attributes alongside the data. One file is created per recording.csv— a widely-known, simple format. CSV files do not store metadata, and each file holds a single sensor, so one file is created per sensor per recording.
SiFi Bridge bundles HDF5 for Rust. See Third-party licenses for its copyright notice.
Exit SiFi Bridge
Leave the REPL:
> quit
You can also use Ctrl+C or Ctrl+D to exit. Similarly to disconnecting, ongoing acquisitions are not stopped.