bluetooth-terminal

BluetoothTerminal is a specialized JavaScript class that bridges a critical gap in web-based Bluetooth communication. It enables real bidirectional serial communication with Bluetooth Low Energy (BLE) devices directly from web browsers using the Web Bluetooth API.

Problem

Web browsers can only communicate with Bluetooth Low Energy (4.0+) devices through the Web Bluetooth API, which uses the Generic Attribute Profile (GATT) with services and characteristics. However, most affordable BLE modules available to hobbyists and makers (such as HM-10, JDY-08, AT-09, CC41-A) only expose a single service (typically 0xFFE0) and characteristic (typically 0xFFE1) that emulates basic serial communication.

These limitations present several challenges:

No native Serial Port Profile support in Web Bluetooth API.
20-byte size limit for individual BLE characteristic values.
Need for a consistent communication protocol between web apps and DIY hardware.

Solution

This class provides a complete solution by:

Creating a robust serial communication layer on top of the Web Bluetooth API.
Automatically handling device discovery, connection, and reconnection.
Bypassing the 20-byte characteristic limitation by automatically chunking longer messages.
Managing message buffering until complete messages are received (using configurable delimiters).
Providing a simple, Promise-based API for sending and receiving data.

With BluetoothTerminal, you can build web applications that seamlessly communicate with your custom BLE hardware by sending and receiving:

text messages,
JSON data from sensors,
commands and control signals,
any other data you need to exchange with your device.

This enables entirely new possibilities for creating web-controlled IoT devices, remote sensors, and other Bluetooth-enabled projects without needing native mobile applications.

Check out the Web Bluetooth Terminal repository for a complete implementation example, or read the full tutorial on building web apps for your own BLE devices.

Quick Start

Install

BluetoothTerminal can be added to your project in two ways:

Direct script usage: download and include the prebuilt JavaScript file (dist/BluetoothTerminal.js) directly in your HTML:

<script src="path/to/BluetoothTerminal.js"></script>

NPM package: for projects using module bundlers (Webpack, Rollup, Parcel, etc.), install via npm:

npm install bluetooth-terminal

Then import in your code:

const BluetoothTerminal = require('bluetooth-terminal');

Use

// Create a BluetoothTerminal instance with the default configuration.
const bluetoothTerminal = new BluetoothTerminal();

// Set a callback that will be called when an incoming message from the
// connected device is received.
bluetoothTerminal.onReceive((message) => {
  console.info(`Message received: "${message}"`);
});

// Open the browser Bluetooth device picker to select a device if none was
// previously selected, establish a connection with the selected device, and
// initiate communication.
bluetoothTerminal.connect()
  .then(() => {
    // Retrieve the name of the currently connected device.
    console.info(`Device "${this.getDeviceName()}" successfully connected`);
    
    // Send a message to the connected device.
    return bluetoothTerminal.send('Simon says: Hello, world!');
  });

// Later, disconnect from the currently connected device and clean up
// associated resources.
// bluetoothTerminal.disconnect();

API
- BluetoothTerminal
Development

API

`BluetoothTerminal`

BluetoothTerminal class.

`new BluetoothTerminal([optionsOrServiceUuid], [characteristicUuid], [receiveSeparator], [sendSeparator], [onConnectCallback], [onDisconnectCallback])`

Creates a BluetoothTerminal instance with the provided configuration.

Supports both options object (preferred) and individual parameters (deprecated and will be removed in v2.0.0).

Parameter	Type	Default	Description
`[optionsOrServiceUuid]`	`BluetoothTerminalOptions` \| `number` \| `string`	`0xFFE0`	Optional options object or service UUID as an integer (16-bit or 32-bit) or a string (128-bit UUID)
`[characteristicUuid]`	`number` \| `string`	`0xFFE1`	Optional characteristic UUID as an integer (16-bit or 32-bit) or a string (128-bit UUID)
`[receiveSeparator]`	`string`	`'\n'`	Optional receive separator with length equal to one character
`[sendSeparator]`	`string`	`'\n'`	Optional send separator with length equal to one character
`[onConnectCallback]`	`() => void`	`null`	Optional callback for successful connection
`[onDisconnectCallback]`	`() => void`	`null`	Optional callback for disconnection

`BluetoothTerminalOptions`

