bivital

bivital is the official Python library for the BI-Vital data workflow.
It helps you organize, preprocess, and manage measurement projects, series, and raw data collected via BI-Vital systems.

🚀 Features

• Project structure setup
• Series and data import
• Label management
• Command-line tool (bvtool) for fast interaction
• Optional Jupyter workflow extras ([notebook])
• Bluetooth (BLE) API and CLI support

📦 Installation

Requires Python ≥ 3.10
(3.11/3.12 recommended)

Stable release (PyPI)

pip install bivital

With notebook extras

pip install "bivital[notebook]"

From source (local checkout)

# in the repo root
pip install .
# or in editable/development mode (plus notebook extras)
pip install -e ".[notebook]"

🛠 Usage

Command-Line Interface (CLI)

bvtool -h
bvtool project -p PATH -n NAME
bvtool series  -p PATH -n NAME
bvtool data    -p PATH -s pc
bvtool label   -p PATH
bvtool commander
bvtool time sync
bvtool time calibrate

Recordings

bvtool recording convert log00.bin -o log00.csv
bvtool recording convert log00.bin
bvtool recording view log00.bin log01.bin log02.csv
bvtool recording view log00.bin 20260723_124839.csv

The recording viewer is hosted at bivital.eu; decoding and plotting happen locally in the browser. The Python command starts a small localhost adapter which passes command-line files to the hosted viewer. CSV recordings are converted in the browser to the same internal binary representation used for BIN recordings. Without -o, recording convert opens a sparse millisecond terminal table. One app annotation .csv can be added globally; loading another replaces it. The viewer starts with a 30-second detail range, pre-aggregates the full overview while indexing and provides two point cursors for Δt and Δy. Choose Set A or Set B, then click anywhere in a detail plot to place it.

BLE (via bvtool)

# Scan BI-Vital devices
bvtool ble scan

# Read one value (short device token from name is supported)
bvtool ble read --address <XXXX> battery_level

# Write one value
bvtool ble write --address <XXXX> led_color green

# Stream one or multiple values
bvtool ble stream --address <XXXX> heart_rate.bpm
bvtool ble stream --address <XXXX> heart_rate.bpm,motion_raw.acc_ms2

Python (minimal check)

import bivital
print("bivital version:", getattr(bivital, "__version__", "unknown"))

📂 Example Project Structure

BiVitalProject/
├── Series1/
│   └── MAC_01/
│       └── log_01.csv
└── Series2/
    └── ...

💬 Support & Contributing

• Issues & feature requests: https://gitlab.ub.uni-bielefeld.de/bi-vital-open-source/py_bivital/-/issues
• Homepage: https://bivital.eu/

Contributions are welcome—please open an issue to discuss changes first.

📜 License

MIT © University Bielefeld