@microbit/microbit-connection 0.9.0-apps.alpha.9 → 1.0.0-beta.1

package/build/cjs/usb/connection.d.ts

@@ -0,0 +1,96 @@
+import { BackgroundErrorData, ConnectionStatusChange, DeviceConnection, FlashDataSource, FlashOptions } from "../device.js";
+import { Logging } from "../logging.js";
+import { type SerialData } from "./serial-events.js";
+export declare const DeviceSelectionMode: {
+    /**
+     * Attempts to connect to known device, otherwise asks which device to
+     * connect to.
+     */
+    readonly AlwaysAsk: "AlwaysAsk";
+    /**
+     * Attempts to connect to known device, otherwise attempts to connect to any
+     * allowed devices. If that fails, asks which device to connect to.
+     */
+    readonly UseAnyAllowed: "UseAnyAllowed";
+};
+export type DeviceSelectionMode = (typeof DeviceSelectionMode)[keyof typeof DeviceSelectionMode];
+export interface MicrobitUSBConnectionOptions {
+    /**
+     * Determines logging behaviour for events, errors, and logs.
+     */
+    logging?: Logging;
+    /**
+     * Determines how a device should be selected.
+     */
+    deviceSelectionMode?: DeviceSelectionMode;
+    /**
+     * Whether to automatically pause the USB connection when the browser tab
+     * becomes hidden and reconnect when it becomes visible again.
+     *
+     * When enabled, the connection transitions to PAUSED instead of staying
+     * connected while the tab is hidden. This frees the USB interface for
+     * other tabs or processes.
+     *
+     * @default true
+     */
+    pauseOnHidden?: boolean;
+}
+export interface MicrobitUSBConnection extends DeviceConnection {
+    readonly type: "usb";
+    addEventListener(type: "status", listener: (data: ConnectionStatusChange) => void): void;
+    addEventListener(type: "backgrounderror", listener: (data: BackgroundErrorData) => void): void;
+    addEventListener(type: "beforerequestdevice", listener: () => void): void;
+    addEventListener(type: "afterrequestdevice", listener: () => void): void;
+    addEventListener(type: "flash", listener: () => void): void;
+    addEventListener(type: "serialdata", listener: (data: SerialData) => void): void;
+    addEventListener(type: "serialreset", listener: () => void): void;
+    removeEventListener(type: "status", listener: (data: ConnectionStatusChange) => void): void;
+    removeEventListener(type: "backgrounderror", listener: (data: BackgroundErrorData) => void): void;
+    removeEventListener(type: "beforerequestdevice", listener: () => void): void;
+    removeEventListener(type: "afterrequestdevice", listener: () => void): void;
+    removeEventListener(type: "flash", listener: () => void): void;
+    removeEventListener(type: "serialdata", listener: (data: SerialData) => void): void;
+    removeEventListener(type: "serialreset", listener: () => void): void;
+    /**
+     * Write serial data to the device.
+     *
+     * @param data The data to write.
+     * @returns A promise that resolves when the write is complete.
+     * @throws {DeviceError} with code `not-connected` if there is no connection.
+     */
+    serialWrite(data: string): Promise<void>;
+    /**
+     * Gets micro:bit deviceId.
+     *
+     * Cached after the first successful connection until {@link clearDevice}
+     * is called, so remains available after disconnection.
+     *
+     * @returns the device id.
+     * @throws {DeviceError} with code `not-connected` if no device has been connected.
+     */
+    getDeviceId(): number;
+    /**
+     * Sets device request exclusion filters.
+     */
+    setRequestDeviceExclusionFilters(exclusionFilters: USBDeviceFilter[]): void;
+    flash(dataSource: FlashDataSource, options: FlashOptions): Promise<void>;
+    /**
+     * Gets micro:bit device.
+     *
+     * @returns the USB device or undefined if there is no connection.
+     */
+    getDevice(): USBDevice | undefined;
+    /**
+     * Resets the micro:bit in software.
+     */
+    softwareReset(): Promise<void>;
+}
+/**
+ * A WebUSB connection factory.
+ */
+export declare const createUSBConnection: (options?: MicrobitUSBConnectionOptions) => MicrobitUSBConnection;
+/**
+ * Applying WebUSB device filter. Exported for testing.
+ * Based on: https://wicg.github.io/webusb/#enumeration
+ */
+export declare const applyDeviceFilters: (device: USBDevice, filters: USBDeviceFilter[], exclusionFilters: USBDeviceFilter[]) => boolean;