@hangtime/grip-connect 0.10.1 → 0.10.2

package/src/models/device.model.ts

@@ -88,6 +88,14 @@ export abstract class Device extends BaseModel implements IDevice {
    */
   protected mean: number
 
+  /**
+   * Lowest instantaneous force recorded in the session; may be negative.
+   * Initialized to Number.POSITIVE_INFINITY so the first sample sets the min.
+   * @type {number}
+   * @protected
+   */
+  protected min: number
+
   /**
    * Display unit for force measurements (output unit for notify callbacks).
    * @type {ForceUnit}
@@ -109,6 +117,52 @@ export abstract class Device extends BaseModel implements IDevice {
    */
   protected samplingRateHz?: number
 
+  /**
+   * Timestamp (ms) of the previous BLE notification for notify-interval calculation.
+   * @protected
+   */
+  protected lastPacketTimestamp = 0
+
+  /**
+   * Count of data packets received this session (one BLE notification = one packet).
+   * @protected
+   */
+  protected packetCount = 0
+
+  /**
+   * Notify interval in ms for the current packet (set by recordPacketReceived).
+   * @protected
+   */
+  protected currentNotifyIntervalMs: number | undefined = undefined
+
+  /**
+   * Samples in the current packet (set by device before buildForceMeasurement).
+   * @protected
+   */
+  protected currentSamplesPerPacket: number | undefined = undefined
+
+  /**
+   * Call at the start of each BLE notification (packet). Updates notify interval and packet count.
+   * @protected
+   */
+  protected recordPacketReceived(): void {
+    const now = Date.now()
+    this.currentNotifyIntervalMs = this.lastPacketTimestamp > 0 ? now - this.lastPacketTimestamp : undefined
+    this.lastPacketTimestamp = now
+    this.packetCount += 1
+  }
+
+  /**
+   * Reset packet tracking (call when starting a new stream).
+   * @protected
+   */
+  protected resetPacketTracking(): void {
+    this.lastPacketTimestamp = 0
+    this.packetCount = 0
+    this.currentNotifyIntervalMs = undefined
+    this.currentSamplesPerPacket = undefined
+  }
+
   /**
    * Start time of the current rate measurement interval.
    * @type {number}
@@ -234,6 +288,7 @@ export abstract class Device extends BaseModel implements IDevice {
 
     this.peak = Number.NEGATIVE_INFINITY
     this.mean = 0
+    this.min = Number.POSITIVE_INFINITY
     this.sum = 0
     this.dataPointCount = 0
     this.unit = "kg"
@@ -261,17 +316,15 @@ export abstract class Device extends BaseModel implements IDevice {
     const current = valueOrCurrent
     const zonePeak = useFullStats ? (peak === 0 && current < 0 ? current : peak) : valueOrCurrent
     const zoneMean = useFullStats ? mean : valueOrCurrent
-    const zone: ForceMeasurement = {
+    const zoneMin = useFullStats ? Math.min(zonePeak, current) : current
+    return {
       unit: this.unit,
       timestamp: Date.now(),
       current,
       peak: zonePeak,
       mean: zoneMean,
+      min: zoneMin,
     }
-    if (this.samplingRateHz !== undefined) {
-      zone.samplingRateHz = this.samplingRateHz
-    }
-    return zone
   }
 
   /**
@@ -304,49 +357,111 @@ export abstract class Device extends BaseModel implements IDevice {
   }
 
   /**
-   * 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
+   * Shared base for ForceMeasurement/DownloadPacket payload construction.
+   * @private
    */
-  protected buildForceMeasurement(
+  private buildForcePayload(
     current: number,
-    distribution?: {
-      left?: ForceMeasurement
-      center?: ForceMeasurement
-      right?: ForceMeasurement
+    overrides?: {
+      timestamp?: number
+      sampleIndex?: number
+      distribution?: { left?: ForceMeasurement; center?: ForceMeasurement; right?: ForceMeasurement }
     },
   ): ForceMeasurement {
-    this.updateSamplingRate()
+    const timestamp = overrides?.timestamp ?? Date.now()
     const payload: ForceMeasurement = {
       unit: this.unit,
-      timestamp: Date.now(),
+      timestamp,
       current: convertForce(current, this.streamUnit, this.unit),
       peak: convertForce(this.peak, this.streamUnit, this.unit),
       mean: convertForce(this.mean, this.streamUnit, this.unit),
+      min: Number.isFinite(this.min)
+        ? convertForce(this.min, this.streamUnit, this.unit)
+        : convertForce(0, this.streamUnit, this.unit),
+      performance: {
+        packetIndex: this.packetCount,
+        ...(overrides?.sampleIndex != null && { sampleIndex: overrides.sampleIndex }),
+        ...(this.currentNotifyIntervalMs != null && { notifyIntervalMs: this.currentNotifyIntervalMs }),
+        ...(this.currentSamplesPerPacket != null && { samplesPerPacket: this.currentSamplesPerPacket }),
+        ...(this.samplingRateHz != null && { samplingRateHz: this.samplingRateHz }),
+      },
     }
-    if (this.samplingRateHz !== undefined) {
-      payload.samplingRateHz = this.samplingRateHz
-    }
-    if (
-      distribution !== undefined &&
-      (distribution.left !== undefined || distribution.center !== undefined || distribution.right !== undefined)
-    ) {
+
+    const distribution = overrides?.distribution
+    if (distribution && (distribution.left != null || distribution.center != null || distribution.right != null)) {
       payload.distribution = {}
-      if (distribution.left !== undefined) {
+      if (distribution.left != null) {
         payload.distribution.left = convertForceMeasurement(distribution.left, this.streamUnit, this.unit)
       }
-      if (distribution.center !== undefined) {
+      if (distribution.center != null) {
         payload.distribution.center = convertForceMeasurement(distribution.center, this.streamUnit, this.unit)
       }
-      if (distribution.right !== undefined) {
+      if (distribution.right != null) {
         payload.distribution.right = convertForceMeasurement(distribution.right, this.streamUnit, this.unit)
       }
     }
+
     return payload
   }
 
+  /**
+   * Builds a ForceMeasurement payload for notify callbacks.
+   * @param current - Current force at this sample
+   * @param distribution - Optional per-zone measurements (e.g. from buildZoneMeasurement)
+   * @returns ForceMeasurement
+   * @protected
+   */
+  protected buildForceMeasurement(
+    current: number,
+    distribution?: {
+      left?: ForceMeasurement
+      center?: ForceMeasurement
+      right?: ForceMeasurement
+    },
+  ): ForceMeasurement {
+    this.updateSamplingRate()
+    return this.buildForcePayload(
+      current,
+      distribution != null ? { sampleIndex: this.dataPointCount, distribution } : { sampleIndex: this.dataPointCount },
+    )
+  }
+
+  /**
+   * Builds a DownloadPacket for export (CSV, JSON, XML).
+   * Converts force values from streamUnit to display unit.
+   * @param current - Current force at this sample (stream unit)
+   * @param samples - Raw sensor/ADC values from device
+   * @param options - Optional timestamp, battRaw, sampleIndex, distribution (for multi-zone)
+   * @returns DownloadPacket
+   * @protected
+   */
+  protected buildDownloadPacket(
+    current: number,
+    samples: number[],
+    options?: {
+      timestamp?: number
+      battRaw?: number
+      sampleIndex?: number
+      distribution?: { left?: ForceMeasurement; center?: ForceMeasurement; right?: ForceMeasurement }
+    },
+  ): DownloadPacket {
+    const overrides: {
+      timestamp?: number
+      sampleIndex?: number
+      distribution?: { left?: ForceMeasurement; center?: ForceMeasurement; right?: ForceMeasurement }
+    } = {}
+    if (options?.timestamp != null) overrides.timestamp = options.timestamp
+    if (options?.sampleIndex != null) overrides.sampleIndex = options.sampleIndex
+    if (options?.distribution != null) overrides.distribution = options.distribution
+    const packet = this.buildForcePayload(
+      current,
+      Object.keys(overrides).length > 0 ? overrides : undefined,
+    ) as DownloadPacket
+    packet.samples = samples
+    if (options?.battRaw != null) packet.battRaw = options.battRaw
+    return packet
+  }
+
   /**
    * Sets the callback function to be called when the activity status changes,
    * and optionally sets the configuration for threshold and duration.
@@ -523,18 +638,30 @@ export abstract class Device extends BaseModel implements IDevice {
       return ""
     }
     return packets
-      .map((packet) =>
-        [
-          packet.received.toString(),
-          packet.sampleNum.toString(),
-          packet.battRaw.toString(),
+      .map((packet) => {
+        const forceValues =
+          packet.distribution != null
+            ? [
+                packet.distribution.left?.current ?? "",
+                packet.distribution.center?.current ?? "",
+                packet.distribution.right?.current ?? "",
+              ].map((v) => (v !== "" ? String(v) : ""))
+            : [packet.current.toString()]
+        return [
+          packet.timestamp.toString(),
+          packet.current.toString(),
+          packet.peak.toString(),
+          packet.mean.toString(),
+          packet.min.toString(),
+          (packet.performance?.sampleIndex ?? "").toString(),
+          (packet.battRaw ?? "").toString(),
           ...packet.samples.map(String),
-          ...packet.masses.map(String),
+          ...forceValues,
         ]
           .map((v) => v.replace(/"/g, '""'))
           .map((v) => `"${v}"`)
-          .join(","),
-      )
+          .join(",")
+      })
       .join("\r\n")
   }
 
@@ -565,14 +692,27 @@ export abstract class Device extends BaseModel implements IDevice {
     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("")
+        const distributionElements =
+          packet.distribution != null
+            ? [
+                packet.distribution.left?.current != null ? `<left>${packet.distribution.left.current}</left>` : "",
+                packet.distribution.center?.current != null
+                  ? `<center>${packet.distribution.center.current}</center>`
+                  : "",
+                packet.distribution.right?.current != null ? `<right>${packet.distribution.right.current}</right>` : "",
+              ].join("")
+            : ""
         return `
           <packet>
-            <received>${packet.received}</received>
-            <sampleNum>${packet.sampleNum}</sampleNum>
-            <battRaw>${packet.battRaw}</battRaw>
+            <timestamp>${packet.timestamp}</timestamp>
+            <current>${packet.current}</current>
+            <peak>${packet.peak}</peak>
+            <mean>${packet.mean}</mean>
+            <min>${packet.min}</min>
+            ${packet.performance?.sampleIndex != null ? `<sampleIndex>${packet.performance.sampleIndex}</sampleIndex>` : ""}
+            ${packet.battRaw != null ? `<battRaw>${packet.battRaw}</battRaw>` : ""}
             <samples>${samples}</samples>
-            <masses>${masses}</masses>
+            ${distributionElements}
           </packet>
         `
       })
@@ -939,7 +1079,7 @@ export abstract class Device extends BaseModel implements IDevice {
    *
    * @example
    * // Example usage of the write function with a custom callback
-   * await Progressor.write("progressor", "tx", ProgressorCommands.GET_BATT_VLTG, 250, (data) => {
+   * await Progressor.write("progressor", "tx", ProgressorCommands.GET_BATTERY_VOLTAGE, 250, (data) => {
    *   console.log(`Battery voltage: ${data}`);
    * });
    */

package/src/utils.ts

@@ -1,10 +1,34 @@
 import type { ForceMeasurement, ForceUnit } from "./interfaces/callback.interface.js"
 
-/** 1 kg = this many lbs (force-equivalent) */
-const KG_TO_LBS = 2.20462262185
+/** 1 kgf = this many N (standard gravity) */
+const KG_TO_N = 9.80665
+/** 1 lbf = this many N */
+const LBS_TO_N = 4.4482216152605
+
+function toNewtons(value: number, from: ForceUnit): number {
+  switch (from) {
+    case "kg":
+      return value * KG_TO_N
+    case "lbs":
+      return value * LBS_TO_N
+    case "n":
+      return value
+  }
+}
+
+function fromNewtons(value: number, to: ForceUnit): number {
+  switch (to) {
+    case "kg":
+      return value / KG_TO_N
+    case "lbs":
+      return value / LBS_TO_N
+    case "n":
+      return value
+  }
+}
 
 /**
- * Converts a force value between kg and lbs.
+ * Converts a force value between kg, lbs, and newtons.
  * @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.
@@ -12,7 +36,7 @@ const KG_TO_LBS = 2.20462262185
  */
 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
+  return fromNewtons(toNewtons(value, from), to)
 }
 
 /**
@@ -32,9 +56,10 @@ export function convertForceMeasurement(
     current: convertForce(measurement.current, from, to),
     peak: convertForce(measurement.peak, from, to),
     mean: convertForce(measurement.mean, from, to),
+    min: convertForce(measurement.min, from, to),
   }
-  if (measurement.samplingRateHz !== undefined) {
-    out.samplingRateHz = measurement.samplingRateHz
+  if (measurement.performance !== undefined) {
+    out.performance = { ...measurement.performance }
   }
   if (
     measurement.distribution &&