@microbit/microbit-connection 0.0.0-tab.change.177 → 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Micro:bit Educational Foundation and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,99 @@
-# JavaScript library for micro:bit connections in browsers via USB and Bluetooth
+# micro:bit connection library
 
-This project is a work in progress. We are extracting WebUSB and Web Bluetooth code from the [micro:bit Python Editor](https://github.com/microbit-foundation/python-editor-v3/) and other projects.
+<a href="https://microbit-foundation.github.io/microbit-connection/" class="typedoc-ignore">This documentation is best viewed on the documentation site rather than GitHub or NPM package site.</a>
 
-It is intended to be used by other Micro:bit Educational Foundation projects that need to connect to a BBC micro:bit.
+This is a JavaScript library for micro:bit connections in browsers via USB and Bluetooth.
 
-The API is not stable and it's not yet recommended that third parties use this project.
+This project is a work in progress. We are extracting WebUSB and Web Bluetooth code from the [micro:bit Python Editor](https://github.com/microbit-foundation/python-editor-v3/) and other projects. The API is not stable and it's not yet recommended that third parties use this project unless they are happy to update usage as the API evolves.
+
+[Demo page](https://microbit-connection.pages.dev/) for this library.
+
+[Alpha releases are now on NPM](https://www.npmjs.com/package/@microbit/microbit-connection).
+
+[micro:bit CreateAI](https://github.com/microbit-foundation/ml-trainer/) is already using this library for WebUSB and Web Bluetooth.
+
+[This Python Editor PR](https://github.com/microbit-foundation/python-editor-v3/pull/1190) tracks updating the micro:bit Python Editor to use this library.
+
+## Usage
+
+### Flash a micro:bit
+
+Instantiate a WebUSB connection using {@link createWebUSBConnection} class and use it to connect to a micro:bit.
+
+```ts
+import { createWebUSBConnection } from "@microbit/microbit-connection";
+
+const usb = createWebUSBConnection();
+const connectionStatus = await usb.connect();
+
+console.log("Connection status: ", connectionStatus);
+```
+
+{@link ConnectionStatus | Connection status} is `"CONNECTED"` if connection succeeds.
+
+Flash a universal hex that supports both V1 and V2:
+
+```ts
+import { createUniversalHexFlashDataSource } from "@microbit/microbit-connection";
+
+await usb.flash(createUniversalHexFlashDataSource(universalHexString), {
+  partial: true,
+  progress: (percentage: number | undefined) => {
+    console.log(percentage);
+  },
+});
+```
+
+This code will also work for non-universal hex files so is a good default for unknown hex files.
+
+Alternatively, you can create and flash a hex for a specific micro:bit version by providing a function that takes a {@link BoardVersion} and returns a hex.
+This can reduce download size or help integrate with APIs that produce a hex for a particular device version.
+This example uses the [@microbit/microbit-fs library](https://microbit-foundation.github.io/microbit-fs/) which can return a hex based on board id.
+
+```ts
+import { MicropythonFsHex, microbitBoardId } from "@microbit/microbit-fs";
+import { BoardId } from "@microbit/microbit-connection";
+
+const micropythonFs = new MicropythonFsHex([
+  { hex: microPythonV1HexFile, boardId: microbitBoardId.V1 },
+  { hex: microPythonV2HexFile, boardId: microbitBoardId.V2 },
+]);
+// Add files to MicroPython file system here (omitted for simplicity)
+// Flash the device
+await usb.flash(
+  async (boardVersion) => {
+    const boardId = BoardId.forVersion(boardVersion).id;
+    return micropythonFs.getIntelHex(boardId);
+  },
+  {
+    partial: true,
+    progress: (percentage: number | undefined) => {
+      console.log(percentage);
+    },
+  },
+);
+```
+
+For more examples of using other methods in the {@link MicrobitWebUSBConnection} class, see our [demo code](https://github.com/microbit-foundation/microbit-connection/blob/main/src/demo.ts) for our [demo site](https://microbit-connection.pages.dev/).
+
+### Connect via Bluetooth
+
+By default, the micro:bit's Bluetooth service is not enabled. Visit our [Bluetooth tech site page](https://tech.microbit.org/bluetooth/) to download a hex file that would enable the bluetooth service.
+
+Instantiate a Bluetooth connection using {@link createWebBluetoothConnection} class and use it to connect to a micro:bit.
+
+```ts
+import { createWebBluetoothConnection } from "@microbit/microbit-connection";
+
+const bluetooth = createWebBluetoothConnection();
+const connectionStatus = await bluetooth.connect();
+
+console.log("Connection status: ", connectionStatus);
+```
+
+{@link ConnectionStatus | Connection status} is `"CONNECTED"` if connection succeeds.
+
+For more examples of using other methods in the {@link createWebBluetoothConnection} class, see our [demo code](https://github.com/microbit-foundation/microbit-connection/blob/main/src/demo.ts) for our [demo site](https://microbit-connection.pages.dev/).
 
 ## License
 
@@ -22,7 +111,7 @@ $ npx license-checker --direct --summary --production
 
 Omit the flags as desired to obtain more detail.
 
-## Code of Conduct
+## Code of conduct
 
 Trust, partnership, simplicity and passion are our core values we live and
 breathe in our daily work life and within our projects. Our open-source

package/build/cjs/accelerometer-service.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccelerometerService = void 0;
+const accelerometer_js_1 = require("./accelerometer.js");
+const bluetooth_profile_js_1 = require("./bluetooth-profile.js");
+const device_js_1 = require("./device.js");
+class AccelerometerService {
+    constructor(accelerometerDataCharacteristic, accelerometerPeriodCharacteristic, dispatchTypedEvent, queueGattOperation) {
+        Object.defineProperty(this, "accelerometerDataCharacteristic", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: accelerometerDataCharacteristic
+        });
+        Object.defineProperty(this, "accelerometerPeriodCharacteristic", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: accelerometerPeriodCharacteristic
+        });
+        Object.defineProperty(this, "dispatchTypedEvent", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: dispatchTypedEvent
+        });
+        Object.defineProperty(this, "queueGattOperation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: queueGattOperation
+        });
+        this.accelerometerDataCharacteristic.addEventListener("characteristicvaluechanged", (event) => {
+            const target = event.target;
+            const data = this.dataViewToData(target.value);
+            this.dispatchTypedEvent("accelerometerdatachanged", new accelerometer_js_1.AccelerometerDataEvent(data));
+        });
+    }
+    static async createService(gattServer, dispatcher, queueGattOperation, listenerInit) {
+        let accelerometerService;
+        try {
+            accelerometerService = await gattServer.getPrimaryService(bluetooth_profile_js_1.profile.accelerometer.id);
+        }
+        catch (err) {
+            if (listenerInit) {
+                dispatcher("backgrounderror", new device_js_1.BackgroundErrorEvent(err));
+                return;
+            }
+            else {
+                throw new device_js_1.DeviceError({
+                    code: "service-missing",
+                    message: err,
+                });
+            }
+        }
+        const accelerometerDataCharacteristic = await accelerometerService.getCharacteristic(bluetooth_profile_js_1.profile.accelerometer.characteristics.data.id);
+        const accelerometerPeriodCharacteristic = await accelerometerService.getCharacteristic(bluetooth_profile_js_1.profile.accelerometer.characteristics.period.id);
+        return new AccelerometerService(accelerometerDataCharacteristic, accelerometerPeriodCharacteristic, dispatcher, queueGattOperation);
+    }
+    dataViewToData(dataView) {
+        return {
+            x: dataView.getInt16(0, true),
+            y: dataView.getInt16(2, true),
+            z: dataView.getInt16(4, true),
+        };
+    }
+    async getData() {
+        const dataView = await this.queueGattOperation(() => this.accelerometerDataCharacteristic.readValue());
+        return this.dataViewToData(dataView);
+    }
+    async getPeriod() {
+        const dataView = await this.queueGattOperation(() => this.accelerometerPeriodCharacteristic.readValue());
+        return dataView.getUint16(0, true);
+    }
+    async setPeriod(value) {
+        if (value === 0) {
+            // Writing 0 causes the device to crash.
+            return;
+        }
+        // Allowed values: 2, 5, 10, 20, 40, 100, 1000
+        // Values passed are rounded up to the allowed values on device.
+        // Documentation for allowed values looks wrong.
+        // https://lancaster-university.github.io/microbit-docs/ble/profile/#about-the-accelerometer-service
+        const dataView = new DataView(new ArrayBuffer(2));
+        dataView.setUint16(0, value, true);
+        return this.queueGattOperation(() => this.accelerometerPeriodCharacteristic.writeValue(dataView));
+    }
+    async startNotifications(type) {
+        await this.characteristicForEvent(type)?.startNotifications();
+    }
+    async stopNotifications(type) {
+        await this.characteristicForEvent(type)?.stopNotifications();
+    }
+    characteristicForEvent(type) {
+        switch (type) {
+            case "accelerometerdatachanged": {
+                return this.accelerometerDataCharacteristic;
+            }
+            default: {
+                return undefined;
+            }
+        }
+    }
+}
+exports.AccelerometerService = AccelerometerService;
+//# sourceMappingURL=accelerometer-service.js.map

package/build/cjs/accelerometer-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accelerometer-service.js","sourceRoot":"","sources":["../../lib/accelerometer-service.ts"],"names":[],"mappings":"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"}

package/build/cjs/accelerometer.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccelerometerDataEvent = void 0;
+class AccelerometerDataEvent extends Event {
+    constructor(data) {
+        super("accelerometerdatachanged");
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: data
+        });
+    }
+}
+exports.AccelerometerDataEvent = AccelerometerDataEvent;
+//# sourceMappingURL=accelerometer.js.map

package/build/cjs/accelerometer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accelerometer.js","sourceRoot":"","sources":["../../lib/accelerometer.ts"],"names":[],"mappings":";;;AAMA,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAA4B,IAAuB;QACjD,KAAK,CAAC,0BAA0B,CAAC,CAAC;QADxB;;;;mBAAgB,IAAI;WAAmB;IAEnD,CAAC;CACF;AAJD,wDAIC"}

package/build/cjs/async-util.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = void 0;
+exports.withTimeout = withTimeout;
+/**
+ * (c) 2021, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+class TimeoutError extends Error {
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Utility to time out an action after a delay.
+ *
+ * The action cannot be cancelled; it may still proceed after the timeout.
+ */
+async function withTimeout(actionPromise, timeout) {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new TimeoutError());
+        }, timeout);
+    });
+    // timeoutPromise never resolves so result must be from action
+    return Promise.race([actionPromise, timeoutPromise]);
+}
+//# sourceMappingURL=async-util.js.map

