Feature/hrv support (#295)

This adds support for importing HRV data from Garmin's HRV_STATUS.fit files,
which contain overnight HRV measurements and daily status summaries.

Changes:
- Add MonitoringHrvValue table for individual HRV RMSSD readings during sleep
- Add MonitoringHrvStatus table for daily HRV status summaries
- Add HRV message handlers in MonitoringFitFileProcessor
- Include FileType.hrv_status in monitoring FIT file processing
- Bump monitoring DB version to 7

The HRV data includes:
- Individual RMSSD readings (5-minute intervals during sleep)
- Weekly average RMSSD
- Last night's average RMSSD
- Baseline low/high bounds
- HRV status (0=unknown, 2=poor, 3=low, 4=balanced)
- Reading count

Requires corresponding changes in the Fit submodule for:
- FileType.hrv_status (68)
- MessageType.hrv_status_summary (370)
- MessageType.hrv_value (371)

Author: alpenglowtek

Fit

@@ -8,7 +8,7 @@
 
 from .garmin_db import GarminDb, Attributes, Device, DeviceInfo, File, Weight, Stress, Sleep, SleepEvents, RestingHeartRate, DailySummary
 from .monitoring_db import MonitoringDb, MonitoringInfo, MonitoringHeartRate, MonitoringIntensity, MonitoringClimb, Monitoring, \
-    MonitoringRespirationRate, MonitoringPulseOx
+    MonitoringRespirationRate, MonitoringPulseOx, MonitoringHrvValue, MonitoringHrvStatus
 from .activities_db import ActivitiesDb, Activities, ActivityLaps, ActivityRecords, ActivitiesDevices, ActivitySplits, SportActivities, StepsActivities, \
     PaddleActivities, CycleActivities, ClimbingActivities
 from .garmin_summary_db import GarminSummaryDb, Summary, YearsSummary, MonthsSummary, WeeksSummary, DaysSummary, IntensityHR

garmindb/garmindb/__init__.py

@@ -16,7 +16,7 @@
 
 logger = logging.getLogger(__name__)
 
-MonitoringDb = idbutils.DB.create('garmin_monitoring', 6, "Database for storing daily health monitoring data from a Garmin device.")
+MonitoringDb = idbutils.DB.create('garmin_monitoring', 7, "Database for storing daily health monitoring data from a Garmin device.")
 
 
 class MonitoringInfo(MonitoringDb.Base, idbutils.DbObject):
@@ -290,3 +290,52 @@ def get_stats(cls, session, start_ts, end_ts):
             'pulse_ox_min' : cls.s_get_col_min(session, cls.pulse_ox, start_ts, end_ts, True),
             'pulse_ox_max' : cls.s_get_col_max(session, cls.pulse_ox, start_ts, end_ts),
         }
+
+
+class MonitoringHrvValue(MonitoringDb.Base, idbutils.DbObject):
+    """Class that represents a database table holding individual HRV (RMSSD) readings during sleep."""
+
+    __tablename__ = 'monitoring_hrv_value'
+
+    db = MonitoringDb
+    table_version = 1
+
+    timestamp = Column(DateTime, primary_key=True)
+    hrv = Column(Float, nullable=False)  # RMSSD in milliseconds
+
+    @classmethod
+    def get_stats(cls, session, start_ts, end_ts):
+        """Return a dict of stats for table entries within the time span."""
+        return {
+            'hrv_avg' : cls.s_get_col_avg(session, cls.hrv, start_ts, end_ts, True),
+            'hrv_min' : cls.s_get_col_min(session, cls.hrv, start_ts, end_ts, True),
+            'hrv_max' : cls.s_get_col_max(session, cls.hrv, start_ts, end_ts),
+        }
+
+
+class MonitoringHrvStatus(MonitoringDb.Base, idbutils.DbObject):
+    """Class that represents a database table holding daily HRV status summaries."""
+
+    __tablename__ = 'monitoring_hrv_status'
+
+    db = MonitoringDb
+    table_version = 1
+
+    timestamp = Column(DateTime, primary_key=True)
+    weekly_average = Column(Float)       # Weekly average RMSSD in milliseconds
+    last_night = Column(Float)           # Last night's RMSSD in milliseconds
+    last_night_average = Column(Float)   # Last night's average RMSSD
+    baseline_low = Column(Float)         # Baseline low bound
+    baseline_high = Column(Float)        # Baseline high bound
+    status = Column(Integer)             # HRV status: 0=unknown, 2=poor, 3=low, 4=balanced
+    reading_count = Column(Integer)      # Number of readings
+
+    @classmethod
+    def get_stats(cls, session, start_ts, end_ts):
+        """Return a dict of stats for table entries within the time span."""
+        return {
+            'hrv_weekly_avg' : cls.s_get_col_avg(session, cls.weekly_average, start_ts, end_ts, True),
+            'hrv_last_night_avg' : cls.s_get_col_avg(session, cls.last_night, start_ts, end_ts, True),
+            'hrv_baseline_low_avg' : cls.s_get_col_avg(session, cls.baseline_low, start_ts, end_ts, True),
+            'hrv_baseline_high_avg' : cls.s_get_col_avg(session, cls.baseline_high, start_ts, end_ts, True),
+        }

