Getting Started

此内容尚不支持你的语言。

Install the package
- npm
- pnpm
- yarn
- bun
Terminal window
npm i @capgo/capacitor-bluetooth-low-energy
Terminal window
pnpm add @capgo/capacitor-bluetooth-low-energy
Terminal window
yarn add @capgo/capacitor-bluetooth-low-energy
Terminal window
bun add @capgo/capacitor-bluetooth-low-energy
Sync with native projects
- npm
- pnpm
- yarn
- bun
Terminal window
npx cap sync
Terminal window
pnpm cap sync
Terminal window
yarn cap sync
Terminal window
bunx cap sync

iOS Setup

Add the following to your Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to communicate with BLE devices.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to communicate with BLE devices.</string>

For background BLE support, add:

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>bluetooth-peripheral</string>
</array>

Android Setup

Works out of the box. The plugin automatically adds required permissions. For Android 12+, request runtime permissions:

await BluetoothLowEnergy.requestPermissions();

Web Setup

Works in Chrome and Chromium-based browsers using the Web Bluetooth API. Requires HTTPS and user interaction to scan for devices.

Basic Usage

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

// Initialize the plugin
await BluetoothLowEnergy.initialize();

// Request permissions (Android 12+)
await BluetoothLowEnergy.requestPermissions();

// Check if Bluetooth is available and enabled
const { available } = await BluetoothLowEnergy.isAvailable();
const { enabled } = await BluetoothLowEnergy.isEnabled();

if (!available || !enabled) {
  console.log('Bluetooth is not available or not enabled');
  return;
}

// Start scanning for devices
BluetoothLowEnergy.addListener('deviceScanned', (event) => {
  console.log('Found device:', event.device.name, event.device.deviceId);
});

await BluetoothLowEnergy.startScan({
  services: ['180d'], // Filter by Heart Rate service UUID
  timeout: 10000, // 10 seconds
});

Connecting to a Device

// Connect to a device
await BluetoothLowEnergy.connect({
  deviceId: 'AA:BB:CC:DD:EE:FF',
});

// Listen for connection events
BluetoothLowEnergy.addListener('deviceConnected', (event) => {
  console.log('Connected to:', event.deviceId);
});

BluetoothLowEnergy.addListener('deviceDisconnected', (event) => {
  console.log('Disconnected from:', event.deviceId);
});

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

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

console.log('Services:', services);

Reading and Writing Characteristics

// Read a characteristic
const { value } = await BluetoothLowEnergy.readCharacteristic({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180d',
  characteristic: '2a37',
});

console.log('Value:', value); // Array of bytes

// Write to a characteristic
await BluetoothLowEnergy.writeCharacteristic({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180d',
  characteristic: '2a39',
  value: [0x01], // Array of bytes
  type: 'withResponse',
});

Subscribing to Notifications

// Listen for characteristic changes
BluetoothLowEnergy.addListener('characteristicChanged', (event) => {
  console.log('Characteristic changed:', event.characteristic);
  console.log('New value:', event.value);
});

// Start notifications
await BluetoothLowEnergy.startCharacteristicNotifications({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180d',
  characteristic: '2a37',
});

// Stop notifications when done
await BluetoothLowEnergy.stopCharacteristicNotifications({
  deviceId: 'AA:BB:CC:DD:EE:FF',
  service: '180d',
  characteristic: '2a37',
});

Complete Example - Heart Rate Monitor

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

const HEART_RATE_SERVICE = '180d';
const HEART_RATE_MEASUREMENT = '2a37';

export class HeartRateMonitor {
  private deviceId: string | null = null;

  async init() {
    await BluetoothLowEnergy.initialize();

    const { available } = await BluetoothLowEnergy.isAvailable();
    if (!available) {
      throw new Error('Bluetooth not available');
    }

    await BluetoothLowEnergy.requestPermissions();
  }

  async scan(): Promise<string[]> {
    const devices: string[] = [];

    BluetoothLowEnergy.addListener('deviceScanned', (event) => {
      if (event.device.name && !devices.includes(event.device.deviceId)) {
        devices.push(event.device.deviceId);
        console.log('Found:', event.device.name);
      }
    });

    await BluetoothLowEnergy.startScan({
      services: [HEART_RATE_SERVICE],
      timeout: 5000,
    });

    return devices;
  }

