@hangtime/grip-connect 0.5.0 → 0.5.2

package/dist/models/device.model.js

@@ -11,13 +11,71 @@ export class Device extends BaseModel {
         this.bluetooth = device.bluetooth;
     }
     /**
-     * Handles the 'disconnected' event.
-     * @param {Event} event - The 'disconnected' event.
+     * Connects to a Bluetooth device.
+     * @param {Function} [onSuccess] - Optional callback function to execute on successful connection. Default logs success.
+     * @param {Function} [onError] - Optional callback function to execute on error. Default logs the error.
      */
-    onDisconnected = (event) => {
-        this.bluetooth = undefined;
-        const device = event.target;
-        throw new Error(`Device ${device.name} is disconnected.`);
+    connect = async (onSuccess = () => console.log("Connected successfully"), onError = (error) => console.error(error)) => {
+        try {
+            // Request device and set up connection
+            const deviceServices = this.getAllServiceUUIDs();
+            this.bluetooth = await navigator.bluetooth.requestDevice({
+                filters: this.filters,
+                optionalServices: deviceServices,
+            });
+            if (!this.bluetooth.gatt) {
+                throw new Error("GATT is not available on this device");
+            }
+            this.bluetooth.addEventListener("gattserverdisconnected", (event) => {
+                this.onDisconnected(event);
+            });
+            server = await this.bluetooth.gatt.connect();
+            if (server.connected) {
+                await this.onConnected(onSuccess);
+            }
+        }
+        catch (error) {
+            onError(error);
+        }
+    };
+    /**
+     * Disconnects the device if it is currently connected.
+     * - Checks if the device is connected via it's GATT server.
+     * - If the device is connected, it attempts to gracefully disconnect.
+     */
+    disconnect = () => {
+        // Verify that the device is connected using the provided helper function
+        if (this.isConnected()) {
+            // Safely attempt to disconnect the device's GATT server, if available
+            this.bluetooth?.gatt?.disconnect();
+        }
+    };
+    /**
+     * Returns UUIDs of all services associated with the device.
+     * @returns {string[]} Array of service UUIDs.
+     */
+    getAllServiceUUIDs = () => {
+        return this.services.map((service) => service.uuid);
+    };
+    /**
+     * Retrieves the characteristic from the device's service.
+     * @param {string} serviceId - The UUID of the service.
+     * @param {string} characteristicId - The UUID of the characteristic.
+     * @returns {BluetoothRemoteGATTCharacteristic | undefined} The characteristic, if found.
+     */
+    getCharacteristic = (serviceId, characteristicId) => {
+        // Find the service with the specified serviceId
+        const boardService = this.services.find((service) => service.id === serviceId);
+        if (boardService) {
+            // If the service is found, find the characteristic with the specified characteristicId
+            const boardCharacteristic = boardService.characteristics.find((characteristic) => characteristic.id === characteristicId);
+            if (boardCharacteristic) {
+                // If the characteristic is found, return it
+                return boardCharacteristic.characteristic;
+            }
+        }
+        // Return undefined if the service or characteristic is not found
+        return undefined;
     };
     /**
      * Handles notifications received from a characteristic.
@@ -38,6 +96,32 @@ export class Device extends BaseModel {
             }
         }
     };
+    /**
+     * Checks if a Bluetooth device is connected.
+     * @returns {boolean} A boolean indicating whether the device is connected.
+     */
+    isConnected = () => {
+        // Check if the device is defined and available
+        if (!this?.bluetooth) {
+            return false;
+        }
+        // Check if the device is connected
+        return !!this.bluetooth.gatt?.connected;
+    };
+    /**
+     * Sets the callback function to be called when notifications are received.
+     * @param {NotifyCallback} callback - The callback function to be set.
+     * @returns {void}
+     */
+    notify = (callback) => {
+        this.notifyCallback = callback;
+    };
+    /**
+     * Defines the type for the callback function.
+     * @callback NotifyCallback
+     * @param {massObject} data - The data passed to the callback.
+     */
+    notifyCallback = (data) => console.log(data);
     /**
      * Handles the 'connected' event.
      * @param {Function} onSuccess - Callback function to execute on successful connection.
@@ -79,62 +163,108 @@ export class Device extends BaseModel {
         onSuccess();
     };
     /**
-     * Returns UUIDs of all services associated with the device.
-     * @returns {string[]} Array of service UUIDs.
+     * Handles the 'disconnected' event.
+     * @param {Event} event - The 'disconnected' event.
      */
-    getAllServiceUUIDs = () => {
-        return this.services.map((service) => service.uuid);
+    onDisconnected = (event) => {
+        this.bluetooth = undefined;
+        const device = event.target;
+        throw new Error(`Device ${device.name} is disconnected.`);
     };
     /**
-     * Connects to a Bluetooth device.
-     * @param {Function} [onSuccess] - Optional callback function to execute on successful connection. Default logs success.
-     * @param {Function} [onError] - Optional callback function to execute on error. Default logs the error.
+     * Reads the value of the specified characteristic from the device.
+     * @param {string} serviceId - The service ID where the characteristic belongs.
+     * @param {string} characteristicId - The characteristic ID to read from.
+     * @param {number} [duration=0] - The duration to wait before resolving the promise, in milliseconds.
+     * @returns {Promise<string>} A promise that resolves when the read operation is completed.
      */
-    connect = async (onSuccess = () => console.log("Connected successfully"), onError = (error) => console.error(error)) => {
-        try {
-            // Request device and set up connection
-            const deviceServices = this.getAllServiceUUIDs();
-            this.bluetooth = await navigator.bluetooth.requestDevice({
-                filters: this.filters,
-                optionalServices: deviceServices,
-            });
-            if (!this.bluetooth.gatt) {
-                throw new Error("GATT is not available on this device");
-            }
-            this.bluetooth.addEventListener("gattserverdisconnected", (event) => {
-                this.onDisconnected(event);
-            });
-            server = await this.bluetooth.gatt.connect();
-            if (server.connected) {
-                await this.onConnected(onSuccess);
+    read = (serviceId, characteristicId, duration = 0) => {
+        return new Promise((resolve, reject) => {
+            if (this.isConnected()) {
+                const characteristic = this.getCharacteristic(serviceId, characteristicId);
+                if (characteristic) {
+                    characteristic
+                        .readValue()
+                        .then((value) => {
+                        let decodedValue;
+                        const decoder = new TextDecoder("utf-8");
+                        switch (characteristicId) {
+                            case "level":
+                                // TODO: This is battery specific.
+                                decodedValue = value.getUint8(0).toString();
+                                break;
+                            default:
+                                decodedValue = decoder.decode(value);
+                                break;
+                        }
+                        // Resolve after specified duration
+                        setTimeout(() => {
+                            return resolve(decodedValue);
+                        }, duration);
+                    })
+                        .catch((error) => {
+                        reject(error);
+                    });
+                }
+                else {
+                    reject(new Error("Characteristic is undefined"));
+                }
             }
-        }
-        catch (error) {
-            onError(error);
-        }
+        });
     };
     /**
-     * Checks if a Bluetooth device is connected.
-     * @returns {boolean} A boolean indicating whether the device is connected.
+     * Writes a message to the specified characteristic of a Bluetooth device and optionally provides a callback to handle responses.
+     * @param {string} serviceId - The service UUID of the Bluetooth device containing the target characteristic.
+     * @param {string} characteristicId - The characteristic UUID where the message will be written.
+     * @param {string | Uint8Array | undefined} message - The message to be written to the characteristic. It can be a string or a Uint8Array.
+     * @param {number} [duration=0] - Optional. The time in milliseconds to wait before resolving the promise. Defaults to 0 for immediate resolution.
+     * @param {WriteCallback} [callback=writeCallback] - Optional. A custom callback to handle the response after the write operation is successful.
+     *
+     * @returns {Promise<void>} A promise that resolves once the write operation is complete.
+     *
+     * @throws {Error} Throws an error if the characteristic is undefined.
+     *
+     * @example
+     * // Example usage of the write function with a custom callback
+     * await Progressor.write("progressor", "tx", ProgressorCommands.GET_BATT_VLTG, 250, (data) => {
+     *   console.log(`Battery voltage: ${data}`);
+     * });
      */
-    isConnected = () => {
-        // Check if the device is defined and available
-        if (!this?.bluetooth) {
-            return false;
+    write = async (serviceId, characteristicId, message, duration = 0, callback = this.writeCallback) => {
+        if (this.isConnected()) {
+            // Check if message is provided
+            if (message === undefined) {
+                // If not provided, return without performing write operation
+                return;
+            }
+            // Get the characteristic from the device using serviceId and characteristicId
+            const characteristic = this.getCharacteristic(serviceId, characteristicId);
+            if (!characteristic) {
+                throw new Error("Characteristic is undefined");
+            }
+            // Convert the message to Uint8Array if it's a string
+            const valueToWrite = typeof message === "string" ? new TextEncoder().encode(message) : message;
+            // Write the value to the characteristic
+            await characteristic.writeValue(valueToWrite);
+            // Update the last written message
+            this.writeLast = message;
+            // Assign the provided callback to `writeCallback`
+            this.writeCallback = callback;
+            // If a duration is specified, resolve the promise after the duration
+            if (duration > 0) {
+                await new Promise((resolve) => setTimeout(resolve, duration));
+            }
         }
-        // Check if the device is connected
-        return !!this.bluetooth.gatt?.connected;
     };
     /**
-     * Disconnects the device if it is currently connected.
-     * - Checks if the device is connected via it's GATT server.
-     * - If the device is connected, it attempts to gracefully disconnect.
+     * A default write callback that logs the response
      */
-    disconnect = () => {
-        // Verify that the device is connected using the provided helper function
-        if (this.isConnected()) {
-            // Safely attempt to disconnect the device's GATT server, if available
-            this.bluetooth?.gatt?.disconnect();
-        }
+    writeCallback = (data) => {
+        console.log(data);
     };
+    /**
+     * The last message written to the device.
+     * @type {string | Uint8Array | null}
+     */
+    writeLast = null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hangtime/grip-connect",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Griptonite Motherboard, Tindeq Progressor, PitchSix Force Board, WHC-06, Entralpi, Climbro, mySmartBoard: Web Bluetooth API Force-Sensing strength analysis for climbers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/{is-device.ts → helpers/is-device.ts}

@@ -1,5 +1,5 @@
-import type { Device } from "./models/device.model"
-import { AuroraUUID } from "./models/device/kilterboard.model"
+import type { Device } from "./../models/device.model"
+import { AuroraUUID } from "./../models/device/kilterboard.model"
 
 /**
  * Checks if the given device is an Entralpi device.

package/src/index.ts

@@ -10,15 +10,11 @@ export {
 } from "./models/index"
 
 // helpers
-export { isEntralpi, isKilterboard, isMotherboard, isWHC06, isProgressor } from "./is-device"
+export { isEntralpi, isKilterboard, isMotherboard, isWHC06, isProgressor } from "./helpers/is-device"
 
-// functions
+// TODO: Make functions device specific
 export { download } from "./download"
 
 export { active, isActive } from "./is-active"
 
-export { notify } from "./notify"
-
-export { stop } from "./stop"
-
 export { tare } from "./tare"

package/src/interfaces/base.interface.ts

@@ -1,5 +1,19 @@
+/**
+ * Represents the base properties for an entity.
+ */
 export interface IBase {
+  /**
+   * Unique identifier for the entity (optional).
+   */
   id?: string
+
+  /**
+   * The date and time when the entity was created (optional).
+   */
   createdAt?: Date
+
+  /**
+   * The date and time when the entity was last updated (optional).
+   */
   updatedAt?: Date
 }

package/src/interfaces/device/climbro.interface.ts

@@ -1,4 +1,6 @@
 import type { IDevice } from "../device.interface"
-
+/**
+ * Interface representing the Climbro device, extending the base Device interface.
+ */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface IClimbro extends IDevice {}

package/src/interfaces/device/entralpi.interface.ts

@@ -1,4 +1,61 @@
 import type { IDevice } from "../device.interface"
 
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface IEntralpi extends IDevice {}
+/**
+ * Interface representing the Entralpi device, extending the base Device interface.
+ */
+export interface IEntralpi extends IDevice {
+  /**
+   * Retrieves battery or voltage information from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the battery or voltage information.
+   */
+  battery(): Promise<string | undefined>
+
+  /**
+   * Retrieves IEEE 11073-20601 Regulatory Certification from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the firmware version.
+   */
+  certification(): Promise<string | undefined>
+
+  /**
+   * Retrieves firmware version from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the firmware version.
+   */
+  firmware(): Promise<string | undefined>
+
+  /**
+   * Retrieves hardware version from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the hardware version.
+   */
+  hardware(): Promise<string | undefined>
+
+  /**
+   * Retrieves manufacturer information from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the manufacturer information.
+   */
+  manufacturer(): Promise<string | undefined>
+
+  /**
+   * Retrieves model number from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the model number.
+   */
+  model(): Promise<string | undefined>
+
+  /**
+   * Retrieves PnP ID from the device, a set of values that used to create a device ID value that is unique for this device.
+   * Included in the characteristic is a Vendor ID Source field, a Vendor ID field, a Product ID field and a Product Version field
+   * @returns {Promise<string | undefined>} A Promise that resolves with the PnP ID.
+   */
+  pnp(): Promise<string | undefined>
+
+  /**
+   * Retrieves software version from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the software version.
+   */
+  software(): Promise<string | undefined>
+
+  /**
+   * Retrieves system id from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the system id.
+   */
+  system(): Promise<string | undefined>
+}

package/src/interfaces/device/forceboard.interface.ts

@@ -1,4 +1,24 @@
 import type { IDevice } from "../device.interface"
 
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface IForceBoard extends IDevice {}
+/**
+ * Interface representing the PitchSix ForceBoard device, extending the base Device interface.
+ */
+export interface IForceBoard extends IDevice {
+  /**
+   * Retrieves battery or voltage information from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the battery or voltage information.
+   */
+  battery(): Promise<string | undefined>
+
+  /**
+   * Retrieves humidity level from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the humidity level.
+   */
+  humidity(): Promise<string | undefined>
+
+  /**
+   * Retrieves manufacturer information from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the manufacturer information.
+   */
+  manufacturer(): Promise<string | undefined>
+}

package/src/interfaces/device/kilterboard.interface.ts

@@ -1,4 +1,85 @@
 import type { IDevice } from "../device.interface"
+/**
+ * Represents a climbing placement with a position and role identifier.
+ */
+export interface ClimbPlacement {
+  /** The position of the hold placement. */
+  position: number
+  /** The role ID associated with the climb placement. */
+  role_id: number
+}
+/**
+ * Interface representing the KilterBoard device, extending the base Device interface.
+ */
+export interface IKilterBoard extends IDevice {
+  /**
+   * Calculates the checksum for a byte array.
+   * @param data - The array of bytes to calculate the checksum for.
+   * @returns The calculated checksum value.
+   */
+  checksum(data: number[]): number
 
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface IKilterBoard extends IDevice {}
+  /**
+   * Wraps a byte array with header and footer bytes for transmission.
+   * @param data - The array of bytes to wrap.
+   * @returns The wrapped byte array.
+   */
+  wrapBytes(data: number[]): number[]
+
+  /**
+   * Encodes a position into a byte array.
+   * @param position - The position to encode.
+   * @returns The encoded byte array representing the position.
+   */
+  encodePosition(position: number): number[]
+
+  /**
+   * Encodes a color string into a numeric representation.
+   * @param color - The color string in hexadecimal format.
+   * @returns The encoded/compressed color value.
+   */
+  encodeColor(color: string): number
+
+  /**
+   * Encodes a placement into a byte array.
+   * @param position - The position to encode.
+   * @param ledColor - The color of the LED in hexadecimal format.
+   * @returns The encoded byte array representing the placement.
+   */
+  encodePlacement(position: number, ledColor: string): number[]
+
+  /**
+   * Prepares byte arrays for transmission based on a list of climb placements.
+   * @param climbPlacementList - The list of climb placements.
+   * @returns The final byte array ready for transmission.
+   */
+  prepBytesV3(climbPlacementList: ClimbPlacement[]): number[]
+
+  /**
+   * Splits a collection into slices of the specified length.
+   * @param n - Number of elements per slice.
+   * @param list - Array to be sliced.
+   * @returns The sliced array.
+   */
+  splitEvery(n: number, list: number[]): number[][]
+
+  /**
+   * Splits a message into 20-byte chunks for Bluetooth transmission.
+   * @param buffer - The message to split.
+   * @returns The array of Uint8Arrays.
+   */
+  splitMessages(buffer: number[]): Uint8Array[]
+
+  /**
+   * Sends a series of messages to the device.
+   * @param messages - Array of Uint8Arrays to send.
+   */
+  writeMessageSeries(messages: Uint8Array[]): Promise<void>
+
+  /**
+   * Configures the LEDs based on an array of climb placements.
+   * @param config - Optional color or array of climb placements.
+   * @returns The prepared payload or undefined.
+   */
+  led(config?: ClimbPlacement[]): Promise<number[] | undefined>
+}

package/src/interfaces/device/motherboard.interface.ts

@@ -1,11 +1,70 @@
 import type { IDevice } from "../device.interface"
 
+/**
+ * Interface representing the Griptonite Motherboard device.
+ */
 export interface IMotherboard extends IDevice {
   /**
    * Applies calibration to a sample value.
-   * @param sample - The sample value to calibrate.
-   * @param calibration - The calibration data.
-   * @returns The calibrated sample value.
+   * @param {number} sample - The sample value to calibrate.
+   * @param {number[][]} calibration - The calibration data.
+   * @returns {number} The calibrated sample value.
    */
   applyCalibration(sample: number, calibration: number[][]): number
+
+  /**
+   * Retrieves battery or voltage information from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the battery or voltage information.
+   */
+  battery(): Promise<string | undefined>
+
+  /**
+   * Writes a command to get calibration data from the device.
+   * @returns {Promise<void>} A Promise that resolves when the command is successfully sent.
+   */
+  calibration(): Promise<void>
+
+  /**
+   * Retrieves firmware version from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the firmware version.
+   */
+  firmware(): Promise<string | undefined>
+
+  /**
+   * Retrieves hardware version from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the hardware version.
+   */
+  hardware(): Promise<string | undefined>
+
+  /**
+   * Sets the LED color based on a single color option.
+   * @param {"green" | "red" | "orange"} [config] - Optional color for the LEDs.
+   * @returns {Promise<number[] | undefined>} A promise that resolves with the payload array for the Kilter Board if LED settings were applied.
+   */
+  led(config?: "green" | "red" | "orange"): Promise<number[] | undefined>
+
+  /**
+   * Retrieves manufacturer information from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the manufacturer information.
+   */
+  manufacturer(): Promise<string | undefined>
+
+  /**
+   * Retrieves serial number from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the serial number.
+   */
+  serial(): Promise<string | undefined>
+
+  /**
+   * Stops the data stream on the specified device.
+   * @returns {Promise<void>} A promise that resolves when the stream is stopped.
+   */
+  stop(): Promise<void>
+
+  /**
+   * Starts streaming data from the specified device.
+   * @param {number} [duration=0] - The duration of the stream in milliseconds. If set to 0, stream will continue indefinitely.
+   * @returns {Promise<void>} A promise that resolves when the streaming operation is completed.
+   */
+  stream(duration?: number): Promise<void>
 }

package/src/interfaces/device/mysmartboard.interface.ts

@@ -1,4 +1,6 @@
 import type { IDevice } from "../device.interface"
-
+/**
+ * Interface representing the mySmartBoard device, extending the base Device interface.
+ */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface ImySmartBoard extends IDevice {}

package/src/interfaces/device/progressor.interface.ts

@@ -1,4 +1,31 @@
 import type { IDevice } from "../device.interface"
 
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface IProgressor extends IDevice {}
+/**
+ * Interface representing the Tindeq Progressor device.
+ */
+export interface IProgressor extends IDevice {
+  /**
+   * Retrieves battery or voltage information from the device.
+   * @returns {Promise<string | undefined>} A Promise that resolves with the battery or voltage information.
+   */
+  battery(): Promise<string | undefined>
+
+  /**
+   * Retrieves firmware version from the device.
+   * @returns {Promise<string>} A Promise that resolves with the firmware version.
+   */
+  firmware(): Promise<string | undefined>
+
+  /**
+   * Stops the data stream on the specified device.
+   * @returns {Promise<void>} A promise that resolves when the stream is stopped.
+   */
+  stop(): Promise<void>
+
+  /**
+   * Starts streaming data from the specified device.
+   * @param {number} [duration=0] - The duration of the stream in milliseconds. If set to 0, stream will continue indefinitely.
+   * @returns {Promise<void>} A promise that resolves when the streaming operation is completed.
+   */
+  stream(duration?: number): Promise<void>
+}

package/src/interfaces/device/wh-c06.interface.ts

@@ -1,4 +1,6 @@
 import type { IDevice } from "../device.interface"
-
+/**
+ * Interface representing the Weiheng WH-C06 device.
+ */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface IWHC06 extends IDevice {}