garmindb/garmindb/monitoring_db.py

@@ -72,7 +72,7 @@ def __init__(self, input_dir, latest, measurement_system, debug):
         debug (Boolean): enable debug logging
 
         """
-        super().__init__(input_dir, debug, latest, True, [fitfile.FileType.monitoring_b], measurement_system)
+        super().__init__(input_dir, debug, latest, True, [fitfile.FileType.monitoring_b, fitfile.FileType.hrv_status], measurement_system)
 
 
 class GarminSleepFitData(FitData):

garmindb/import_monitoring.py

@@ -13,7 +13,7 @@
 import idbutils
 
 from .garmindb import File
-from .garmindb import MonitoringDb, Monitoring, MonitoringInfo, MonitoringHeartRate, MonitoringIntensity, MonitoringClimb, MonitoringRespirationRate, MonitoringPulseOx
+from .garmindb import MonitoringDb, Monitoring, MonitoringInfo, MonitoringHeartRate, MonitoringIntensity, MonitoringClimb, MonitoringRespirationRate, MonitoringPulseOx, MonitoringHrvValue, MonitoringHrvStatus
 from .fit_file_processor import FitFileProcessor
 
 
@@ -109,3 +109,31 @@ def _write_pulse_ox_entry(self, fit_file, message_fields):
                 MonitoringPulseOx.s_insert_or_update(self.garmin_mon_db_session, pulse_ox_entry)
         else:
             raise ValueError(f'Unexpected file type {repr(fit_file.type)} for pulse ox')
+
+    def _write_hrv_value_entry(self, fit_file, message_fields):
+        """Write an HRV reading entry to the database."""
+        logger.debug("hrv_value message: %r", message_fields)
+        hrv_value = message_fields.get('hrv_value')
+        if hrv_value is not None and hrv_value > 0:
+            # HRV values are scaled by 128 in the FIT file
+            hrv_entry = {
+                'timestamp': fit_file.utc_datetime_to_local(message_fields.timestamp),
+                'hrv': hrv_value / 128.0,  # Convert to milliseconds
+            }
+            MonitoringHrvValue.s_insert_or_update(self.garmin_mon_db_session, hrv_entry)
+
+    def _write_hrv_status_summary_entry(self, fit_file, message_fields):
+        """Write an HRV status summary entry to the database."""
+        logger.debug("hrv_status_summary message: %r", message_fields)
+        # HRV values are scaled by 128 in the FIT file
+        hrv_status_entry = {
+            'timestamp': fit_file.utc_datetime_to_local(message_fields.timestamp),
+            'weekly_average': message_fields.get('weekly_average', 0) / 128.0 if message_fields.get('weekly_average') else None,
+            'last_night': message_fields.get('last_night', 0) / 128.0 if message_fields.get('last_night') else None,
+            'last_night_average': message_fields.get('last_night_average', 0) / 128.0 if message_fields.get('last_night_average') else None,
+            'baseline_low': message_fields.get('baseline_low', 0) / 128.0 if message_fields.get('baseline_low') else None,
+            'baseline_high': message_fields.get('baseline_high', 0) / 128.0 if message_fields.get('baseline_high') else None,
+            'status': message_fields.get('status'),
+            'reading_count': message_fields.get('reading_count'),
+        }
+        MonitoringHrvStatus.s_insert_or_update(self.garmin_mon_db_session, hrv_status_entry)