edilkamin 1.10.2 → 1.12.0

package/dist/cjs/src/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlarmDescriptions = exports.AlarmCode = void 0;
+exports.StoveStateDescriptions = exports.StoveState = exports.OperationalPhaseDescriptions = exports.OperationalPhase = exports.IgnitionSubPhaseDescriptions = exports.IgnitionSubPhase = exports.getStoveStateDescription = exports.getOperationalPhaseDescription = exports.getIgnitionSubPhaseDescription = exports.AlarmDescriptions = exports.AlarmCode = void 0;
 /**
  * Alarm type codes from Edilkamin devices.
  * Based on AlarmsEnum.java from Android app (version 1.3.1-RC2 released 2025/12/10).
@@ -64,3 +64,97 @@ const AlarmDescriptions = {
     [AlarmCode.BOARD_FUSE]: "Control board fuse issue",
 };
 exports.AlarmDescriptions = AlarmDescriptions;
+/**
+ * Main operational phases of the stove.
+ * Values derived from device behavior observation.
+ */
+var OperationalPhase;
+(function (OperationalPhase) {
+    OperationalPhase[OperationalPhase["OFF"] = 0] = "OFF";
+    OperationalPhase[OperationalPhase["STANDBY"] = 1] = "STANDBY";
+    OperationalPhase[OperationalPhase["IGNITION"] = 2] = "IGNITION";
+    OperationalPhase[OperationalPhase["ON"] = 6] = "ON";
+})(OperationalPhase || (exports.OperationalPhase = OperationalPhase = {}));
+/**
+ * Human-readable descriptions for operational phases.
+ */
+const OperationalPhaseDescriptions = {
+    [OperationalPhase.OFF]: "Off",
+    [OperationalPhase.STANDBY]: "Standby",
+    [OperationalPhase.IGNITION]: "Ignition",
+    [OperationalPhase.ON]: "On",
+};
+exports.OperationalPhaseDescriptions = OperationalPhaseDescriptions;
+/**
+ * Get description for an operational phase, with fallback for unknown values.
+ */
+const getOperationalPhaseDescription = (phase) => { var _a; return (_a = OperationalPhaseDescriptions[phase]) !== null && _a !== void 0 ? _a : `Unknown phase (${phase})`; };
+exports.getOperationalPhaseDescription = getOperationalPhaseDescription;
+/**
+ * Sub-phases during ignition sequence.
+ * These are only meaningful when operational_phase === IGNITION.
+ */
+var IgnitionSubPhase;
+(function (IgnitionSubPhase) {
+    IgnitionSubPhase[IgnitionSubPhase["STARTING_CLEANING"] = 0] = "STARTING_CLEANING";
+    IgnitionSubPhase[IgnitionSubPhase["PELLET_LOAD"] = 1] = "PELLET_LOAD";
+    IgnitionSubPhase[IgnitionSubPhase["LOADING_BREAK"] = 2] = "LOADING_BREAK";
+    IgnitionSubPhase[IgnitionSubPhase["SMOKE_TEMPERATURE_CHECK"] = 3] = "SMOKE_TEMPERATURE_CHECK";
+    IgnitionSubPhase[IgnitionSubPhase["THRESHOLD_EXCEEDING_CHECK"] = 4] = "THRESHOLD_EXCEEDING_CHECK";
+    IgnitionSubPhase[IgnitionSubPhase["WARMUP"] = 5] = "WARMUP";
+    IgnitionSubPhase[IgnitionSubPhase["TRANSITION_TO_ON"] = 6] = "TRANSITION_TO_ON";
+})(IgnitionSubPhase || (exports.IgnitionSubPhase = IgnitionSubPhase = {}));
+/**
+ * Human-readable descriptions for ignition sub-phases.
+ */
+const IgnitionSubPhaseDescriptions = {
+    [IgnitionSubPhase.STARTING_CLEANING]: "Starting cleaning",
+    [IgnitionSubPhase.PELLET_LOAD]: "Pellet load",
+    [IgnitionSubPhase.LOADING_BREAK]: "Loading break",
+    [IgnitionSubPhase.SMOKE_TEMPERATURE_CHECK]: "Smoke temperature check",
+    [IgnitionSubPhase.THRESHOLD_EXCEEDING_CHECK]: "Threshold exceeding check",
+    [IgnitionSubPhase.WARMUP]: "Warmup",
+    [IgnitionSubPhase.TRANSITION_TO_ON]: "Starting up",
+};
+exports.IgnitionSubPhaseDescriptions = IgnitionSubPhaseDescriptions;
+/**
+ * Get description for an ignition sub-phase, with fallback for unknown values.
+ */
+const getIgnitionSubPhaseDescription = (subPhase) => { var _a; return (_a = IgnitionSubPhaseDescriptions[subPhase]) !== null && _a !== void 0 ? _a : `Unknown sub-phase (${subPhase})`; };
+exports.getIgnitionSubPhaseDescription = getIgnitionSubPhaseDescription;
+/**
+ * Combined stove states.
+ * This is a composite value combining operational phase and sub-phase.
+ */
+var StoveState;
+(function (StoveState) {
+    StoveState[StoveState["OFF"] = 0] = "OFF";
+    StoveState[StoveState["STANDBY"] = 1] = "STANDBY";
+    StoveState[StoveState["IGNITION_CLEANING"] = 2] = "IGNITION_CLEANING";
+    StoveState[StoveState["IGNITION_LOADING"] = 3] = "IGNITION_LOADING";
+    StoveState[StoveState["IGNITION_WAITING"] = 4] = "IGNITION_WAITING";
+    StoveState[StoveState["IGNITION_WARMUP"] = 5] = "IGNITION_WARMUP";
+    StoveState[StoveState["ON"] = 6] = "ON";
+    StoveState[StoveState["COOLING"] = 7] = "COOLING";
+    StoveState[StoveState["ALARM"] = 8] = "ALARM";
+})(StoveState || (exports.StoveState = StoveState = {}));
+/**
+ * Human-readable descriptions for stove states.
+ */
+const StoveStateDescriptions = {
+    [StoveState.OFF]: "Off",
+    [StoveState.STANDBY]: "Standby",
+    [StoveState.IGNITION_CLEANING]: "Ignition - Cleaning",
+    [StoveState.IGNITION_LOADING]: "Ignition - Loading pellets",
+    [StoveState.IGNITION_WAITING]: "Ignition - Waiting",
+    [StoveState.IGNITION_WARMUP]: "Ignition - Warming up",
+    [StoveState.ON]: "On",
+    [StoveState.COOLING]: "Cooling down",
+    [StoveState.ALARM]: "Alarm",
+};
+exports.StoveStateDescriptions = StoveStateDescriptions;
+/**
+ * Get description for a stove state, with fallback for unknown values.
+ */
+const getStoveStateDescription = (state) => { var _a; return (_a = StoveStateDescriptions[state]) !== null && _a !== void 0 ? _a : `Unknown state (${state})`; };
+exports.getStoveStateDescription = getStoveStateDescription;

package/dist/esm/package.json

@@ -1,6 +1,6 @@
 {
     "name": "edilkamin",
-    "version": "1.10.2",
+    "version": "1.12.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;
+};