Remote Configuration

The Vitals SDK supports remote configuration, allowing you to customize measurement parameters, signal processing thresholds, and output formatting without redeploying your application.

Configuration Overview

Configuration settings can be applied at multiple levels:

SDK Initialization: Initial configuration when creating the SDK instance
Session Level: Configuration specific to individual measurement sessions
Remote API: Dynamic configuration changes via the Admin API
Default Presets: Pre-configured settings for common use cases

Window Duration

Adjust the aggregation window duration for stable, averaged results.

Configuration

javascript

const config = {
  windowDuration: 45, // seconds (default)
  windowOverlap: 15,  // seconds overlap for continuous monitoring
  updateRate: 5       // seconds between updates
};

// Short windows for real-time feedback
const realtimeConfig = {
  windowDuration: 15,  // 15 seconds
  updateRate: 2        // Update every 2 seconds
};

// Long windows for high accuracy
const accurateConfig = {
  windowDuration: 60,  // 60 seconds
  updateRate: 10       // Update every 10 seconds
};

Trade-offs

Shorter Windows (15-30s): Faster response, higher variance
Default (45s): Balanced speed and stability
Longer Windows (60-90s): Slower response, higher stability

Signal Threshold Tuning

Customize signal quality thresholds to balance accuracy and usability.

Quality Thresholds

javascript

const qualityThresholds = {
  // Signal-to-Noise Ratio
  snr: {
    minimum: 8,        // Minimum SNR for valid measurement
    good: 12,          // SNR considered "good"
    excellent: 20      // SNR considered "excellent"
  },
  
  // Usable Frame Ratio
  usableFrameRatio: {
    minimum: 0.5,      // 50% minimum usable frames
    good: 0.7,         // 70% considered good
    excellent: 0.85    // 85% considered excellent
  },
  
  // Brightness Range (0-255)
  brightness: {
    min: 50,           // Minimum brightness
    max: 200,          // Maximum brightness
    optimal: 125       // Optimal brightness
  },
  
  // Sharpness (0-1)
  sharpness: {
    minimum: 0.4,      // Minimum sharpness threshold
    optimal: 0.7       // Optimal sharpness
  },
  
  // Motion (pixels per frame)
  motion: {
    maximum: 10,       // Maximum allowed motion
    good: 5,           // Motion considered good
    excellent: 2       // Minimal motion
  }
};

Applying Thresholds

javascript

const vitals = new VitalsSDK({
  qualityThresholds: {
    snr: { minimum: 10, good: 15 },
    usableFrameRatio: { minimum: 0.6, good: 0.75 },
    brightness: { min: 60, max: 190 },
    sharpness: { minimum: 0.5 },
    motion: { maximum: 8 }
  }
});

Calibration Offsets

Apply calibration offsets to adjust estimated values based on ground truth measurements.

Individual Calibration

javascript

const calibration = {
  userId: 'user-123',
  
  // Heart rate calibration (BPM)
  heartRate: {
    offset: 2.5,          // Add 2.5 BPM to all measurements
    multiplier: 1.02      // Multiply by 1.02
  },
  
  // HRV calibration (ms)
  hrv: {
    offset: 5,            // Add 5 ms to all measurements
    multiplier: 1.05      // Multiply by 1.05
  },
  
  // Blood pressure calibration (mmHg)
  bloodPressure: {
    systolic: { offset: 3, multiplier: 1.01 },
    diastolic: { offset: -2, multiplier: 0.99 }
  },
  
  // SpO2 calibration (%)
  spo2: {
    offset: -0.5,         // Subtract 0.5%
    multiplier: 1.0       // No multiplier
  }
};

// Apply calibration
vitals.setCalibration(calibration);

Population Calibration

javascript

// Create calibration profiles for different populations
const calibrationProfiles = {
  general: {
    heartRate: { offset: 0, multiplier: 1.0 }
  },
  
  athletes: {
    heartRate: { offset: -2, multiplier: 0.98 },
    hrv: { offset: 10, multiplier: 1.1 }
  },
  
  elderly: {
    heartRate: { offset: 1, multiplier: 1.01 },
    hrv: { offset: -5, multiplier: 0.95 }
  }
};

// Apply based on user profile
const user = { age: 65, activityLevel: 'low' };
const profile = user.age > 60 ? 'elderly' : 'general';
vitals.setCalibration(calibrationProfiles[profile]);

Output Formatting

Configure the format and content of measurement outputs.

Output Options

javascript

const outputFormat = {
  // Include/exclude data
  includeRawSignal: false,
  includeTimestamp: true,
  includeConfidence: true,
  includeQualityMetrics: true,
  includeWindowInfo: true,
  
  // Precision settings
  precision: {
    heartRate: 1,        // 1 decimal place
    hrv: 1,              // 1 decimal place
    respiratoryRate: 1,  // 1 decimal place
    spo2: 1,             // 1 decimal place
    bloodPressure: 0     // No decimal places
  },
  
  // Units
  units: {
    heartRate: 'BPM',
    hrv: 'ms',
    respiratoryRate: 'RPM',
    spo2: '%',
    bloodPressure: 'mmHg',
    bloodSugar: 'mg/dL'
  },
  
  // Timestamp format
  timestampFormat: 'ISO8601',  // 'ISO8601' or 'unix'
  
  // Response format
  format: 'json'              // 'json' or 'compact'
};

Quality Gating Thresholds

Configure quality gating to control when measurements are accepted or rejected.

Gating Configuration

javascript

const qualityGating = {
  // Minimum requirements for any measurement
  minimumRequirements: {
    snr: 8,
    usableFrameRatio: 0.5,
    confidence: 0.4
  },
  
  // Requirements for "good" measurements
  goodThresholds: {
    snr: 12,
    usableFrameRatio: 0.7,
    confidence: 0.6
  },
  
  // Requirements for "excellent" measurements
  excellentThresholds: {
    snr: 20,
    usableFrameRatio: 0.85,
    confidence: 0.8
  },
  
  // Gating behavior
  behavior: {
    rejectBelowMinimum: true,      // Reject poor measurements
    flagBelowGood: true,           // Flag suboptimal measurements
    includeQualityFlags: true,     // Include quality indicators
    requireFullWindow: true        // Require complete window
  }
};