WIP flashing integration - use the existing wrapper not Device

Remains to fix the conflicting ideas about connection/disconnection, status updates etc.

Author: microbit-matt-hillsdon

lib/bluetooth-device-wrapper.ts

@@ -4,7 +4,11 @@
  * SPDX-License-Identifier: MIT
  */
 
-import { BleClient, BleDevice } from "@capacitor-community/bluetooth-le";
+import {
+  BleClient,
+  BleDevice,
+  TimeoutOptions,
+} from "@capacitor-community/bluetooth-le";
 import { AccelerometerService } from "./accelerometer-service.js";
 import { ButtonService } from "./button-service.js";
 import { BoardVersion } from "./device.js";
@@ -19,6 +23,23 @@ import {
 import { UARTService } from "./uart-service.js";
 import { DeviceInformationService } from "./device-information-service.js";
 
+const disconnectSymbol: unique symbol = Symbol("disconnected");
+const timeoutSymbol: unique symbol = Symbol("timeout");
+
+export class BluetoothError extends Error {}
+
+export class TimeoutError extends BluetoothError {
+  constructor() {
+    super("Timeout");
+  }
+}
+
+export class DisconnectError extends BluetoothError {
+  constructor() {
+    super("Disconnect");
+  }
+}
+
 const deviceIdToWrapper: Map<string, BluetoothDeviceWrapper> = new Map();
 
 const connectTimeoutDuration: number = 10000;
@@ -113,6 +134,25 @@ export class BluetoothDeviceWrapper {
     ];
   }
 
