googlearchive / platinum-bluetooth

A set of Polymer elements to discover and communicate with nearby Bluetooth devices
https://elements.polymer-project.org/elements/platinum-bluetooth
Apache License 2.0
22 stars 13 forks source link

Build status

Demo and API docs

<platinum-bluetooth-characteristic>

The <platinum-bluetooth-characteristic> element allows you to read and write characteristics on nearby bluetooth devices thanks to the young Web Bluetooth API. It is currently partially implemented behind the experimental flag chrome://flags/#enable-web-bluetooth. It is also now available in Chrome 53 as an origin trial for Chrome OS, Android M, and Mac.

<platinum-bluetooth-characteristic> needs to be a child of a <platinum-bluetooth-service> element.

For instance, here's how to read battery level from a nearby bluetooth device advertising Battery service:

<platinum-bluetooth-device services-filter='["battery_service"]'>
  <platinum-bluetooth-service service='battery_service'>
    <platinum-bluetooth-characteristic characteristic='battery_level'>
    </platinum-bluetooth-characteristic>
  </platinum-bluetooth-service>
</platinum-bluetooth-device>
var bluetoothDevice = document.querySelector('platinum-bluetooth-device');
var batteryLevel = document.querySelector('platinum-bluetooth-characteristic');

button.addEventListener('click', function() {
  bluetoothDevice.request().then(function() {
    return batteryLevel.read().then(function(value) {
      console.log('Battery Level is ' + value.getUint8(0) + '%');
    });
  })
  .catch(function(error) { });
});

Here's another example on how to reset energy expended on nearby bluetooth device advertising Heart Rate service:

<platinum-bluetooth-device services-filter='["heart_rate"]'>
  <platinum-bluetooth-service service='heart_rate'>
    <platinum-bluetooth-characteristic characteristic='heart_rate_control_point'>
    </platinum-bluetooth-characteristic>
  </platinum-bluetooth-service>
</platinum-bluetooth-device>
var bluetoothDevice = document.querySelector('platinum-bluetooth-device');
var heartRateCtrlPoint = document.querySelector('platinum-bluetooth-characteristic');

button.addEventListener('click', function() {
  bluetoothDevice.request().then(function() {
    // Writing 1 is the signal to reset energy expended.
    var resetEnergyExpended = new Uint8Array([1]);
    return heartRateCtrlPoint.write(resetEnergyExpended).then(function() {
      console.log('Energy expended has been reset');
    });
  })
  .catch(function(error) { });
});

It is also possible for <platinum-bluetooth-characteristic> to fill in a data-bound field in response to a read.

<platinum-bluetooth-device services-filter='["heart_rate"]'>
  <platinum-bluetooth-service service='heart_rate'>
    <platinum-bluetooth-characteristic characteristic='body_sensor_location'
                                       value={{bodySensorLocation}}>
    </platinum-bluetooth-characteristic>
  </platinum-bluetooth-service>
</platinum-bluetooth-device>
...
<span>{{bodySensorLocation}}</span>
var bluetoothDevice = document.querySelector('platinum-bluetooth-device');
var bodySensorLocation = document.querySelector('platinum-bluetooth-characteristic');

button.addEventListener('click', function() {
  bluetoothDevice.request().then(function() {
    return bodySensorLocation.read()
  })
  .catch(function(error) { });
});

Starting and stopping notifications on a <platinum-bluetooth-characteristic> is pretty straightforward when taking advantage of the Polymer Change notification protocol. Here's how to get your Heart Rate Measurement for instance:

<platinum-bluetooth-device services-filter='["heart_rate"]'>
  <platinum-bluetooth-service service='heart_rate'>
    <platinum-bluetooth-characteristic characteristic='heart_rate_measurement'
                                       on-value-changed='parseHeartRate'>
    </platinum-bluetooth-characteristic>
  </platinum-bluetooth-service>
</platinum-bluetooth-device>
var bluetoothDevice = document.querySelector('platinum-bluetooth-device');
var heartRate = document.querySelector('platinum-bluetooth-characteristic');

startButton.addEventListener('click', function() {
  bluetoothDevice.request().then(function() {
    return heartRate.startNotifications().catch(function(error) { });
  });
});

