Aller au contenu principal

Comment créer un moniteur de fréquence cardiaque avec Capacitor

Créez un moniteur de fréquence cardiaque avec Capacitor et Bluetooth Low Energy : scannez les capteurs 0x180D, analysez le BPM et les intervalles RR, et enregistrez les mesures dans Health.

Capacitor app showing live heart rate from a Bluetooth chest strap

Pour créer un moniteur de fréquence cardiaque avec Capacitor, connectez-vous à un capteur Bluetooth Low Energy qui expose le service Heart Rate standard (0x180D), puis abonnez-vous à la caractéristique Heart Rate Measurement (0x2A37), et décode chaque notification en battements par minute. Ce tutoriel le fait avec @capgo/capacitor-bluetooth-low-energy sur Capacitor 8, incluant les intervalles RR, le contact du capteur, la reconnexion et l'enregistrement des mesures dans Apple Health ou Health Connect.

Comment fonctionnent les capteurs de fréquence cardiaque BLE

Le Bluetooth Low Energy divise les appareils en deux rôles. Votre téléphone est le central: il scanne, se connecte et demande les données. La ceinture pectorale est le périphérique: il diffuse et fournit les données.

Un périphérique expose des services, et chaque service contient des caractéristiques, de petites valeurs que vous pouvez lire, écrire ou auxquelles vous pouvez vous abonner. Les services standard ont des UUID 16 bits attribués par le Bluetooth SIG :

UUID Nom Accès Ce que cela vous apporte
0x180D Service de fréquence cardiaque Service Conteneur pour les éléments ci-dessous
0x2A37 Mesure du rythme cardiaque Notifier BPM, contact du capteur, énergie dépensée, intervalles RR
0x2A38 Emplacement du capteur corporel Lecture Poitrine, poignet, doigt, main, lobe de l'oreille, pied
0x2A39 Point de contrôle de la fréquence cardiaque Écrire 0x01 réinitialise le compteur d'énergie dépensée
0x180F Service de batterie Service Niveau de batterie du bracelet
0x2A19 Niveau de batterie Lire / Notifier de 0 à 100 pour cent

Un UUID 16 bits est la forme abrégée de l'UUID complet sur 128 bits 0000XXXX-0000-1000-8000-00805F9B34FB. Le plugin Capgo accepte les deux formes.

