Apps branch for experimentation

This contains breaking changes (e.g. flash progress interface, connect
signature, device error codes) and will form part of a v1 at some point.
Migrating USB-only code should be trivial though.

Changes:
- Switch to capacitor-ble for bluetooth
  - Quite a simplication as the service/characteristic lookups are deferred to
    point of use and the interactions are internally queued.

- Support DFU and partial flashing on iOS/Android platforms
- Drop a bunch of workarounds that need reevaluating after the switch
- Temporarily drop uBit name support due to capacitor-ble limitation
- Don't try to start notifications on absent services. Prevents issues when not
  in application mode for a flash.
- Improve connect interface (which had a misleading return value) and
  connect/flash progress.

This branch is going to be long lived for a month or two during apps work, then
we'll loop back around and see what it means for Web Bluetooth - does it
replace it or do we have both implementations.

Design issues:

- Should connecting and connecting for flashing both be the same flow? Or are
  the ideas different enough that we split them? It's nice in that it matches
  USB but it's also quite different because of pairing.

Author: microbit-matt-hillsdon

.github/workflows/build-docs.yml

@@ -24,7 +24,7 @@ jobs:
           path: ./docs/build
 
   deploy:
-    if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    if: false
     permissions:
       pages: write
       id-token: write

.github/workflows/build.yml

