bluetooth-serial

Use classic bluetooth functionality.

How this plugin is different from it's source:

Capacitor-based

Promise-based

Adapted for permission requirements at least from Android 5.1 upto Android 11+

Only supports bluetooth classic on Android, no other platform is supported

Permissions

For things to work, you need to add certain permissions into your AndroidManifest. Refer to this for a detailed description: https://developer.android.com/guide/topics/connectivity/bluetooth/permissions

The plugin requests/checks permissions in a granular fashion; a call that only requires the CONNECT permission will only check/request that permission. As opposed to every call that requires any permission, requesting all of them.

Install

npm install bluetooth-serial
npx cap sync

API

• echo(...)
• connect(...)
• connectInsecure(...)
• disconnect()
• read()
• write(...)
• available()
• isEnabled()
• isConnected()
• clear()
• enable()
• settings()
• list()
• discoverUnpaired()
• cancelDiscovery()
• checkPermissions()
• requestPermissions(...)
• addListener('discoverUnpaired', ...)
• addListener('connectionChange', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

echo(...)

echo(options: { value: string; }) => Promise<{ value: string; }>

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

Returns: Promise<{ value: string; }>

connect(...)

connect(options: connectionOptions) => Promise<void>

Creates a secure connection (https://developer.android.com/reference/android/bluetooth/BluetoothDevice#createRfcommSocketToServiceRecord(java.util.UUID)) to the bluetooth device with the given address. The plugin only retains one connection at a time; upon connecting to a device, while there is already an existing connection, the previous device is disconnected. If there is already a running connect call that hasn't resolved, and a new one starts, the original will reject with "Connection interrupted". Requires CONNECT permission on Android API >= 30

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | connectionOptions |

connectInsecure(...)

connectInsecure(options: connectionOptions) => Promise<void>

Creates an insecure connection (https://developer.android.com/reference/android/bluetooth/BluetoothDevice#createInsecureRfcommSocketToServiceRecord(java.util.UUID)) to the bluetooth device with the given address. The plugin only retains one connection at a time; upon connecting to a device, while there is already an existing connection, the previous device is disconnected. If there is already a running connect call that hasn't resolved, and a new one starts, the original will reject with "Connection interrupted". Requires CONNECT permission on Android API >= 30

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | connectionOptions |

disconnect()

disconnect() => Promise<void>

Disconnects from the currently connected device. This may be called while there is no connected device; in that case, the method will resolve with void.

read()

read() => Promise<{ data: string; }>

Returns data emitted from the currently connected device.

Returns: Promise<{ data: string; }>

write(...)

write(options: { data: string; }) => Promise<void>

Writes data to the currently connected device.

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

available()

available() => Promise<{ available: number; }>

Returns the length of the data that can be read by calling read().

Returns: Promise<{ available: number; }>

isEnabled()

isEnabled() => Promise<{ isEnabled: boolean; }>

Returns true or false depending on whether bluetooth is enabled.

Returns: Promise<{ isEnabled: boolean; }>

isConnected()

isConnected() => Promise<{ isConnected: boolean; }>

Returns true or false depending on whether the plugin is currently connected to a device.

Returns: Promise<{ isConnected: boolean; }>

clear()

clear() => Promise<void>

Clears the data readable by calling read().

enable()

enable() => Promise<{ isEnabled: boolean; }>

Displays the native prompt for enabling bluetooth. Returns true or false depending on whether the user enabled bluetooth. Requires CONNECT permission on Android API >= 30

Returns: Promise<{ isEnabled: boolean; }>

settings()

settings() => Promise<void>

Opens the native bluetooth settings activity. Resolves immediately upon being called.

list()

list() => Promise<devices>

Returns a list of bonded devices. This includes devices that were previously paired with the user's device Requires CONNECT permission on Android API >= 30

Returns: Promise<devices>

discoverUnpaired()

discoverUnpaired() => Promise<devices>

Begins the discovery of nearby devices and resolves with them once discovery is finished. There may only be one discovery process at a time. If another call starts while there is a discovery in progress, the original call will resolve with "Discovery cancelled".

On Android API >= 30 requires SCAN, CONNECT and FINE_LOCATION permissions. You can declare in your manifest that scanning for devices is not used to derive the user's location. In that case, you may also add the following into your capacitor.config.ts to indicate that the plugin should not require FINE_LOCATION:

BluetoothSerial: { neverScanForLocation: true, }

In that case, only SCAN and CONNECT are required.

On Android 10 and 11, only FINE_LOCATION is required.

On lower versions, only COARSE_LOCATION is required.

The versions of Android that require location permissions, also require location services to be enabled. So this plugin will reject with "Location services not enabled" if the device requires location for scanning, but it is disabled.

https://developer.android.com/guide/topics/connectivity/bluetooth/permissions

Returns: Promise<devices>

cancelDiscovery()

cancelDiscovery() => Promise<void>

Cancels current unpaired devices discovery, if there is one in progress. If there is no discovery in progress, resolves with void. Be sure to note that calling this will reject any existing discoverUnpaired() call which hasn't resolved yet. Requires SCAN permission on Android API >= 30

checkPermissions()

checkPermissions() => Promise<PermissionStatus[]>

Takes into account the fact that SCAN and CONNECT permissions only exist on Android 11+; those permissions will always resolve as GRANTED on devices below Android 11.

Returns: Promise<PermissionStatus[]>

requestPermissions(...)

requestPermissions(options: { permissions: permissions[]; }) => Promise<PermissionStatus[]>

Takes into account the fact that SCAN and CONNECT permissions only exist on Android 11+; those permissions will always resolve as GRANTED on devices below Android 11.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | { permissions: permissions[]; } |

Returns: Promise<PermissionStatus[]>

addListener('discoverUnpaired', ...)

addListener(event: 'discoverUnpaired', listenerFunc: (event: devices) => any) => Promise<PluginListenerHandle> & PluginListenerHandle

| Param | Type | | ------------------ | -------------------------------------------------------------- | | event | 'discoverUnpaired' | | listenerFunc | (event: devices) => any |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

addListener('connectionChange', ...)

addListener(event: 'connectionChange', listenerFunc: (event: { state: ConnectionState; }) => any) => Promise<PluginListenerHandle> & PluginListenerHandle

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------ | | event | 'connectionChange' | | listenerFunc | (event: { state: ConnectionState; }) => any |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

removeAllListeners()

removeAllListeners() => Promise<void>

Interfaces

BluetoothDevice

| Prop | Type | | ----------------- | ------------------- | | address | string | | name | string | | deviceClass | number |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Type Aliases

connectionOptions

{ address: string }

devices

{ devices: BluetoothDevice[] }

PermissionStatus

{ [permission in permissions]?: PermissionState }

permissions

'coarseLocation' | 'fineLocation' | 'scan' | 'connect'

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

ConnectionState

| Members | | ---------------- | | NONE | | CONNECTING | | CONNECTED |