Prerequisites

  • Une application Capacitor 8 (n'importe quel framework : Angular, React, Vue, Svelte ou TypeScript pur)
  • Un iPhone ou un téléphone Android physique. Les simulateurs et émulateurs ne disposent pas de radio Bluetooth utilisable
  • Une ceinture cardiorespiratoire BLE comme la Polar H10, la Garmin HRM-Pro ou la Wahoo TICKR. Humidifiez les électrodes et portez-la, car de nombreuses ceintures restent en veille sans contact cutané

Si vous partez de zéro :

bun create vite heart-rate --template vanilla-ts
cd heart-rate
bun add @capacitor/core @capacitor/ios @capacitor/android
bun add -d @capacitor/cli
bunx cap init "Heart Rate" com.example.heartrate --web-dir dist
bun run build
bunx cap add ios
bunx cap add android

Installer le plugin Bluetooth Low Energy

bun add @capgo/capacitor-bluetooth-low-energy
bunx cap sync

Configuration iOS

Ajoutez les chaînes d'utilisation Bluetooth au ios/App/App/Info.plist, et le bluetooth-central mode arrière-plan si vous souhaitez obtenir des relevés avec l'écran verrouillé :

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Connect to your heart rate sensor during workouts.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Connect to your heart rate sensor during workouts.</string>
<key>UIBackgroundModes</key>
<array>
  <string>bluetooth-central</string>
</array>

Configuration Android

Le plugin fusionne les permissions nécessaires dans votre manifeste : BLUETOOTH_SCAN (avec neverForLocation), BLUETOOTH_CONNECT et BLUETOOTH_ADVERTISE pour Android 12+, ainsi que les anciennes BLUETOOTH, BLUETOOTH_ADMIN et les permissions de localisation pour Android 11 et versions antérieures. Sur Android 12+, vous devez toujours les demander à l'exécution, ce que requestPermissions() fait.

Il déclare également android.hardware.bluetooth_le comme obligatoire, ce qui masque votre application sur Google Play pour les appareils sans BLE. Si la fréquence cardiaque est une fonctionnalité facultative dans votre app, surchargez-la dans android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-feature
        android:name="android.hardware.bluetooth_le"
        android:required="false"
        tools:replace="android:required" />
</manifest>

Décoder la mesure de la fréquence cardiaque

Commencez par cette étape, car c'est là que la plupart des implémentations échouent. La valeur de la caractéristique est un tableau d'octets :

Octet(s) Signification
0 Drapeaux
1 ou 1-2 Fréquence cardiaque : UINT8 si le bit 0 du flag est 0, UINT16 little-endian si 1
2 suivants (facultatif) Énergie dépensée en kJ, présente si le bit 3 du flag est 1
reste (facultatif) Intervalles RR, UINT16 little-endian, unité 1/1024 s, présents si le bit 4 du flag est 1

Les bits 1 et 2 des flags décrivent le contact avec la peau : le bit 2 indique si le capteur prend en charge la détection de contact, le bit 1 indique si un contact est détecté.

export interface HeartRateMeasurement {
  bpm: number;
  contactDetected: boolean | null; // null when the sensor does not report contact
  energyExpendedKj?: number;
  rrIntervalsMs: number[];
}

export function parseHeartRate(bytes: number[]): HeartRateMeasurement {
  const data = Uint8Array.from(bytes);
  const view = new DataView(data.buffer);
  const flags = data[0];
  let offset = 1;

  const is16Bit = (flags & 0x01) !== 0;
  const bpm = is16Bit ? view.getUint16(offset, true) : view.getUint8(offset);
  offset += is16Bit ? 2 : 1;

  const contactSupported = (flags & 0x04) !== 0;
  const contactDetected = contactSupported ? (flags & 0x02) !== 0 : null;

  let energyExpendedKj: number | undefined;
  if (flags & 0x08) {
    energyExpendedKj = view.getUint16(offset, true);
    offset += 2;
  }

  const rrIntervalsMs: number[] = [];
  if (flags & 0x10) {
    for (; offset + 1 < data.length; offset += 2) {
      rrIntervalsMs.push(Math.round((view.getUint16(offset, true) / 1024) * 1000));
    }
  }

  return { bpm, contactDetected, energyExpendedKj, rrIntervalsMs };
}

Le true argument à getUint16 signifie little-endian, comme l’exige la spécification Bluetooth. Code décale le premier octet vers la gauche (byte1 << 8 | byte2) lit les valeurs sur 16 bits à l’envers.

Un test de validité rapide :

parseHeartRate([0x16, 0x48, 0x00, 0x04]);
// flags 0x16: 8-bit value, contact supported and detected, RR present
// => { bpm: 72, contactDetected: true, rrIntervalsMs: [1000] }

Se connecter au capteur

Le module suivant scanne les appareils qui diffusent le service Heart Rate, se connecte au premier trouvé et transmet les mesures analysées à un callback.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';
import type { PluginListenerHandle } from '@capacitor/core';
import { parseHeartRate, type HeartRateMeasurement } from './heart-rate-parser';

const HEART_RATE_SERVICE = '180D';
const HEART_RATE_MEASUREMENT = '2A37';
const BODY_SENSOR_LOCATION = '2A38';
const BATTERY_SERVICE = '180F';
const BATTERY_LEVEL = '2A19';

// iOS reports short UUIDs ("2A37"), Android reports the full 128-bit form
const isUuid = (value: string, short: string) =>
  value.toUpperCase() === short || value.toUpperCase().startsWith(`0000${short}-`);

let listeners: PluginListenerHandle[] = [];
let connectedId: string | null = null;

export async function startHeartRate(onReading: (m: HeartRateMeasurement) => void) {
  await BluetoothLowEnergy.initialize({ mode: 'central' });

  const { available } = await BluetoothLowEnergy.isAvailable();
  if (!available) throw new Error('This device has no Bluetooth LE');

  const perms = await BluetoothLowEnergy.requestPermissions();
  if (perms.bluetooth !== 'granted') throw new Error('Bluetooth permission denied');

  const { enabled } = await BluetoothLowEnergy.isEnabled();
  if (!enabled) {
    await BluetoothLowEnergy.openBluetoothSettings();
    throw new Error('Bluetooth is off. Turn it on and tap Connect again.');
  }

  listeners.push(
    await BluetoothLowEnergy.addListener('characteristicChanged', (event) => {
      if (isUuid(event.characteristic, HEART_RATE_MEASUREMENT)) {
        onReading(parseHeartRate(event.value));
      }
    }),
    await BluetoothLowEnergy.addListener('deviceDisconnected', ({ deviceId }) => {
      if (deviceId === connectedId) void reconnect(deviceId);
    }),
  );

  try {
    const device = await scanForSensor(10_000);
    try {
      await connectTo(device.deviceId);
    } catch (error) {
      // connect() may have succeeded before a later step failed: release the half-open link
      await BluetoothLowEnergy.disconnect({ deviceId: device.deviceId }).catch(() => undefined);
      throw error;
    }
  } catch (error) {
    // Don't leave listeners behind, or each retry would handle every event again
    await Promise.all(listeners.map((l) => l.remove()));
    listeners = [];
    throw error;
  }
}

function scanForSensor(timeoutMs: number) {
  return new Promise<{ deviceId: string; name: string | null }>((resolve, reject) => {
    let handle: PluginListenerHandle | undefined;
    let settled = false;

    const finish = (error: Error | null, device?: { deviceId: string; name: string | null }) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      void handle?.remove();
      void BluetoothLowEnergy.stopScan().catch(() => undefined);
      if (error) reject(error);
      else resolve(device!);
    };

    const timer = setTimeout(
      () => finish(new Error('No heart rate sensor found. Is the strap worn and moist?')),
      timeoutMs,
    );

    BluetoothLowEnergy.addListener('deviceScanned', ({ device }) => finish(null, device))
      .then((h) => {
        handle = h;
        if (settled) {
          void h.remove();
          return;
        }
        return BluetoothLowEnergy.startScan({ services: [HEART_RATE_SERVICE] });
      })
      .catch((error) => finish(error instanceof Error ? error : new Error(String(error))));
  });
}

