@hangtime/grip-connect 0.5.8 → 0.5.9

package/dist/models/device.model.js

@@ -160,6 +160,11 @@ export class Device extends BaseModel {
      * @param {number} [options.duration=1000] - The duration (in milliseconds) to monitor the input for activity.
      * @returns {void}
      * @public
+     *
+     * @example
+     * device.active((isActive) => {
+     *   console.log(`Device is ${isActive ? 'active' : 'inactive'}`);
+     * }, { threshold: 3.0, duration: 1500 });
      */
     active = (callback, options) => {
         this.activeCallback = callback;
@@ -178,21 +183,34 @@ export class Device extends BaseModel {
      *
      * @param {number} input - The dynamic value to check for activity status.
      * @returns {Promise<void>} A promise that resolves once the activity check is complete.
+     *
+     * @example
+     * await device.activityCheck(5.0);
      */
     activityCheck = (input) => {
         return new Promise((resolve) => {
-            // Check the activity status after the specified duration
-            setTimeout(() => {
-                // Determine the activity status based on the stored threshold in the config
-                const activeNow = input > this.activeConfig.threshold;
-                if (this.isActive !== activeNow) {
-                    this.isActive = activeNow;
-                    if (this.activeCallback) {
-                        this.activeCallback(activeNow);
+            const startTime = Date.now();
+            const checkActivity = () => {
+                const currentTime = Date.now();
+                const elapsedTime = currentTime - startTime;
+                if (elapsedTime >= this.activeConfig.duration) {
+                    // Determine the activity status based on the most recent input
+                    const activeNow = input > this.activeConfig.threshold;
+                    if (this.isActive !== activeNow) {
+                        this.isActive = activeNow;
+                        if (this.activeCallback) {
+                            this.activeCallback(activeNow);
+                        }
                     }
+                    resolve();
+                }
+                else {
+                    // Continue checking until the duration is met
+                    requestAnimationFrame(checkActivity);
                 }
-                resolve();
-            }, this.activeConfig.duration);
+            };
+            // Start the activity check
+            checkActivity();
         });
     };
     /**
@@ -200,6 +218,12 @@ export class Device extends BaseModel {
      * @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.
      * @public
+     *
+     * @example
+     * device.connect(
+     *   () => console.log("Connected successfully"),
+     *   (error) => console.error("Connection failed:", error)
+     * );
      */
     connect = async (onSuccess = () => console.log("Connected successfully"), onError = (error) => console.error(error)) => {
         try {
@@ -226,24 +250,57 @@ export class Device extends BaseModel {
     };
     /**
      * 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.
+     * - Removes all notification listeners from the device's characteristics.
+     * - Removes the 'gattserverdisconnected' event listener.
+     * - Attempts to gracefully disconnect the device's GATT server.
+     * - Resets relevant properties to their initial states.
+     * @returns {void}
      * @public
+     *
+     * @example
+     * device.disconnect();
      */
     disconnect = () => {
-        // Verify that the device is connected using the provided helper function
         if (this.isConnected()) {
+            // Remove all notification listeners
+            this.services.forEach((service) => {
+                service.characteristics.forEach((char) => {
+                    if (char.characteristic && char.id === "rx") {
+                        char.characteristic.stopNotifications();
+                        char.characteristic.removeEventListener("characteristicvaluechanged", (event) => {
+                            const target = event.target;
+                            if (target && target.value) {
+                                this.handleNotifications(target);
+                            }
+                        });
+                    }
+                });
+            });
+            // Remove disconnect listener
+            this.bluetooth?.removeEventListener("gattserverdisconnected", this.onDisconnected);
             // Safely attempt to disconnect the device's GATT server, if available
             this.bluetooth?.gatt?.disconnect();
+            // Reset properties
+            this.server = undefined;
+            this.writeLast = null;
+            this.isActive = false;
         }
     };
     /**
      * Converts the `downloadPackets` array into a CSV formatted string.
      * @returns {string} A CSV string representation of the `downloadPackets` data, with each packet on a new line.
      * @private
+     *
+     * @example
+     * const csvData = device.downloadToCSV();
+     * console.log(csvData);
      */
     downloadToCSV = () => {
-        return this.downloadPackets
+        const packets = [...this.downloadPackets];
+        if (packets.length === 0) {
+            return "";
+        }
+        return packets
             .map((packet) => [
             packet.received.toString(),
             packet.sampleNum.toString(),
@@ -260,6 +317,10 @@ export class Device extends BaseModel {
      * Converts an array of DownloadPacket objects to a JSON string.
      * @returns {string} JSON string representation of the data.
      * @private
+     *
+     * @example
+     * const jsonData = device.downloadToJSON();
+     * console.log(jsonData);
      */
     downloadToJSON = () => {
         // Pretty print JSON with 2-space indentation
@@ -269,6 +330,10 @@ export class Device extends BaseModel {
      * Converts an array of DownloadPacket objects to an XML string.
      * @returns {string}  XML string representation of the data.
      * @private
+     *
+     * @example
+     * const xmlData = device.downloadToXML();
+     * console.log(xmlData);
      */
     downloadToXML = () => {
         const xmlPackets = this.downloadPackets
@@ -297,6 +362,9 @@ export class Device extends BaseModel {
      *
      * @returns {void} Initiates a download of the data in the specified format.
      * @private
+     *
+     * @example
+     * device.download('json');
      */
     download = (format = "csv") => {
         let content = "";
@@ -341,9 +409,13 @@ export class Device extends BaseModel {
      * Returns UUIDs of all services associated with the device.
      * @returns {string[]} Array of service UUIDs.
      * @protected
+     *
+     * @example
+     * const serviceUUIDs = device.getAllServiceUUIDs();
+     * console.log(serviceUUIDs);
      */
     getAllServiceUUIDs = () => {
-        return this.services.map((service) => service.uuid);
+        return this.services.filter((service) => service?.uuid).map((service) => service.uuid);
     };
     /**
      * Retrieves the characteristic from the device's service.
@@ -351,6 +423,12 @@ export class Device extends BaseModel {
      * @param {string} characteristicId - The UUID of the characteristic.
      * @returns {BluetoothRemoteGATTCharacteristic | undefined} The characteristic, if found.
      * @protected
+     *
+     * @example
+     * const characteristic = device.getCharacteristic('battery', 'level');
+     * if (characteristic) {
+     *   console.log('Characteristic found');
+     * }
      */
     getCharacteristic = (serviceId, characteristicId) => {
         // Find the service with the specified serviceId
@@ -368,25 +446,34 @@ export class Device extends BaseModel {
     };
     /**
      * Handles notifications received from a characteristic.
-     * @param {Event} event - The notification event.
-     * @protected
+     * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
+     *
+     * @example
+     * device.handleNotifications(someCharacteristic);
      */
-    handleNotifications = (event) => {
-        const characteristic = event.target;
+    handleNotifications = (characteristic) => {
         const value = characteristic.value;
-        if (value) {
-            if (value.buffer) {
-                console.log(value);
-            }
-            else {
-                console.log(value);
-            }
+        if (!value) {
+            return;
+        }
+        if (value.buffer) {
+            console.log(value);
+        }
+        else {
+            console.log(value);
         }
     };
     /**
      * Checks if a Bluetooth device is connected.
      * @returns {boolean} A boolean indicating whether the device is connected.
      * @public
+     *
+     * @example
+     * if (device.isConnected()) {
+     *   console.log('Device is connected');
+     * } else {
+     *   console.log('Device is not connected');
+     * }
      */
     isConnected = () => {
         // Check if the device is defined and available
@@ -401,6 +488,11 @@ export class Device extends BaseModel {
      * @param {NotifyCallback} callback - The callback function to be set.
      * @returns {void}
      * @public
+     *
+     * @example
+     * device.notify((data) => {
+     *   console.log('Received notification:', data);
+     * });
      */
     notify = (callback) => {
         this.notifyCallback = callback;
@@ -409,10 +501,18 @@ export class Device extends BaseModel {
      * Handles the 'connected' event.
      * @param {Function} onSuccess - Callback function to execute on successful connection.
      * @public
+     *
+     * @example
+     * device.onConnected(() => {
+     *   console.log('Device connected successfully');
+     * });
      */
     onConnected = async (onSuccess) => {
+        if (!this.server) {
+            throw new Error("GATT server is not available");
+        }
         // Connect to GATT server and set up characteristics
-        const services = await this.server?.getPrimaryServices();
+        const services = await this.server.getPrimaryServices();
         if (!services || services.length === 0) {
             throw new Error("No services found");
         }
@@ -432,7 +532,10 @@ export class Device extends BaseModel {
                             if (element.id === "rx") {
                                 matchingCharacteristic.startNotifications();
                                 matchingCharacteristic.addEventListener("characteristicvaluechanged", (event) => {
-                                    this.handleNotifications(event);
+                                    const target = event.target;
+                                    if (target && target.value) {
+                                        this.handleNotifications(target);
+                                    }
                                 });
                             }
                         }
@@ -450,11 +553,14 @@ export class Device extends BaseModel {
      * Handles the 'disconnected' event.
      * @param {Event} event - The 'disconnected' event.
      * @public
+     *
+     * @example
+     * device.onDisconnected(event);
      */
     onDisconnected = (event) => {
         this.bluetooth = undefined;
         const device = event.target;
-        throw new Error(`Device ${device.name} is disconnected.`);
+        console.warn(`Device ${device.name} is disconnected.`);
     };
     /**
      * Reads the value of the specified characteristic from the device.
@@ -463,6 +569,10 @@ export class Device extends BaseModel {
      * @param {number} [duration=0] - The duration to wait before resolving the promise, in milliseconds.
      * @returns {Promise<string | undefined>} A promise that resolves when the read operation is completed.
      * @public
+     *
+     * @example
+     * const value = await device.read('battery', 'level', 1000);
+     * console.log('Battery level:', value);
      */
     read = async (serviceId, characteristicId, duration = 0) => {
         if (!this.isConnected()) {
@@ -496,20 +606,35 @@ export class Device extends BaseModel {
     /**
      * Initiates the tare calibration process.
      * @param {number} duration - The duration time for tare calibration.
-     * @returns {void}
+     * @returns {boolean} A boolean indicating whether the tare calibration was successful.
      * @public
+     *
+     * @example
+     * const success = device.tare(5000);
+     * if (success) {
+     *   console.log('Tare calibration started');
+     * } else {
+     *   console.log('Tare calibration failed to start');
+     * }
      */
     tare(duration = 5000) {
+        if (this.tareActive)
+            return false;
         this.tareActive = true;
         this.tareDuration = duration;
         this.tareSamples = [];
         this.tareStartTime = Date.now();
+        return true;
     }
     /**
      * Apply tare calibration to the provided sample.
      * @param {number} sample - The sample to calibrate.
      * @returns {number} The calibrated tare value.
      * @protected
+     *
+     * @example
+     * const calibratedSample = device.applyTare(rawSample);
+     * console.log('Calibrated sample:', calibratedSample);
      */
     applyTare(sample) {
         if (this.tareActive && this.tareStartTime) {
@@ -549,7 +674,7 @@ export class Device extends BaseModel {
     write = async (serviceId, characteristicId, message, duration = 0, callback = this.writeCallback) => {
         // Check if not connected or no message is provided
         if (!this.isConnected() || message === undefined) {
-            return undefined;
+            return Promise.resolve();
         }
         // Get the characteristic from the service
         const characteristic = this.getCharacteristic(serviceId, characteristicId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hangtime/grip-connect",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "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/interfaces/device.interface.ts

@@ -69,19 +69,54 @@ export interface IDevice extends IBase {
    */
   commands: Commands
 
+  /**
+   * Sets the callback function to be called when the activity status changes,
+   * and optionally sets the configuration for threshold and duration.
+   *
+   * This function allows you to specify a callback that will be invoked whenever
+   * the activity status changes, indicating whether the device is currently active.
+   * It also allows optionally configuring the threshold and duration used to determine activity.
+   *
+   * @param {ActiveCallback} callback - The callback function to be set. This function
+   *                                      receives a boolean value indicating the new activity status.
+   * @param {object} [options] - Optional configuration object containing the threshold and duration.
+   * @param {number} [options.threshold=2.5] - The threshold value for determining activity.
+   * @param {number} [options.duration=1000] - The duration (in milliseconds) to monitor the input for activity.
+   * @returns {void}
+   * @public
+   *
+   * @example
+   * device.active((isActive) => {
+   *   console.log(`Device is ${isActive ? 'active' : 'inactive'}`);
+   * }, { threshold: 3.0, duration: 1500 });
+   */
+  active(callback?: (data: boolean) => void, options?: { threshold?: number; duration?: number }): void
+
   /**
    * 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.
    * @public
+   *
+   * @example
+   * device.connect(
+   *   () => console.log("Connected successfully"),
+   *   (error) => console.error("Connection failed:", error)
+   * );
    */
   connect(onSuccess?: () => void, onError?: (error: Error) => void): Promise<void>
 
   /**
    * 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.
+   * - Removes all notification listeners from the device's characteristics.
+   * - Removes the 'gattserverdisconnected' event listener.
+   * - Attempts to gracefully disconnect the device's GATT server.
+   * - Resets relevant properties to their initial states.
+   * @returns {void}
    * @public
+   *
+   * @example
+   * device.disconnect();
    */
   disconnect(): void
 
@@ -94,6 +129,9 @@ export interface IDevice extends IBase {
    *
    * @returns {void} Initiates a download of the data in the specified format.
    * @private
+   *
+   * @example
+   * device.download('json');
    */
   download(format?: "csv" | "json" | "xml"): void
 
@@ -101,6 +139,13 @@ export interface IDevice extends IBase {
    * Checks if a Bluetooth device is connected.
    * @returns {boolean} A boolean indicating whether the device is connected.
    * @public
+   *
+   * @example
+   * if (device.isConnected()) {
+   *   console.log('Device is connected');
+   * } else {
+   *   console.log('Device is not connected');
+   * }
    */
   isConnected(): boolean
 
@@ -109,6 +154,11 @@ export interface IDevice extends IBase {
    * @param {NotifyCallback} callback - The callback function to be set.
    * @returns {void}
    * @public
+   *
+   * @example
+   * device.notify((data) => {
+   *   console.log('Received notification:', data);
+   * });
    */
   notify(callback: (data: massObject) => void): void
 
@@ -119,15 +169,28 @@ export interface IDevice extends IBase {
    * @param {number} [duration=0] - The duration to wait before resolving the promise, in milliseconds.
    * @returns {Promise<string | undefined>} A promise that resolves when the read operation is completed.
    * @public
+   *
+   * @example
+   * const value = await device.read('battery', 'level', 1000);
+   * console.log('Battery level:', value);
    */
   read(serviceId: string, characteristicId: string, duration?: number): Promise<string | undefined>
 
   /**
    * Initiates the tare calibration process.
    * @param {number} duration - The duration time for tare calibration.
-   * @returns {void}
+   * @returns {boolean} A boolean indicating whether the tare calibration was successful.
+   * @public
+   *
+   * @example
+   * const success = device.tare(5000);
+   * if (success) {
+   *   console.log('Tare calibration started');
+   * } else {
+   *   console.log('Tare calibration failed to start');
+   * }
    */
-  tare(duration?: number): void
+  tare(duration?: number): boolean
 
   /**
    * Writes a message to the specified characteristic of a Bluetooth device and optionally provides a callback to handle responses.

package/src/models/device/entralpi.model.ts

@@ -153,10 +153,9 @@ export class Entralpi extends Device implements IEntralpi {
    * and updates mass data including maximum and average values.
    * It also handles command responses for retrieving device information.
    *
-   * @param {Event} event - The notification event.
+   * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
    */
-  handleNotifications = (event: Event): void => {
-    const characteristic: BluetoothRemoteGATTCharacteristic = event.target as BluetoothRemoteGATTCharacteristic
+  handleNotifications = (characteristic: BluetoothRemoteGATTCharacteristic): void => {
     const value: DataView | undefined = characteristic.value
 
     if (value) {

package/src/models/device/forceboard.model.ts

@@ -180,10 +180,9 @@ export class ForceBoard extends Device implements IForceBoard {
    * and updates mass data including maximum and average values.
    * It also handles command responses for retrieving device information.
    *
-   * @param {Event} event - The notification event.
+   * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
    */
-  handleNotifications = (event: Event): void => {
-    const characteristic: BluetoothRemoteGATTCharacteristic = event.target as BluetoothRemoteGATTCharacteristic
+  handleNotifications = (characteristic: BluetoothRemoteGATTCharacteristic): void => {
     const value: DataView | undefined = characteristic.value
     if (value) {
       if (value.buffer) {

package/src/models/device/motherboard.model.ts

@@ -201,10 +201,9 @@ export class Motherboard extends Device implements IMotherboard {
    * to extract samples, calibrate masses, and update running averages of mass data.
    * If the received data is not a valid hex packet, it returns the unprocessed data.
    *
-   * @param {Event} event - The notification event.
+   * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
    */
-  handleNotifications = (event: Event): void => {
-    const characteristic: BluetoothRemoteGATTCharacteristic = event.target as BluetoothRemoteGATTCharacteristic
+  handleNotifications = (characteristic: BluetoothRemoteGATTCharacteristic): void => {
     const value: DataView | undefined = characteristic.value
 
     if (value) {

package/src/models/device/progressor.model.ts

@@ -120,10 +120,9 @@ export class Progressor extends Device implements IProgressor {
    * and updates mass data including maximum and average values.
    * It also handles command responses for retrieving device information.
    *
-   * @param {Event} event - The notification event.
+   * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
    */
-  handleNotifications = (event: Event): void => {
-    const characteristic: BluetoothRemoteGATTCharacteristic = event.target as BluetoothRemoteGATTCharacteristic
+  handleNotifications = (characteristic: BluetoothRemoteGATTCharacteristic): void => {
     const value: DataView | undefined = characteristic.value
 
     if (value) {