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

package/build/cjs/usb-serial-protocol.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * (c) 2024, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRandomRadioFrequency = exports.generateCmdRemoteMbId = exports.generateCmdRadioFrequency = exports.generateCmdStop = exports.generateCmdStart = exports.generateCmdHandshake = exports.processPeriodicMessage = exports.processResponseMessage = exports.splitMessages = exports.version = exports.ResponseTypes = exports.CommandTypes = void 0;
+var MessageTypes;
+(function (MessageTypes) {
+    MessageTypes["Command"] = "C";
+    MessageTypes["Response"] = "R";
+    MessageTypes["Periodic"] = "P";
+})(MessageTypes || (MessageTypes = {}));
+var CommandTypes;
+(function (CommandTypes) {
+    CommandTypes["Handshake"] = "HS";
+    CommandTypes["RadioFrequency"] = "RF";
+    CommandTypes["RemoteMbId"] = "RMBID";
+    CommandTypes["SoftwareVersion"] = "SWVER";
+    CommandTypes["HardwareVersion"] = "HWVER";
+    CommandTypes["Zstart"] = "ZSTART";
+    CommandTypes["Stop"] = "STOP";
+})(CommandTypes || (exports.CommandTypes = CommandTypes = {}));
+var ResponseExtraTypes;
+(function (ResponseExtraTypes) {
+    ResponseExtraTypes["Error"] = "ERROR";
+})(ResponseExtraTypes || (ResponseExtraTypes = {}));
+exports.ResponseTypes = { ...CommandTypes, ...ResponseExtraTypes };
+// Currently implemented protocol version
+exports.version = 1;
+const splitMessages = (message) => {
+    if (!message) {
+        return {
+            messages: [],
+            remainingInput: "",
+        };
+    }
+    let messages = message.split("\n");
+    let remainingInput = messages.pop() || "";
+    // Throw away any empty messages and messages that don't start with a valid type
+    messages = messages.filter((msg) => msg.length > 0 &&
+        Object.values(MessageTypes).includes(msg[0]));
+    // Any remaining input will be the start of the next message, so if it doesn't start
+    // with a valid type throw it away as it'll be prepended to the next serial string
+    if (remainingInput.length > 0 &&
+        !Object.values(MessageTypes).includes(remainingInput[0])) {
+        remainingInput = "";
+    }
+    return {
+        messages,
+        remainingInput,
+    };
+};
+exports.splitMessages = splitMessages;
+const processResponseMessage = (message) => {
+    // Regex for a message response with 3 groups:
+    // id    -> The message ID, 1-8 hex characters
+    // cmd   -> The command type, a string, only capital letters, matching CommandTypes
+    // value -> The response value, empty string or a word, number,
+    //          or version (e.g 1.2.3) depending on the command type
+    const responseMatch = /^R\[(?<id>[0-9A-Fa-f]{1,8})\](?<cmd>[A-Z]+)\[(?<value>-?[\w.]*)\]$/.exec(message);
+    if (!responseMatch || !responseMatch.groups) {
+        return undefined;
+    }
+    const messageId = parseInt(responseMatch.groups["id"], 16);
+    if (isNaN(messageId)) {
+        return undefined;
+    }
+    const responseType = responseMatch.groups["cmd"];
+    if (!Object.values(exports.ResponseTypes).includes(responseType)) {
+        return undefined;
+    }
+    let value = responseMatch.groups["value"];
+    switch (responseType) {
+        // Commands with numeric values
+        case exports.ResponseTypes.Handshake:
+        case exports.ResponseTypes.RadioFrequency:
+        case exports.ResponseTypes.RemoteMbId:
+        case exports.ResponseTypes.HardwareVersion:
+        case exports.ResponseTypes.Error:
+            value = Number(value);
+            if (isNaN(value) || value < 0 || value > 0xffffffff) {
+                return undefined;
+            }
+            break;
+        // Commands without values
+        case exports.ResponseTypes.Zstart:
+        case exports.ResponseTypes.Stop:
+            if (value !== "") {
+                return undefined;
+            }
+            break;
+        // Semver-ish values (valid range 00.00.00 to 99.99.99)
+        case exports.ResponseTypes.SoftwareVersion:
+            if (!/^[0-9]{1,2}\.[0-9]{1,2}\.[0-9]{1,2}$/.test(value)) {
+                return undefined;
+            }
+            break;
+    }
+    return {
+        message,
+        messageId,
+        type: responseType,
+        value,
+    };
+};
+exports.processResponseMessage = processResponseMessage;
+const processPeriodicMessage = (message) => {
+    // Basic checks to match the message being a compact periodic message
+    if (message.length !== 13 || message[0] !== MessageTypes.Periodic) {
+        return undefined;
+    }
+    // All characters except the first one should be hex
+    if (!/^[0-9A-Fa-f]+$/.test(message.substring(1))) {
+        return undefined;
+    }
+    // Only the two Least Significant Bits from the buttons are used
+    const buttons = parseInt(message[12], 16);
+    if (buttons > 3) {
+        return undefined;
+    }
+    return {
+        // The accelerometer data has been clamped to -2048 to 2047, and an offset
+        // added to make the values positive, so that needs to be reversed
+        accelerometerX: parseInt(message.substring(3, 6), 16) - 2048,
+        accelerometerY: parseInt(message.substring(6, 9), 16) - 2048,
+        accelerometerZ: parseInt(message.substring(9, 12), 16) - 2048,
+        // Button A is the LSB, button B is the next bit
+        buttonA: buttons & 1,
+        buttonB: (buttons >> 1) & 1,
+    };
+};
+exports.processPeriodicMessage = processPeriodicMessage;
+const generateCommand = (cmdType, cmdData = "") => {
+    // Generate an random (enough) ID with max value of 8 hex digits
+    const msgID = Math.floor(Math.random() * 0xffffffff);
+    return {
+        message: `C[${msgID.toString(16).toUpperCase()}]${cmdType}[${cmdData}]\n`,
+        messageId: msgID,
+        type: cmdType,
+        value: cmdData,
+    };
+};
+const generateCmdHandshake = () => {
+    return generateCommand(CommandTypes.Handshake);
+};
+exports.generateCmdHandshake = generateCmdHandshake;
+const generateCmdStart = (sensors) => {
+    let cmdData = "";
+    if (sensors.accelerometer) {
+        cmdData += "A";
+    }
+    if (sensors.buttons) {
+        cmdData += "B";
+    }
+    return generateCommand(CommandTypes.Zstart, cmdData);
+};
+exports.generateCmdStart = generateCmdStart;
+const generateCmdStop = () => {
+    return generateCommand(CommandTypes.Stop);
+};
+exports.generateCmdStop = generateCmdStop;
+const generateCmdRadioFrequency = (frequency) => {
+    if (frequency < 0 || frequency > 83) {
+        throw new Error("Radio frequency out of range");
+    }
+    return generateCommand(CommandTypes.RadioFrequency, frequency.toString());
+};
+exports.generateCmdRadioFrequency = generateCmdRadioFrequency;
+const generateCmdRemoteMbId = (remoteMicrobitId) => {
+    if (remoteMicrobitId < 0 || remoteMicrobitId > 0xffffffff) {
+        throw new Error("Remote micro:bit ID out of range");
+    }
+    return generateCommand(CommandTypes.RemoteMbId, remoteMicrobitId.toString());
+};
+exports.generateCmdRemoteMbId = generateCmdRemoteMbId;
+const generateRandomRadioFrequency = () => {
+    // The value range for radio frequencies is 0 to 83
+    return Math.floor(Math.random() * 84);
+};
+exports.generateRandomRadioFrequency = generateRandomRadioFrequency;
+//# sourceMappingURL=usb-serial-protocol.js.map

