Capacitor Bluetooth Serial Plugin

A client implementation for interacting with Bluetooth (serial), using Capacitor.

Fork from e-is/capacitor-bluetooth-serial

Which is in turn forked from:

Forked from agro1desenvolvimento/capacitor-bluetooth-serial (archived)

I needed this plugin with Capacitor 8 and some additional logic for getting the paired devices. This is why I have forked it. I most likely won't add additional features. But I will try to keep the packages updated and working with newer versions of Capacitor. Our project only uses Android, and I don't have a iOS device to check if it works. This is why supported platforms only states Android.

Supported platforms

- [ ] Web
- [x] Android
- [?] iOS

Supported Capacitor versions:

- Capacitor 8 : use version 8.x
- Capacitor 7 : use version 7.x
- Capacitor 6 : use version 6.x
- Capacitor 5 : use version 5.x
- Capacitor 4 : use version 0.6.x
- Capacitor <= 3: Please use capacitor-bluetooth-serial (<= v0.0.3)

Usage

Install the plugin via npm

npm intall --save @ascentio-it/capacitor-bluetooth-serial

``typescript
import { BluetoothSerial } from '@ascentio-it/capacitor-bluetooth-serial';

//...do something with plugin
`

readStream (Helper Example)

The following is a helper function to continuously read data from a Bluetooth device as a stream, using notifications and a subscription pattern.

`typescript
import { BluetoothSerial } from '@ascentio-it/capacitor-bluetooth-serial';
import type { PluginListenerHandle } from '@capacitor/core';

const readStream = (address: string, delimiter: string = '\n') => {
let listener: PluginListenerHandle | null = null;
let stopped = false;
const subscribers: Array<(data: string) => void> = [];

BluetoothSerial.startNotifications({ address, delimiter })
.then(() => {
BluetoothSerial.addListener('onRead', (data: { value: string }) => {
if (!stopped) {
subscribers.forEach((cb) => cb(data.value));
}
}).then((handle) => {
listener = handle;
});
})
.catch((err) => {
subscribers.forEach((cb) =>
cb(Error starting notifications: ${err instanceof Error ? err.message : String(err)}),
);
});

return {
subscribe(cb: (data: string) => void) {
subscribers.push(cb);

return {
unsubscribe() {
stopped = true;
if (listener) {
listener.remove();
}
},
};
},
};
};

// Usage example:
const stream = readStream('00:11:22:33:44:55');
const subscription = stream.subscribe((data) => {
console.log('Received:', data);
});

