@wodzik/cubecore 0.1.0

package/bluetooth/vendor/smartcube-web-bluetooth/gan-cube-encrypter.js

@@ -0,0 +1,70 @@
+import { ModeOfOperation } from 'aes-js';
+/**
+ * Implementation for encryption scheme used in the GAN Gen2 Smart Cubes
+ */
+class GanGen2CubeEncrypter {
+    _key;
+    _iv;
+    constructor(key, iv, salt) {
+        if (key.length != 16)
+            throw new Error("Key must be 16 bytes (128-bit) long");
+        if (iv.length != 16)
+            throw new Error("Iv must be 16 bytes (128-bit) long");
+        if (salt.length != 6)
+            throw new Error("Salt must be 6 bytes (48-bit) long");
+        // Apply salt to key and iv
+        this._key = new Uint8Array(key);
+        this._iv = new Uint8Array(iv);
+        for (let i = 0; i < 6; i++) {
+            this._key[i] = (key[i] + salt[i]) % 0xFF;
+            this._iv[i] = (iv[i] + salt[i]) % 0xFF;
+        }
+    }
+    /** Encrypt 16-byte buffer chunk starting at offset using AES-128-CBC */
+    encryptChunk(buffer, offset) {
+        var cipher = new ModeOfOperation.cbc(this._key, this._iv);
+        var chunk = cipher.encrypt(buffer.subarray(offset, offset + 16));
+        buffer.set(chunk, offset);
+    }
+    /** Decrypt 16-byte buffer chunk starting at offset using AES-128-CBC */
+    decryptChunk(buffer, offset) {
+        var cipher = new ModeOfOperation.cbc(this._key, this._iv);
+        var chunk = cipher.decrypt(buffer.subarray(offset, offset + 16));
+        buffer.set(chunk, offset);
+    }
+    encrypt(data) {
+        if (data.length < 16)
+            throw Error('Data must be at least 16 bytes long');
+        var res = new Uint8Array(data);
+        // encrypt 16-byte chunk aligned to message start
+        this.encryptChunk(res, 0);
+        // encrypt 16-byte chunk aligned to message end
+        if (res.length > 16) {
+            this.encryptChunk(res, res.length - 16);
+        }
+        return res;
+    }
+    decrypt(data) {
+        if (data.length < 16)
+            throw Error('Data must be at least 16 bytes long');
+        var res = new Uint8Array(data);
+        // decrypt 16-byte chunk aligned to message end
+        if (res.length > 16) {
+            this.decryptChunk(res, res.length - 16);
+        }
+        // decrypt 16-byte chunk aligned to message start
+        this.decryptChunk(res, 0);
+        return res;
+    }
+}
+/**
+ * Implementation for encryption scheme used in the GAN Gen3 cubes
+ */
+class GanGen3CubeEncrypter extends GanGen2CubeEncrypter {
+}
+/**
+ * Implementation for encryption scheme used in the GAN Gen3 cubes
+ */
+class GanGen4CubeEncrypter extends GanGen2CubeEncrypter {
+}
+export { GanGen2CubeEncrypter, GanGen3CubeEncrypter, GanGen4CubeEncrypter };

package/bluetooth/vendor/smartcube-web-bluetooth/gan-cube-protocol.d.ts

