시작하기

설치

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

Import

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

API 개요

initialize

__CAPGO_KEEP_0__ BLE 플러그인을 초기화합니다. 이 메소드는 다른 메소드 호출하기 전에 반드시 호출해야 합니다.

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

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

shimWebBluetooth

Capacitor Web Bluetooth shim을 __CAPGO_KEEP_1__에 설치합니다. navigator.bluetooth Capacitor 네이티브 앱에서 Web Bluetooth API을 사용하기 전에 수동으로 호출해야 합니다.

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

BluetoothLowEnergy.shimWebBluetooth();

isAvailable

장치에서 블루투스가 사용 가능한지 확인합니다.

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

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

isEnabled

장치에서 블루투스가 활성화되어 있는지 확인합니다.

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

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

isLocationEnabled

장치에서 위치 서비스가 활성화되어 있는지 확인합니다. (안드로이드 전용).

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

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

openAppSettings

앱 설정 페이지를 열어줍니다.

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

await BluetoothLowEnergy.openAppSettings();

openBluetoothSettings

안드로이드 전용으로 블루투스 설정 페이지를 열습니다.

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

await BluetoothLowEnergy.openBluetoothSettings();

openLocationSettings

안드로이드 전용으로 위치 설정 페이지를 열습니다.

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

await BluetoothLowEnergy.openLocationSettings();

checkPermissions

권한 상태를 확인합니다.

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

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

requestPermissions

블루투스 권한을 요청합니다.

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

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

startScan

블루투스 디바이스를 스캔합니다.

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

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

stopScan

블루투스 디바이스 스캔을 중지합니다.

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

await BluetoothLowEnergy.stopScan();

connect

클립보드에 복사

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

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

disconnect

__CAPGO_KEEP_0__

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

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

createBond

Android용 BLE 장치와 Bond를 생성합니다.

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

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

isBonded

Android용 장치가 Bond되어 있는지 확인합니다.

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

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

discoverServices

연결된 장치의 서비스를 발견합니다.

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

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

getServices

장치의 발견된 서비스를 가져옵니다.

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

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

getConnectedDevices

연결된 장치 목록을 가져옵니다.

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

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

readCharacteristic

특성값을 읽습니다.

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

특성값을 씁니다.

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

특성값에 대한 알림을 시작합니다.

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

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

stopCharacteristicNotifications

특성에 대한 알림을 중지합니다.

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

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

readDescriptor

설명자 값 읽기

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

설명자에 값 쓰기

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

연결된 장치의 RSSI(신호 강도)를 읽습니다.

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

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

requestMtu

Android에서 MTU 크기 변경 요청.

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

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

requestConnectionPriority

클립보드 복사

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

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

startAdvertising

광고 중지

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

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

stopAdvertising

클립보드 복사

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

await BluetoothLowEnergy.stopAdvertising();

startForegroundService

배경에서 BLE 연결을 유지하기 위해 Android에서만 전경 서비스를 시작합니다.

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

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

stopForegroundService

Android에서만 전경 서비스를 중지합니다.

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

await BluetoothLowEnergy.stopForegroundService();

타입 참조

InitializeOptions

클립보드에 복사

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

__CAPGO_KEEP_0__ 결과입니다.

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

IsEnabledResult

__CAPGO_KEEP_0__ 결과입니다.

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

IsLocationEnabledResult

__CAPGO_KEEP_0__ 결과입니다.

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

PermissionStatus

__CAPGO_KEEP_0__ 및 위치에 대한 권한 상태입니다.

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

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

StartScanOptions

스캔 시작 옵션.

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

디바이스에 연결하는 옵션.

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

디바이스에서 연결 해제하는 옵션.

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

CreateBondOptions

디바이스와 결합하는 옵션.

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

IsBondedOptions

__CAPGO_KEEP_0__ 상태 확인 옵션.

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

IsBondedResult

isBonded 메서드의 결과.

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

DiscoverServicesOptions

서비스를 발견하는 옵션.

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

진실의 근원

이 페이지는 플러그인의 src/definitions.ts. API의 공개 버전이 업스트림에서 변경되면 다시 싱크를 실행하십시오.