bluetooth-terminal

ES6 class for serial communication with Bluetooth Low Energy (Smart) devices

Usage no npm install needed!

<script type="module">
  import bluetoothTerminal from 'https://cdn.skypack.dev/bluetooth-terminal';
</script>

README

bluetooth-terminal

npm CI Coverage Status

BluetoothTerminal is a class written in ES6 for serial communication with Bluetooth Low Energy (Smart) devices from the web using Web Bluetooth API.

With this class you can communicate bidirectionally with your own device through the one General Attribute Profile characteristic that only offered by DIY modules.

Please check out the Web-Bluetooth-Terminal repository to see implementation details in a real life example.

Quick Start

Install

You can use the script directly or install it using npm and require in your code.

npm install bluetooth-terminal

Use

// Obtain configured instance.
let terminal = new BluetoothTerminal();

// Override `receive` method to handle incoming data as you want.
terminal.receive = function(data) {
  alert(data);
};

// Request the device for connection and get its name after successful connection.
terminal.connect().then(() => {
  alert(terminal.getDeviceName() + ' is connected!');
});

// Send something to the connected device.
terminal.send('Simon says: Hello, world!');

// Disconnect from the connected device.
terminal.disconnect();

API

BluetoothTerminal

Bluetooth Terminal class.

Kind: global class


new BluetoothTerminal([serviceUuid], [characteristicUuid], [receiveSeparator], [sendSeparator], [onConnected], [onDisconnected])

Create preconfigured Bluetooth Terminal instance.

Parameter Type Default Description
[serviceUuid] number | string 0xFFE0 Service UUID
[characteristicUuid] number | string 0xFFE1 Characteristic UUID
[receiveSeparator] string '\n' Receive separator
[sendSeparator] string '\n' Send separator
[onConnected] Function | undefined undefined Listener for connected event
[onDisconnected] Function | undefined undefined Listener for disconnected event

setServiceUuid(uuid)

Set number or string representing service UUID used.

Kind: instance method of BluetoothTerminal

Parameter Type Description
uuid number | string Service UUID

setCharacteristicUuid(uuid)

Set number or string representing characteristic UUID used.

Kind: instance method of BluetoothTerminal

Parameter Type Description
uuid number | string Characteristic UUID

setReceiveSeparator(separator)

Set character representing separator for data coming from the connected device, end of line for example.

Kind: instance method of BluetoothTerminal

Parameter Type Description
separator string Receive separator with length equal to one

setSendSeparator(separator)

Set string representing separator for data coming to the connected device, end of line for example.

Kind: instance method of BluetoothTerminal

Parameter Type Description
separator string Send separator

setOnConnected(listener)

Set a listener to be called after a device is connected.

Kind: instance method of BluetoothTerminal

Parameter Type Description
listener Function | undefined Listener for connected event

setOnDisconnected(listener)

Set a listener to be called after a device is disconnected.

Kind: instance method of BluetoothTerminal

Parameter Type Description
listener Function | undefined Listener for disconnected event

connect()Promise

Launch Bluetooth device chooser and connect to the selected device.

Kind: instance method of BluetoothTerminal

Returns: Promise - Promise which will be fulfilled when notifications will be started or rejected if something went wrong


disconnect()

Disconnect from the connected device.

Kind: instance method of BluetoothTerminal


receive(data)

Data receiving handler which called whenever the new data comes from the connected device, override it to handle incoming data.

Kind: instance method of BluetoothTerminal

Parameter Type Description
data string Data

send(data)Promise

Send data to the connected device.

Kind: instance method of BluetoothTerminal

Returns: Promise - Promise which will be fulfilled when data will be sent or rejected if something went wrong

Parameter Type Description
data string Data

getDeviceName()string

Get the connected device name.

Kind: instance method of BluetoothTerminal

Returns: string - Device name or empty string if not connected