Use TypeDocs to document API (#52)

Export a few missing types flagged by the docs generation. Some odd cases remain but not clear that exporting is the right plan.

Author: microbit-grace

.github/workflows/build-docs.yml

@@ -0,0 +1,39 @@
+name: build-docs
+on:
+  release:
+    types: [created]
+  push:
+    branches:
+      - "**"
+    tags:
+      - "**"
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - run: npm ci
+      - name: Build docs
+        run: npm run docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build
+
+  deploy:
+    if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -11,6 +11,7 @@ node_modules
 dist
 dist-ssr
 *.local
+docs
 
 # Editor directories and files
 .vscode/*

README.md

@@ -1,16 +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.
+[This documentation is best viewed on the documentation site rather than GitHub](https://microbit-foundation.github.io/microbit-connection/).
 
-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 unless they are happy to update usage as the API evolves.
+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.
 
-[micro:bit CreateAI](https://github.com/microbit-foundation/ml-trainer/) is already using this library for WebUSB and Web Bluetooth.
+## Usage
+
+### Flash a micro:bit
+
+Instantiate a WebUSB connection using {@link MicrobitWebUSBConnection} class and use it to connect to a micro:bit.
+
+```ts
+import { MicrobitWebUSBConnection } from "@microbit/microbit-connection";
+
+const usb = new MicrobitWebUSBConnection();
+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 MicrobitWebBluetoothConnection} class and use it to connect to a micro:bit.
+
+```ts
+import { MicrobitWebBluetoothConnection } from "@microbit/microbit-connection";
+
+const bluetooth = new MicrobitWebBluetoothConnection();
+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 MicrobitWebBluetoothConnection} 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
 
@@ -28,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

lib/bluetooth.ts

@@ -49,7 +49,7 @@ export class MicrobitWebBluetoothConnection
   private device: BluetoothDevice | undefined;
 
   private logging: Logging;
-  connection: BluetoothDeviceWrapper | undefined;
+  private connection: BluetoothDeviceWrapper | undefined;
 
   private availabilityListener = (e: Event) => {
     // TODO: is this called? is `value` correct?

lib/index.ts

@@ -1,9 +1,13 @@
 import { AccelerometerData, AccelerometerDataEvent } from "./accelerometer.js";
-import { MicrobitWebBluetoothConnection } from "./bluetooth.js";
+import {
+  MicrobitWebBluetoothConnection,
+  MicrobitWebBluetoothConnectionOptions,
+} from "./bluetooth.js";
 import { BoardId } from "./board-id.js";
 import { ButtonEvent, ButtonEventType, ButtonState } from "./buttons.js";
 import {
   AfterRequestDevice,
+  BackgroundErrorEvent,
   BeforeRequestDevice,
   BoardVersion,
   ConnectionStatus,
@@ -15,19 +19,30 @@ import {
   FlashDataError,
   FlashDataSource,
   FlashEvent,
+  FlashOptions,
   SerialDataEvent,
   SerialErrorEvent,
   SerialResetEvent,
 } from "./device.js";
 import { TypedEventTarget } from "./events.js";
 import { createUniversalHexFlashDataSource } from "./hex-flash-data-source.js";
+import { LedMatrix } from "./led.js";
+import { Logging, LoggingEvent } from "./logging.js";
 import { MagnetometerData, MagnetometerDataEvent } from "./magnetometer.js";
 import { ServiceConnectionEventMap } from "./service-events.js";
-import { MicrobitRadioBridgeConnection } from "./usb-radio-bridge.js";
-import { MicrobitWebUSBConnection } from "./usb.js";
+import { UARTDataEvent } from "./uart.js";
+import {
+  MicrobitRadioBridgeConnection,
+  MicrobitRadioBridgeConnectionOptions,
+} from "./usb-radio-bridge.js";
+import {
+  MicrobitWebUSBConnection,
+  MicrobitWebUSBConnectionOptions,
+} from "./usb.js";
 
 export {
   AfterRequestDevice,
+  BackgroundErrorEvent,
   BeforeRequestDevice,
   BoardId,
   ConnectionStatus,
@@ -45,6 +60,7 @@ export {
   SerialResetEvent,
   ServiceConnectionEventMap,
   TypedEventTarget,
+  UARTDataEvent,
 };
 
 export type {
@@ -57,6 +73,13 @@ export type {
   DeviceConnection,
   DeviceErrorCode,
   FlashDataSource,
+  FlashOptions,
+  LedMatrix,
+  Logging,
+  LoggingEvent,
   MagnetometerData,
   MagnetometerDataEvent,
+  MicrobitRadioBridgeConnectionOptions,
+  MicrobitWebBluetoothConnectionOptions,
+  MicrobitWebUSBConnectionOptions,
 };

lib/logging.ts

@@ -3,21 +3,21 @@
  *
  * SPDX-License-Identifier: MIT
  */
-export interface Event {
+export interface LoggingEvent {
   type: string;
   message?: string;
   value?: number;
   detail?: any;
 }
 
 export interface Logging {
-  event(event: Event): void;
+  event(event: LoggingEvent): void;
   error(message: string, e: unknown): void;
   log(e: any): void;
 }
 
 export class NullLogging implements Logging {
-  event(_event: Event): void {
+  event(_event: LoggingEvent): void {
     console.log(_event);
   }
   error(_m: string, _e: unknown): void {