Blu is a framework that streamlines the integration of Web Bluetooth into your projects. Designed with ease of use in mind, Blu offers a robust and intuitive interface for interacting with Bluetooth Low Energy devices from the web, as well as native platforms that don’t support Web Bluetooth (yet).
npm install @blu.js/blu
Blu takes the complexity out of working with Web Bluetooth by providing extendable base classes for each component of the Bluetooth protocol with intuitive interfaces, streamlining the development process.
😕 Web Bluetooth API
await device.gatt.connect()
const service = await device.gatt.getPrimaryService("0x180F")
const characteristic = await service.getCharacteristic("0x2A19")
const value = await characteristic.readValue()
return value
✨ Blu
await device.connect()
const value = await device.service.characteristic.readValue()
return value
Blu streamlines interactions with Bluetooth characteristics by implementing an intuitive communication model based on requests and responses. Fetching data from a Bluetooth device is made simple: Just request
it and await
a response. No need for dealing with adding and removing listeners, parsing data and – if you’re using TypeScript – casting values for type safety.
😕 Web Bluetooth API
return new Promise(resolve => {
const onCharacteristicValueChanged = () => {
/**
* Ensure that the characteristic's value actually contains the data
* I wanted to get and is not the data for a `writeValueWithResponse`
* call that was triggered elsewhere in my application.
*
* ¯\_(ツ)_/¯
*/
/**
* Parse the data so that my application can actually use it.
*
* ¯\_(ツ)_/¯
*/
characteristic.removeEventListener(
"characteristicvaluechanged",
onCharacteristicValueChanged
)
resolve(myData)
}
characteristic.addEventListener(
"characteristicvaluechanged",
onCharacteristicValueChanged
)
// Let the characteristic know what data I want to query.
const GET_MY_DATA_COMMAND = 1
const PAYLOAD = [0, 1]
/**
* Ensure that the device is actually ready to receive and send the data,
* so that it does not throw errors – telling me that it is busy.
*
* ¯\_(ツ)_/¯
*/
await characteristic.writeValueWithResponse(
new Uint8Array([MY_DATA_OPCODE, ...PAYLOAD]),
)
})
✨ Blu
class MyDataResponse extends BluResponse {
static validatorFunction(response) {
return response.data?.getUint8(0) === Command.GET_MY_DATA
}
get myData() {
return this.data?.getUint8(1)
}
}
class MyDataRequest extends BluRequest {
responseType = MyDataResponse
constructor(...payload) {
super(convert.toUint8Array([Command.GET_MY_DATA, ...payload]))
}
}
const response = await characteristic.request(new MyDataRequest(0, 1))
return response.myData
Blu automatically queues all GATT (Generic Attribute Profile) operations your application triggers. This prevents “device busy” errors and potential data loss and enables you to have truly asynchronous communication with a connected device, globally – across your whole application.
Blu can also be used in environments where Web Bluetooth is not natively available, i.e. where globalThis.navigator.bluetooth
is missing, by allowing you to register a custom polyfill. You could, for example take the bluetooth-le plugin for Capacitor and to run your Blu-based application on iOS devices, where Web Bluetooth support is still lacking due to WebKit.
Blu is built with TypeScript, offering you a strongly typed and safely extendable interface.
The Blu framework is packaged as a minified ECMAScript module with source maps.
import blu from "@blu.js/blu"
// blu.bluetooth
// blu.configuration
// blu.convert
// blu.scanner
// blu.version
import {
BluDevice,
BluCharacteristic,
bluetooth,
configuration,
// ...
} from "@blu.js/blu"
You can find a detailed guide on how to use Blu in this repo’s wiki.
➡ How to implement your own device with Blu
To start building Blu locally, run the following:
git clone https://github.com/maxherrmann/blu.git && cd blu && npm i
npm run build
Builds the package with esbuild and DTS Bundle Generator.
npm run format
Formats the source code with Prettier.
npm run lint
Lints the source code with ESLint.
npm run lint:fix
Lints the source code with ESLint and fixes all auto-solvable issues.
npm run update
Interactively updates all dependencies with ncu
.
npm run update:auto
Automatically updates all dependencies with ncu
.