+  // TODO: this is the Device connect method
+  async connect(tag: string) {
+    this.tag = tag;
+    let onDisconnect: (() => void) | undefined;
+    const promise = new Promise<typeof disconnectSymbol>((resolve) => {
+      onDisconnect = () => {
+        this.log("Disconnected");
+        this.internalNotificationListeners = new Map();
+        resolve(disconnectSymbol);
+      };
+    });
+    this.disconnectTracker = { promise, onDisconnect: onDisconnect! };
+    this.log("Connecting");
+    await BleClient.connect(this.device.deviceId, onDisconnect, {
+      timeout: connectTimeoutInMs,
+    });
+    this.log("Connected");
+  }
+
   async connect(): Promise<void> {
     this.logging.event({
       type: this.isReconnect ? "Reconnect" : "Connect",
@@ -322,6 +362,184 @@ export class BluetoothDeviceWrapper {
       .find((s) => s.getRelevantEvents().includes(type))
       ?.stopNotifications(type);
   }
+
+  // Added for flashing
+
+  private tag: string | undefined;
+  disconnectTracker:
+    | { promise: Promise<typeof disconnectSymbol>; onDisconnect: () => void }
+    | undefined;
+  private internalNotificationListeners = new Map<
+    string,
+    Set<(data: Uint8Array) => void>
+  >();
+
+  async startInternalNotifications(
+    serviceId: string,
+    characteristicId: string,
+    options?: TimeoutOptions,
+  ): Promise<void> {
+    const key = this.getNotificationKey(serviceId, characteristicId);
+    await this.raceDisconnectAndTimeout(
+      BleClient.startNotifications(
+        this.device.deviceId,
+        serviceId,
+        characteristicId,
+        (value: DataView) => {
+          const bytes = new Uint8Array(value.buffer);
+          // Notify all registered callbacks.
+          this.internalNotificationListeners
+            .get(key)
+            ?.forEach((cb) => cb(bytes));
+        },
+        options,
+      ),
+      { actionName: "start notifications" },
+    );
+  }
+
+  subscribe(
+    serviceId: string,
+    characteristicId: string,
+    callback: (data: Uint8Array) => void,
+  ): void {
+    const key = this.getNotificationKey(serviceId, characteristicId);
+    if (!this.internalNotificationListeners.has(key)) {
+      this.internalNotificationListeners.set(key, new Set());
+    }
+    this.internalNotificationListeners.get(key)!.add(callback);
+  }
+
+  unsubscribe(
+    serviceId: string,
+    characteristicId: string,
+    callback: (data: Uint8Array) => void,
+  ): void {
+    const key = this.getNotificationKey(serviceId, characteristicId);
+    this.internalNotificationListeners.get(key)?.delete(callback);
+  }
+
+  async stopInternalNotifications(
+    serviceId: string,
+    characteristicId: string,
+  ): Promise<void> {
+    await BleClient.stopNotifications(
+      this.device.deviceId,
+      serviceId,
+      characteristicId,
+    );
+    const key = this.getNotificationKey(serviceId, characteristicId);
+    this.internalNotificationListeners.delete(key);
+  }
+
+  /**
+   * Write to characteristic and wait for a notification response.
+   *
+   * It is the responsibility of the caller to have started notifications
+   * for the characteristic.
+   */
+  async writeForNotification(
+    serviceId: string,
+    characteristicId: string,
+    value: DataView,
+    notificationId: number,
+    isFinalNotification: (p: Uint8Array) => boolean = () => true,
+  ): Promise<Uint8Array> {
+    let notificationListener: ((bytes: Uint8Array) => void) | undefined;
+    const notificationPromise = new Promise<Uint8Array>((resolve) => {
+      notificationListener = (bytes: Uint8Array) => {
+        if (bytes[0] === notificationId && isFinalNotification(bytes)) {
+          resolve(bytes);
+        }
+      };
+      this.subscribe(serviceId, characteristicId, notificationListener);
+    });
+
+    try {
+      await BleClient.writeWithoutResponse(
+        this.device.deviceId,
+        serviceId,
+        characteristicId,
+        value,
+      );
+      return await this.raceDisconnectAndTimeout(notificationPromise, {
+        timeout: 3_000,
+        actionName: "flash notification wait",
+      });
+    } finally {
+      if (notificationListener) {
+        this.unsubscribe(serviceId, characteristicId, notificationListener);
+      }
+    }
+  }
+
+  async waitForDisconnect(timeout: number): Promise<void> {
+    if (!this.disconnectTracker) {
+      this.log("Waiting for disconnect but not connected");
+      return;
+    }
+    this.log(`Waiting for disconnect (timeout ${timeout})`);
+    const result = await Promise.race([
+      this.disconnectTracker.promise,
+      this.timeoutPromise(timeout),
+    ]);
+    if (result === timeoutSymbol) {
+      this.log("Timeout waiting for disconnect");
+      throw new TimeoutError();
+    }
+  }
+
+  /**
+   * Suitable for running a series of BLE interactions with an overall timeout
+   * and general disconnection
+   */
+  async raceDisconnectAndTimeout<T>(
+    promise: Promise<T>,
+    options: {
+      actionName?: string;
+      timeout?: number;
+    } = {},
+  ): Promise<T> {
+    if (!this.disconnectTracker) {
+      throw new DisconnectError();
+    }
+    const actionName = options.actionName ?? "action";
+    const result = await Promise.race([
+      promise,
+      this.disconnectTracker.promise,
+      ...(options.timeout ? [this.timeoutPromise(options.timeout)] : []),
+    ]);
+    if (result === timeoutSymbol) {
+      this.log(`Timeout during ${actionName}`);
+      throw new TimeoutError();
+    }
+    if (result === disconnectSymbol) {
+      this.log(`Disconnected during ${actionName}`);
+      throw new DisconnectError();
+    }
+    return result;
+  }
+
+  private timeoutPromise(timeout: number): Promise<typeof timeoutSymbol> {
+    return new Promise((resolve) =>
+      setTimeout(() => resolve(timeoutSymbol), timeout),
+    );
+  }
+
+  log(message: string) {
+    console.log(`[${this.tag}] ${message}`);
+  }
+
+  error(e: unknown) {
+    console.error(e);
+  }
+
+  private getNotificationKey(
+    serviceId: string,
+    characteristicId: string,
+  ): string {
+    return `${serviceId}:${characteristicId}`;
+  }
 }
 
 export const createBluetoothDeviceWrapper = async (

lib/bluetooth-profile.ts

@@ -1,27 +1,28 @@
-// Very incomplete BT profile
 export const profile = {
-  uart: {
-    id: "6e400001-b5a3-f393-e0a9-e50e24dcca9e",
-    characteristics: {
-      tx: { id: "6e400002-b5a3-f393-e0a9-e50e24dcca9e" },
-      rx: { id: "6e400003-b5a3-f393-e0a9-e50e24dcca9e" },
-    },
-  },
+  // Alphabetised
   accelerometer: {
     id: "e95d0753-251d-470a-a062-fa1922dfa9a8",
     characteristics: {
       data: { id: "e95dca4b-251d-470a-a062-fa1922dfa9a8" },
       period: { id: "e95dfb24-251d-470a-a062-fa1922dfa9a8" },
     },
   },
+  button: {
+    id: "e95d9882-251d-470a-a062-fa1922dfa9a8",
+    characteristics: {
+      a: { id: "e95dda90-251d-470a-a062-fa1922dfa9a8" },
+      b: { id: "e95dda91-251d-470a-a062-fa1922dfa9a8" },
+    },
+  },
+
   deviceInformation: {
     id: "0000180a-0000-1000-8000-00805f9b34fb",
     characteristics: {
-      modelNumber: { id: "00002a24-0000-1000-8000-00805f9b34fb" },
-      serialNumber: { id: "00002a25-0000-1000-8000-00805f9b34fb" },
       firmwareRevision: { id: "00002a26-0000-1000-8000-00805f9b34fb" },
       hardwareRevision: { id: "00002a27-0000-1000-8000-00805f9b34fb" },
       manufacturer: { id: "00002a29-0000-1000-8000-00805f9b34fb" },
+      modelNumber: { id: "00002a24-0000-1000-8000-00805f9b34fb" },
+      serialNumber: { id: "00002a25-0000-1000-8000-00805f9b34fb" },
     },
   },
   dfuControl: {
@@ -30,37 +31,30 @@ export const profile = {
       control: { id: "e95d93b1-251d-470a-a062-fa1922dfa9a8" },
     },
   },
-  led: {
-    id: "e95dd91d-251d-470a-a062-fa1922dfa9a8",
+  event: {
+    id: "e95d93af-251d-470a-a062-fa1922dfa9a8",
     characteristics: {
-      matrixState: { id: "e95d7b77-251d-470a-a062-fa1922dfa9a8" },
-      text: { id: "e95d93ee-251d-470a-a062-fa1922dfa9a8" },
-      scrollingDelay: { id: "e95d0d2d-251d-470a-a062-fa1922dfa9a8" },
+      clientEvent: { id: "e95d5404-251d-470a-a062-fa1922dfa9a8" },
+      clientRequirements: { id: "e95d23c4-251d-470a-a062-fa1922dfa9a8" },
+      microBitEvent: { id: "e95d9775-251d-470a-a062-fa1922dfa9a8" },
+      microBitRequirements: { id: "e95db84c-251d-470a-a062-fa1922dfa9a8" },
     },
   },
   ioPin: {
     id: "e95d127b-251d-470a-a062-fa1922dfa9a8",
     characteristics: {
-      pinData: { id: "e95d8d00-251d-470a-a062-fa1922dfa9a8" },
       pinAdConfiguration: { id: "e95d5899-251d-470a-a062-fa1922dfa9a8" },
+      pinData: { id: "e95d8d00-251d-470a-a062-fa1922dfa9a8" },
       pinIoConfiguration: { id: "e95db9fe-251d-470a-a062-fa1922dfa9a8" },
       pwmControl: { id: "e95dd822-251d-470a-a062-fa1922dfa9a8" },
     },
   },
-  button: {
-    id: "e95d9882-251d-470a-a062-fa1922dfa9a8",
-    characteristics: {
-      a: { id: "e95dda90-251d-470a-a062-fa1922dfa9a8" },
-      b: { id: "e95dda91-251d-470a-a062-fa1922dfa9a8" },
-    },
-  },
-  event: {
-    id: "e95d93af-251d-470a-a062-fa1922dfa9a8",
+  led: {
+    id: "e95dd91d-251d-470a-a062-fa1922dfa9a8",
     characteristics: {
-      microBitRequirements: { id: "e95db84c-251d-470a-a062-fa1922dfa9a8" },
-      microBitEvent: { id: "e95d9775-251d-470a-a062-fa1922dfa9a8" },
-      clientRequirements: { id: "e95d23c4-251d-470a-a062-fa1922dfa9a8" },
-      clientEvent: { id: "e95d5404-251d-470a-a062-fa1922dfa9a8" },
+      matrixState: { id: "e95d7b77-251d-470a-a062-fa1922dfa9a8" },
+      scrollingDelay: { id: "e95d0d2d-251d-470a-a062-fa1922dfa9a8" },
+      text: { id: "e95d93ee-251d-470a-a062-fa1922dfa9a8" },
     },
   },
   magnetometer: {
@@ -72,11 +66,24 @@ export const profile = {
       calibration: { id: "e95db358-251d-470a-a062-fa1922dfa9a8" },
     },
   },
+  partialFlashing: {
+    id: "e97dd91d-251d-470a-a062-fa1922dfa9a8",
+    characteristics: {
+      partialFlash: { id: "e97d3b10-251d-470a-a062-fa1922dfa9a8" },
+    },
+  },
   temperature: {
     id: "e95d6100-251d-470a-a062-fa1922dfa9a8",
     characteristics: {
       data: { id: "e95d9250-251d-470a-a062-fa1922dfa9a8" },
       period: { id: "e95d1b25-251d-470a-a062-fa1922dfa9a8" },
     },
   },
+  uart: {
+    id: "6e400001-b5a3-f393-e0a9-e50e24dcca9e",
+    characteristics: {
+      rx: { id: "6e400003-b5a3-f393-e0a9-e50e24dcca9e" },
+      tx: { id: "6e400002-b5a3-f393-e0a9-e50e24dcca9e" },
+    },
+  },
 };