web-bluetooth

web-bluetooth

A Javascript Library for interacting with Bluetooth Low Energy Devices.

Bridging the gap between the web and the physical world through Bluetooth.

Previously, interacting with Bluetooth devices was limited to native applications. Access to connect, read, and write from Bluetooth devices is now made available to web applications thanks to the Web Bluetooth API and modern web browsers like Chrome and Firefox, Opera who are incresingly adding support for new features in the Web Bluetooth API Spec.

Overview

Web-bluetooth is a configurable application framework for integrating bluetooth functionality with client-side Javascript.

Getting Started

Web-Bluetooth (currently v1.0.0) has a few easy ways to quickly get started, each one appealing to your preferences.

Download

You can install web-bluetooth by downloading our minified library here

Make the library available by referencing it in your index.html file.

<script>/lib/web-bluetooth.js</script>

Install with npm

You can install web-bluetooth with npm

Require('web-bluetooth') will load all of the files necessary to run our library.

$ npm install web-bluetooth

General Accesibility

While the Web Bluetooth API is still in development, features have been made available. This library has made available several important features to develop web applications using Bluetooth connections.

Note: The Web Bluetooth API is still in development and many features have not been implemented across browsers. For the current status of the API, please follow this link.

Feature	ChromeOS	Android Mobile	MacOSX
Device Discovery	✓	✓	✓
Device Connecting	✓	✓	✓
Device Disconnecting	✓	✓	✓
Device Services Read	✓	✓

GATT Services Support

Services are collections of characteristics and relationships to other services that encapsulate the behavior of part of a device. For example, the “Battery Service” exposes the Battery Level of a device broadcasting the “Battery Service” service.

This library abstracts over core GATT Service types with special attention to service types that are common and that are most applicable in this current stage of Bluetooth device availability.

For the full list of normative Services click here. As the Web Bluetooth API continues to be developed and as this library matures, more service types will be made available.

Service	Supported	Spec Type	Assigned Number
Alert Notification		'alert-notification'	0x1811
Battery Service	✓	'battery_service'	0x180F
Blood Pressure		'blood_pressure'	0x1810
Cycling Power		'cycling_power'	0x1818
Cycling Speed and Cadence		'cycling_speed_and_cadence'	0x1816
Device Info	✓	'device_information'	0x180A
Generic Access	✓	'generic_access'	0x1800
Generic Attribute	✓	'generic_attribute'	0x1801
Health Thermometer		'health-thermometer'	0x1809
Heart Rate	✓	'health-heart_rate'	0x180D
Running Speed and Cadence		'running_speed_and_cadence'	0x1814
Tx Power	✓	'tx_power'	0x1804

General Methods Provided by Library

Create a New Bluetooth Device Object

Before calling methods on your Bluetooth device, create a new Bluetooth device object.

var fitbit = new Device({
  namePrefix: 'Surge'
  services: ['battery_service']
});

In the example above, we have created a new Bluetooth device object titled 'blue' by requesting the object with it's 'namePrefix' and a service of 'battery service'. Device is a constructor that takes in an object corresponding to attributes on the bluetooth device. Below is a schema for what can be used to connect to a device. At least one option is needed to request a device.

{
  name: 'device_name',
  namePrefix: 'devicePrefix',
  uuid: 'uuid',
  service: 'service'
}

'name': is the name (hardware) of the device

'namePrefix': looks for a name starting with namePrefix

'services': represents a 128-bit UUID. A valid UUID is a string that matches the regexp '/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/'

'uuid': collection of characteristics and the relationships to other services encapsulate the behavior of part of a device

.connect()

Method allows you to establish a persistent connection with a Bluetooth device.

fitbit.connect(connectedDevice,(server) => {
  connectedDevice = device;
};

.disconnect()

Method disconnects you from the device.

fitbit.disconnect();

.getValue('characteristic')

Method reads the value from the device you are connected to by passing in the characteristic as a string.

fitbit
  .getValue('battery_level')
    .then(value => {
      console.log(value);
    });

In the above example, .getValue() returns the current battery level as a percentage from 0% to 100%; 0% represents a battery that is fully discharged, 100% represents a battery that is fully charged.

Demo

Battery Service

This demo uses the Web-Bluetooth library to connect to a device broadcasting a Battery Service characteristic and reads it's level.

View the demo. | Visit the GitHub page.

Notes: • Requires Android 6.0 Marshmallow, ChromeOS or Chrome for Linux. • Enable the 'Web Bluetooth' flag.

Authors and Contributors

Sabertooth is a team of four software developers enthusiastic to be contributing to the open source community. Visit their GitHub page for more information.