Property	Type	Default	Description
`[serviceUuid]`	`number` \| `string`	`0xFFE0`	Optional service UUID as an integer (16-bit or 32-bit) or a string (128-bit UUID)
`[characteristicUuid]`	`number` \| `string`	`0xFFE1`	Optional characteristic UUID as an integer (16-bit or 32-bit) or a string (128-bit UUID)
`[characteristicValueSize]`	`number`	`20`	Optional maximum characteristic value size in bytes (positive integer)
`[receiveSeparator]`	`string`	`'\n'`	Optional receive separator with length equal to one character
`[sendSeparator]`	`string`	`'\n'`	Optional send separator with length equal to one character
`[onConnectCallback]`	`() => void`	`null`	Optional callback for successful connection
`[onDisconnectCallback]`	`() => void`	`null`	Optional callback for disconnection
`[onReceiveCallback]`	`(message: string) => void`	`null`	Optional callback for incoming message
`[onLogCallback]`	`(logLevel: string, method: string, message: string, error?: unknown) => void`	`null`	Optional callback for log messages
`[logLevel]`	`string`	`'log'`	Optional log level as a string ("none", "error", "warn", "info", "log", or "debug")

`setServiceUuid(uuid)`

Sets integer or string representing service UUID used.

Parameter	Type	Description
`uuid`	`number` \| `string`	Service UUID as an integer (16-bit or 32-bit) or a string (128-bit UUID)

`setCharacteristicUuid(uuid)`

Sets integer or string representing characteristic UUID used.

Parameter	Type	Description
`uuid`	`number` \| `string`	Characteristic UUID as an integer (16-bit or 32-bit) or a string (128-bit UUID)

`setCharacteristicValueSize(size)`

Sets the maximum size (in bytes) for each characteristic write operation. Larger messages will be automatically split into chunks of this size.

Parameter	Type	Description
size	`number`	Maximum characteristic value size in bytes (positive integer)

`setReceiveSeparator(separator)`

Sets character representing separator for messages received from the connected device, end of line for example.

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

`setSendSeparator(separator)`

Sets character representing separator for messages sent to the connected device, end of line for example.

Parameter	Type	Description
`separator`	`string`	Send separator with length equal to one character

`onConnect([callback])`

Sets a callback that will be called after the device is fully connected and communication has started.

Parameter	Type	Description
`[callback]`	`() => void` \| `null` \| `undefined`	Callback for successful connection; omit or pass null/undefined to remove

`onDisconnect([callback])`

Sets a callback that will be called after the device is disconnected.

Parameter	Type	Description
`[callback]`	`() => void` \| `null` \| `undefined`	Callback for disconnection; omit or pass null/undefined to remove

`onReceive([callback])`

Sets a callback that will be called when an incoming message from the connected device is received.

Parameter	Type	Description
`[callback]`	`(message: string) => void` \| `null` \| `undefined`	Callback for incoming message; omit or pass null/undefined to remove

`onLog([callback])`

Sets a callback that will be called every time any log message is produced by the class, regardless of the log level set.

Parameter	Type	Description
`[callback]`	`(logLevel: string, method: string, message: string, error?: unknown) => void` \| `null` \| `undefined`	Callback for log messages; omit or pass null/undefined to remove

`setLogLevel(logLevel)`

Sets the log level that controls which messages are displayed in the console. The level hierarchy (from least to most verbose) is: "none", "error", "warn", "info", "log", "debug". Each level includes all less verbose levels.

Parameter	Type	Description
`logLevel`	`string`	Log level as a string ("none", "error", "warn", "info", "log", or "debug")

`connect()` ⇒ `Promise`

Opens the browser Bluetooth device picker to select a device if none was previously selected, establishes a connection with the selected device, and initiates communication.

If configured, the onConnect() callback function will be executed after the connection is established.

Returns: Promise - Promise that resolves when the device is fully connected and communication has started, or rejects if an error occurs.

`disconnect()`

Disconnects from the currently connected device and cleans up associated resources.

If configured, the onDisconnect() callback function will be executed after the complete disconnection.

`send(message)` ⇒ `Promise`

Sends a message to the connected device, automatically adding the configured send separator and splitting the message into appropriate chunks if it exceeds the maximum characteristic value size.

Parameter	Type	Description
`message`	`string`	String message to send to the connected device

Returns: Promise - Promise that resolves when message successfully sent, or rejects if the device is disconnected or an error occurs.

`getDeviceName()` ⇒ `string`

Retrieves the name of the currently connected device.

Returns: string - Device name or an empty string if no device is connected or has no name.

Deprecated API

`setOnConnected([callback])`

Sets a callback that will be called after the device is fully connected and communication has started.

Parameter	Type	Description
`[callback]`	`() => void` \| `null` \| `undefined`	Callback for successful connection; omit or pass null/undefined to remove

