Erste Schritte

Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-bluetooth-low-energy`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/bluetooth-low-energy/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

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

Importieren

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

Quickstart

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

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

Beispiel: shimWebBluetooth

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

BluetoothLowEnergy.shimWebBluetooth();

Beispiel: isAvailable

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

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

Häufige Stolperfallen

Berechtigungen: aufrufen checkPermissions() dann requestPermissions() bei Bedarf.
Listener: Handles beim Unmounten von Screens entfernen.
Einmalige Initialisierung: Setup beim App-Bootstrap ausführen.

API Übersicht

`initialize`

Initialisiere das BLE-Plugin. Muss vor jeder anderen Methode aufgerufen werden.

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

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

`shimWebBluetooth`

Installiere den Capacitor Web Bluetooth Shim auf navigator.bluetooth. Rufen Sie dies manuell auf, bevor Sie Web Bluetooth API in einer nativen Capacitor-App verwenden.

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

BluetoothLowEnergy.shimWebBluetooth();

`isAvailable`

Prüft, ob Bluetooth auf dem Gerät verfügbar ist.

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

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

`isEnabled`

Prüfen, ob Bluetooth auf dem Gerät aktiviert ist.

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

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

`isLocationEnabled`

Prüfen, ob die Standortdienste aktiviert sind (nur Android).

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

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

`openAppSettings`

Öffne die App-Einstellungen.

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

await BluetoothLowEnergy.openAppSettings();

`openBluetoothSettings`

Öffne die Bluetooth-Einstellungen (nur Android).

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

await BluetoothLowEnergy.openBluetoothSettings();

`openLocationSettings`

Öffne die Standort-Einstellungen (nur Android).

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

await BluetoothLowEnergy.openLocationSettings();

`checkPermissions`

Prüfe den aktuellen Berechtigungsstatus.

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

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

`requestPermissions`

Bluetooth-Berechtigungen anfordern.

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

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

`startScan`

Scan nach BLE-Geräten starten.

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

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

`stopScan`

Scan nach BLE-Geräten stoppen.

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

await BluetoothLowEnergy.stopScan();

`connect`

Mit einem BLE-Gerät verbinden.

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

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

`disconnect`

Verbindung zu einem BLE-Gerät trennen.

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

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

`createBond`

Einen Bond mit einem BLE-Gerät erstellen (nur Android).

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

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

`isBonded`

Prüfen, ob ein Gerät gebondet ist (nur Android).

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

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

`discoverServices`

Services auf einem verbundenen Gerät entdecken.

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

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

`getServices`

Entdeckte Services eines Geräts abrufen.

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

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

`getConnectedDevices`

Ruft eine Liste verbundener Geräte ab.

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

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

`readCharacteristic`

Liest einen Characteristic-Wert.

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`

Schreibt einen Wert in eine Characteristic.

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`

Benachrichtigungen für eine Eigenschaft starten.

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

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

`stopCharacteristicNotifications`

Benachrichtigungen für eine Characteristic stoppen.

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

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

`readDescriptor`

Einen Descriptor-Wert lesen.

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`

Einen Wert in einen Descriptor schreiben.

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`

Den RSSI (Signalstärke) eines verbundenen Geräts lesen.

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

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

`requestMtu`

MTU-Größenänderung anfordern (nur Android).

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

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

`requestConnectionPriority`

Verbindungspriorität anfordern (nur Android).

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

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

`startAdvertising`

Advertising als Peripheriegerät (BLE-Server) starten.

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

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

`stopAdvertising`

Werbung stoppen.

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

await BluetoothLowEnergy.stopAdvertising();

`startForegroundService`

Startet einen Foreground Service, um BLE-Verbindungen im Hintergrund aufrechtzuerhalten (nur Android).

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

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

`stopForegroundService`

Stoppt den Foreground Service (nur Android).

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

await BluetoothLowEnergy.stopForegroundService();

Typreferenz

`InitializeOptions`

Initialisierungsoptionen für das 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`

Ergebnis der isAvailable-Methode.

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

`IsEnabledResult`

Ergebnis der isEnabled-Methode.

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

`IsLocationEnabledResult`

Ergebnis der isLocationEnabled-Methode.

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

`PermissionStatus`

Berechtigungsstatus für Bluetooth und Standort.

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

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

`StartScanOptions`

Optionen zum Starten eines Scans.

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`

Optionen zum Verbinden mit einem Gerät.

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`

Optionen zum Trennen von einem Gerät.

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

`CreateBondOptions`

Optionen zum Erstellen einer Kopplung.

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

`IsBondedOptions`

Optionen zum Prüfen des Bonding-Status.

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

`IsBondedResult`

Ergebnis der isBonded-Methode.

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

`DiscoverServicesOptions`

Optionen zum Entdecken von Services.

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

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit @capgo/capacitor-bluetooth-low-energy verwenden für die native Funktion in „@capgo/capacitor-bluetooth-low-energy verwenden“, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.