async function connectTo(deviceId: string) {
  await BluetoothLowEnergy.connect({ deviceId });
  await BluetoothLowEnergy.discoverServices({ deviceId });
  await BluetoothLowEnergy.startCharacteristicNotifications({
    deviceId,
    service: HEART_RATE_SERVICE,
    characteristic: HEART_RATE_MEASUREMENT,
  });
  connectedId = deviceId;
  localStorage.setItem('hr-sensor', deviceId);
}

async function reconnect(deviceId: string, attempt = 0) {
  // stopHeartRate() clears connectedId, which ends any pending retry chain
  if (attempt > 5 || connectedId !== deviceId) return;
  try {
    await connectTo(deviceId);
  } catch {
    setTimeout(() => void reconnect(deviceId, attempt + 1), 2000 * (attempt + 1));
  }
}

export async function stopHeartRate() {
  if (connectedId) {
    await BluetoothLowEnergy.stopCharacteristicNotifications({
      deviceId: connectedId,
      service: HEART_RATE_SERVICE,
      characteristic: HEART_RATE_MEASUREMENT,
    }).catch(() => undefined);
    const id = connectedId;
    connectedId = null; // prevents the disconnect listener from reconnecting
    await BluetoothLowEnergy.disconnect({ deviceId: id });
  }
  await Promise.all(listeners.map((l) => l.remove()));
  listeners = [];
}

