Prise en main

Installation

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil d'IA en utilisant la commande suivante :

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Ensuite, utilisez la prompt suivante :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-bluetooth-low-energy` plugin in my project.

Si vous préférez la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques au plateforme ci-dessous :

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

Importer

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

Démarrage rapide

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.initialize({ mode: 'central' });

Exemple : shimWebBluetooth

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

BluetoothLowEnergy.shimWebBluetooth();

Exemple : isAvailable

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { available } = await BluetoothLowEnergy.isAvailable();

Pièges courants

• PermissionsAutorisations checkPermissions() : appeler requestPermissions() lorsqu'il le faut.
• Listeners: supprimez les gérants lorsqu'un écran se démonte.
• Initialise une fois: run setup during app bootstrap.

API Présentation

initialize

Initialisez le plugin BLE. Doit être appelé avant toute autre méthode.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.initialize({ mode: 'central' });

shimWebBluetooth

Installez le shim Web Bluetooth Capacitor sur navigator.bluetoothAppeler cela manuellement avant d'utiliser le Bluetooth Web API depuis une application native Capacitor.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

BluetoothLowEnergy.shimWebBluetooth();

isAvailable

Vérifiez si le Bluetooth est disponible sur le dispositif.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { available } = await BluetoothLowEnergy.isAvailable();

isEnabled

Vérifiez si le Bluetooth est activé sur le dispositif.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { enabled } = await BluetoothLowEnergy.isEnabled();

isLocationEnabled

Titre de la section « isLocationEnabled »

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { enabled } = await BluetoothLowEnergy.isLocationEnabled();

openAppSettings

Titre de la section « openAppSettings »

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.openAppSettings();

openBluetoothSettings

Titre de la section « openBluetoothSettings »

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.openBluetoothSettings();

openLocationSettings

Ouvrez la page des paramètres de localisation (seulement Android).

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.openLocationSettings();

checkPermissions

Vérifiez l'état actuel des autorisations.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { bluetooth, location } = await BluetoothLowEnergy.checkPermissions();

requestPermissions

Demandez les autorisations Bluetooth.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { bluetooth, location } = await BluetoothLowEnergy.requestPermissions();

startScan

Démarrer la recherche de périphériques BLE.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.startScan({
  services: ['180D'], // Heart Rate Service
  timeout: 10000
});

stopScan

Arrêter la recherche de périphériques BLE.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.stopScan();

connect

Se connecter à un appareil BLE.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.connect({ deviceId: 'AA:BB:CC:DD:EE:FF' });

disconnect

Se connecter à un périphérique BLE.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.disconnect({ deviceId: 'AA:BB:CC:DD:EE:FF' });

createBond

Se déconnecter d'un périphérique BLE.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.createBond({ deviceId: 'AA:BB:CC:DD:EE:FF' });

isBonded

Vérifiez si un appareil est lié (seulement pour Android).

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { bonded } = await BluetoothLowEnergy.isBonded({ deviceId: 'AA:BB:CC:DD:EE:FF' });

discoverServices

Découvrez les services sur un appareil connecté.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.discoverServices({ deviceId: 'AA:BB:CC:DD:EE:FF' });

getServices

Obtenez les services découverts pour un appareil.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { services } = await BluetoothLowEnergy.getServices({ deviceId: 'AA:BB:CC:DD:EE:FF' });

getConnectedDevices

Obtenez une liste des appareils connectés.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { devices } = await BluetoothLowEnergy.getConnectedDevices();

readCharacteristic

Lire une valeur de caractéristique.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { value } = await BluetoothLowEnergy.readCharacteristic({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37'
});

writeCharacteristic

Écrire une valeur à une caractéristique.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.writeCharacteristic({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A39',
  value: [0x01]
});

startCharacteristicNotifications

Démarrer les notifications pour une caractéristique.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.startCharacteristicNotifications({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37'
});

stopCharacteristicNotifications

Arrêter les notifications pour une caractéristique.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.stopCharacteristicNotifications({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37'
});

readDescriptor

Lire une valeur de décripteur.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { value } = await BluetoothLowEnergy.readDescriptor({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37',
  descriptor: '2902'
});

writeDescriptor

Écrire une valeur dans un décripteur.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.writeDescriptor({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180D',
  characteristic: '2A37',
  descriptor: '2902',
  value: [0x01, 0x00]
});

readRssi

Lire la puissance du signal (RSSI) d'un appareil connecté.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { rssi } = await BluetoothLowEnergy.readRssi({ deviceId: 'AA:BB:CC:DD:EE:FF' });

requestMtu

Request MTU size change (Android only).

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

const { mtu } = await BluetoothLowEnergy.requestMtu({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  mtu: 512
});

requestConnectionPriority

Requérir la priorité de connexion (seulement Android).

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.requestConnectionPriority({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  priority: 'high'
});

startAdvertising

Démarrer l'annonce en tant que périphérique (serveur BLE).

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.startAdvertising({
  name: 'MyDevice',
  services: ['180D']
});

stopAdvertising

Arrêter l'annonce.

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.stopAdvertising();

startForegroundService

Démarrer un service de fond pour maintenir les connexions BLE en arrière-plan (seulement Android).

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.startForegroundService({
  title: 'BLE Connection',
  body: 'Maintaining connection...'
});

stopForegroundService

Arrêtez le service de foreground (seulement pour Android).

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.stopForegroundService();

Type de référence

InitializeOptions

Options d’initialisation pour le plugin.

export interface InitializeOptions {
  /**
   * The mode to initialize the plugin in.
   * - 'central': Act as a BLE central (client)
   * - 'peripheral': Act as a BLE peripheral (server)
   *
   * @default 'central'
   * @since 1.0.0
   */
  mode?: 'central' | 'peripheral';
}

IsAvailableResult

Résultat de la méthode isAvailable.

export interface IsAvailableResult {
  /**
   * Whether Bluetooth is available on the device.
   *
   * @since 1.0.0
   */
  available: boolean;
}

IsEnabledResult

Résultat de la méthode isEnabled.

export interface IsEnabledResult {
  /**
   * Whether Bluetooth is enabled on the device.
   *
   * @since 1.0.0
   */
  enabled: boolean;
}

IsLocationEnabledResult

Résultat de la méthode isLocationEnabled.

export interface IsLocationEnabledResult {
  /**
   * Whether location services are enabled on the device.
   *
   * @since 1.0.0
   */
  enabled: boolean;
}

PermissionStatus

État de permission pour le Bluetooth et la localisation.

export interface PermissionStatus {
  /**
   * Bluetooth permission status.
   *
   * @since 1.0.0
   */
  bluetooth: PermissionState;

  /**
   * Location permission status (Android only).
   *
   * @since 1.0.0
   */
  location: PermissionState;
}

StartScanOptions

Options pour lancer une exploration.

export interface StartScanOptions {
  /**
   * List of service UUIDs to filter by.
   * Only devices advertising these services will be returned.
   *
   * @since 1.0.0
   */
  services?: string[];

  /**
   * Scan timeout in milliseconds.
   * Set to 0 for no timeout.
   *
   * @default 0
   * @since 1.0.0
   */
  timeout?: number;

  /**
   * Whether to allow duplicate scan results.
   *
   * @default false
   * @since 1.0.0
   */
  allowDuplicates?: boolean;
}

ConnectOptions

Options pour se connecter à un appareil.

export interface ConnectOptions {
  /**
   * The device ID (MAC address on Android, UUID on iOS).
   *
   * @since 1.0.0
   */
  deviceId: string;

  /**
   * Whether to automatically connect when the device becomes available.
   *
   * @default false
   * @since 1.0.0
   */
  autoConnect?: boolean;
}

DisconnectOptions

Options pour se déconnecter d'un appareil.

export interface DisconnectOptions {
  /**
   * The device ID to disconnect from.
   *
   * @since 1.0.0
   */
  deviceId: string;
}

CreateBondOptions

Options pour se déconnecter d'un appareil.

export interface CreateBondOptions {
  /**
   * The device ID to bond with.
   *
   * @since 1.0.0
   */
  deviceId: string;
}

IsBondedOptions

Options pour créer une liaison.

export interface IsBondedOptions {
  /**
   * The device ID to check.
   *
   * @since 1.0.0
   */
  deviceId: string;
}

IsBondedResult

Résultat de la méthode isBonded.

export interface IsBondedResult {
  /**
   * Whether the device is bonded.
   *
   * @since 1.0.0
   */
  bonded: boolean;
}

DiscoverServicesOptions

Options pour découvrir les services.

export interface DiscoverServicesOptions {
  /**
   * The device ID to discover services on.
   *
   * @since 1.0.0
   */
  deviceId: string;
}

Source de vérité

Cette page est générée à partir du plugin’s src/definitions.tsRe-run la synchronisation lorsque le public API change en amont.

Continuez de Getting Started

Si vous utilisez Prise en main planifier l'interface de suivi et les API opérations, connectez-l’à Utilisation de @capgo/capacitor-Bluetooth Low Energy pour la capacité native dans l'utilisation de @capgo/capacitor-Bluetooth faible en énergie API Vue d'ensemble pour le détail d'implémentation dans API Vue d'ensemble, Introduction pour le détail d'implémentation dans Introduction, API Clés pour le détail d'implémentation dans API Clés, et Appareils pour les détails d'implémentation dans les appareils.