package/build/cjs/async-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-util.js","sourceRoot":"","sources":["../../lib/async-util.ts"],"names":[],"mappings":";;;AAYA,kCAWC;AAvBD;;;;GAIG;AACH,MAAa,YAAa,SAAQ,KAAK;CAAG;AAA1C,oCAA0C;AAE1C;;;;GAIG;AACI,KAAK,UAAU,WAAW,CAC/B,aAAyB,EACzB,OAAe;IAEf,MAAM,cAAc,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC/C,UAAU,CAAC,GAAG,EAAE;YACd,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC;QAC7B,CAAC,EAAE,OAAO,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;IACH,8DAA8D;IAC9D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,cAAc,CAAC,CAAe,CAAC;AACrE,CAAC"}

package/build/{bluetooth-device-wrapper.d.ts → cjs/bluetooth-device-wrapper.d.ts}

@@ -7,7 +7,9 @@ import { AccelerometerService } from "./accelerometer-service.js";
 import { BoardVersion } from "./device.js";
 import { LedService } from "./led-service.js";
 import { Logging } from "./logging.js";
+import { MagnetometerService } from "./magnetometer-service.js";
 import { ServiceConnectionEventMap, TypedServiceEvent, TypedServiceEventDispatcher } from "./service-events.js";
+import { UARTService } from "./uart-service.js";
 export interface Service {
     startNotifications(type: TypedServiceEvent): Promise<void>;
     stopNotifications(type: TypedServiceEvent): Promise<void>;
@@ -29,10 +31,12 @@ export declare class BluetoothDeviceWrapper {
     private disconnectPromise;
     private connecting;
     private isReconnect;
-    private reconnectReadyPromise;
+    private connectReadyPromise;
     private accelerometer;
     private buttons;
     private led;
+    private magnetometer;
+    private uart;
     private serviceInfo;
     boardVersion: BoardVersion | undefined;
     private disconnectedRejectionErrorFactory;
@@ -49,6 +53,8 @@ export declare class BluetoothDeviceWrapper {
     private createIfNeeded;
     getAccelerometerService(): Promise<AccelerometerService | undefined>;
     getLedService(): Promise<LedService | undefined>;
+    getMagnetometerService(): Promise<MagnetometerService | undefined>;
+    getUARTService(): Promise<UARTService | undefined>;
     startNotifications(type: TypedServiceEvent): Promise<void>;
     stopNotifications(type: TypedServiceEvent): Promise<void>;
     private disposeServices;