stopButton.addEventListener('click', function() {
  heartRate.stopNotifications().catch(function(error) { });
});

function parseHeartRate(event) {
 let value = event.target.value;
 // Do something with the DataView Object value...
}

You can also use changes in value to drive characteristic writes when auto-write property is set to true.

<platinum-bluetooth-device services-filter='["heart_rate"]'>
  <platinum-bluetooth-service service='heart_rate'>
    <platinum-bluetooth-characteristic characteristic='heart_rate_control_point'
                                       auto-write>
    </platinum-bluetooth-characteristic>
  </platinum-bluetooth-service>
</platinum-bluetooth-device>
var bluetoothDevice = document.querySelector('platinum-bluetooth-device');
var heartRateCtrlPoint = document.querySelector('platinum-bluetooth-characteristic');

button.addEventListener('click', function() {
  bluetoothDevice.request().then(function() {
    // Writing 1 is the signal to reset energy expended.
    heartRateCtrlPoint.value = new Uint8Array([1]);
  })
  .catch(function(error) { });
});

heartRateCtrlPoint.addEventListener('platinum-bluetooth-auto-write-error',
    function(event) {
  // Handle error...
});

<platinum-bluetooth-device>

The <platinum-bluetooth-device> element allows you to discover nearby bluetooth devices thanks to the young Web Bluetooth API. It is currently partially implemented behind the experimental flag chrome://flags/#enable-web-bluetooth. It is also now available in Chrome 53 as an origin trial for Chrome OS, Android M, and Mac.

<platinum-bluetooth-device> is used as a parent element for <platinum-bluetooth-service> child elements.

For instance, here's how to request a nearby bluetooth device advertising Battery service:

<platinum-bluetooth-device services-filter='["battery_service"]'>
</platinum-bluetooth-device>
button.addEventListener('click', function() {
  document.querySelector('platinum-bluetooth-device').request()
  .then(function(device) { console.log(device.name); })
  .catch(function(error) { console.error(error); });
});

You can also request a nearby bluetooth device by setting a filter on a name or name Prefix:

<platinum-bluetooth-device name-filter='foobar'>
</platinum-bluetooth-device>
<platinum-bluetooth-device name-prefix-filter='foo'>
</platinum-bluetooth-device>

And you can combine some of the filters as well. Here's how to request a nearby bluetooth device advertising Battery service and whose name is "foobar":

<platinum-bluetooth-device services-filter='["battery_service"]'
                           name-filter='foobar'>
</platinum-bluetooth-device>

If you filter just by name, then you must use optional-services-filter to get access to any services:

<platinum-bluetooth-device name-filter='foobar'
                           optional-services-filter='["battery_service"]'>
</platinum-bluetooth-device>

Disconnecting manually from a connected bluetooth device is pretty straightforward:

disconnectButton.addEventListener('click', function() {
  document.querySelector('platinum-bluetooth-device').disconnect();
});

<platinum-bluetooth-service>

The <platinum-bluetooth-service> element is used in conjuction with the <platinum-bluetooth-characteristic> element to read and write characteristics on nearby bluetooth devices thanks to the young Web Bluetooth API. It is currently partially implemented behind the experimental flag chrome://flags/#enable-web-bluetooth. It is also now available in Chrome 53 as an origin trial for Chrome OS, Android M, and Mac.

<platinum-bluetooth-service> needs to be a child of a <platinum-bluetooth-device> element.

For instance, here's how to read battery level from a nearby bluetooth device advertising Battery service:

<platinum-bluetooth-device services-filter='["battery_service"]'>
  <platinum-bluetooth-service service='battery_service'>
    <platinum-bluetooth-characteristic characteristic='battery_level'>
    </platinum-bluetooth-characteristic>
  </platinum-bluetooth-service>
</platinum-bluetooth-device>
var bluetoothDevice = document.querySelector('platinum-bluetooth-device');
var batteryLevel = document.querySelector('platinum-bluetooth-characteristic');

button.addEventListener('click', function() {
  bluetoothDevice.request().then(function() {
    return batteryLevel.read().then(function(value) {
      console.log('Battery Level is ' + value.getUint8(0) + '%');
    });
  })
  .catch(function(error) { });
});