Repository files navigation

A client implementation for interacting with Bluetooth

Supported platforms

• Web
• Android
• iOS

Install the plugin via npm

npm install --save capacitor-bluetooth-serial

In your capacitor project, make sure to register the Android plugin inin the projectsMainActivity as follows

importcom.bluetoothserial.plugin.BluetoothSerial;publicclassMainActivityextendsBridgeActivity {@OverridepublicvoidonCreate(BundlesavedInstanceState) {super.onCreate(savedInstanceState);this.init(savedInstanceState,newArrayList<Class<?extendsPlugin>>() {{add(BluetoothSerial.class);    }});  }}

import{Plugins}from"@capacitor/core";const{ BluetoothSerial}=Plugins;//...do something with plugin

Interface and type definitions can be foundhere.

• BluetoothSerial.isEnabled
• BluetoothSerial.enable
• BluetoothSerial.scan
• BluetoothSerial.connect
• BluetoothSerial.connectInsecure
• BluetoothSerial.disconnect
• BluetoothSerial.isConnected
• BluetoothSerial.read
• BluetoothSerial.readUntil
• BluetoothSerial.enableNotifications
• BluetoothSerial.disableNotifications
• BluetoothSerial.enableRawNotifications
• BluetoothSerial.disableRawNotifications
• BluetoothSerial.write

Reports if bluetooth is enabled.

isEnabled(): Promise<BluetoothEnabledResult>;

FunctionisEnabled calls the success whatever bluetooth is enabled or not. The promise will contain an attributeenabled indicating if bluetooth is enabled ornot 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.

None.

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

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

enable(): Promise<BluetoothEnabledResult>;

Functionenable calls the success whatever bluetooth is successfully enabled or not. The promise will contain an attributeenabled indicating if bluetooth is enabled ornot 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.

None.

BluetoothSerial.enable().then((response:BluetoothEnabledResult)=>{constmessage=response.enabled ?'enabled' :'disabled';console.log(`Bluetooth is${message}`);}).catch(()=>{console.log('Error enabling bluetooth');});

Discover devices visible and close to the device

scan(): Promise<BluetoothScanResult>;

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

Example list passed to success callback.

[{"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.

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

None.

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

Connect to a Bluetooth device.

connect(options: BluetoothConnectOptions): Promise<void>;

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

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

• {address }: Identifier of the remote device.

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

Connect insecurely to a Bluetooth device.

connectInsecure(options: BluetoothConnectOptions): Promise<void>;

FunctionconnectInsecure connects to a Bluetooth device. The callback Success will be called when the connection is successful. Failure is called if the connection fails.FunctionconnectInsecure works likeBluetoothSerial.connect, but creates an insecure connection to a Bluetooth device. See theAndroid docs for more information.

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

• {address }: Identifier of the remote device.

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

Disconnect a Bluetooth device.

disconnect(options: BluetoothConnectOptions): Promise<void>;

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

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

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

• {address }: Identifier of the remote device.

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

Reports the connection status.

isConnected(options: BluetoothConnectOptions): Promise<BluetoothConnectResult>;

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

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

• {address }: Identifier of the remote device.

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

Reads data from the buffer.

read(options: BluetoothReadOptions): Promise<BluetoothDataResult>;

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

• {address }: Identifier of the remote device.

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

Reads data from the buffer until it reaches a delimiter.

readUntil(options: BluetoothReadUntilOptions): Promise<BluetoothDataResult>;

FunctionreadUntil 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.

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

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

Enable and be notified when any data is received.

enableNotifications(options: BluetoothEnableNotificationsOptions): Promise<BluetoothEnableNotificationsResult>;

FunctionenableNotifications enable notifications. The success callback will return an event name. In order to retrieve the values, one has to use an Event Listener with the returned event name.

constlistener=BluetoothSerial.addListener(eventName,(data:BluetoothDataResult)=>{const{ value}=data.data;//Do something with the dataq});

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

BluetoothSerial.enableNotifications({address:'00:11:22:33:44:55',delimiter:'\n',}).then((result:BluetoothEnableNotificationsResult)=>{event=BluetoothSerial.addListener(result.eventName,(data:BluetoothDataResult)=>{console.log(data.data);});}).catch(()=>{console.log('Error enabling listener for device');});

Stops the propagation of value changes.

disableNotifications(options: BluetoothDisableNotificationsOptions): Promise<void>;

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

listener.remove();

• {address }: Identifier of the remote device.

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

Under development.

Under development.

Write data to the buffer.

write(options: BluetoothWriteOptions): Promise<void>;

Functionwrite writes data to the buffer.

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

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