@@ -0,0 +1,273 @@
+/// <reference types="web-bluetooth" />
+import { GanCubeEncrypter } from './gan-cube-encrypter.js';
+import { Observable, Subject } from 'rxjs';
+/** Command for requesting information about GAN Smart Cube hardware  */
+type GanCubeReqHardwareCommand = {
+    type: "REQUEST_HARDWARE";
+};
+/** Command for requesting information about current facelets state  */
+type GanCubeReqFaceletsCommand = {
+    type: "REQUEST_FACELETS";
+};
+/** Command for requesting information about current battery level  */
+type GanCubeReqBatteryCommand = {
+    type: "REQUEST_BATTERY";
+};
+/** Command for resetting GAN Smart Cube internal facelets state to solved state */
+type GanCubeReqResetCommand = {
+    type: "REQUEST_RESET";
+};
+/** Command message */
+type GanCubeCommand = GanCubeReqHardwareCommand | GanCubeReqFaceletsCommand | GanCubeReqBatteryCommand | GanCubeReqResetCommand;
+/**
+ * Representation of GAN Smart Cube move
+ */
+type GanCubeMove = {
+    /** Face: 0 - U, 1 - R, 2 - F, 3 - D, 4 - L, 5 - B */
+    face: number;
+    /** Face direction: 0 - CW, 1 - CCW */
+    direction: number;
+    /** Cube move in common string notation, like R' or U */
+    move: string;
+    /** Timestamp according to host device clock, null in case if bluetooth event was missed and recovered */
+    localTimestamp: number | null;
+    /** Timestamp according to cube internal clock, for some cube models may be null in case if bluetooth event was missed and recovered */
+    cubeTimestamp: number | null;
+};
+/**
+ * Move event
+ */
+type GanCubeMoveEvent = {
+    type: "MOVE";
+    /** Serial number, value range 0-255, increased in a circle on each facelets state change */
+    serial: number;
+} & GanCubeMove;
+/**
+ * Representation of GAN Smart Cube facelets state
+ */
+type GanCubeState = {
+    /** Corner Permutation: 8 elements, values from 0 to 7 */
+    CP: Array<number>;
+    /** Corner Orientation: 8 elements, values from 0 to 2 */
+    CO: Array<number>;
+    /** Edge Permutation: 12 elements, values from 0 to 11 */
+    EP: Array<number>;
+    /** Edge Orientation: 12 elements, values from 0 to 1 */
+    EO: Array<number>;
+};
+/**
+ * Facelets event
+ */
+type GanCubeFaceletsEvent = {
+    type: "FACELETS";
+    /** Serial number, value range 0-255, increased in a circle on each facelets state change */
+    serial: number;
+    /** Cube facelets state in the Kociemba notation like "UUUUUUUUURRRRRRRRRFFFFFFFFFDDDDDDDDDLLLLLLLLLBBBBBBBBB" */
+    facelets: string;
+    /** Cube state representing corners and edges orientation and permutation */
+    state: GanCubeState;
+};
+/**
+ * Quaternion to represent orientation
+ */
+type GanCubeOrientationQuaternion = {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+};
+/**
+ * Representation of angular velocity by axes
+ */
+type GanCubeAngularVelocity = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Gyroscope event
+ */
+type GanCubeGyroEvent = {
+    type: "GYRO";
+    /** Cube orientation quaternion, uses Right-Handed coordinate system, +X - Red, +Y - Blue, +Z - White */
+    quaternion: GanCubeOrientationQuaternion;
+    /** Cube angular velocity over current ODR time frame */
+    velocity?: GanCubeAngularVelocity;
+};
+/**
+ * Battery event
+ */
+type GanCubeBatteryEvent = {
+    type: "BATTERY";
+    /** Current battery level in percent */
+    batteryLevel: number;
+};
+/**
+ * Hardware event
+ */
+type GanCubeHardwareEvent = {
+    type: "HARDWARE";
+    /** Internal cube hardware device model name */
+    hardwareName?: string;
+    /** Software/Firmware version of the cube */
+    softwareVersion?: string;
+    /** Hardware version of the cube */
+    hardwareVersion?: string;
+    /** Production Date of the cube */
+    productDate?: string;
+    /** Is gyroscope supported by this cube model */
+    gyroSupported?: boolean;
+};
+/**
+ * Disconnect event
+ */
+type GanCubeDisconnectEvent = {
+    type: "DISCONNECT";
+};
+/** All possible event message types */
+type GanCubeEventMessage = GanCubeMoveEvent | GanCubeFaceletsEvent | GanCubeGyroEvent | GanCubeBatteryEvent | GanCubeHardwareEvent | GanCubeDisconnectEvent;
+/** Cube event / response to command */
+type GanCubeEvent = {
+    timestamp: number;
+} & GanCubeEventMessage;
+/** Extention to the BluetoothDevice for storing and accessing device MAC address */
+interface BluetoothDeviceWithMAC extends BluetoothDevice {
+    mac?: string;
+}
+/**
+ * Connection object representing connection API and state
+ */
+interface GanCubeConnection {
+    /** Connected Bluetooth cube device name */
+    readonly deviceName: string;
+    /** Connected Bluetoooth cube device MAC address */
+    readonly deviceMAC: string;
+    /** RxJS Subject to subscribe for cube event messages */
+    events$: Observable<GanCubeEvent>;
+    /** Method to send command to the cube */
+    sendCubeCommand(command: GanCubeCommand): Promise<void>;
+    /** Close this connection */
+    disconnect(): Promise<void>;
+}
+/** Raw connection interface for internal use */
+interface GanCubeRawConnection {
+    sendCommandMessage(message: Uint8Array): Promise<void>;
+    disconnect(): Promise<void>;
+}
+/** Protocol Driver interface */
+interface GanProtocolDriver {
+    /** Create binary command message for cube device */
+    createCommandMessage(command: GanCubeCommand): Uint8Array | undefined;
+    /** Handle binary event messages from cube device */
+    handleStateEvent(conn: GanCubeRawConnection, eventMessage: Uint8Array): Promise<GanCubeEvent[]>;
+}
+/** Optional hooks for {@link GanCubeClassicConnection.create}. */
+export type GanClassicConnectionOptions = {
+    /** If set, decrypted payloads that fail this check are dropped (wrong MAC / noise). */
+    validateDecrypted?: (plaintext: Uint8Array) => boolean;
+};
+/**
+ * Implementation of classic command/response connection with GAN Smart Cube device
+ */
+declare class GanCubeClassicConnection implements GanCubeConnection, GanCubeRawConnection {
+    device: BluetoothDeviceWithMAC;
+    commandCharacteristic: BluetoothRemoteGATTCharacteristic;
+    stateCharacteristic: BluetoothRemoteGATTCharacteristic;
+    encrypter: GanCubeEncrypter;
+    driver: GanProtocolDriver;
+    events$: Subject<GanCubeEvent>;
+    private readonly validateDecrypted?;
+    private readonly writeQueue;
+    private disconnectOnce;
+    private constructor();
+    static create(device: BluetoothDeviceWithMAC, commandCharacteristic: BluetoothRemoteGATTCharacteristic, stateCharacteristic: BluetoothRemoteGATTCharacteristic, encrypter: GanCubeEncrypter, driver: GanProtocolDriver, options?: GanClassicConnectionOptions): Promise<GanCubeConnection>;
+    get deviceName(): string;
+    get deviceMAC(): string;
+    sendCommandMessage(message: Uint8Array): Promise<void>;
+    onStateUpdate: (evt: Event) => Promise<void>;
+    onDisconnect: () => Promise<void>;
+    sendCubeCommand(command: GanCubeCommand): Promise<void>;
+    disconnect(): Promise<void>;
+}
+/**
+ * Driver implementation for GAN Gen2 protocol, supported cubes:
+ *  - GAN Mini ui FreePlay
+ *  - GAN12 ui FreePlay
+ *  - GAN12 ui
+ *  - GAN356 i Carry S
+ *  - GAN356 i Carry
+ *  - GAN356 i 3
+ *  - Monster Go 3Ai
+ */
+declare class GanGen2ProtocolDriver implements GanProtocolDriver {
+    private lastSerial;
+    private lastMoveTimestamp;
+    private cubeTimestamp;
+    createCommandMessage(command: GanCubeCommand): Uint8Array | undefined;
+    handleStateEvent(conn: GanCubeRawConnection, eventMessage: Uint8Array): Promise<GanCubeEvent[]>;
+}
+/**
+ * Driver implementation for GAN Gen3 protocol, supported cubes:
+ *  - GAN356 i Carry 2
+ */
+declare class GanGen3ProtocolDriver implements GanProtocolDriver {
+    private serial;
+    private lastSerial;
+    private lastLocalTimestamp;
+    private moveBuffer;
+    createCommandMessage(command: GanCubeCommand): Uint8Array | undefined;
+    /** Private cube command for requesting move history */
+    private requestMoveHistory;
+    /**
+     * Evict move events from FIFO buffer until missing move event detected
+     * In case of missing move, and if connection is provided, submit request for move history to fill gap in buffer
+     */
+    private evictMoveBuffer;
+    /**
+     * Check if circular serial number (modulo 256) fits into (start,end) serial number range.
+     * By default range is open, set closedStart / closedEnd to make it closed.
+     */
+    private isSerialInRange;
+    /** Used to inject missed moves to FIFO buffer */
+    private injectMissedMoveToBuffer;
+    /** Used in response to periodic facelets event to check if any moves missed */
+    private checkIfMoveMissed;
+    handleStateEvent(conn: GanCubeRawConnection, eventMessage: Uint8Array): Promise<GanCubeEvent[]>;
+}
+/**
+ * Driver implementation for GAN Gen4 protocol, supported cubes:
+ *  - GAN12 ui Maglev
+ *  - GAN14 ui FreePlay
+ */
+declare class GanGen4ProtocolDriver implements GanProtocolDriver {
+    private serial;
+    private lastSerial;
+    private lastLocalTimestamp;
+    private moveBuffer;
+    private hwInfo;
+    /** Set when we have seen at least one 0xEC GYRO packet this connection (not cleared on REQUEST_HARDWARE). */
+    private gyroObserved;
+    /** Set when a full HARDWARE snapshot was emitted for the current hwInfo assembly; reset when REQUEST_HARDWARE clears hwInfo. */
+    private hardwareInfoEmitted;
+    createCommandMessage(command: GanCubeCommand): Uint8Array | undefined;
+    private buildHardwareEvent;
+    /** Private cube command for requesting move history */
+    private requestMoveHistory;
+    /**
+     * Evict move events from FIFO buffer until missing move event detected
+     * In case of missing move, and if connection is provided, submit request for move history to fill gap in buffer
+     */
+    private evictMoveBuffer;
+    /**
+     * Check if circular serial number (modulo 256) fits into (start,end) serial number range.
+     * By default range is open, set closedStart / closedEnd to make it closed.
+     */
+    private isSerialInRange;
+    /** Used to inject missed moves to FIFO buffer */
+    private injectMissedMoveToBuffer;
+    /** Used in response to periodic facelets event to check if any moves missed */
+    private checkIfMoveMissed;
+    handleStateEvent(conn: GanCubeRawConnection, eventMessage: Uint8Array): Promise<GanCubeEvent[]>;
+}
+export type { BluetoothDeviceWithMAC, GanCubeConnection, GanCubeEvent, GanCubeCommand, GanCubeMove, GanProtocolDriver };
+export { GanCubeClassicConnection, GanGen2ProtocolDriver, GanGen3ProtocolDriver, GanGen4ProtocolDriver };