edilkamin 1.9.0 → 1.10.1

package/src/library.ts

@@ -6,11 +6,18 @@ import { cognitoUserPoolsTokenProvider } from "aws-amplify/auth/cognito";
 import { processResponse } from "./buffer-utils";
 import { API_URL } from "./constants";
 import {
+  AlarmsLogType,
   DeviceAssociationBody,
   DeviceAssociationResponse,
   DeviceInfoRawType,
   DeviceInfoType,
   EditDeviceAssociationBody,
+  PowerDistributionType,
+  RegenerationDataType,
+  ServiceCountersType,
+  ServiceStatusType,
+  TotalCountersType,
+  UsageAnalyticsType,
 } from "./types";
 
 /**
@@ -236,95 +243,71 @@ const getPowerLevel =
     return info.nvm.user_parameters.manual_power;
   };
 
-const setFan1Speed =
+const setFanSpeed =
   (baseURL: string) =>
   /**
-   * Sets the speed of fan 1.
+   * Sets the speed of a fan by index.
    *
    * @param {string} jwtToken - The JWT token for authentication.
    * @param {string} macAddress - The MAC address of the device.
+   * @param {1 | 2 | 3} fanIndex - The fan index (1, 2, or 3).
    * @param {number} speed - The fan speed (0-5, 0=auto on some models).
    * @returns {Promise<unknown>} - A promise that resolves to the command response.
    */
-  (jwtToken: string, macAddress: string, speed: number) =>
+  (jwtToken: string, macAddress: string, fanIndex: 1 | 2 | 3, speed: number) =>
     mqttCommand(baseURL)(jwtToken, macAddress, {
-      name: "fan_1_speed",
+      name: `fan_${fanIndex}_speed`,
       value: speed,
     });
 
-const setFan2Speed =
+const getFanSpeed =
   (baseURL: string) =>
   /**
-   * Sets the speed of fan 2.
+   * Retrieves the current speed of a fan by index.
    *
    * @param {string} jwtToken - The JWT token for authentication.
    * @param {string} macAddress - The MAC address of the device.
-   * @param {number} speed - The fan speed (0-5, 0=auto on some models).
-   * @returns {Promise<unknown>} - A promise that resolves to the command response.
+   * @param {1 | 2 | 3} fanIndex - The fan index (1, 2, or 3).
+   * @returns {Promise<number>} - A promise that resolves to the fan speed.
    */
-  (jwtToken: string, macAddress: string, speed: number) =>
-    mqttCommand(baseURL)(jwtToken, macAddress, {
-      name: "fan_2_speed",
-      value: speed,
-    });
+  async (
+    jwtToken: string,
+    macAddress: string,
+    fanIndex: 1 | 2 | 3,
+  ): Promise<number> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    const fields: Record<1 | 2 | 3, number> = {
+      1: info.nvm.user_parameters.fan_1_ventilation,
+      2: info.nvm.user_parameters.fan_2_ventilation,
+      3: info.nvm.user_parameters.fan_3_ventilation,
+    };
+    return fields[fanIndex];
+  };
+
+// Fan speed aliases for convenience
+const setFan1Speed =
+  (baseURL: string) => (jwtToken: string, macAddress: string, speed: number) =>
+    setFanSpeed(baseURL)(jwtToken, macAddress, 1, speed);
+
+const setFan2Speed =
+  (baseURL: string) => (jwtToken: string, macAddress: string, speed: number) =>
+    setFanSpeed(baseURL)(jwtToken, macAddress, 2, speed);
 
 const setFan3Speed =
-  (baseURL: string) =>
-  /**
-   * Sets the speed of fan 3.
-   *
-   * @param {string} jwtToken - The JWT token for authentication.
-   * @param {string} macAddress - The MAC address of the device.
-   * @param {number} speed - The fan speed (0-5, 0=auto on some models).
-   * @returns {Promise<unknown>} - A promise that resolves to the command response.
-   */
-  (jwtToken: string, macAddress: string, speed: number) =>
-    mqttCommand(baseURL)(jwtToken, macAddress, {
-      name: "fan_3_speed",
-      value: speed,
-    });
+  (baseURL: string) => (jwtToken: string, macAddress: string, speed: number) =>
+    setFanSpeed(baseURL)(jwtToken, macAddress, 3, speed);
 
 const getFan1Speed =
