capacitor-ble-messaging

Messaging between BLE supporting devices

Install

npm install capacitor-ble-messaging
npx cap sync

Permissions

Android

Add the following permissions to your AndroidManifest.xml file:

<!-- Request legacy Bluetooth permissions on older devices. -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- Include "neverForLocation" only if you can strongly assert that your app never derives physical location from Bluetooth scan results. -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Needed only if your app makes the device discoverable to Bluetooth devices. -->
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

iOS

Add the following permissions to your Info.plist file:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>We use bluetooth to communicate with nearby devices</string>

API

• startAdvertising(...)
• stopAdvertising()
• startScan(...)
• stopScan()
• connectToDevice(...)
• disconnectFromDevice(...)
• sendMessage(...)
• isAdvertising()
• isScanning()
• addListener('onScanStarted', ...)
• addListener('onScanStopped', ...)
• addListener('onScanFailed', ...)
• addListener('onAdvertisingStarted', ...)
• addListener('onAdvertisingStopped', ...)
• addListener('onAdvertisingFailed', ...)
• addListener('onDeviceFound', ...)
• addListener('onDeviceConnected', ...)
• addListener('onDeviceDisconnected', ...)
• addListener('onMessageReceived', ...)
• removeAllListeners()
• cleanup()
• Interfaces

startAdvertising(...)

startAdvertising(options: { serviceUUID: string; }) => any

| Param | Type | | ------------- | ------------------------------------- | | options | { serviceUUID: string; } |

Returns: any

stopAdvertising()

stopAdvertising() => any

Returns: any

startScan(...)

startScan(options: { serviceUUID: string; scanTimeout?: number; }) => any

Start scanning for devices advertising the specified service UUID.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | { serviceUUID: string; scanTimeout?: number; } |

Returns: any

stopScan()

stopScan() => any

Stop scanning for devices.

Returns: any

connectToDevice(...)

connectToDevice(options: { uuid: string; }) => any

Connect to a device with the specified UUID.

| Param | Type | | ------------- | ------------------------------ | | options | { uuid: string; } |

Returns: any

disconnectFromDevice(...)

disconnectFromDevice(options: { uuid: string; }) => any

Disconnect from a connected device.

| Param | Type | | ------------- | ------------------------------ | | options | { uuid: string; } |

Returns: any

sendMessage(...)

sendMessage(options: { to: string; message: string; }) => any

Send a message to a connected device.

| Param | Type | | ------------- | --------------------------------------------- | | options | { to: string; message: string; } |

Returns: any

isAdvertising()

isAdvertising() => any

Check if the device is currently advertising.

Returns: any

isScanning()

isScanning() => any

Check if the device is currently scanning.

Returns: any

addListener('onScanStarted', ...)

addListener(eventName: 'onScanStarted', listenerFunc: () => void) => any

| Param | Type | | ------------------ | ---------------------------- | | eventName | 'onScanStarted' | | listenerFunc | () => void |

Returns: any

addListener('onScanStopped', ...)

addListener(eventName: 'onScanStopped', listenerFunc: () => void) => any

| Param | Type | | ------------------ | ---------------------------- | | eventName | 'onScanStopped' | | listenerFunc | () => void |

Returns: any

addListener('onScanFailed', ...)

addListener(eventName: 'onScanFailed', listenerFunc: () => void) => any

| Param | Type | | ------------------ | --------------------------- | | eventName | 'onScanFailed' | | listenerFunc | () => void |

Returns: any

addListener('onAdvertisingStarted', ...)

addListener(eventName: 'onAdvertisingStarted', listenerFunc: () => void) => any

| Param | Type | | ------------------ | ----------------------------------- | | eventName | 'onAdvertisingStarted' | | listenerFunc | () => void |

Returns: any

addListener('onAdvertisingStopped', ...)

addListener(eventName: 'onAdvertisingStopped', listenerFunc: () => void) => any

| Param | Type | | ------------------ | ----------------------------------- | | eventName | 'onAdvertisingStopped' | | listenerFunc | () => void |

Returns: any

addListener('onAdvertisingFailed', ...)

addListener(eventName: 'onAdvertisingFailed', listenerFunc: () => void) => any

| Param | Type | | ------------------ | ---------------------------------- | | eventName | 'onAdvertisingFailed' | | listenerFunc | () => void |

Returns: any

addListener('onDeviceFound', ...)

addListener(eventName: 'onDeviceFound', listenerFunc: ({ uuid }: { uuid: string; }) => void) => any

Emitted when a device advertising the specified service UUID is found.

| Param | Type | | ------------------ | ----------------------------------------------------- | | eventName | 'onDeviceFound' | | listenerFunc | ({ uuid }: { uuid: string; }) => void |

Returns: any

addListener('onDeviceConnected', ...)

addListener(eventName: 'onDeviceConnected', listenerFunc: ({ uuid }: { uuid: string; }) => void) => any

Emitted when a device is connected.

| Param | Type | | ------------------ | ----------------------------------------------------- | | eventName | 'onDeviceConnected' | | listenerFunc | ({ uuid }: { uuid: string; }) => void |

Returns: any

addListener('onDeviceDisconnected', ...)

addListener(eventName: 'onDeviceDisconnected', listenerFunc: ({ uuid }: { uuid: string; }) => void) => any

| Param | Type | | ------------------ | ----------------------------------------------------- | | eventName | 'onDeviceDisconnected' | | listenerFunc | ({ uuid }: { uuid: string; }) => void |

Returns: any

addListener('onMessageReceived', ...)

addListener(eventName: 'onMessageReceived', listenerFunc: ({ from, message, timestamp }: { from: string; message: string; timestamp: number; }) => void) => any

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------------------------- | | eventName | 'onMessageReceived' | | listenerFunc | ({ from, message, timestamp }: { from: string; message: string; timestamp: number; }) => void |

Returns: any

removeAllListeners()

removeAllListeners() => any

Returns: any

cleanup()

cleanup() => any

Cleanup the plugin. This is useful to call when the app is closed or when the plugin is no longer needed. It will stop any ongoing advertising or scanning, and close any open connections.

Returns: any

Interfaces

PluginListenerHandle

| Prop | Type | | ------------ | ------------------------- | | remove | () => any |