  async connect(deviceId: string) {
    this.deviceId = deviceId;

    await BluetoothLowEnergy.connect({ deviceId });
    await BluetoothLowEnergy.discoverServices({ deviceId });
  }

  async startMonitoring(callback: (heartRate: number) => void) {
    if (!this.deviceId) throw new Error('Not connected');

    BluetoothLowEnergy.addListener('characteristicChanged', (event) => {
      if (event.characteristic === HEART_RATE_MEASUREMENT) {
        // Parse heart rate from BLE Heart Rate Measurement format
        const flags = event.value[0];
        const is16Bit = (flags & 0x01) !== 0;
        const heartRate = is16Bit
          ? (event.value[2] << 8) | event.value[1]
          : event.value[1];
        callback(heartRate);
      }
    });

    await BluetoothLowEnergy.startCharacteristicNotifications({
      deviceId: this.deviceId,
      service: HEART_RATE_SERVICE,
      characteristic: HEART_RATE_MEASUREMENT,
    });
  }

  async disconnect() {
    if (this.deviceId) {
      await BluetoothLowEnergy.disconnect({ deviceId: this.deviceId });
      this.deviceId = null;
    }
  }
}

API Reference

Core Methods

Method	Description
`initialize()`	Initialize the BLE plugin (required before other calls)
`isAvailable()`	Check if Bluetooth is available on the device
`isEnabled()`	Check if Bluetooth is enabled
`checkPermissions()`	Check current permission status
`requestPermissions()`	Request Bluetooth permissions

Scanning

Method	Description
`startScan(options?)`	Start scanning for BLE devices
`stopScan()`	Stop scanning

Connection

Method	Description
`connect(options)`	Connect to a BLE device
`disconnect(options)`	Disconnect from a device
`getConnectedDevices()`	Get list of connected devices
`createBond(options)`	Create a bond (Android only)
`isBonded(options)`	Check if device is bonded (Android only)

Service Discovery

Method	Description
`discoverServices(options)`	Discover services on connected device
`getServices(options)`	Get discovered services

Characteristics

Method	Description
`readCharacteristic(options)`	Read a characteristic value
`writeCharacteristic(options)`	Write to a characteristic
`startCharacteristicNotifications(options)`	Subscribe to notifications
`stopCharacteristicNotifications(options)`	Unsubscribe from notifications

Descriptors

Method	Description
`readDescriptor(options)`	Read a descriptor value
`writeDescriptor(options)`	Write to a descriptor

Advanced

Method	Description
`readRssi(options)`	Read signal strength of connected device
`requestMtu(options)`	Request MTU size change (Android)
`requestConnectionPriority(options)`	Request connection priority (Android)
`startAdvertising(options)`	Start advertising as peripheral
`stopAdvertising()`	Stop advertising
`startForegroundService(options)`	Start foreground service (Android)
`stopForegroundService()`	Stop foreground service (Android)

Events

Event	Description
`deviceScanned`	Emitted when a device is found during scanning
`deviceConnected`	Emitted when connected to a device
`deviceDisconnected`	Emitted when disconnected from a device
`characteristicChanged`	Emitted when a characteristic value changes

Best Practices

Always initialize first
```
await BluetoothLowEnergy.initialize();
```

Check permissions before scanning

const { bluetooth } = await BluetoothLowEnergy.checkPermissions();
if (bluetooth !== 'granted') {
  await BluetoothLowEnergy.requestPermissions();
}

Handle disconnections gracefully

BluetoothLowEnergy.addListener('deviceDisconnected', async (event) => {
  // Attempt reconnection or notify user
});

Clean up listeners when done

await BluetoothLowEnergy.removeAllListeners();

Use foreground service for long-running operations (Android)

await BluetoothLowEnergy.startForegroundService({
  title: 'BLE Active',
  body: 'Connected to device',
  smallIcon: 'ic_notification',
});

Platform Notes

iOS

Requires iOS 10.0+
Uses CoreBluetooth framework
Supports background modes with proper entitlements
Device IDs are UUIDs (not MAC addresses)

Android

Requires Android 5.0 (API 21)+
Android 12+ requires BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions
Device IDs are MAC addresses
Location services may be required for scanning

Web

Requires Chrome/Chromium with Web Bluetooth API
Must be served over HTTPS
Requires user interaction to initiate scanning
Limited compared to native implementations