edilkamin 1.10.0 → 1.10.2

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";
 
 /**
@@ -624,6 +631,267 @@ 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;
+
+/**
+ * Derives usage analytics from an existing DeviceInfo response.
+ * This is a pure function that performs client-side calculations without API calls.
+ *
+ * Use this when you already have a DeviceInfo object (e.g., from a previous deviceInfo() call)
+ * to avoid making an additional API request.
+ *
+ * @param {DeviceInfoType} deviceInfo - The device info response object.
+ * @param {number} [serviceThreshold=2000] - Service threshold in hours.
+ * @returns {UsageAnalyticsType} - Comprehensive usage analytics.
+ *
+ * @example
+ * const info = await api.deviceInfo(token, mac);
+ * const analytics = deriveUsageAnalytics(info);
+ */
+export const deriveUsageAnalytics = (
+  deviceInfo: DeviceInfoType,
+  serviceThreshold: number = DEFAULT_SERVICE_THRESHOLD,
+): UsageAnalyticsType => {
+  const totalCounters = deviceInfo.nvm.total_counters;
+  const serviceCounters = deviceInfo.nvm.service_counters;
+  const regeneration = deviceInfo.nvm.regeneration;
+  const alarmsLog = deviceInfo.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: deviceInfo.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 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);
+    return deriveUsageAnalytics(info, serviceThreshold);
+  };
+
 const registerDevice =
   (baseURL: string) =>
   /**
@@ -748,6 +1016,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 {

package/src/types.ts

@@ -24,11 +24,19 @@ interface PelletAutonomyType {
   autonomy_time: number;
 }
 
+/**
+ * Status counters including service time.
+ */
+interface StatusCountersType {
+  service_time: number;
+}
+
 interface StatusType {
   commands: CommandsType;
   temperatures: TemperaturesType;
   flags: GeneralFlagsType;
   pellet: PelletAutonomyType;
+  counters: StatusCountersType;
 }
 
 interface UserParametersType {
@@ -47,10 +55,171 @@ interface UserParametersType {
   language: number;
 }
 
+/**
+ * Lifetime operating counters - never reset.
+ * Tracks total power-on cycles and runtime hours per power level.
+ */
+interface TotalCountersType {
+  power_ons: number;
+  p1_working_time: number;
+  p2_working_time: number;
+  p3_working_time: number;
+  p4_working_time: number;
+  p5_working_time: number;
+}
+
+/**
+ * Service counters - reset after maintenance.
+ * Tracks runtime hours per power level since last service.
+ */
+interface ServiceCountersType {
+  p1_working_time: number;
+  p2_working_time: number;
+  p3_working_time: number;
+  p4_working_time: number;
+  p5_working_time: number;
+}
+
+/**
+ * Individual alarm entry from the alarm history log.
+ */
+interface AlarmEntryType {
+  type: number;
+  timestamp: number;
+}
+
+/**
+ * Alarm history log - circular buffer of recent alarms.
+ */
+interface AlarmsLogType {
+  number: number;
+  index: number;
+  alarms: AlarmEntryType[];
+}
+
+/**
+ * Regeneration and maintenance tracking data.
+ */
+interface RegenerationDataType {
+  time: number;
+  last_intervention: number;
+  daylight_time_flag: number;
+  blackout_counter: number;
+  airkare_working_hours_counter: number;
+}
+
+/**
+ * Power level distribution as percentages.
+ */
+interface PowerDistributionType {
+  p1: number;
+  p2: number;
+  p3: number;
+  p4: number;
+  p5: number;
+}
+
+/**
+ * Service status with computed fields.
+ */
+interface ServiceStatusType {
+  totalServiceHours: number;
+  hoursSinceService: number;
+  serviceThresholdHours: number;
+  isServiceDue: boolean;
+}
+
+/**
+ * Comprehensive usage analytics.
+ */
+interface UsageAnalyticsType {
+  totalPowerOns: number;
+  totalOperatingHours: number;
+  powerDistribution: PowerDistributionType;
+  serviceStatus: ServiceStatusType;
+  blackoutCount: number;
+  lastMaintenanceDate: Date | null;
+  alarmCount: number;
+}
+
+/**
+ * Alarm type codes from Edilkamin devices.
+ * Based on AlarmsEnum.java from Android app (version 1.3.1-RC2 released 2025/12/10).
+ */
+enum AlarmCode {
+  NONE = 0,
+  FLUE_BLOCK = 1,
+  SMOKE_EXTRACTOR_FAILURE = 2,
+  END_PELLET = 3,
+  MISSING_LIGHTING = 4,
+  NO_NAME_ALARM = 5,
+  SMOKE_PROBE_FAILURE = 6,
+  FUMES_OVERTEMPERATURE = 7,
+  PELLET_TANK_SAFETY_THERMOSTAT = 8,
+  GEAR_MOTOR_FAILURE = 9,
+  BOARD_OVER_TEMPERATURE = 10,
+  SAFETY_PRESSURE_SWITCH_INTERVENTION = 11,
+  ROOM_PROBE_FAILURE = 12,
+  ROOM_PROBE_2_OR_BOILER_PROBE_FAILURE = 13,
+  ROOM_PROBE_3_OR_BOILER_PROBE_FAILURE = 14,
+  WATER_EARTHQUAKE_SAFETY_THERMOSTAT_INTERVENTION = 15,
+  WATER_PRESSURE_TRANSDUCER_FAILURE = 16,
+  OUTSIDE_PROBE_OR_LOW_STORAGE_PROBE_FAILURE = 17,
+  PUFFER_PROBE_FAILURE = 18,
+  CRUCIBLE_CLEANING_FAILURE = 19,
+  TRIAC_FAILURE = 20,
+  BLACKOUT = 21,
+  OPEN_DOOR = 22,
+  OVERTEMPERATURE_PANEL = 23,
+  BOARD_FUSE = 24,
+}
+
+/**
+ * Human-readable descriptions for alarm codes.
+ */
+const AlarmDescriptions: Record<AlarmCode, string> = {
+  [AlarmCode.NONE]: "No alarm",
+  [AlarmCode.FLUE_BLOCK]: "Flue/chimney blockage",
+  [AlarmCode.SMOKE_EXTRACTOR_FAILURE]: "Smoke extractor motor failure",
+  [AlarmCode.END_PELLET]: "Pellet tank empty",
+  [AlarmCode.MISSING_LIGHTING]: "Ignition failure",
+  [AlarmCode.NO_NAME_ALARM]: "Unnamed alarm",
+  [AlarmCode.SMOKE_PROBE_FAILURE]: "Smoke temperature probe failure",
+  [AlarmCode.FUMES_OVERTEMPERATURE]: "Exhaust overtemperature",
+  [AlarmCode.PELLET_TANK_SAFETY_THERMOSTAT]:
+    "Pellet tank safety thermostat triggered",
+  [AlarmCode.GEAR_MOTOR_FAILURE]: "Gear motor/auger failure",
+  [AlarmCode.BOARD_OVER_TEMPERATURE]: "Control board overtemperature",
+  [AlarmCode.SAFETY_PRESSURE_SWITCH_INTERVENTION]:
+    "Safety pressure switch activated",
+  [AlarmCode.ROOM_PROBE_FAILURE]: "Room temperature probe failure",
+  [AlarmCode.ROOM_PROBE_2_OR_BOILER_PROBE_FAILURE]:
+    "Room probe 2 or boiler probe failure",
+  [AlarmCode.ROOM_PROBE_3_OR_BOILER_PROBE_FAILURE]:
+    "Room probe 3 or boiler probe failure",
+  [AlarmCode.WATER_EARTHQUAKE_SAFETY_THERMOSTAT_INTERVENTION]:
+    "Water/earthquake safety thermostat",
+  [AlarmCode.WATER_PRESSURE_TRANSDUCER_FAILURE]:
+    "Water pressure transducer failure",
+  [AlarmCode.OUTSIDE_PROBE_OR_LOW_STORAGE_PROBE_FAILURE]:
+    "Outside probe or low storage probe failure",
+  [AlarmCode.PUFFER_PROBE_FAILURE]: "Buffer tank probe failure",
+  [AlarmCode.CRUCIBLE_CLEANING_FAILURE]: "Crucible cleaning failure",
+  [AlarmCode.TRIAC_FAILURE]: "Power control (TRIAC) failure",
+  [AlarmCode.BLACKOUT]: "Power outage detected",
+  [AlarmCode.OPEN_DOOR]: "Door open alarm",
+  [AlarmCode.OVERTEMPERATURE_PANEL]: "Panel overtemperature",
+  [AlarmCode.BOARD_FUSE]: "Control board fuse issue",
+};
+
 interface DeviceInfoType {
   status: StatusType;
   nvm: {
     user_parameters: UserParametersType;
+    total_counters: TotalCountersType;
+    service_counters: ServiceCountersType;
+    alarms_log: AlarmsLogType;
+    regeneration: RegenerationDataType;
   };
 }
 
@@ -115,6 +284,8 @@ interface DiscoveredDevice {
 }
 
 export type {
+  AlarmEntryType,
+  AlarmsLogType,
   BufferEncodedType,
   CommandsType,
   DeviceAssociationBody,
@@ -125,7 +296,16 @@ export type {
   EditDeviceAssociationBody,
   GeneralFlagsType,
   PelletAutonomyType,
+  PowerDistributionType,
+  RegenerationDataType,
+  ServiceCountersType,
+  ServiceStatusType,
+  StatusCountersType,
   StatusType,
   TemperaturesType,
+  TotalCountersType,
+  UsageAnalyticsType,
   UserParametersType,
 };
+
+export { AlarmCode, AlarmDescriptions };