edilkamin 1.10.1 → 1.11.0

package/dist/cjs/src/library.test.js

@@ -1014,6 +1014,139 @@ describe("library", () => {
             assert_1.strict.equal(result.lastMaintenanceDate, null);
         }));
     });
+    describe("deriveUsageAnalytics", () => {
+        const mockDeviceInfoForDerive = {
+            status: {
+                commands: {
+                    power: false,
+                },
+                temperatures: {
+                    enviroment: 20,
+                    set_air: 21,
+                    get_air: 20,
+                    set_water: 40,
+                    get_water: 35,
+                },
+                counters: {
+                    service_time: 1108,
+                },
+                flags: {
+                    is_pellet_in_reserve: false,
+                },
+                pellet: {
+                    autonomy_time: 180,
+                },
+            },
+            nvm: {
+                user_parameters: {
+                    language: 1,
+                    is_auto: false,
+                    is_fahrenheit: false,
+                    is_sound_active: false,
+                    enviroment_1_temperature: 19,
+                    enviroment_2_temperature: 20,
+                    enviroment_3_temperature: 20,
+                    manual_power: 1,
+                    fan_1_ventilation: 3,
+                    fan_2_ventilation: 0,
+                    fan_3_ventilation: 0,
+                    is_standby_active: false,
+                    standby_waiting_time: 60,
+                },
+                total_counters: {
+                    power_ons: 278,
+                    p1_working_time: 833,
+                    p2_working_time: 15,
+                    p3_working_time: 19,
+                    p4_working_time: 8,
+                    p5_working_time: 17,
+                },
+                service_counters: {
+                    p1_working_time: 100,
+                    p2_working_time: 10,
+                    p3_working_time: 5,
+                    p4_working_time: 2,
+                    p5_working_time: 1,
+                },
+                regeneration: {
+                    time: 0,
+                    last_intervention: 1577836800,
+                    daylight_time_flag: 0,
+                    blackout_counter: 43,
+                    airkare_working_hours_counter: 0,
+                },
+                alarms_log: {
+                    number: 6,
+                    index: 6,
+                    alarms: [],
+                },
+            },
+        };
+        it("should derive analytics from device info without API call", () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const analytics = (0, library_1.deriveUsageAnalytics)(mockDeviceInfoForDerive);
+            assert_1.strict.equal(analytics.totalPowerOns, 278);
+            assert_1.strict.equal(analytics.totalOperatingHours, 892); // 833+15+19+8+17
+            assert_1.strict.equal(analytics.blackoutCount, 43);
+            assert_1.strict.equal(analytics.alarmCount, 6);
+        });
+        it("should calculate power distribution correctly", () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const analytics = (0, library_1.deriveUsageAnalytics)(mockDeviceInfoForDerive);
+            // P1: 833/892 ≈ 93.4%
+            assert_1.strict.ok(analytics.powerDistribution.p1 > 93);
+            assert_1.strict.ok(analytics.powerDistribution.p1 < 94);
+            // Sum should be 100%
+            const sum = Object.values(analytics.powerDistribution).reduce((a, b) => a + b, 0);
+            assert_1.strict.ok(Math.abs(sum - 100) < 0.001);
+        });
+        it("should handle zero operating hours", () => {
+            const zeroHoursInfo = Object.assign(Object.assign({}, mockDeviceInfoForDerive), { nvm: Object.assign(Object.assign({}, mockDeviceInfoForDerive.nvm), { total_counters: {
+                        power_ons: 0,
+                        p1_working_time: 0,
+                        p2_working_time: 0,
+                        p3_working_time: 0,
+                        p4_working_time: 0,
+                        p5_working_time: 0,
+                    } }) });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const analytics = (0, library_1.deriveUsageAnalytics)(zeroHoursInfo);
+            assert_1.strict.deepEqual(analytics.powerDistribution, {
+                p1: 0,
+                p2: 0,
+                p3: 0,
+                p4: 0,
+                p5: 0,
+            });
+        });
+        it("should respect custom service threshold", () => {
+            const analytics = (0, library_1.deriveUsageAnalytics)(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mockDeviceInfoForDerive, 100);
+            // 118 hours since service >= 100 threshold
+            assert_1.strict.equal(analytics.serviceStatus.isServiceDue, true);
+            assert_1.strict.equal(analytics.serviceStatus.serviceThresholdHours, 100);
+        });
+        it("should use default threshold of 2000 hours", () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const analytics = (0, library_1.deriveUsageAnalytics)(mockDeviceInfoForDerive);
+            assert_1.strict.equal(analytics.serviceStatus.serviceThresholdHours, 2000);
+            assert_1.strict.equal(analytics.serviceStatus.isServiceDue, false); // 118 < 2000
+        });
+        it("should convert last_intervention timestamp to Date", () => {
+            var _a;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const analytics = (0, library_1.deriveUsageAnalytics)(mockDeviceInfoForDerive);
+            assert_1.strict.ok(analytics.lastMaintenanceDate instanceof Date);
+            assert_1.strict.equal((_a = analytics.lastMaintenanceDate) === null || _a === void 0 ? void 0 : _a.getTime(), 1577836800 * 1000);
+        });
+        it("should return null for lastMaintenanceDate when timestamp is 0", () => {
+            const noMaintenanceInfo = Object.assign(Object.assign({}, mockDeviceInfoForDerive), { nvm: Object.assign(Object.assign({}, mockDeviceInfoForDerive.nvm), { regeneration: Object.assign(Object.assign({}, mockDeviceInfoForDerive.nvm.regeneration), { last_intervention: 0 }) }) });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const analytics = (0, library_1.deriveUsageAnalytics)(noMaintenanceInfo);
+            assert_1.strict.equal(analytics.lastMaintenanceDate, null);
+        });
+    });
     describe("Error Handling", () => {
         const errorTests = [
             { status: 400, statusText: "Bad Request" },

package/dist/esm/package.json

@@ -1,6 +1,6 @@
 {
     "name": "edilkamin",
-    "version": "1.10.1",
+    "version": "1.11.0",
     "description": "",
     "main": "dist/cjs/src/index.js",
     "module": "dist/esm/src/index.js",

package/dist/esm/src/bluetooth-protocol.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Edilkamin BLE Protocol Implementation
+ *
+ * Transport-agnostic protocol layer for communicating with Edilkamin stoves via BLE.
+ * Handles AES-128-CBC encryption, CRC16-Modbus checksums, and Modbus packet building/parsing.
+ *
+ * The consuming application is responsible for:
+ * - BLE device scanning and connection
+ * - Writing to BLE characteristics
+ * - Subscribing to BLE notifications
+ *
+ * Protocol details derived from: https://github.com/netmb/Edilkamin_BT
+ */
+/** Edilkamin GATT service UUID */
+export declare const SERVICE_UUID = "0000abf0-0000-1000-8000-00805f9b34fb";
+/** Write characteristic UUID (WRITE NO RESPONSE) */
+export declare const WRITE_CHARACTERISTIC_UUID = "0000abf1-0000-1000-8000-00805f9b34fb";
+/** Notify characteristic UUID (NOTIFY) */
+export declare const NOTIFY_CHARACTERISTIC_UUID = "0000abf2-0000-1000-8000-00805f9b34fb";
+/**
+ * Parsed Modbus response from the device.
+ */
+export interface ModbusResponse {
+    /** Slave address (always 0x01 for Edilkamin) */
+    slaveAddress: number;
+    /** Function code (0x03 for read, 0x06 for write) */
+    functionCode: number;
+    /** Byte count (for read responses) */
+    byteCount?: number;
+    /** Response data */
+    data: Uint8Array;
+    /** Whether the response indicates an error */
+    isError: boolean;
+}
+/**
+ * Calculate CRC16-Modbus checksum.
+ *
+ * @param data - Data to calculate CRC for
+ * @returns 2-byte CRC in little-endian order [crcLo, crcHi]
+ */
+export declare const crc16Modbus: (data: Uint8Array) => Uint8Array;
+/**
+ * Encrypt data using AES-128-CBC (raw, without PKCS7 padding).
+ *
+ * This manually applies PKCS7 padding to make input a multiple of 16 bytes,
+ * encrypts with Web Crypto, then strips the extra padding block from output.
+ *
+ * @param plaintext - Data to encrypt (must be 32 bytes)
+ * @returns Encrypted data (32 bytes)
+ */
+export declare const aesEncrypt: (plaintext: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Decrypt data using AES-128-CBC (raw, handling PKCS7 padding).
+ *
+ * @param ciphertext - Data to decrypt (must be 32 bytes)
+ * @returns Decrypted data (32 bytes)
+ */
+export declare const aesDecrypt: (ciphertext: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Build and encrypt a command packet to send to the device.
+ *
+ * Packet structure (32 bytes before encryption):
+ * - Bytes 0-3: Unix timestamp (big-endian)
+ * - Bytes 4-19: Fixed key
+ * - Bytes 20-25: Modbus command (6 bytes)
+ * - Bytes 26-27: CRC16-Modbus of command
+ * - Bytes 28-31: Padding [0x04, 0x04, 0x04, 0x04]
+ *
+ * @param modbusCommand - 6-byte Modbus RTU command
+ * @returns 32-byte encrypted packet ready to send via BLE
+ */
+export declare const createPacket: (modbusCommand: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Decrypt and parse a response packet from the device.
+ *
+ * Response structure (32 bytes before decryption):
+ * - Bytes 0-3: Unix timestamp
+ * - Bytes 4-19: Fixed key
+ * - Bytes 20-26: Modbus response (7 bytes)
+ * - Bytes 27-28: CRC16-Modbus
+ * - Bytes 29-31: Padding [0x03, 0x03, 0x03]
+ *
+ * @param encrypted - 32-byte encrypted response from BLE notification
+ * @returns Parsed Modbus response
+ */
+export declare const parseResponse: (encrypted: Uint8Array) => Promise<ModbusResponse>;
+/**
+ * Pre-built Modbus read commands for querying device state.
+ * Each command is 6 bytes: [SlaveAddr, FuncCode, RegHi, RegLo, CountHi, CountLo]
+ */
+export declare const readCommands: {
+    /** Power state (0=off, 1=on) */
+    power: Uint8Array<ArrayBuffer>;
+    /** Current ambient temperature (value / 10 = °C) */
+    temperature: Uint8Array<ArrayBuffer>;
+    /** Target temperature (value / 10 = °C) */
+    targetTemperature: Uint8Array<ArrayBuffer>;
+    /** Power level (1-5) */
+    powerLevel: Uint8Array<ArrayBuffer>;
+    /** Fan 1 speed (0=auto, 1-5=speed) */
+    fan1Speed: Uint8Array<ArrayBuffer>;
+    /** Fan 2 speed (0=auto, 1-5=speed) */
+    fan2Speed: Uint8Array<ArrayBuffer>;
+    /** Device state code */
+    state: Uint8Array<ArrayBuffer>;
+    /** Alarm status code */
+    alarm: Uint8Array<ArrayBuffer>;
+    /** Pellet warning status */
+    pelletAlarm: Uint8Array<ArrayBuffer>;
+    /** Auto mode (0=manual, 1=auto) */
+    autoMode: Uint8Array<ArrayBuffer>;
+    /** Standby mode status */
+    standby: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Builder functions for Modbus write commands.
+ * Each function returns a 6-byte command: [SlaveAddr, FuncCode, RegHi, RegLo, ValHi, ValLo]
+ */
+export declare const writeCommands: {
+    /**
+     * Turn power on or off.
+     * @param on - true to turn on, false to turn off
+     */
+    setPower: (on: boolean) => Uint8Array;
+    /**
+     * Set target temperature.
+     * @param tempCelsius - Temperature in Celsius (e.g., 21.5)
+     */
+    setTemperature: (tempCelsius: number) => Uint8Array;
+    /**
+     * Set power level.
+     * @param level - Power level (1-5)
+     */
+    setPowerLevel: (level: number) => Uint8Array;
+    /**
+     * Set fan 1 speed.
+     * @param speed - Fan speed (0=auto, 1-5=manual speed)
+     */
+    setFan1Speed: (speed: number) => Uint8Array;
+    /**
+     * Set fan 2 speed.
+     * @param speed - Fan speed (0=auto, 1-5=manual speed)
+     */
+    setFan2Speed: (speed: number) => Uint8Array;
+    /**
+     * Enable or disable auto mode.
+     * @param enabled - true to enable auto mode
+     */
+    setAutoMode: (enabled: boolean) => Uint8Array;
+    /**
+     * Enable or disable standby mode.
+     * @param enabled - true to enable standby mode
+     */
+    setStandby: (enabled: boolean) => Uint8Array;
+};
+/**
+ * Parser functions to extract meaningful values from Modbus responses.
+ */
+export declare const parsers: {
+    /**
+     * Parse boolean response (power state, auto mode, etc.).
+     * @param response - Parsed Modbus response
+     * @returns true if value is 0x01, false if 0x00
+     */
+    boolean: (response: ModbusResponse) => boolean;
+    /**
+     * Parse temperature response.
+     * @param response - Parsed Modbus response
+     * @returns Temperature in Celsius
+     */
+    temperature: (response: ModbusResponse) => number;
+    /**
+     * Parse numeric value (power level, fan speed, state code, etc.).
+     * @param response - Parsed Modbus response
+     * @returns Numeric value
+     */
+    number: (response: ModbusResponse) => number;
+};