@hangtime/grip-connect 0.9.0 → 0.10.1

package/src/models/device.model.ts

@@ -1,8 +1,15 @@
 import { BaseModel } from "./../models/base.model.js"
 import type { IDevice, Service } from "../interfaces/device.interface.js"
-import type { ActiveCallback, massObject, NotifyCallback, WriteCallback } from "../interfaces/callback.interface.js"
+import type {
+  ActiveCallback,
+  ForceMeasurement,
+  ForceUnit,
+  NotifyCallback,
+  WriteCallback,
+} from "../interfaces/callback.interface.js"
 import type { DownloadPacket } from "../interfaces/download.interface.js"
 import type { Commands } from "../interfaces/command.interface.js"
+import { convertForce, convertForceMeasurement } from "../utils.js"
 
 export abstract class Device extends BaseModel implements IDevice {
   /**
@@ -67,26 +74,62 @@ export abstract class Device extends BaseModel implements IDevice {
   }
 
   /**
-   * Maximum mass recorded from the device, initialized to "0".
-   * @type {string}
+   * Highest instantaneous force (peak) recorded in the session; may be negative.
+   * Initialized to Number.NEGATIVE_INFINITY so the first sample sets the peak.
+   * @type {number}
    * @protected
    */
-  protected massMax: string
+  protected peak: number
 
   /**
-   * Average mass calculated from the device data, initialized to "0".
-   * @type {string}
+   * Mean (average) force over the session, initialized to 0.
+   * @type {number}
    * @protected
    */
-  protected massAverage: string
+  protected mean: number
 
   /**
-   * Total sum of all mass data points recorded from the device.
-   * Used to calculate the average mass.
+   * Display unit for force measurements (output unit for notify callbacks).
+   * @type {ForceUnit}
+   * @protected
+   */
+  protected unit: ForceUnit
+
+  /**
+   * Unit of the values streamed by the device (kg for most devices, lbs for ForceBoard).
+   * @type {ForceUnit}
+   * @protected
+   */
+  protected streamUnit: ForceUnit = "kg"
+
+  /**
+   * Optional sampling rate in Hz when known or calculated from notification timestamps.
+   * @type {number | undefined}
+   * @protected
+   */
+  protected samplingRateHz?: number
+
+  /**
+   * Start time of the current rate measurement interval.
+   * @type {number}
+   * @private
+   */
+  private rateIntervalStart = 0
+
+  /**
+   * Number of samples in the current rate measurement interval.
+   * @type {number}
+   * @private
+   */
+  private rateIntervalSamples = 0
+
+  /**
+   * Running sum of force values for the session.
+   * Used to calculate mean (average) force.
    * @type {number}
    * @protected
    */
-  protected massTotalSum: number
+  protected sum: number
 
   /**
    * Number of data points received from the device.
@@ -135,13 +178,13 @@ export abstract class Device extends BaseModel implements IDevice {
   private tareDuration = 5000
 
   /**
-   * Optional callback for handling write operations.
+   * Optional callback for handling mass/force data notifications.
    * @callback NotifyCallback
-   * @param {massObject} data - The data passed to the callback.
+   * @param {ForceMeasurement} data - The force measurement passed to the callback.
    * @type {NotifyCallback | undefined}
    * @protected
    */
-  protected notifyCallback: NotifyCallback = (data: massObject) => console.log(data)
+  protected notifyCallback: NotifyCallback = (data: ForceMeasurement) => console.log(data)
 
   /**
    * Optional callback for handling write operations.
@@ -189,15 +232,121 @@ export abstract class Device extends BaseModel implements IDevice {
       this.bluetooth = device.bluetooth
     }
 
-    this.massMax = "0"
-    this.massAverage = "0"
-    this.massTotalSum = 0
+    this.peak = Number.NEGATIVE_INFINITY
+    this.mean = 0
+    this.sum = 0
     this.dataPointCount = 0
+    this.unit = "kg"
+
+    // Reset sampling rate calculation state
+    this.rateIntervalStart = 0
+    this.rateIntervalSamples = 0
 
     this.createdAt = new Date()
     this.updatedAt = new Date()
   }
 
+  /**
+   * Builds a ForceMeasurement for a single zone (e.g. left/center/right).
+   * With one argument, current/peak/mean are all set to that value.
+   * With three arguments, uses the given current, peak, and mean for the zone.
+   * @param valueOrCurrent - Force value, or current force for this zone
+   * @param peak - Optional peak for this zone (required if mean is provided)
+   * @param mean - Optional mean for this zone
+   * @returns ForceMeasurement (no nested distribution)
+   * @protected
+   */
+  protected buildZoneMeasurement(valueOrCurrent: number, peak?: number, mean?: number): ForceMeasurement {
+    const useFullStats = peak !== undefined && mean !== undefined
+    const current = valueOrCurrent
+    const zonePeak = useFullStats ? (peak === 0 && current < 0 ? current : peak) : valueOrCurrent
+    const zoneMean = useFullStats ? mean : valueOrCurrent
+    const zone: ForceMeasurement = {
+      unit: this.unit,
+      timestamp: Date.now(),
+      current,
+      peak: zonePeak,
+      mean: zoneMean,
+    }
+    if (this.samplingRateHz !== undefined) {
+      zone.samplingRateHz = this.samplingRateHz
+    }
+    return zone
+  }
+
+  /**
+   * Interval duration (ms) for sampling rate calculation.
+   * @private
+   * @readonly
+   */
+  private static readonly RATE_INTERVAL_MS = 1000
+
+  /**
+   * Calculates sampling rate: samples per second.
+   * Uses fixed intervals to avoid sliding window edge effects.
+   * @private
+   */
+  private updateSamplingRate(): void {
+    const now = Date.now()
+
+    if (this.rateIntervalStart === 0) {
+      this.rateIntervalStart = now
+    }
+
+    this.rateIntervalSamples++
+
+    const elapsed = now - this.rateIntervalStart
+    if (elapsed >= Device.RATE_INTERVAL_MS) {
+      this.samplingRateHz = Math.round((this.rateIntervalSamples / elapsed) * 1000)
+      this.rateIntervalStart = now
+      this.rateIntervalSamples = 0
+    }
+  }
+
+  /**
+   * Builds a ForceMeasurement payload with unit and timestamp for notify callbacks.
+   * @param current - Current force at this sample
+   * @param distribution - Optional zone distribution: numbers (converted via buildZoneMeasurement) or full ForceMeasurement per zone
+   * @returns ForceMeasurement
+   * @protected
+   */
+  protected buildForceMeasurement(
+    current: number,
+    distribution?: {
+      left?: ForceMeasurement
+      center?: ForceMeasurement
+      right?: ForceMeasurement
+    },
+  ): ForceMeasurement {
+    this.updateSamplingRate()
+    const payload: ForceMeasurement = {
+      unit: this.unit,
+      timestamp: Date.now(),
+      current: convertForce(current, this.streamUnit, this.unit),
+      peak: convertForce(this.peak, this.streamUnit, this.unit),
+      mean: convertForce(this.mean, this.streamUnit, this.unit),
+    }
+    if (this.samplingRateHz !== undefined) {
+      payload.samplingRateHz = this.samplingRateHz
+    }
+    if (
+      distribution !== undefined &&
+      (distribution.left !== undefined || distribution.center !== undefined || distribution.right !== undefined)
+    ) {
+      payload.distribution = {}
+      if (distribution.left !== undefined) {
+        payload.distribution.left = convertForceMeasurement(distribution.left, this.streamUnit, this.unit)
+      }
+      if (distribution.center !== undefined) {
+        payload.distribution.center = convertForceMeasurement(distribution.center, this.streamUnit, this.unit)
+      }
+      if (distribution.right !== undefined) {
+        payload.distribution.right = convertForceMeasurement(distribution.right, this.streamUnit, this.unit)
+      }
+    }
+    return payload
+  }
+
   /**
    * Sets the callback function to be called when the activity status changes,
    * and optionally sets the configuration for threshold and duration.
@@ -276,6 +425,28 @@ export abstract class Device extends BaseModel implements IDevice {
 
       const bluetooth = await this.getBluetooth()
 
+      // Experiment: Reconnect to known devices, enable these Chrome flags:
+      // - chrome://flags/#enable-experimental-web-platform-features → enables getDevices() API
+      // - chrome://flags/#enable-web-bluetooth-new-permissions-backend → ensures it returns all permitted devices, not just connected ones
+      // let reconnectDevice: BluetoothDevice | undefined
+      // if (typeof bluetooth.getDevices === "function") {
+      //   const devices: BluetoothDevice[] = await bluetooth.getDevices()
+      //   if (devices.length > 0 && this.filters.length > 0) {
+      //     reconnectDevice = devices.find((device) => {
+      //       if (!device.name) return false
+      //       const d = device
+      //       return this.filters.some(
+      //         (f) => (f.name && d.name === f.name) || (f.namePrefix && d.name?.startsWith(f.namePrefix)),
+      //       )
+      //     })
+      //   }
+      //   if (reconnectDevice) {
+      //     this.bluetooth = reconnectDevice
+      //     // It's currently impossible to call this.bluetooth.gatt.connect() here.
+      //     // After restarting the Browser, it will always give: "Bluetooth Device is no longer in range."
+      //   }
+      // }
+
       this.bluetooth = await bluetooth.requestDevice({
         filters: this.filters,
         optionalServices: deviceServices,
@@ -540,6 +711,7 @@ export abstract class Device extends BaseModel implements IDevice {
   /**
    * Sets the callback function to be called when notifications are received.
    * @param {NotifyCallback} callback - The callback function to be set.
+   * @param {ForceUnit} [unit="kg"] - Optional display unit for force values in the callback payload.
    * @returns {void}
    * @public
    *
@@ -547,8 +719,10 @@ export abstract class Device extends BaseModel implements IDevice {
    * device.notify((data) => {
    *   console.log('Received notification:', data);
    * });
+   * device.notify((data) => { ... }, 'lbs');
    */
-  notify = (callback: NotifyCallback): void => {
+  notify = (callback: NotifyCallback, unit?: ForceUnit): void => {
+    this.unit = unit ?? "kg"
     this.notifyCallback = callback
   }
 

package/src/models/index.ts

@@ -4,12 +4,14 @@ export { Entralpi } from "./device/entralpi.model.js"
 
 export { ForceBoard } from "./device/forceboard.model.js"
 
-export { KilterBoard } from "./device/kilterboard.model.js"
+export { KilterBoard, KilterBoardPlacementRoles } from "./device/kilterboard.model.js"
 
 export { Motherboard } from "./device/motherboard.model.js"
 
 export { mySmartBoard } from "./device/mysmartboard.model.js"
 
+export { PB700BT } from "./device/pb-700bt.model.js"
+
 export { Progressor } from "./device/progressor.model.js"
 
 export { SmartBoardPro } from "./device/smartboard-pro.model.js"

package/src/utils.ts

@@ -0,0 +1,57 @@
+import type { ForceMeasurement, ForceUnit } from "./interfaces/callback.interface.js"
+
+/** 1 kg = this many lbs (force-equivalent) */
+const KG_TO_LBS = 2.20462262185
+
+/**
+ * Converts a force value between kg and lbs.
+ * @param value - The numeric force value in the source unit.
+ * @param from - The unit of the input value.
+ * @param to - The unit for the output value.
+ * @returns The force value in the target unit.
+ */
+export function convertForce(value: number, from: ForceUnit, to: ForceUnit): number {
+  if (from === to) return value
+  return from === "kg" ? value * KG_TO_LBS : value / KG_TO_LBS
+}
+
+/**
+ * Converts all numeric force fields in a ForceMeasurement from one unit to another.
+ * Recurses one level into distribution.left / center / right.
+ * Used internally by the device model when building notify payloads.
+ */
+export function convertForceMeasurement(
+  measurement: ForceMeasurement,
+  from: ForceUnit,
+  to: ForceUnit,
+): ForceMeasurement {
+  if (from === to) return measurement
+  const out: ForceMeasurement = {
+    unit: to,
+    timestamp: measurement.timestamp,
+    current: convertForce(measurement.current, from, to),
+    peak: convertForce(measurement.peak, from, to),
+    mean: convertForce(measurement.mean, from, to),
+  }
+  if (measurement.samplingRateHz !== undefined) {
+    out.samplingRateHz = measurement.samplingRateHz
+  }
+  if (
+    measurement.distribution &&
+    (measurement.distribution.left !== undefined ||
+      measurement.distribution.center !== undefined ||
+      measurement.distribution.right !== undefined)
+  ) {
+    out.distribution = {}
+    if (measurement.distribution.left !== undefined) {
+      out.distribution.left = convertForceMeasurement(measurement.distribution.left, from, to)
+    }
+    if (measurement.distribution.center !== undefined) {
+      out.distribution.center = convertForceMeasurement(measurement.distribution.center, from, to)
+    }
+    if (measurement.distribution.right !== undefined) {
+      out.distribution.right = convertForceMeasurement(measurement.distribution.right, from, to)
+    }
+  }
+  return out
+}