`setOnDisconnected([callback])`

Sets a callback that will be called after the device is disconnected.

Parameter	Type	Description
`[callback]`	`() => void` \| `null` \| `undefined`	Callback for disconnection; omit or pass null/undefined to remove

`receive(message)`

Handler for incoming messages received from the connected device. Override this method to process messages received from the connected device. Each time a complete message (ending with the receive separator) is processed, this method will be called with the message string.

Parameter	Type	Description
`message`	`string`	String message received from the connected device, with separators removed

Development

Requires Node.js v22 (for development only).

Runtime Dependencies

The class is designed to have zero runtime dependencies as it should be easily used in browser applications.

Scripts and Development Dependencies

Linting uses ESLint: @eslint/js, eslint, eslint-config-google, eslint-plugin-jsdoc, typescript-eslint

npm run lint

TypeScript checking uses TypeScript: typescript.

npm run typecheck

Testing uses Jest and Web Bluetooth Mock: @types/jest, babel-jest, jest, jest-environment-jsdom, web-bluetooth-mock

npm test - run tests,
npm run test:coverage - run tests with coverage,
npm run coverage:clean - clean coverage directory,
npm run coverage - clean coverage directory and run tests with coverage.

Building uses Babel: @babel/cli, @babel/core, @babel/preset-env, @babel/preset-typescript

npm run build:clean - clean dist directory,
npm run build:code - build code,
npm run build:types - build TypeScript declaration,
npm run build - clean dist directory, build code and TypeScript declaration.

Logging

The logging system is implemented using simple private functions to avoid the complexity of additional classes or decorators. This lightweight approach reduces bundle size and maintains code readability while still providing comprehensive logging capabilities.

Log Levels

The class supports six hierarchical log levels (from least to most verbose):

none - disables all logging output,
error - only critical error messages,
warn - error messages plus warnings about unexpected but non-breaking behavior,
info - connection and disconnection status information, plus all warnings and errors,
log - detailed connection process information, plus all info-level messages,
debug - complete, verbose output of all operations, including internal method calls.

Log Levels Implementation

The following components log at specific levels throughout the class:

All errors - always logged at error level regardless of source,
Constructor, setter methods and callback function invocations - logged at debug level,
connect() - primary operation logged at info level,
- _requestDevice() - device selection logged at debug level,
- _connectDevice() - connection details logged at log level,
  - _startNotifications() - GATT operations logged at log level,
disconnect() - primary operation logged at info level (unexpected conditions at warn),
send() - message sending logged at debug level,
characteristicvaluechanged event listener - message reception logged at debug level,
gattserverdisconnected event listener - reconnection logged at log level.

bluetooth-terminal

bluetooth-terminal

Problem

Solution

Quick Start

Install

Use

Contents

API

BluetoothTerminal

new BluetoothTerminal([optionsOrServiceUuid], [characteristicUuid], [receiveSeparator], [sendSeparator], [onConnectCallback], [onDisconnectCallback])

BluetoothTerminalOptions

setServiceUuid(uuid)

setCharacteristicUuid(uuid)

setCharacteristicValueSize(size)

setReceiveSeparator(separator)

setSendSeparator(separator)

onConnect([callback])

onDisconnect([callback])

onReceive([callback])

onLog([callback])

setLogLevel(logLevel)

connect() ⇒ Promise

disconnect()

send(message) ⇒ Promise

getDeviceName() ⇒ string

Deprecated API

setOnConnected([callback])

setOnDisconnected([callback])

receive(message)

Development

Runtime Dependencies

Scripts and Development Dependencies

Logging

Log Levels

Log Levels Implementation

/bluetooth-terminal/

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`BluetoothTerminal`

`new BluetoothTerminal([optionsOrServiceUuid], [characteristicUuid], [receiveSeparator], [sendSeparator], [onConnectCallback], [onDisconnectCallback])`

`BluetoothTerminalOptions`

`setServiceUuid(uuid)`

`setCharacteristicUuid(uuid)`

`setCharacteristicValueSize(size)`

`setReceiveSeparator(separator)`

`setSendSeparator(separator)`

`onConnect([callback])`

`onDisconnect([callback])`

`onReceive([callback])`

`onLog([callback])`

`setLogLevel(logLevel)`

`connect()` ⇒ `Promise`

`disconnect()`

`send(message)` ⇒ `Promise`

`getDeviceName()` ⇒ `string`

`setOnConnected([callback])`

`setOnDisconnected([callback])`

`receive(message)`

Weekly Downloads