Complete Docs

documentation.md

@@ -0,0 +1,46 @@
+# micro:bit Web Bluetooth
+
+Web Bluetooth library for micro:bit implementing the [micro:bit Bluetooth Profile](https://lancaster-university.github.io/microbit-docs/resources/bluetooth/bluetooth_profile.html).
+
+## Prerequisites
+
+[Node.js > v8.14.0](https://nodejs.org), which includes `npm`
+
+## Installation
+
+```bash
+$ npm install microbit-web-bluetooth
+```
+
+## Usage
+
+Include the package in your web page, exposing a global named `microbit`:
+
+```html
+<script type="text/javascript" src="microbit.umd.js"></script>
+```
+
+Use `window.navigator.bluetooth.requestDevice()` to obtain a bluetooth device or use the [requestMicrobit()](globals.html#requestmicrobit) helper to discover a micro:bit:
+
+```javascript
+const device = await microbit.requestMicrobit(window.navigator.bluetooth);
+```
+
+Use [getServices()](globals.html#getservices) to return an array of available services:
+
+```javascript
+const services = await microbit.getServices(device);
+```
+
+Services returned could be any of the following:
+
+- [deviceInformationService](classes/deviceinformationservice.html)
+- [uartService](classes/uartservice.html)
+- [ledService](classes/ledservice.html)
+- [buttonService](classes/buttonservice.html)
+- [temperatureService](classes/temperatureservice.html)
+- [accelerometerService](classes/accelerometerservice.html)
+- [magnetometerService](classes/magnetometerservice.html)
+- [eventService](classes/eventservice.html)
+
+Refer to the [web example](https://github.com/thegecko/microbit-web-bluetooth/blob/master/examples/index.html) ([running](https://thegecko.github.io/microbit-web-bluetooth/examples/index.html)) for a full example for each supported service.

examples/index.html

@@ -22,19 +22,19 @@
                     }
 
                     if (services.uartService) {
-                        services.uartService.addEventListener("receiveString", eventHandler);
+                        services.uartService.addEventListener("receiveText", eventHandler);
                         await services.uartService.send(new Uint8Array([104, 101, 108, 108, 111, 58])); // hello:
                     }
 
                     if (services.ledService) {
-                        await services.ledService.setMatrixState([
+                        await services.ledService.writeMatrixState([
                             [1, 0, 1, 0, 0],
                             [1, 1, 1, 1, 1],
                             [0, 0, 1, 0, 0],
                             [0, 1, 0, 1, 0],
                             [1, 0, 0, 0, 1]
                         ]);
-                        logJson(await services.ledService.getMatrixState());
+                        logJson(await services.ledService.readMatrixState());
 
                         await services.ledService.setScrollingDelay(50);
                         log(await services.ledService.getScrollingDelay());

package.json

@@ -1,6 +1,6 @@
 {
   "name": "microbit-web-bluetooth",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Web Bluetooth library for micro:bit",
   "homepage": "https://github.com/thegecko/microbit-web-bluetooth",
   "license": "MIT",

src/index.ts

@@ -45,11 +45,17 @@ export interface Services {
     eventService?: EventService;
 }
 
+/**
+ * @hidden
+ */
 interface Service {
     uuid: BluetoothCharacteristicUUID;
     create(service: BluetoothRemoteGATTService): Promise<any>;
 }
 
+/**
+ * @hidden
+ */
 class ServiceBuilder {
 
     constructor(private services: BluetoothRemoteGATTService[]) {

src/promise-queue.ts

@@ -23,12 +23,18 @@
 * SOFTWARE.
 */
 
+/**
+ * @hidden
+ */
 interface QueuedPromise {
     fn: () => Promise<any>;
     resolve: (value?: any | PromiseLike<any> | undefined) => void;
     reject: (reason?: any) => void;
 }
 
+/**
+ * @hidden
+ */
 export class PromiseQueue {
 
     private queue: QueuedPromise[] = [];

src/service-helper.ts

@@ -26,11 +26,17 @@
 import { EventEmitter } from "events";
 import { PromiseQueue } from "./promise-queue";
 
+/**
+ * @hidden
+ */
 export interface ServiceEventHandler {
     characteristic: BluetoothCharacteristicUUID;
     handler: (event: Event) => void;
 }
 
+/**
+ * @hidden
+ */
 export class ServiceHelper {
 
     private static queue = new PromiseQueue();

src/services/accelerometer.ts

@@ -34,20 +34,50 @@ export enum AccelerometerCharacteristic {
     accelerometerPeriod = "e95dfb24-251d-470a-a062-fa1922dfa9a8"
 }
 
+/**
+ * Data received from the accelerometer
+ */
 export interface AccelerometerData {
+    /**
+     * Force in direction X
+     */
     x: number;
+    /**
+     * Force in direction Y
+     */
     y: number;
+    /**
+     * Force in direction Z
+     */
     z: number;
 }
 
+/**
+ * The sample period to read accelerometer data (milliseconds)
+ */
 export type AccelerometerPeriod = 1 | 2 | 5 | 10 | 20 | 80 | 160 | 640;
 
+/**
+ * Events raised by the accelerometer service
+ */
 export interface AccelerometerEvents {
+    /**
+     * @hidden
+     */
     newListener: keyof AccelerometerEvents;
+    /**
+     * @hidden
+     */
     removeListener: keyof AccelerometerEvents;
+    /**
+     * Accelerometer data changed event
+     */
     accelerometerdatachanged: AccelerometerData;
 }
 
+/**
+ * Accelerometer Service
+ */
 export class AccelerometerService extends (EventDispatcher as new() => TypedDispatcher<AccelerometerEvents>) {
 
     /**
@@ -66,6 +96,9 @@ export class AccelerometerService extends (EventDispatcher as new() => TypedDisp
 
     private helper: ServiceHelper;
 
+    /**
+     * @hidden
+     */
     constructor(service: BluetoothRemoteGATTService) {
         super();
         this.helper = new ServiceHelper(service, this);
@@ -75,16 +108,26 @@ export class AccelerometerService extends (EventDispatcher as new() => TypedDisp
         await this.helper.handleListener("accelerometerdatachanged", AccelerometerCharacteristic.accelerometerData, this.accelerometerDataChangedHandler.bind(this));
     }
 
+    /**
+     * Read acceleromter data
+     */
     public async readAccelerometerData(): Promise<AccelerometerData> {
         const view = await this.helper.getCharacteristicValue(AccelerometerCharacteristic.accelerometerData);
         return this.dataViewToAccelerometerData(view);
     }
 
+    /**
+     * Get accelerometer sample period
+     */
     public async getAccelerometerPeriod(): Promise<AccelerometerPeriod> {
         const value = await this.helper.getCharacteristicValue(AccelerometerCharacteristic.accelerometerPeriod);
         return value.getUint16(0, true) as AccelerometerPeriod;
     }
 
+    /**
+     * Set accelerometer sample period
+     * @param frequency The frequency interval to use
+     */
     public async setAccelerometerPeriod(frequency: AccelerometerPeriod): Promise<void> {
         const view = new DataView(new ArrayBuffer(2));
         view.setUint16(0, frequency, true);

src/services/button.ts

@@ -34,19 +34,49 @@ export enum ButtonCharacteristic {
     buttonBState = "e95dda91-251d-470a-a062-fa1922dfa9a8"
 }
 
+/**
+ * Button state enum
+ */
 export enum ButtonState {
+    /**
+     * Button released
+     */
     Release = 0,
+    /**
+     * Button pressed - short
+     */
     ShortPress = 1,
+    /**
+     * Button pressed - long
+     */
     LongPress = 2
 }
 
+/**
+ * Events raised by the button service
+ */
 export interface ButtonEvents {
+    /**
+     * @hidden
+     */
     newListener: keyof ButtonEvents;
+    /**
+     * @hidden
+     */
     removeListener: keyof ButtonEvents;
+    /**
+     * Button A state changed event
+     */
     buttonastatechanged: ButtonState;
+    /**
+     * Button B state changed event
+     */
     buttonbstatechanged: ButtonState;
 }
 
+/**
+ * Button Service
+ */
 export class ButtonService extends (EventDispatcher as new() => TypedDispatcher<ButtonEvents>) {
 
     /**
@@ -65,6 +95,9 @@ export class ButtonService extends (EventDispatcher as new() => TypedDispatcher<
 
     private helper: ServiceHelper;
 
+    /**
+     * @hidden
+     */
     constructor(service: BluetoothRemoteGATTService) {
         super();
         this.helper = new ServiceHelper(service, this);
@@ -75,11 +108,17 @@ export class ButtonService extends (EventDispatcher as new() => TypedDispatcher<
         await this.helper.handleListener("buttonbstatechanged", ButtonCharacteristic.buttonBState, this.buttonBStateChangedHandler.bind(this));
     }
 
+    /**
+     * Read state of button A
+     */
     public async readButtonAState(): Promise<ButtonState> {
         const value = await this.helper.getCharacteristicValue(ButtonCharacteristic.buttonAState);
         return value.getUint8(0);
     }
 
+    /**
+     * Read state of button B
+     */
     public async readButtonBState(): Promise<ButtonState> {
         const value = await this.helper.getCharacteristicValue(ButtonCharacteristic.buttonBState);
         return value.getUint8(0);

src/services/device-information.ts

@@ -36,14 +36,35 @@ export enum DeviceInformationCharacteristic {
     manufacturer = "00002a29-0000-1000-8000-00805f9b34fb"
 }
 
+/**
+ * Device information structure
+ */
 export interface DeviceInformation {
+    /**
+     * Model Number
+     */
     modelNumber?: string;
+    /**
+     * Serial Number
+     */
     serialNumber?: string;
+    /**
+     * Firmware Revision
+     */
     firmwareRevision?: string;
+    /**
+     * Hardware Revision
+     */
     hardwareRevision?: string;
+    /**
+     * Manufacturer Name
+     */
     manufacturer?: string;
 }
 
+/**
+ * Device Information Service
+ */
 export class DeviceInformationService {
 
     /**
@@ -60,10 +81,16 @@ export class DeviceInformationService {
 
     private helper: ServiceHelper;
 
+    /**
+     * @hidden
+     */
     constructor(service: BluetoothRemoteGATTService) {
         this.helper = new ServiceHelper(service);
     }
 
+    /**
+     * Read device information
+     */
     public async readDeviceInformation(): Promise<DeviceInformation> {
         const info: DeviceInformation = {};
 

src/services/dfu-control.ts

@@ -32,6 +32,9 @@ export enum DfuCharacteristic {
     dfuControl = "e95d93b1-251d-470a-a062-fa1922dfa9a8"
 }
 
+/**
+ * @hidden
+ */
 export class DfuControlService {
 
     /**
@@ -46,8 +49,14 @@ export class DfuControlService {
         return new DfuControlService(service);
     }
 
+    /**
+     * @hidden
+     */
     public helper: ServiceHelper;
 
+    /**
+     * @hidden
+     */
     constructor(service: BluetoothRemoteGATTService) {
         this.helper = new ServiceHelper(service);
     }