How fg1/bleheartratelogger works
Summary of project type and purpose
• Type: Small single-process CLI utility / data-logger written in Python for Linux.
• Purpose: Connect to a Bluetooth Low-Energy (BLE) heart-rate monitor (HRM) device using system BLE tools (hcitool/gatttool), parse the output, and store heart-rate and RR (heart-rate variability) values into a local sqlite database. It is a device-integration and persistence tool, not a web service or microservice.
Top-level architectural analysis (from file tree + README)
• Single main executable script: BLEHeartRateLogger.py — contains the entire runtime logic (device discovery, connection establishment, data parsing, persistence and CLI options).
• Config example: BLEHeartRateLogger.conf.example — runtime settings (likely: MAC override, battery check flag, gatttool path, output filename).
• Packaging metadata: setup.py — indicates it's packaged as a Python script / module.
• External system dependencies: hcitool, gatttool, Python pexpect, BlueZ stack (Linux).
• Persistence: sqlite database file written by the script.
• Execution context: Linux user environment; requires root or capabilities set on hcitool/hciconfig.
Main components
• External BLE Device(s): e.g., Polar H7, Zephyr HxM, Wahoo TICKR — emits BLE advertisements and GATT notifications.
• Linux Host OS and BlueZ stack: kernel BLE controller + Bluetooth stack; provides low-level BLE capability to tools.
• System BLE Tools: hcitool and gatttool (executables; used by the script to discover and talk to device).
• BLEHeartRateLogger Process (Python runtime):
• CLI / Argument Parser (presentation layer: -m, -b, -g, -o, -v)
• Discovery & Connection Manager (invokes hcitool lescan / gatttool -I connect)
• BLE Interaction Layer (pexpect wrapper processes talking to gatttool/hcitool)
• Parser / Decoder for HRM GATT notifications (hex -> HR value, RR intervals)
• Persistence Layer (sqlite3): write heart rate + timestamps + RR to DB file
• Logging & Error handling: console/log file output, reconnection logic
• Config loader (reads conf example or CLI args)
• Local sqlite DB file (output: file on disk)
• Operator (user) — invokes the CLI, may ctrl-C to stop
• Optional: systemd/service manager if deployed as background service (mention as extension)
Important architectural patterns and design principles
• Integration pattern: External process wrapping — the script integrates with BLE devices indirectly by controlling system tools (hcitool/gatttool) via pexpect. Represent this as "Process Adapter" or "System Tool Adapter".
• Layered separation (recommended representation even if implemented in one file):
• Presentation (CLI + config)
• Integration / Adapter layer (pexpect to gatttool/hcitool)
• Domain logic (parse HRM messages)
• Persistence (sqlite)
• Resilience concerns: reconnection loops, timeouts, error handling — include these as annotations on the connection manager component.
• Security/Permissions: drawing should emphasize host-level capability requirement (root or setcap).
• Single-process vs distributed: this is a single-process local tool — do not show microservices. Keep it simple: one runtime process interacting with external device and DB.
Relevant technologies, libs and OS elements to label
• Python runtime (interpreter)
• pexpect (used to script gatttool/hcitool)
• hcitool, gatttool (executables from BlueZ)
• BlueZ (Linux Bluetooth stack / kernel interface)
• sqlite3 (local DB)
• setcap / root privileges (cap_net_raw / cap_net_admin) — permission model
• Optional: packaging via setup.py; config via .conf example
• Error & reconnect flow: a small flowchart showing reconnection attempts and logging on failure.
Specific elements to include (explicit checklist
• Discovery: BLEHeartRateLogger → hcitool (lescan) → BLE device
• /subscribe: BLEHeartRateLogger → gatttool (connect, characteristics, subscribe)
• Notifications: BLE device → gatttool → BLEHeartRateLogger (notifications containing HR/ RR)
• Persistence: BLEHeartRateLogger → sqlite DB (INSERT timestamp, HR, RR)
• Logging: BLEHeartRateLogger → console/log
• Permissions: Host OS → hcitool/hciconfig setcap / root privilege
• Pexpect as the mechanism bridging the Python process and the system tools.
• Config file / CLI options feeding into the BLEHeartRateLogger Process.
• User/operator and mention Ctrl-C to stop (signal handling).