-  (baseURL: string) =>
-  /**
-   * Retrieves the current speed of fan 1.
-   *
-   * @param {string} jwtToken - The JWT token for authentication.
-   * @param {string} macAddress - The MAC address of the device.
-   * @returns {Promise<number>} - A promise that resolves to the fan speed.
-   */
-  async (jwtToken: string, macAddress: string): Promise<number> => {
-    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
-    return info.nvm.user_parameters.fan_1_ventilation;
-  };
+  (baseURL: string) => (jwtToken: string, macAddress: string) =>
+    getFanSpeed(baseURL)(jwtToken, macAddress, 1);
 
 const getFan2Speed =
-  (baseURL: string) =>
-  /**
-   * Retrieves the current speed of fan 2.
-   *
-   * @param {string} jwtToken - The JWT token for authentication.
-   * @param {string} macAddress - The MAC address of the device.
-   * @returns {Promise<number>} - A promise that resolves to the fan speed.
-   */
-  async (jwtToken: string, macAddress: string): Promise<number> => {
-    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
-    return info.nvm.user_parameters.fan_2_ventilation;
-  };
+  (baseURL: string) => (jwtToken: string, macAddress: string) =>
+    getFanSpeed(baseURL)(jwtToken, macAddress, 2);
 
 const getFan3Speed =
-  (baseURL: string) =>
-  /**
-   * Retrieves the current speed of fan 3.
-   *
-   * @param {string} jwtToken - The JWT token for authentication.
-   * @param {string} macAddress - The MAC address of the device.
-   * @returns {Promise<number>} - A promise that resolves to the fan speed.
-   */
-  async (jwtToken: string, macAddress: string): Promise<number> => {
-    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
-    return info.nvm.user_parameters.fan_3_ventilation;
-  };
+  (baseURL: string) => (jwtToken: string, macAddress: string) =>
+    getFanSpeed(baseURL)(jwtToken, macAddress, 3);
 
 const setAirkare =
   (baseURL: string) =>
@@ -479,92 +462,76 @@ const getEnvironmentTemperature =
 const getTargetTemperature =
   (baseURL: string) =>
   /**
-   * Retrieves the target temperature value set on the device.
+   * Retrieves the target temperature for an environment zone.
    *
    * @param {string} jwtToken - The JWT token for authentication.
    * @param {string} macAddress - The MAC address of the device.
-   * @returns {Promise<number>} - A promise that resolves to the target temperature (degree celsius).
+   * @param {1 | 2 | 3} envIndex - The environment zone index (1, 2, or 3).
+   * @returns {Promise<number>} - A promise that resolves to the target temperature (degrees Celsius).
    */
