Skip to content

Latest commit

 

History

History
94 lines (70 loc) · 3.86 KB

documentation.md

File metadata and controls

94 lines (70 loc) · 3.86 KB
Raw

micro:bit Web Bluetooth

Web Bluetooth library for micro:bit implementing the micro:bit Bluetooth Profile.

Prerequisites

Node.js > v10.16.0, which includes npm

Installation

$ npm install microbit-web-bluetooth

Device Setup

Your micro:bit needs to be running a program which exposes the bluetooth service you wish to interact with.

Pre-compiled programs exposing bluetooth services are available for testing purposes:

https://github.com/thegecko/microbit-web-bluetooth/tree/main/hex

The first image targets the new micro:bit v2 while older micro:bit v1 versions exist for backwards compatibility:

Service microbit-universal no-magnet-no-io no-magnet-no-uart no-event-no-uart-no-dfu no-event-no-io-no-temp-no-acc
Device Info ✓ ✓ ✓ ✓ ✓
Button ✓ ✓ ✓ ✓ ✓
LED ✓ ✓ ✓ ✓ ✓
Temperature ✓ ✓ ✓ ✓ -
Accelerometer ✓ ✓ ✓ ✓ -
Event ✓ ✓ ✓ - -
DFU ✓ ✓ ✓ - ✓
UART ✓ ✓ - - ✓
Magnetometer ✓ - - ✓ ✓
IO Pin ✓ - ✓ ✓ -

The source for these sample programs is based on the codal example with the main.cpp file as outlined in the examples.

Note: The codal.json configuration must mark bluetooth as being open in order for Web Bluetooth to work. e.g.:

{
    "target": {
        "name": "codal-microbit",
        "url": "https://github.com/microbit-foundation/codal-microbit",
        "branch": "master",
        "type": "git",
        "test_ignore": true,
        "dev": true
    } ,
    "config":{
        "DEVICE_BLE": 1,
        "MICROBIT_BLE_ENABLED" : 1,
        "MICROBIT_BLE_OPEN" : 1,
        "MICROBIT_BLE_DFU_SERVICE": 1,
        "MICROBIT_BLE_EVENT_SERVICE" : 1,
        "MICROBIT_BLE_DEVICE_INFORMATION_SERVICE": 1
    }
}

Usage

Include the package in your web page, exposing a global named microbit:

<script type="text/javascript" src="microbit.umd.js"></script>

Use window.navigator.bluetooth.requestDevice() to obtain a bluetooth device or use the requestMicrobit() helper to discover a micro:bit:

const device = await microbit.requestMicrobit(window.navigator.bluetooth);

Use getServices() to return an array of available services:

const services = await microbit.getServices(device);

Services returned could be any of the following:

Refer to the web example (running) for a full example for each supported service.