How celesteinter/heartwatch works
HeartWatch combines an ESP32-S3 wearable prototype with a desktop monitoring and session-analysis app. The documented firmware workflow initializes the OLED and MAX30102, polls optical samples, derives beats per minute, and displays the result. The host app presents live monitoring, persists session samples, and supports history, statistics, activity-classification scaffolding, and optional local-LLM summaries. The live monitor currently uses generated demo data; the ML inference module is explicitly unfinished. Some UI and firmware wiring is inferred only where sampled source supports it.
Main entry points: db.py Database operations · main.py App entry · main_window.py Main window · worker.py LLM worker
Components 25
Wearable firmware
- Device app
HeartWatch/src/main.c - Pulse driver
HeartWatch/src/max30102.c - OLED driver
HeartWatch/src/sh1107.c
Desktop interface
- App entry
heartwatchapp/main.py - Main window
heartwatchapp/ui/main_window.py - Live monitor
heartwatchapp/ui/live_monitor.py - Dashboard
heartwatchapp/ui/dashboard.py - Session history
heartwatchapp/ui/sessions.py - ML view
heartwatchapp/ui/ml_view.py
Session data
- Write worker
heartwatchapp/data/writer.py - Database operations
heartwatchapp/data/db.py - SQLite schema
heartwatchapp/data/schema.sql - Session database
Analysis features
- Session statistics
heartwatchapp/data/stats.py - Activity classifier
heartwatchapp/ml/inference.py
Local summaries
- LLM worker
heartwatchapp/llm/worker.py - Ollama client
heartwatchapp/llm/client.py - Summary prompts
heartwatchapp/llm/prompts.py - Summary checks
heartwatchapp/llm/validate.py
Other components
- Wearer
- MAX30102
- MPU sensor
- SH1107 display
- Desktop user
- Ollama runtime
Connections 28
- Wearer → Device app: wears device
- Device app → Pulse driver: initializes, reads
- MAX30102 → Pulse driver: optical signal
- Device app → MPU sensor: configures I2C
- Device app → OLED driver: prints BPM
- OLED driver → SH1107 display: updates display
- Desktop user → App entry: starts app
- App entry → Database operations: initializes database
- App entry → Write worker: starts worker
- App entry → LLM worker: starts worker
- App entry → Main window: opens interface
- Main window → Live monitor: shows view
- Main window → Dashboard: shows view
- Main window → Session history: shows view
- Main window → ML view: shows view
- Live monitor → Write worker: queues samples
- Write worker → Database operations: executes writes
- Database operations → Session database: reads and writes
- SQLite schema → Session database: defines tables
- Session history → Database operations: loads session data
- Session history → Session statistics: computes summary
- Session statistics → Database operations: queries aggregates
- Database operations → Activity classifier: exports training CSV
- Session history → LLM worker: requests summary
- LLM worker → Summary prompts: builds messages
- LLM worker → Ollama client: checks and chats
- LLM worker → Summary checks: screens reply
- Ollama client → Ollama runtime: calls local model