Pourquoi c’est écrit ainsi :

  • Filtrer le scan par service. startScan({ services: ['180D'] }) ne renvoie que les capteurs de fréquence cardiaque, ce qui évite de filtrer par nom d’appareil, qui varie selon les modèles et les versions de firmware.
  • Enregistrer les listeners avant de s’abonner, sinon les premières notifications peuvent arriver avant que votre handler n’existe.
  • Arrêtez le scan une fois connecté. Le scan consomme de la batterie et ralentit les connexions sur certains téléphones Android.
  • Les identifiants d’appareil diffèrent selon la plateforme: une adresse MAC sur Android, un UUID par application sur iOS. Stockez la valeur obtenue et réutilisez-l’uniquement sur le même appareil.

Lire l'emplacement et la batterie du capteur

const LOCATIONS = ['Other', 'Chest', 'Wrist', 'Finger', 'Hand', 'Ear lobe', 'Foot'];

export async function readSensorInfo(deviceId: string) {
  const location = await BluetoothLowEnergy.readCharacteristic({
    deviceId,
    service: HEART_RATE_SERVICE,
    characteristic: BODY_SENSOR_LOCATION,
  }).catch(() => null);

  const battery = await BluetoothLowEnergy.readCharacteristic({
    deviceId,
    service: BATTERY_SERVICE,
    characteristic: BATTERY_LEVEL,
  }).catch(() => null);

  return {
    location: location ? LOCATIONS[location.value[0]] ?? 'Unknown' : 'Unknown',
    batteryPercent: battery ? battery.value[0] : null,
  };
}

Les deux sont optionnels dans la spécification, donc enveloppez les lectures et gérez les valeurs manquantes.

Créer l'écran

Une interface minimale avec un bouton de connexion, le BPM en direct et un avertissement de contact :

<main>
  <h1>Heart rate</h1>
  <p id="bpm" aria-live="polite">--</p>
  <p id="status"></p>
  <button id="connect" type="button">Connect sensor</button>
</main>
import { startHeartRate } from './heart-rate';

const bpmEl = document.getElementById('bpm')!;
const statusEl = document.getElementById('status')!;

document.getElementById('connect')!.addEventListener('click', async () => {
  statusEl.textContent = 'Searching...';
  try {
    await startHeartRate((m) => {
      bpmEl.textContent = m.contactDetected === false ? '--' : `${m.bpm} bpm`;
      statusEl.textContent = m.contactDetected === false ? 'Check strap contact' : 'Connected';
    });
  } catch (e) {
    statusEl.textContent = (e as Error).message;
  }
});

Lancez le scan depuis un appui sur le bouton, pas au chargement de la page. iOS et Android affichent des prompts d’autorisation la première fois, et les utilisateurs les acceptent plus souvent lorsqu’ils comprennent pourquoi.

Exécutez-le sur un appareil :

bun run build
bunx cap run android
bunx cap run ios

Utiliser les intervalles RR pour la VFC

Les intervalles RR sont le temps entre deux battements. Ils permettent de calculer la variabilité de la fréquence cardiaque, utilisée par les applications pour les scores de récupération et de stress. Le RMSSD sur une fenêtre glissante est la métrique courante :

export function rmssd(rr: number[]): number | null {
  if (rr.length < 2) return null;
  let sum = 0;
  for (let i = 1; i < rr.length; i++) sum += (rr[i] - rr[i - 1]) ** 2;
  return Math.sqrt(sum / (rr.length - 1));
}

Collectez au moins une minute d'intervalles au repos et éliminez les valeurs aberrantes (par exemple, les intervalles qui diffèrent de plus de 20 % par rapport au précédent) causées par des artefacts de mouvement.

Enregistrer les mesures dans Apple Health ou Health Connect

Pour rendre les lectures disponibles à d'autres applications, écrivez-les avec @capgo/capacitor-health. Moyennnez sur une courte fenêtre plutôt que d'écrire chaque notification :