@@ -16,14 +16,14 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: "20.x"
-          registry-url: 'https://registry.npmjs.org'
+          registry-url: "https://registry.npmjs.org"
           cache: npm
       - uses: microbit-foundation/npm-package-versioner-action@v1
       - run: npm ci
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - run: npm run ci
-      - run: npm publish
+      - run: npm publish --tag apps
         if: github.event_name == 'release' && github.event.action == 'created'
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -38,8 +38,8 @@ import { createUniversalHexFlashDataSource } from "@microbit/microbit-connection
 
 await usb.flash(createUniversalHexFlashDataSource(universalHexString), {
   partial: true,
-  progress: (percentage: number | undefined) => {
-    console.log(percentage);
+  progress: (stage, percentage) => {
+    console.log(stage, percentage);
   },
 });
 ```
@@ -67,8 +67,8 @@ await usb.flash(
   },
   {
     partial: true,
-    progress: (percentage: number | undefined) => {
-      console.log(percentage);
+    progress: (stage, percentage) => {
+      console.log(stage, percentage);
     },
   },
 );

lib/accelerometer-service.ts

@@ -1,69 +1,30 @@
+import { BleClient } from "@capacitor-community/bluetooth-le";
 import { AccelerometerData, AccelerometerDataEvent } from "./accelerometer.js";
 import { Service } from "./bluetooth-device-wrapper.js";
-import { profile } from "./bluetooth-profile.js";
-import { BackgroundErrorEvent, DeviceError } from "./device.js";
 import {
-  CharacteristicDataTarget,
   TypedServiceEvent,
   TypedServiceEventDispatcher,
 } from "./service-events.js";
+import { profile } from "./bluetooth-profile.js";
+import { BackgroundErrorEvent } from "./device.js";
 
 export class AccelerometerService implements Service {
+  uuid = profile.accelerometer.id;
+
+  static createService(
+    deviceId: string,
+    dispatchTypedEvent: TypedServiceEventDispatcher,
+  ): AccelerometerService {
+    return new AccelerometerService(deviceId, dispatchTypedEvent);
+  }
+
   constructor(
-    private accelerometerDataCharacteristic: BluetoothRemoteGATTCharacteristic,
-    private accelerometerPeriodCharacteristic: BluetoothRemoteGATTCharacteristic,
+    private deviceId: string,
     private dispatchTypedEvent: TypedServiceEventDispatcher,
-    private queueGattOperation: <R>(action: () => Promise<R>) => Promise<R>,
-  ) {
-    this.accelerometerDataCharacteristic.addEventListener(
-      "characteristicvaluechanged",
-      (event: Event) => {
-        const target = event.target as CharacteristicDataTarget;
-        const data = this.dataViewToData(target.value);
-        this.dispatchTypedEvent(
-          "accelerometerdatachanged",
-          new AccelerometerDataEvent(data),
-        );
-      },
-    );
-  }
+  ) {}
 
-  static async createService(
-    gattServer: BluetoothRemoteGATTServer,
-    dispatcher: TypedServiceEventDispatcher,
-    queueGattOperation: <R>(action: () => Promise<R>) => Promise<R>,
-    listenerInit: boolean,
-  ): Promise<AccelerometerService | undefined> {
-    let accelerometerService: BluetoothRemoteGATTService;
-    try {
-      accelerometerService = await gattServer.getPrimaryService(
-        profile.accelerometer.id,
-      );
-    } catch (err) {
-      if (listenerInit) {
-        dispatcher("backgrounderror", new BackgroundErrorEvent(err as string));
-        return;
-      } else {
-        throw new DeviceError({
-          code: "service-missing",
-          message: err as string,
-        });
-      }
-    }
-    const accelerometerDataCharacteristic =
-      await accelerometerService.getCharacteristic(
-        profile.accelerometer.characteristics.data.id,
-      );
-    const accelerometerPeriodCharacteristic =
-      await accelerometerService.getCharacteristic(
-        profile.accelerometer.characteristics.period.id,
-      );
-    return new AccelerometerService(
-      accelerometerDataCharacteristic,
-      accelerometerPeriodCharacteristic,
-      dispatcher,
-      queueGattOperation,
-    );
+  getRelevantEvents(): TypedServiceEvent[] {
+    return ["accelerometerdatachanged"];
   }
 
   private dataViewToData(dataView: DataView): AccelerometerData {
@@ -75,15 +36,19 @@ export class AccelerometerService implements Service {
   }
 
   async getData(): Promise<AccelerometerData> {
-    const dataView = await this.queueGattOperation(() =>
-      this.accelerometerDataCharacteristic.readValue(),
+    const dataView = await BleClient.read(
+      this.deviceId,
+      profile.accelerometer.id,
+      profile.accelerometer.characteristics.data.id,
     );
     return this.dataViewToData(dataView);
   }
 
   async getPeriod(): Promise<number> {
-    const dataView = await this.queueGattOperation(() =>
-      this.accelerometerPeriodCharacteristic.readValue(),
+    const dataView = await BleClient.read(
+      this.deviceId,
+      profile.accelerometer.id,
+      profile.accelerometer.characteristics.period.id,
     );
     return dataView.getUint16(0, true);
   }
@@ -99,23 +64,66 @@ export class AccelerometerService implements Service {
     // 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),
+    await BleClient.write(
+      this.deviceId,
+      profile.accelerometer.id,
+      profile.accelerometer.characteristics.period.id,
+      dataView,
     );
   }
 
   async startNotifications(type: TypedServiceEvent): Promise<void> {
-    await this.characteristicForEvent(type)?.startNotifications();
+    const result = this.characteristicForEvent(type);
+    if (result) {
+      const { service, characteristic } = result;
+      try {
+        await BleClient.startNotifications(
+          this.deviceId,
+          service,
+          characteristic,
+          (value) => {
+            const data = this.dataViewToData(value);
+            this.dispatchTypedEvent(
+              "accelerometerdatachanged",
+              new AccelerometerDataEvent(data),
+            );
+          },
+        );
+      } catch (e) {
+        this.dispatchTypedEvent(
+          "backgrounderror",
+          new BackgroundErrorEvent("Failed to start notifications", e),
+        );
+      }
+    }
   }
 
   async stopNotifications(type: TypedServiceEvent): Promise<void> {
-    await this.characteristicForEvent(type)?.stopNotifications();
+    const result = this.characteristicForEvent(type);
+    if (result) {
+      const { service, characteristic } = result;
+      try {
+        await BleClient.stopNotifications(
+          this.deviceId,
+          service,
+          characteristic,
+        );
+      } catch (e) {
+        this.dispatchTypedEvent(
+          "backgrounderror",
+          new BackgroundErrorEvent("Failed to stop notifications", e),
+        );
+      }
+    }
   }
 
   private characteristicForEvent(type: TypedServiceEvent) {
     switch (type) {
       case "accelerometerdatachanged": {
-        return this.accelerometerDataCharacteristic;
+        return {
+          service: profile.accelerometer.id,
+          characteristic: profile.accelerometer.characteristics.data.id,
+        };
       }
       default: {
         return undefined;

lib/async-util.ts

@@ -5,6 +5,12 @@
  */
 export class TimeoutError extends Error {}
 
+export class DisconnectError extends Error {
+  constructor(message: string = "Disconnect") {
+    super(message);
+  }
+}
+
 /**
  * Utility to time out an action after a delay.
  *
@@ -14,11 +20,28 @@ export async function withTimeout<T>(
   actionPromise: Promise<T>,
   timeout: number,
 ): Promise<T> {
-  const timeoutPromise = new Promise((_, reject) => {
-    setTimeout(() => {
-      reject(new TimeoutError());
-    }, timeout);
+  return Promise.race([
+    actionPromise,
+    timeoutErrorAfter(timeout),
+  ]) as Promise<T>;
+}
+
+export async function delay(millis: number) {
+  return new Promise((resolve) => setTimeout(resolve, millis));
+}
+
+export async function timeoutErrorAfter<T>(
+  millis: number,
+  message: string = "Timeout",
+): Promise<T> {
+  await delay(millis);
+  throw new TimeoutError(message);
+}
+
+export function disconnectErrorCallback<T>(message: string = "Disconnect") {
+  let callback: () => void | undefined;
+  const promise = new Promise<T>((_, reject) => {
+    callback = () => reject(new DisconnectError(message));
   });
-  // timeoutPromise never resolves so result must be from action
-  return Promise.race([actionPromise, timeoutPromise]) as Promise<T>;
+  return { promise, callback: callback! };
 }