package/build/cjs/usb-serial-protocol.js.map

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

package/build/cjs/usb.d.ts

@@ -0,0 +1,64 @@
+import { DeviceConnection, FlashDataSource } from "./device.js";
+import { Logging } from "./logging.js";
+import { SerialConnectionEventMap } from "./serial-events.js";
+export declare const isChromeOS105: () => boolean;
+export declare enum DeviceSelectionMode {
+    /**
+     * Attempts to connect to known device, otherwise asks which device to
+     * connect to.
+     */
+    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.
+     */
+    UseAnyAllowed = "UseAnyAllowed"
+}
+export interface MicrobitWebUSBConnectionOptions {
+    /**
+     * Determines logging behaviour for events, errors, and logs.
+     */
+    logging?: Logging;
+    /**
+     * Determines how a device should be selected.
+     */
+    deviceSelectionMode?: DeviceSelectionMode;
+}
+export interface MicrobitWebUSBConnection extends DeviceConnection<SerialConnectionEventMap> {
+    /**
+     * Gets micro:bit deviceId.
+     *
+     * @returns the device id or undefined if there is no connection.
+     */
+    getDeviceId(): number | undefined;
+    /**
+     * Sets device request exclusion filters.
+     */
+    setRequestDeviceExclusionFilters(exclusionFilters: USBDeviceFilter[]): void;
+    /**
+     * Flash the micro:bit.
+     *
+     * @param dataSource The data to use.
+     * @param options Flash options and progress callback.
+     */
+    flash(dataSource: FlashDataSource, options: {}): 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 createWebUSBConnection: (options?: MicrobitWebUSBConnectionOptions) => MicrobitWebUSBConnection;
+/**
+ * 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;