-  async (jwtToken: string, macAddress: string): Promise<number> => {
+  async (
+    jwtToken: string,
+    macAddress: string,
+    envIndex: 1 | 2 | 3,
+  ): Promise<number> => {
     const info = await deviceInfo(baseURL)(jwtToken, macAddress);
-    return info.nvm.user_parameters.enviroment_1_temperature;
+    const fields: Record<1 | 2 | 3, number> = {
+      1: info.nvm.user_parameters.enviroment_1_temperature,
+      2: info.nvm.user_parameters.enviroment_2_temperature,
+      3: info.nvm.user_parameters.enviroment_3_temperature,
+    };
+    return fields[envIndex];
   };
 
 const setTargetTemperature =
   (baseURL: string) =>
   /**
-   * Sends a command to set the target temperature (degree celsius) of a device.
+   * Sets the target temperature for an environment zone.
    *
    * @param {string} jwtToken - The JWT token for authentication.
    * @param {string} macAddress - The MAC address of the device.
-   * @param {number} temperature - The desired target temperature (degree celsius).
-   * @returns {Promise<string>} - A promise that resolves to the command response.
+   * @param {1 | 2 | 3} envIndex - The environment zone index (1, 2, or 3).
+   * @param {number} temperature - The desired target temperature (degrees Celsius).
+   * @returns {Promise<unknown>} - A promise that resolves to the command response.
    */
-  (jwtToken: string, macAddress: string, temperature: number) =>
+  (
+    jwtToken: string,
+    macAddress: string,
+    envIndex: 1 | 2 | 3,
+    temperature: number,
+  ) =>
     mqttCommand(baseURL)(jwtToken, macAddress, {
-      name: "enviroment_1_temperature",
+      name: `enviroment_${envIndex}_temperature`,
       value: temperature,
     });
 
-const setEnvironment2Temperature =
+// Environment temperature aliases for convenience
+const setEnvironment1Temperature =
   (baseURL: string) =>
-  /**
-   * Sets the target temperature for Environment 2 zone.
-   *
-   * @param {string} jwtToken - The JWT token for authentication.
-   * @param {string} macAddress - The MAC address of the device.
-   * @param {number} temperature - The target temperature in degrees Celsius.
-   * @returns {Promise<unknown>} - A promise that resolves to the command response.
-   */
   (jwtToken: string, macAddress: string, temperature: number) =>
-    mqttCommand(baseURL)(jwtToken, macAddress, {
-      name: "enviroment_2_temperature",
-      value: temperature,
-    });
+    setTargetTemperature(baseURL)(jwtToken, macAddress, 1, temperature);
 
-const getEnvironment2Temperature =
+const setEnvironment2Temperature =
   (baseURL: string) =>
-  /**
-   * Retrieves the target temperature for Environment 2 zone.
-   *
-   * @param {string} jwtToken - The JWT token for authentication.
-   * @param {string} macAddress - The MAC address of the device.
-   * @returns {Promise<number>} - A promise that resolves to the temperature in degrees Celsius.
-   */
-  async (jwtToken: string, macAddress: string): Promise<number> => {
-    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
-    return info.nvm.user_parameters.enviroment_2_temperature;
-  };
+  (jwtToken: string, macAddress: string, temperature: number) =>
+    setTargetTemperature(baseURL)(jwtToken, macAddress, 2, temperature);
 
 const setEnvironment3Temperature =
   (baseURL: string) =>
-  /**
-   * Sets the target temperature for Environment 3 zone.
-   *
-   * @param {string} jwtToken - The JWT token for authentication.
-   * @param {string} macAddress - The MAC address of the device.
-   * @param {number} temperature - The target temperature in degrees Celsius.
-   * @returns {Promise<unknown>} - A promise that resolves to the command response.
-   */
   (jwtToken: string, macAddress: string, temperature: number) =>
-    mqttCommand(baseURL)(jwtToken, macAddress, {
-      name: "enviroment_3_temperature",
-      value: temperature,
-    });
+    setTargetTemperature(baseURL)(jwtToken, macAddress, 3, temperature);
+
+const getEnvironment1Temperature =
+  (baseURL: string) => (jwtToken: string, macAddress: string) =>
+    getTargetTemperature(baseURL)(jwtToken, macAddress, 1);
+
+const getEnvironment2Temperature =
+  (baseURL: string) => (jwtToken: string, macAddress: string) =>
+    getTargetTemperature(baseURL)(jwtToken, macAddress, 2);
 
 const getEnvironment3Temperature =
-  (baseURL: string) =>
-  /**
-   * Retrieves the target temperature for Environment 3 zone.
-   *
-   * @param {string} jwtToken - The JWT token for authentication.
-   * @param {string} macAddress - The MAC address of the device.
-   * @returns {Promise<number>} - A promise that resolves to the temperature in degrees Celsius.
-   */
-  async (jwtToken: string, macAddress: string): Promise<number> => {
-    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
-    return info.nvm.user_parameters.enviroment_3_temperature;
-  };
+  (baseURL: string) => (jwtToken: string, macAddress: string) =>
+    getTargetTemperature(baseURL)(jwtToken, macAddress, 3);
 
 const setMeasureUnit =
   (baseURL: string) =>
@@ -664,6 +631,246 @@ const getPelletAutonomyTime =
     return info.status.pellet.autonomy_time;
   };
 
