시작하기

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

        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.

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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

가져오기

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

빠른 시작

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

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

예시: shimWebBluetooth

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

BluetoothLowEnergy.shimWebBluetooth();

예시: isAvailable

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

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

자주 하는 실수

권한: 호출 checkPermissions() 그다음 requestPermissions() 필요할 때.
리스너: 화면이 언마운트될 때 핸들을 제거합니다.
한 번만 초기화: 앱 부트스트랩 시 setup을 실행하세요.

API 개요

`initialize`

BLE 플러그인을 초기화합니다. 다른 메서드를 호출하기 전에 반드시 먼저 호출해야 합니다.

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

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

`shimWebBluetooth`

Capacitor Web Bluetooth shim을 설치하려면 navigator.bluetooth를 실행하세요. Capacitor 네이티브 앱에서 Web Bluetooth API를 사용하기 전에 이 메서드를 수동으로 호출해야 합니다.

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

BluetoothLowEnergy.shimWebBluetooth();

`isAvailable`

기기에서 Bluetooth를 사용할 수 있는지 확인합니다.

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

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

`isEnabled`

기기의 Bluetooth 활성화 여부를 확인합니다.

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

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

`isLocationEnabled`

위치 서비스 활성화 여부를 확인합니다 (Android 전용).

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`

Bluetooth 설정 페이지를 엽니다 (Android 전용).

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

await BluetoothLowEnergy.openBluetoothSettings();

`openLocationSettings`

위치 설정 페이지를 엽니다 (Android 전용).

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`

Bluetooth 권한을 요청합니다.

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

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

`startScan`

BLE 장치 스캔을 시작합니다.

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

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

`stopScan`

BLE 장치 스캔을 중단합니다.

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

await BluetoothLowEnergy.stopScan();

`connect`

BLE 장치에 연결합니다.

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

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

`disconnect`

BLE 장치 연결을 해제합니다.

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

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

`createBond`

BLE 기기와 본딩합니다 (Android 전용).

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

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

`isBonded`

기기가 본딩되었는지 확인합니다 (Android 전용).

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`

Characteristic 값을 읽습니다.

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`

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`

Characteristic 알림을 시작합니다.

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

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

`stopCharacteristicNotifications`

characteristic의 알림을 중지합니다.

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

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

`readDescriptor`

descriptor 값을 읽습니다.

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`

descriptor에 값을 씁니다.

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`

MTU 크기 변경을 요청합니다 (Android 전용).

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

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

`requestConnectionPriority`

연결 우선순위를 요청합니다 (Android 전용).

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

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

`startAdvertising`

Peripheral(BLE server)로 advertising을 시작합니다.

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

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

`stopAdvertising`

Advertising을 중지합니다.

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`

isAvailable 메서드의 결과값입니다.

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

`IsEnabledResult`

isEnabled 메서드의 결과값입니다.

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

`IsLocationEnabledResult`

isLocationEnabled 메서드의 결과값입니다.

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

`PermissionStatus`

Bluetooth 및 위치 권한 상태입니다.

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`

본딩 상태를 확인하는 옵션입니다.

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;
}

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-bluetooth-low-energy 사용하기 @capgo/capacitor-bluetooth-low-energy 사용하기의 네이티브 기능을 위한, API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 API Keys의 구현 세부 사항은, 기기 Devices의 구현 세부 사항은.