import { Health } from '@capgo/capacitor-health';

await Health.requestAuthorization({ write: ['heartRate'] });

export async function saveAverage(bpm: number, start: Date, end: Date) {
  await Health.saveSample({
    dataType: 'heartRate',
    value: bpm,
    unit: 'bpm',
    startDate: start.toISOString(),
    endDate: end.toISOString(),
  });
}

HealthKit nécessite la capacité HealthKit et les chaînes d'utilisation sur iOS. Health Connect nécessite des permissions déclarées dans le manifest et un écran de politique de confidentialité sur Android. Notre guide de migration de Google Fit vers Health Connect couvre cette configuration.

Maintenir le moniteur actif pendant l'entraînement

  • iOS: avec bluetooth-central dans UIBackgroundModes, les notifications continuent d’arriver lorsque l’app est en arrière-plan et que l’écran est verrouillé. iOS peut toujours interrompre la connexion sous pression mémoire, donc conservez la logique de reconnexion.
  • Android: une session GATT connectée continue de délivrer des notifications tant que votre processus est actif. Pour des entraînements de plus de quelques minutes avec l’écran éteint, Android peut figer ou tuer l’app. La solution simple est de garder l’écran allumé pendant une session active avec @capgo/capacitor-keep-awake (KeepAwake.keepAwake() et KeepAwake.allowSleep()). Pour un enregistrement en arrière-plan réel, ajoutez votre propre service en premier plan avec android:foregroundServiceType="connectedDevice" et le FOREGROUND_SERVICE_CONNECTED_DEVICE permission.

Troubleshooting

Aucun appareil trouvé: la sangle n’est pas portée ou les électrodes sont sèches. De nombreuses sangles n’autorisent qu’une seule connexion, donc déconnectez-les d’abord d’une montre, d’un compteur de vélo ou d’une autre application.

requestPermissions renvoie « denied » sur Android 11 ou inférieur: le scan BLE sur ces versions nécessite l’autorisation de localisation et les services de localisation activés. Vérifiez isLocationEnabled() et appeler openLocationSettings().

La détection ne trouve rien sur Android 12+, mais fonctionne sur 11: l'utilisateur a refusé « Appareils à proximité ». Redirigez-le vers openAppSettings().

Le rythme cardiaque est toujours à 0: aucun contact avec la peau. Vérifiez contactDetected.

Valeurs supérieures à 255 bpm ou chiffres aléatoires: vous ignorez le bit 0 du flag ou vous lisez des valeurs 16 bits en big-endian. Utilisez le parser ci-dessus.

Les notifications s'arrêtent après le verrouillage du téléphone sur Android: optimisation de la batterie. Gardez l'écran actif pendant les sessions ou utilisez un service en premier plan.

L'application est absente sur certains appareils dans Google Play : celle du plugin uses-feature pour le BLE est requis par défaut. Remplacez-le comme indiqué dans la section de configuration Android.

Prochaines étapes

Le même principe s'applique aux autres profils GATT standard : Cycling Speed and Cadence (0x1816), Vitesse de course et cadence (0x1814), et Cycling Power (0x1818). Seul le parser change. Voir le Docs du plugin Bluetooth Low Energy pour les écritures, les requêtes MTU et le mode périphérique. Une fois l'app native publiée sur les stores, les corrections de parsing et les changements d'UI sont en JavaScript : vous pouvez donc les déployer avec les live updates Capgo au lieu d'attendre la validation.

Live updates pour les apps Capacitor

Lorsqu'un bug de la couche web est en ligne, déployez le correctif via Capgo au lieu d'attendre des jours l'approbation des stores. Les utilisateurs reçoivent la mise à jour en arrière-plan, tandis que les changements natifs suivent le circuit de validation habituel.

Les derniers articles du blog

Capgo vous offre les meilleures informations pour créer une application mobile vraiment professionnelle.