+const getTotalCounters =
+  (baseURL: string) =>
+  /**
+   * Retrieves lifetime operating counters.
+   * Includes power-on count and runtime hours per power level.
+   * These counters are never reset.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<TotalCountersType>} - Lifetime operating statistics.
+   */
+  async (jwtToken: string, macAddress: string): Promise<TotalCountersType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.nvm.total_counters;
+  };
+
+const getServiceCounters =
+  (baseURL: string) =>
+  /**
+   * Retrieves service counters (runtime since last maintenance).
+   * These counters track hours per power level since last service reset.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<ServiceCountersType>} - Service tracking statistics.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+  ): Promise<ServiceCountersType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.nvm.service_counters;
+  };
+
+const getAlarmHistory =
+  (baseURL: string) =>
+  /**
+   * Retrieves the alarm history log.
+   * Contains a circular buffer of recent alarms with timestamps.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<AlarmsLogType>} - Alarm history log.
+   */
+  async (jwtToken: string, macAddress: string): Promise<AlarmsLogType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.nvm.alarms_log;
+  };
+
+const getRegenerationData =
+  (baseURL: string) =>
+  /**
+   * Retrieves regeneration and maintenance data.
+   * Includes blackout counter and last intervention timestamp.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<RegenerationDataType>} - Maintenance tracking data.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+  ): Promise<RegenerationDataType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.nvm.regeneration;
+  };
+
+const getServiceTime =
+  (baseURL: string) =>
+  /**
+   * Retrieves the total service time in hours.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<number>} - Total service hours.
+   */
+  async (jwtToken: string, macAddress: string): Promise<number> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.status.counters.service_time;
+  };
+
+/**
+ * Default service threshold in hours (from OEM parameters).
+ * Most devices use 2000 hours.
+ */
+const DEFAULT_SERVICE_THRESHOLD = 2000;
+
+const getTotalOperatingHours =
+  (baseURL: string) =>
+  /**
+   * Calculates total operating hours across all power levels.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<number>} - Total operating hours.
+   */
+  async (jwtToken: string, macAddress: string): Promise<number> => {
+    const counters = await getTotalCounters(baseURL)(jwtToken, macAddress);
+    return (
+      counters.p1_working_time +
+      counters.p2_working_time +
+      counters.p3_working_time +
+      counters.p4_working_time +
+      counters.p5_working_time
+    );
+  };
+
+const getPowerDistribution =
+  (baseURL: string) =>
+  /**
+   * Calculates power level usage distribution as percentages.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<PowerDistributionType>} - Percentage time at each power level.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+  ): Promise<PowerDistributionType> => {
+    const counters = await getTotalCounters(baseURL)(jwtToken, macAddress);
+    const total =
+      counters.p1_working_time +
+      counters.p2_working_time +
+      counters.p3_working_time +
+      counters.p4_working_time +
+      counters.p5_working_time;
+
+    if (total === 0) {
+      return { p1: 0, p2: 0, p3: 0, p4: 0, p5: 0 };
+    }
+
+    return {
+      p1: (counters.p1_working_time / total) * 100,
+      p2: (counters.p2_working_time / total) * 100,
+      p3: (counters.p3_working_time / total) * 100,
+      p4: (counters.p4_working_time / total) * 100,
+      p5: (counters.p5_working_time / total) * 100,
+    };
+  };
+
+const getServiceStatus =
+  (baseURL: string) =>
+  /**
+   * Calculates service status including whether maintenance is due.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @param {number} [thresholdHours=2000] - Service threshold in hours.
+   * @returns {Promise<ServiceStatusType>} - Service status with computed fields.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+    thresholdHours: number = DEFAULT_SERVICE_THRESHOLD,
+  ): Promise<ServiceStatusType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    const serviceCounters = info.nvm.service_counters;
+    const hoursSinceService =
+      serviceCounters.p1_working_time +
+      serviceCounters.p2_working_time +
+      serviceCounters.p3_working_time +
+      serviceCounters.p4_working_time +
+      serviceCounters.p5_working_time;
+
+    return {
+      totalServiceHours: info.status.counters.service_time,
+      hoursSinceService,
+      serviceThresholdHours: thresholdHours,
+      isServiceDue: hoursSinceService >= thresholdHours,
+    };
+  };
+
+const getUsageAnalytics =
+  (baseURL: string) =>
+  /**
+   * Retrieves comprehensive usage analytics in a single call.
+   * Combines multiple statistics into a unified analytics object.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @param {number} [serviceThreshold=2000] - Service threshold in hours.
+   * @returns {Promise<UsageAnalyticsType>} - Comprehensive usage analytics.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+    serviceThreshold: number = DEFAULT_SERVICE_THRESHOLD,
+  ): Promise<UsageAnalyticsType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+
+    const totalCounters = info.nvm.total_counters;
+    const serviceCounters = info.nvm.service_counters;
+    const regeneration = info.nvm.regeneration;
+    const alarmsLog = info.nvm.alarms_log;
+
+    const totalOperatingHours =
+      totalCounters.p1_working_time +
+      totalCounters.p2_working_time +
+      totalCounters.p3_working_time +
+      totalCounters.p4_working_time +
+      totalCounters.p5_working_time;
+
+    const hoursSinceService =
+      serviceCounters.p1_working_time +
+      serviceCounters.p2_working_time +
+      serviceCounters.p3_working_time +
+      serviceCounters.p4_working_time +
+      serviceCounters.p5_working_time;
+
+    const powerDistribution: PowerDistributionType =
+      totalOperatingHours === 0
+        ? { p1: 0, p2: 0, p3: 0, p4: 0, p5: 0 }
+        : {
+            p1: (totalCounters.p1_working_time / totalOperatingHours) * 100,
+            p2: (totalCounters.p2_working_time / totalOperatingHours) * 100,
+            p3: (totalCounters.p3_working_time / totalOperatingHours) * 100,
+            p4: (totalCounters.p4_working_time / totalOperatingHours) * 100,
+            p5: (totalCounters.p5_working_time / totalOperatingHours) * 100,
+          };
+
+    return {
+      totalPowerOns: totalCounters.power_ons,
+      totalOperatingHours,
+      powerDistribution,
+      serviceStatus: {
+        totalServiceHours: info.status.counters.service_time,
+        hoursSinceService,
+        serviceThresholdHours: serviceThreshold,
+        isServiceDue: hoursSinceService >= serviceThreshold,
+      },
+      blackoutCount: regeneration.blackout_counter,
+      lastMaintenanceDate:
+        regeneration.last_intervention > 0
+          ? new Date(regeneration.last_intervention * 1000)
+          : null,
+      alarmCount: alarmsLog.number,
+    };
+  };
+
 const registerDevice =
   (baseURL: string) =>
   /**
@@ -757,6 +964,8 @@ const configure = (baseURL: string = API_URL) => ({
   getPower: getPower(baseURL),
   setPowerLevel: setPowerLevel(baseURL),
   getPowerLevel: getPowerLevel(baseURL),
+  setFanSpeed: setFanSpeed(baseURL),
+  getFanSpeed: getFanSpeed(baseURL),
   setFan1Speed: setFan1Speed(baseURL),
   setFan2Speed: setFan2Speed(baseURL),
   setFan3Speed: setFan3Speed(baseURL),
@@ -774,6 +983,8 @@ const configure = (baseURL: string = API_URL) => ({
   getEnvironmentTemperature: getEnvironmentTemperature(baseURL),
   getTargetTemperature: getTargetTemperature(baseURL),
   setTargetTemperature: setTargetTemperature(baseURL),
+  setEnvironment1Temperature: setEnvironment1Temperature(baseURL),
+  getEnvironment1Temperature: getEnvironment1Temperature(baseURL),
   setEnvironment2Temperature: setEnvironment2Temperature(baseURL),
   getEnvironment2Temperature: getEnvironment2Temperature(baseURL),
   setEnvironment3Temperature: setEnvironment3Temperature(baseURL),
@@ -784,6 +995,17 @@ const configure = (baseURL: string = API_URL) => ({
   getLanguage: getLanguage(baseURL),
   getPelletInReserve: getPelletInReserve(baseURL),
   getPelletAutonomyTime: getPelletAutonomyTime(baseURL),
+  // Statistics getters
+  getTotalCounters: getTotalCounters(baseURL),
+  getServiceCounters: getServiceCounters(baseURL),
+  getAlarmHistory: getAlarmHistory(baseURL),
+  getRegenerationData: getRegenerationData(baseURL),
+  getServiceTime: getServiceTime(baseURL),
+  // Analytics functions
+  getTotalOperatingHours: getTotalOperatingHours(baseURL),
+  getPowerDistribution: getPowerDistribution(baseURL),
+  getServiceStatus: getServiceStatus(baseURL),
+  getUsageAnalytics: getUsageAnalytics(baseURL),
 });
 
 export {