Skip to content

Cordova bluetooth-serial plugin converted into Capacitor and made compatible with Android API 31.

License

Notifications You must be signed in to change notification settings

Glavotaner/bluetooth-serial

 
 

Repository files navigation

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(...)

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

The deviceClass property is a decimal representation of a given device's Bluetooth Class of Device which signifies what type of device it is. Eg. for printers, deviceClass will be 1664. If you need to know what deviceClass to expect for devices you're working with, you may use this website to get the binary or hexadecimal representation of a given device type: http://bluetooth-pentest.narod.ru/software/bluetooth_class_of_device-service_generator.html Then you can use a website such as: https://www.rapidtables.com/convert/number/hex-to-decimal.html , to convert the given hexadecimal value into a decimal value, which will ultimately correspond to the deviceClass.

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

About

Cordova bluetooth-serial plugin converted into Capacitor and made compatible with Android API 31.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Java 65.5%
  • TypeScript 17.5%
  • JavaScript 8.6%
  • Swift 2.9%
  • HTML 2.2%
  • Ruby 1.9%
  • Other 1.4%