@hangtime/grip-connect 0.5.6 → 0.5.7

package/dist/models/device.model.js

@@ -3,27 +3,55 @@ export class Device extends BaseModel {
     /**
      * Filters to identify the device during Bluetooth scanning.
      * Used to match devices that meet specific criteria such as name, service UUIDs, etc.
+     * @type {BluetoothLEScanFilter[]}
+     * @public
+     * @readonly
      */
     filters;
     /**
      * Array of services provided by the device.
      * Services represent functionalities that the device supports, such as weight measurement, battery information, or custom services.
+     * @type {Service[]}
+     * @public
+     * @readonly
      */
     services;
     /**
      * Reference to the `BluetoothDevice` object representing this device.
      * This is the actual device object obtained from the Web Bluetooth API after a successful connection.
+     * @type {BluetoothDevice | undefined}
+     * @public
      */
     bluetooth;
     /**
      * Object representing the set of commands available for this device.
      * These commands allow communication with the device to perform various operations such as starting measurements, retrieving data, or calibrating the device.
+     * @type {Commands}
+     * @public
+     * @readonly
      */
     commands;
     /**
      * The BluetoothRemoteGATTServer interface of the Web Bluetooth API represents a GATT Server on a remote device.
+     * @type {BluetoothRemoteGATTServer | undefined}
+     * @private
      */
     server;
+    /**
+     * The last message written to the device.
+     * @type {string | Uint8Array | null}
+     * @protected
+     */
+    writeLast = null;
+    /**
+     * Indicates whether the device is currently active.
+     * @type {boolean}
+     */
+    isActive = false;
+    /**
+     * Configuration for threshold and duration.
+     */
+    activeConfig = { threshold: 2.5, duration: 1000 };
     /**
      * Maximum mass recorded from the device, initialized to "0".
      * @type {string}
@@ -50,6 +78,38 @@ export class Device extends BaseModel {
      * @protected
      */
     dataPointCount;
+    /**
+     * Array of DownloadPacket entries.
+     * This array holds packets that contain data downloaded from the device.
+     * @type {DownloadPacket[]}
+     * @protected
+     */
+    downloadPackets = []; // Initialize an empty array of DownloadPacket entries
+    /**
+     * Represents the current tare value for calibration.
+     * @type {number}
+     */
+    tareCurrent = 0;
+    /**
+     * Indicates whether the tare calibration process is active.
+     * @type {boolean}
+     */
+    tareActive = false;
+    /**
+     * Timestamp when the tare calibration process started.
+     * @type {number | null}
+     */
+    tareStartTime = null;
+    /**
+     * Array holding the samples collected during tare calibration.
+     * @type {number[]}
+     */
+    tareSamples = [];
+    /**
+     * Duration time for the tare calibration process.
+     * @type {number}
+     */
+    tareDuration = 5000;
     /**
      * Optional callback for handling write operations.
      * @callback NotifyCallback
@@ -67,10 +127,13 @@ export class Device extends BaseModel {
      */
     writeCallback = (data) => console.log(data);
     /**
-     * The last message written to the device.
-     * @type {string | Uint8Array | null}
+     * Optional callback for handling write operations.
+     * @callback ActiveCallback
+     * @param {string} data - The data passed to the callback.
+     * @type {ActiveCallback | undefined}
+     * @protected
      */
-    writeLast = null;
+    activeCallback = (data) => console.log(data);
     constructor(device) {
         super(device);
         this.filters = device.filters || [];
@@ -82,10 +145,61 @@ export class Device extends BaseModel {
         this.massTotalSum = 0;
         this.dataPointCount = 0;
     }
+    /**
+     * 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
+     */
+    active = (callback, options) => {
+        this.activeCallback = callback;
+        // Update the config values only if provided, otherwise use defaults
+        this.activeConfig = {
+            threshold: options?.threshold ?? this.activeConfig.threshold, // Use new threshold if provided, else use default
+            duration: options?.duration ?? this.activeConfig.duration, // Use new duration if provided, else use default
+        };
+    };
+    /**
+     * Checks if a dynamic value is active based on a threshold and duration.
+     *
+     * This function assesses whether a given dynamic value surpasses a specified threshold
+     * and remains active for a specified duration. If the activity status changes from
+     * the previous state, the callback function is called with the updated activity status.
+     *
+     * @param {number} input - The dynamic value to check for activity status.
+     * @returns {Promise<void>} A promise that resolves once the activity check is complete.
+     */
+    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);
+                    }
+                }
+                resolve();
+            }, this.activeConfig.duration);
+        });
+    };
     /**
      * 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
      */
     connect = async (onSuccess = () => console.log("Connected successfully"), onError = (error) => console.error(error)) => {
         try {
@@ -114,6 +228,7 @@ 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.
+     * @public
      */
     disconnect = () => {
         // Verify that the device is connected using the provided helper function
@@ -122,9 +237,110 @@ export class Device extends BaseModel {
             this.bluetooth?.gatt?.disconnect();
         }
     };
+    /**
+     * 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
+     */
+    downloadToCSV = () => {
+        return this.downloadPackets
+            .map((packet) => [
+            packet.received.toString(),
+            packet.sampleNum.toString(),
+            packet.battRaw.toString(),
+            ...packet.samples.map(String),
+            ...packet.masses.map(String),
+        ]
+            .map((v) => v.replace(/"/g, '""'))
+            .map((v) => `"${v}"`)
+            .join(","))
+            .join("\r\n");
+    };
+    /**
+     * Converts an array of DownloadPacket objects to a JSON string.
+     * @returns {string} JSON string representation of the data.
+     * @private
+     */
+    downloadToJSON = () => {
+        // Pretty print JSON with 2-space indentation
+        return JSON.stringify(this.downloadPackets, null, 2);
+    };
+    /**
+     * Converts an array of DownloadPacket objects to an XML string.
+     * @returns {string}  XML string representation of the data.
+     * @private
+     */
+    downloadToXML = () => {
+        const xmlPackets = this.downloadPackets
+            .map((packet) => {
+            const samples = packet.samples.map((sample) => `<sample>${sample}</sample>`).join("");
+            const masses = packet.masses.map((mass) => `<mass>${mass}</mass>`).join("");
+            return `
+          <packet>
+            <received>${packet.received}</received>
+            <sampleNum>${packet.sampleNum}</sampleNum>
+            <battRaw>${packet.battRaw}</battRaw>
+            <samples>${samples}</samples>
+            <masses>${masses}</masses>
+          </packet>
+        `;
+        })
+            .join("");
+        return `<DownloadPackets>${xmlPackets}</DownloadPackets>`;
+    };
+    /**
+     * Exports the data in the specified format (CSV, JSON, XML) with a filename format:
+     * 'data-export-YYYY-MM-DD-HH-MM-SS.{format}'.
+     *
+     * @param {('csv' | 'json' | 'xml')} [format='csv'] - The format in which to download the data.
+     * Defaults to 'csv'. Accepted values are 'csv', 'json', and 'xml'.
+     *
+     * @returns {void} Initiates a download of the data in the specified format.
+     * @private
+     */
+    download = (format = "csv") => {
+        let content = "";
+        let mimeType = "";
+        let fileName = "";
+        if (format === "csv") {
+            content = this.downloadToCSV();
+            mimeType = "text/csv";
+        }
+        else if (format === "json") {
+            content = this.downloadToJSON();
+            mimeType = "application/json";
+        }
+        else if (format === "xml") {
+            content = this.downloadToXML();
+            mimeType = "application/xml";
+        }
+        const now = new Date();
+        // YYYY-MM-DD
+        const date = now.toISOString().split("T")[0];
+        // HH-MM-SS
+        const time = now.toTimeString().split(" ")[0].replace(/:/g, "-");
+        fileName = `data-export-${date}-${time}.${format}`;
+        // Create a Blob object containing the data
+        const blob = new Blob([content], { type: mimeType });
+        // Create a URL for the Blob
+        const url = window.URL.createObjectURL(blob);
+        // Create a link element
+        const link = document.createElement("a");
+        // Set link attributes
+        link.href = url;
+        link.setAttribute("download", fileName);
+        // Append link to document body
+        document.body.appendChild(link);
+        // Programmatically click the link to trigger the download
+        link.click();
+        // Clean up: remove the link and revoke the URL
+        document.body.removeChild(link);
+        window.URL.revokeObjectURL(url);
+    };
     /**
      * Returns UUIDs of all services associated with the device.
      * @returns {string[]} Array of service UUIDs.
+     * @protected
      */
     getAllServiceUUIDs = () => {
         return this.services.map((service) => service.uuid);
@@ -134,6 +350,7 @@ export class Device extends BaseModel {
      * @param {string} serviceId - The UUID of the service.
      * @param {string} characteristicId - The UUID of the characteristic.
      * @returns {BluetoothRemoteGATTCharacteristic | undefined} The characteristic, if found.
+     * @protected
      */
     getCharacteristic = (serviceId, characteristicId) => {
         // Find the service with the specified serviceId
@@ -152,6 +369,7 @@ export class Device extends BaseModel {
     /**
      * Handles notifications received from a characteristic.
      * @param {Event} event - The notification event.
+     * @protected
      */
     handleNotifications = (event) => {
         const characteristic = event.target;
@@ -171,6 +389,7 @@ export class Device extends BaseModel {
     /**
      * Checks if a Bluetooth device is connected.
      * @returns {boolean} A boolean indicating whether the device is connected.
+     * @public
      */
     isConnected = () => {
         // Check if the device is defined and available
@@ -184,6 +403,7 @@ export class Device extends BaseModel {
      * Sets the callback function to be called when notifications are received.
      * @param {NotifyCallback} callback - The callback function to be set.
      * @returns {void}
+     * @public
      */
     notify = (callback) => {
         this.notifyCallback = callback;
@@ -191,6 +411,7 @@ export class Device extends BaseModel {
     /**
      * Handles the 'connected' event.
      * @param {Function} onSuccess - Callback function to execute on successful connection.
+     * @public
      */
     onConnected = async (onSuccess) => {
         // Connect to GATT server and set up characteristics
@@ -231,6 +452,7 @@ export class Device extends BaseModel {
     /**
      * Handles the 'disconnected' event.
      * @param {Event} event - The 'disconnected' event.
+     * @public
      */
     onDisconnected = (event) => {
         this.bluetooth = undefined;
@@ -243,6 +465,7 @@ export class Device extends BaseModel {
      * @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 | undefined>} A promise that resolves when the read operation is completed.
+     * @public
      */
     read = async (serviceId, characteristicId, duration = 0) => {
         if (!this.isConnected()) {
@@ -273,6 +496,42 @@ export class Device extends BaseModel {
         }
         return decodedValue;
     };
+    /**
+     * Initiates the tare calibration process.
+     * @param {number} duration - The duration time for tare calibration.
+     * @returns {void}
+     * @public
+     */
+    tare(duration = 5000) {
+        this.tareActive = true;
+        this.tareDuration = duration;
+        this.tareSamples = [];
+        this.tareStartTime = Date.now();
+    }
+    /**
+     * Apply tare calibration to the provided sample.
+     * @param {number} sample - The sample to calibrate.
+     * @returns {number} The calibrated tare value.
+     * @protected
+     */
+    applyTare(sample) {
+        if (this.tareActive && this.tareStartTime) {
+            // Add current sample to the tare samples array
+            this.tareSamples.push(sample);
+            // Check if the tare calibration duration has passed
+            if (Date.now() - this.tareStartTime >= this.tareDuration) {
+                // Calculate the average of the tare samples
+                const total = this.tareSamples.reduce((acc, sample) => acc + sample, 0);
+                this.tareCurrent = total / this.tareSamples.length;
+                // Reset the tare calibration process
+                this.tareActive = false;
+                this.tareStartTime = null;
+                this.tareSamples = [];
+            }
+        }
+        // Return the current tare-adjusted value
+        return this.tareCurrent;
+    }
     /**
      * 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.
@@ -280,9 +539,8 @@ export class Device extends BaseModel {
      * @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.
-     *
+     * @public
      * @throws {Error} Throws an error if the characteristic is undefined.
      *
      * @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hangtime/grip-connect",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "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/index.ts

@@ -8,12 +8,3 @@ export {
   WHC06,
   Progressor,
 } from "./models/index"
-
-// helpers
-export { isEntralpi, isKilterBoard, isMotherboard, isWHC06, isProgressor } from "./helpers/is-device"
-
-export { download } from "./helpers/download"
-
-export { active, isActive } from "./helpers/is-active"
-
-export { tare } from "./helpers/tare"

package/src/interfaces/callback.interface.ts

@@ -54,3 +54,10 @@ export type NotifyCallback = (data: massObject) => void
  * @param {string} data - The string data passed to the callback.
  */
 export type WriteCallback = (data: string) => void
+
+/**
+ * Type definition for the callback function that is called when the activity status changes.
+ * @callback ActiveCallback
+ * @param {boolean} value - The new activity status (true if active, false if not).
+ */
+export type ActiveCallback = (data: boolean) => void

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

@@ -4,14 +4,6 @@ import type { IDevice } from "../device.interface"
  * Interface representing the Griptonite Motherboard device.
  */
 export interface IMotherboard extends IDevice {
-  /**
-   * Applies calibration to a 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.

package/src/interfaces/device.interface.ts

@@ -37,24 +37,35 @@ export interface IDevice extends IBase {
   /**
    * Filters to identify the device during Bluetooth scanning.
    * Used to match devices that meet specific criteria such as name, service UUIDs, etc.
+   * @type {BluetoothLEScanFilter[]}
+   * @public
+   * @readonly
    */
   filters: BluetoothLEScanFilter[]
 
   /**
    * Array of services provided by the device.
    * Services represent functionalities that the device supports, such as weight measurement, battery information, or custom services.
+   * @type {Service[]}
+   * @public
+   * @readonly
    */
   services: Service[]
 
   /**
    * Reference to the `BluetoothDevice` object representing this device.
    * This is the actual device object obtained from the Web Bluetooth API after a successful connection.
+   * @type {BluetoothDevice | undefined}
+   * @public
    */
   bluetooth?: BluetoothDevice
 
   /**
    * Object representing the set of commands available for this device.
    * These commands allow communication with the device to perform various operations such as starting measurements, retrieving data, or calibrating the device.
+   * @type {Commands}
+   * @public
+   * @readonly
    */
   commands: Commands
 
@@ -62,6 +73,7 @@ export interface IDevice extends IBase {
    * 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
    */
   connect(onSuccess?: () => void, onError?: (error: Error) => void): Promise<void>
 
@@ -69,32 +81,26 @@ export interface IDevice extends IBase {
    * 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.
+   * @public
    */
   disconnect(): void
 
   /**
-   * Returns UUIDs of all services associated with the device.
-   * @returns {string[]} Array of service UUIDs.
-   */
-  getAllServiceUUIDs(): string[]
-
-  /**
-   * 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: string, characteristicId: string): BluetoothRemoteGATTCharacteristic | undefined
-
-  /**
-   * Handles notifications received from a characteristic.
-   * @param {Event} event - The notification event.
+   * Exports the data in the specified format (CSV, JSON, XML) with a filename format:
+   * 'data-export-YYYY-MM-DD-HH-MM-SS.{format}'.
+   *
+   * @param {('csv' | 'json' | 'xml')} [format='csv'] - The format in which to download the data.
+   * Defaults to 'csv'. Accepted values are 'csv', 'json', and 'xml'.
+   *
+   * @returns {void} Initiates a download of the data in the specified format.
+   * @private
    */
-  handleNotifications(event: Event): void
+  download(format?: "csv" | "json" | "xml"): void
 
   /**
    * Checks if a Bluetooth device is connected.
    * @returns {boolean} A boolean indicating whether the device is connected.
+   * @public
    */
   isConnected(): boolean
 
@@ -102,30 +108,27 @@ export interface IDevice extends IBase {
    * Sets the callback function to be called when notifications are received.
    * @param {NotifyCallback} callback - The callback function to be set.
    * @returns {void}
+   * @public
    */
   notify(callback: (data: massObject) => void): void
 
-  /**
-   * Handles the 'connected' event.
-   * @param {Function} onSuccess - Callback function to execute on successful connection.
-   */
-  onConnected(onSuccess: () => void): Promise<void>
-
-  /**
-   * Handles the 'disconnected' event.
-   * @param {Event} event - The 'disconnected' event.
-   */
-  onDisconnected(event: Event): void
-
   /**
    * 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 | undefined>} A promise that resolves when the read operation is completed.
+   * @public
    */
   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}
+   */
+  tare(duration?: number): void
+
   /**
    * 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.
@@ -133,9 +136,8 @@ export interface IDevice extends IBase {
    * @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.
-   *
+   * @public
    * @throws {Error} Throws an error if the characteristic is undefined.
    *
    * @example

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

@@ -1,8 +1,5 @@
 import { Device } from "../device.model"
 import type { IEntralpi } from "../../interfaces/device/entralpi.interface"
-import { applyTare } from "../../helpers/tare"
-import { checkActivity } from "../../helpers/is-active"
-import { DownloadPackets } from "../../helpers/download"
 
 export class Entralpi extends Device implements IEntralpi {
   constructor() {
@@ -170,10 +167,13 @@ export class Entralpi extends Device implements IEntralpi {
         const receivedData: string = (rawData.getUint16(0) / 100).toFixed(1)
 
         const convertedData = Number(receivedData)
-        // Tare correction
-        const numericData = convertedData - applyTare(convertedData)
+        // Adjust weight by using the tare value
+        // If tare is 0, use the original weight, otherwise subtract tare and invert.
+        // This will display the romoved or 'no-hanging' weight.
+        const tare = this.applyTare(convertedData)
+        const numericData = tare === 0 ? convertedData : (convertedData - tare) * -1
         // Add data to downloadable Array
-        DownloadPackets.push({
+        this.downloadPackets.push({
           received: receivedTime,
           sampleNum: this.dataPointCount,
           battRaw: 0,
@@ -193,7 +193,7 @@ export class Entralpi extends Device implements IEntralpi {
         this.massAverage = (this.massTotalSum / this.dataPointCount).toFixed(1)
 
         // Check if device is being used
-        checkActivity(numericData)
+        this.activityCheck(numericData)
 
         // Notify with weight data
         this.notifyCallback({

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

@@ -1,8 +1,5 @@
 import { Device } from "../device.model"
 import type { IForceBoard } from "../../interfaces/device/forceboard.interface"
-import { DownloadPackets, emptyDownloadPackets } from "../../helpers/download"
-import { checkActivity } from "../../helpers/is-active"
-import { applyTare } from "../../helpers/tare"
 
 /**
  * Represents a PitchSix Force Board device
@@ -198,9 +195,9 @@ export class ForceBoard extends Device implements IForceBoard {
         // Convert from LBS to KG
         const convertedReceivedData = receivedData * 0.453592
         // Tare correction
-        const numericData = convertedReceivedData - applyTare(convertedReceivedData)
+        const numericData = convertedReceivedData - this.applyTare(convertedReceivedData)
         // Add data to downloadable Array
-        DownloadPackets.push({
+        this.downloadPackets.push({
           received: receivedTime,
           sampleNum: this.dataPointCount,
           battRaw: 0,
@@ -220,7 +217,7 @@ export class ForceBoard extends Device implements IForceBoard {
         this.massAverage = (this.massTotalSum / this.dataPointCount).toFixed(1)
 
         // Check if device is being used
-        checkActivity(numericData)
+        this.activityCheck(numericData)
 
         // Notify with weight data
         this.notifyCallback({
@@ -263,7 +260,7 @@ export class ForceBoard extends Device implements IForceBoard {
    */
   stream = async (duration = 0): Promise<void> => {
     // Reset download packets
-    emptyDownloadPackets()
+    this.downloadPackets.length = 0
     // Start streaming data
     await this.write("weight", "tx", new Uint8Array([0x04]), duration) // ASCII control character EOT (End of Transmission)
     // Stop streaming if duration is set