// To stop listening:
// subscription.unsubscribe();
`

API Documentation

Interface and type definitions can be found here.

API

Methods

- BluetoothSerial.checkBluetoothPermissions
- BluetoothSerial.getPairedDevices
- BluetoothSerial.isEnabled
- BluetoothSerial.canEnable
- BluetoothSerial.enable
- BluetoothSerial.disable
- BluetoothSerial.startEnabledNotifications
- BluetoothSerial.stopEnabledNotifications
- BluetoothSerial.scan
- BluetoothSerial.connect
- BluetoothSerial.connectInsecure
- BluetoothSerial.disconnect
- BluetoothSerial.isConnected
- BluetoothSerial.read
- BluetoothSerial.readUntil
- BluetoothSerial.startNotifications
- BluetoothSerial.stopNotifications
- BluetoothSerial.write

checkBluetoothPermissions

Checks if Bluetooth permissions are granted (Android only).

checkBluetoothPermissions(): Promise;

$3

Checks whether the required Bluetooth permissions are granted on Android. Returns a promise that resolves to true if permissions are granted, or false otherwise.

$3

None.

$3

`typescript
BluetoothSerial.checkBluetoothPermissions()
.then((granted: boolean) => {
if (granted) {
console.log('Bluetooth permissions granted');
} else {
console.log('Bluetooth permissions not granted');
}
})
.catch(() => {
console.log('Error checking Bluetooth permissions');
});
`

getPairedDevices

Get a list of paired Bluetooth devices.

getPairedDevices(): Promise<{ devices: PairedBluetoothDevice[] }>;

$3

Returns a promise that resolves to an object containing an array of paired Bluetooth devices. Each device includes a name and address.

$3

None.

$3

`typescript
BluetoothSerial.getPairedDevices()
.then(({ devices }) => {
devices.forEach((device) => {
console.log(Device: ${device.name}, Address: ${device.address});
});
})
.catch(() => {
console.log('Error retrieving paired devices');
});
`

isEnabled

Reports if bluetooth is enabled.

isEnabled(): Promise;

$3

Function isEnabled calls the success whatever bluetooth is enabled or not. The promise will contain an attribute enabled indicating if bluetooth is enabled or _not_ enabled. The failure callback will be called only if an error occurs.

If you want to enable bluetooth afterwards, you can use #enable directly, once #enable also check if the bluetooth is conected or not.

$3

None.

$3

`typescript
BluetoothSerial.isEnabled()
.then((response: BluetoothState) => {
const status = response.enabled ? 'enabled' : 'disabled';
console.log(Bluetooth is ${status});
})
.catch(() => {
console.log('Error checking bluetooth status');
});
`

canEnable

Reports if bluetooth can be enabled.

canEnable(): Promise;

$3

Function canEnable calls the success whatever bluetooth can be enabled or not. The promise will contain an attribute enabled indicating if bluetooth can be enabled or _not_. The failure callback will be called only if an error occurs.

$3

None.

$3

`typescript
BluetoothSerial.canEnable()
.then((response: BluetoothState) => {
const canEnable = response.enabled;
console.log(Bluetooth can be enabled ? ${canEnable});
})
.catch(() => {
console.log('Error checking if bluetooth can be enabled');
});
`

enable

Enable bluetooth if it is not enabled. Also request permissions for bluetooth access if it is necessary.

enable(): Promise;

$3

Function enable calls the success whatever bluetooth is successfully enabled or not. The promise will contain an attribute enabled indicating if bluetooth is enabled or _not_ enabled after the process. The failure callback will be called only if an error occurs.

If the app does not have permission to use bluetooth, it will request it.

$3

None.

$3

`typescript
BluetoothSerial.enable()
.then((response: BluetoothState) => {
const status = response.enabled ? 'enabled' : 'disabled';
console.log(Bluetooth is ${status});
})
.catch(() => {
console.log('Error enabling bluetooth');
});
`

disable

Disable bluetooth if enabled. Also request permissions for bluetooth access if it is necessary.

disable(): Promise;

$3

Function disable calls the success whatever bluetooth is successfully disabled or not.
The promise will contain an attribute enabled indicating if bluetooth is enabled or _not_ enabled after the process.
The failure callback will be called only if an error occurs.

If the app does not have permission to use bluetooth, it will request it.

$3

None.

$3

`typescript
BluetoothSerial.disable()
.then((response: BluetoothState) => {
const status = response.enabled ? 'enabled' : 'disabled';
console.log(Bluetooth is ${status});
})
.catch(() => {
console.log('Error disabling bluetooth');
});
`

startEnabledNotifications

Be notified when bluetooth status changed.

startEnabledNotifications(): Promise;

$3

Function startEnabledNotifications enable status notifications. In order to retrieve the values, use an Event Listener with 'onEnabledChanged' as event name.

`typescript
const eventListener = BluetoothSerial.addListener('onEnabledChanged', (response: BluetoothState) => {
const { enabled } = response;
//Do something with enabled variable
});
`

$3

None.

$3

`typescript
BluetoothSerial.startEnabledNotifications()
.then(() => {
eventListener = BluetoothSerial.addListener('onEnabledChanged', (data: BluetoothState) => {
console.log('Bluetooth state changed to ' + (data.enabled ? 'Enabled' : 'Disabled'));
});
})
.catch(() => {
console.log('Error starting enabled listener');
});
`

stopEnabledNotifications

Stops the propagation of value changes.

stopEnabledNotifications(): Promise;

$3

Function stopEnabledNotifications disable bluetooth state notifications. Additionally, the event listener has to be removed.

`typescript
eventListener.remove();
`

$3

None.

$3

`typescript
BluetoothSerial.stopEnabledNotifications()
.then(() => {
eventListener.remove();
})
.catch(() => {
console.log('Error disabling listener for device');
});
`

scan

Discover devices visible and close to the device

scan(): Promise;

$3

#### Android

Function scan discovers Bluetooth devices close to the device and visible. The success callback is called with a list of objects similar to list, or an empty list if no devices are found.

Example list passed to success callback.

`json
[
{
"class": 0,
"id": "00:11:22:33:44:55",
"address": "00:11:22:33:44:55",
"name": "Device 1"
},
{
"class": 7936,
"id": "01:23:6645:4D67:89:00",
"address": "01:23:6645:4D67:89:00",
"name": "Device 2"
}
]
`

The discovery process takes a while to happen.
You may want to show a progress indicator while waiting for the discover proces to finish, and the sucess callback to be invoked.

Calling connect on an unpaired Bluetooth device should begin the Android pairing process.

$3

None.

$3

`typescript
BluetoothSerial
.scan()
.then((result: BluetoothScanResult) => {
result.devices.forEach((device: BluetoothDevice) {
console.log(device.id);
});
})
.catch(() => {
console.log('Error scanning devices');
});
`

connect

Connect to a Bluetooth device.

connect(options: BluetoothConnectOptions): Promise;

$3

Function connect connects to a Bluetooth device. The callback Success will be called when the connection is successful. Failure is called if the connection fails.

#### Android

For Android, connect takes a MAC address of the remote device.

$3

- { address }: Identifier of the remote device.

$3

`typescript
BluetoothSerial.connect({
address: '00:11:22:33:44:55',
})
.then(() => {
console.log('Successfully connected');
})
.catch(() => {
console.log('Error connecting...');
});
`

connectInsecure

Connect insecurely to a Bluetooth device.

connectInsecure(options: BluetoothConnectOptions): Promise;

$3

Function connectInsecure connects to a Bluetooth device. The callback Success will be called when the connection is successful. Failure is called if the connection fails.
Function connectInsecure works like BluetoothSerial.connect, but creates an insecure connection to a Bluetooth device. See the Android docs>) for more information.

#### Android

For Android, connectInsecure takes a MAC address of the remote device.

$3

- { address }: Identifier of the remote device.

$3

`typescript
BluetoothSerial.connectInsecure({
address: '00:11:22:33:44:55',
})
.then(() => {
console.log('Successfully connected');
})
.catch(() => {
console.log('Error connecting...');
});
`

disconnect

Disconnect a Bluetooth device.

disconnect(options: BluetoothConnectOptions): Promise;

$3

Function disconnect disconnects a Bluetooth device. The callback Success will be called when the disconnection is successful. Failure is called if the disconnection fails.

#### Android

For Android, disconnect takes a MAC address of the remote device.

Warning: If no address is passed, all devices will be disconnected.

$3

- { address }: Identifier of the remote device.

$3

`typescript
BluetoothSerial.disconnect({
address: '00:11:22:33:44:55',
})
.then(() => {
console.log('Successfully disconnected');
})
.catch(() => {
console.log('Error disconnecting...');
});
`

isConnected

Reports the connection status.

isConnected(options: BluetoothConnectOptions): Promise;

$3

Function isConnected calls the success callback with the connection status (connected or not connected). Failure will be called only if an error occurs.

#### Android

For Android, isConnected takes a MAC address of the remote device.

$3

- { address }: Identifier of the remote device.

$3

`typescript
BluetoothSerial.isConnected({
address: '00:11:22:33:44:55',
})
.then((result: BluetoothConnectResult) => {
const status = result.connected ? 'connected' : 'disconnected';
console.log(Device is ${status});
})
.catch(() => {
console.log('Error checking connection status');
});
`

read

Reads data from the buffer.

read(options: BluetoothReadOptions): Promise;

$3

Function read reads the data from the buffer. The data is passed to the success callback as a String. Calling read when no data is available will pass an empty String to the callback.

$3

- { address }: Identifier of the remote device.

$3

`typescript
BluetoothSerial.read({
address: '00:11:22:33:44:55',
})
.then((result: BluetoothReadResult) => {
console.log(result.data);
})
.catch(() => {
console.log('Error reading data from device');
});
`

readUntil

Reads data from the buffer until it reaches a delimiter.

readUntil(options: BluetoothReadUntilOptions): Promise;

$3

Function readUntil reads the data from the buffer until it reaches a delimiter. The data is passed to the success callback as a String. If the buffer does not contain the delimiter, an empty String is passed to the callback.

$3

- { address }: Identifier of the remote device.
- { delimiter }: Delimiter.

$3

`typescript
BluetoothSerial.readUntil({
address: '00:11:22:33:44:55',
delimiter: '\n',
})
.then((result: BluetoothReadResult) => {
console.log(result.data);
})
.catch(() => {
console.log('Error reading data from device');
});
`

startNotifications

Enable and be notified when any data is received.

startNotifications(options: BluetoothEnableNotificationsOptions): Promise;

$3

Function startNotifications enable notifications. In order to retrieve the values, use an Event Listener with 'onRead' as event name.

`typescript
const eventListener = BluetoothSerial.addListener('onRead', (response: BluetoothReadResult) => {
const { value } = response;
//Do something with the value
});
`

$3

- { address }: Identifier of the remote device.
- { delimiter }: Delimiter for notification.

$3

`typescript
BluetoothSerial.startNotifications({
address: '00:11:22:33:44:55',
delimiter: '\n',
})
.then((result: BluetoothEnableNotificationsResult) => {
eventListener = BluetoothSerial.addListener('onRead', (data: BluetoothReadResult) => {
console.log('Received value: ' + data.value);
});
})
.catch(() => {
console.log('Error enabling listener for device');
});
`

stopNotifications

Stops the propagation of value changes.

stopNotifications(options: BluetoothDisableNotificationsOptions): Promise;

$3

Function stopNotifications disable notifications. Additionally, the event listener has to be removed.

`typescript
eventListener.remove();
`

$3

- { address }: Identifier of the remote device.

$3

`typescript
BluetoothSerial.stopNotifications({
address: '00:11:22:33:44:55',
})
.then(() => {
eventListener.remove();
})
.catch(() => {
console.log('Error disabling listener for device');
});
`

write

Write data to the buffer.

write(options: BluetoothWriteOptions): Promise;

$3

Function write writes data to the buffer.

$3

- { address }: Identifier of the remote device.
- { value }: String to send.

$3

`typescript
BluetoothSerial.write({
address: '00:11:22:33:44:55',
value: 'Hello world',
})
.then(() => {
console.log('Value sent to device');
})
.catch(() => {
console.log('Error writing data to device');
});
``