mclimate-payload-helper 1.3.5 → 1.4.2

package/CONTEXT.md

@@ -5,7 +5,7 @@ This file is the canonical, high-level reference for the `mclimate-payload-helpe
 ## 1. Project Overview
 
 - **Name:** `mclimate-payload-helper` (npm package)
-- **Version:** `1.3.4` (see `package.json`)
+- **Version:** `1.4.0` (see `package.json`)
 - **Language / Runtime:** TypeScript, compiled to CommonJS for Node.js consumers
 - **Purpose:** Encode LoRaWAN downlink commands and decode uplink payloads for MClimate IoT devices (Vicki, Relay 16, T-Valve, T-Flood, CO₂ sensors/displays, Fan-Coil thermostat, PIR Mini, etc.).
 - **Distribution:** Published to npm; consumers import `uplinkPayloadParser`, `CommandBuilder`, `DeviceType`, schemas and per-device command classes.
@@ -160,3 +160,7 @@ When starting a new task, read these in order:
 
 - **2026-05-14** — Initial `CONTEXT.md` created. Captures architecture as of `package.json` v1.3.4: 22 supported `DeviceType`s, mixin-based encoder hierarchy, single shared `commandsReadingHelper`, Zod-validated command params, colocated encoder tests + consolidated decoder tests.
 - **2026-05-14** — Added `FanCoilThermostatCommands.getFctOperationalMode` (cmdId `0x53`) in `src/encoders/FanCoilThermostatCommands.ts`. Added a `DeviceType.FanCoilThermostat` branch to case `'53'` in `src/decoders/commandsReadingHelper.ts` that decodes the byte as `fctOperationalMode` (raw int, 0=Vent / 1=Heat / 2=Cool) while leaving the default `targetTemperatureStep` decoding intact for other devices. Encoder + decoder tests added (`FanCoilThermostatCommands.test.ts`, `payloadDecoders.test.ts`). Reinforces the existing pattern of guarding shared response cmdIds by `deviceType` (gotcha §9).
+- **2026-05-19** — Audited `VickiCommands` against the official Vicki cheat-sheet (`docs.mclimate.eu/.../command-cheat-sheet`). Only one documented GET was missing: `0x52` _GET Target temperature with resolution 0.1°C_. Added `VickiCommands.getTargetTemperaturePrecisely()` returning `BaseCommand('GetTargetTemperaturePrecisely', 0x52)`, a matching no-param Zod schema entry in `VickiCommandSchemas`, and an encoder test. Decoder already handles case `'52'` as `targetTemperatureFloat` (2-byte / 10) for all devices, so no `commandsReadingHelper` change needed. All other documented Vicki GETs (incl. `0x14`/`0x15` via `ChildLockCommands`/`TemperatureCommonCommands` mixins and `0x12`/`0x19`/`0x1b`/`0x1d`/`0xa4` via `GeneralCommands`) are already present.
+- **2026-05-19** — Completed Vicki SET audit. Two documented SETs were missing: `0x33` _Set LoRaWAN AppEUI & AppKey_ (≥4.1) and `0x57` _SET target temperature in Fahrenheit_ (≥4.4). Added `setAppEuiAndAppKey({ appEui: hex16, appKey: hex32 })` and `setTargetTemperatureFahrenheit({ targetTemperature: 41–86 })` to `VickiCommands.ts`, matching Zod schemas (`appEui`/`appKey` are hex-string-typed with regex + length), type exports, and 4 new tests (encode + zod-fail per command). All other documented Vicki SETs were already present (incl. `0x4e`/`0x4f` valve openness, `0x59`/`0x5b`/`0x5d`/`0x5f`/`0x61`/`0x63`/`0x65`/`0x67`/`0x69`/`0x6b`/`0x6d` heating-schedule/time/setback/etc.). `0x58` _Additional notifications_ and `0xa6` _External crystal not working_ are uplink-only — out of scope.
+- **2026-05-19** — HT-Sensor D2D protocol additions (per internal _HT new commands (1).odt_). **Encoder** (`HTSensorCommands.ts`): added `setD2dCommunicationState({ enabled: boolean })` (`0xa9`), `getD2dCommunicationState()` (`0xaa`), `setD2dCommunicationPeriod({ period: 1–8 min })` (`0xab`), `getD2dCommunicationPeriod()` (`0xac`). **Decoder** (`commandsReadingHelper.ts`): added `HTSensor`-guarded branches for cases `'aa'` → `d2dCommunicationState: boolean` and `'ac'` → `d2dCommunicationPeriod: number`. **Schemas** (`schemas.ts`): 4 new entries in `HTSensorCommandSchemas` + 2 type exports. 9 new tests (6 encoder + 3 decoder). 324/324 passing.\n- **2026-05-19** — Vicki keep-alive bit-by-bit audit (current docs `/vicki-lorawan-device-communication-protocol/keep-alive`). Only one bit was missing from `vickiPayloadParser`: byte 8 bit 1 → `batteryTooLow`. Pre-4.6 docs label that bit as "Reserved", but current spec exposes it. Added `batteryTooLow: boolean` to `VickiKeepAliveData` type and parser. All 5 existing Vicki keepalive snapshots updated (`batteryTooLow: false` since byte 8 = `0x30`/`0x34` in fixtures). New regression test with byte 8 = `0x32` confirms `batteryTooLow: true`. All other byte 7/8 bits were already covered.\n- **2026-05-19** — Vicki D2D / HT-sensor protocol additions (per internal _Vicki new commands (7).odt_). **Encoder:** added `setD2dNotificationDeviceAppKey({ appKey: hex32 })` (`0x6f` + 16-byte AppKey), `getD2dNotificationDeviceAppKey()` (`0x70`), `requestListenForD2dNotificationDevice()` (`0x71`). Extended `VickiCommandSchemas.setOperationalMode` enum + `VickiEnums.setOperationalMode` to include mode `'03'` (Online automatic with HT-sensor D2D temp). **Decoder:** added Vicki branches to `case '70'` (16-byte AppKey → `d2dNotificationDeviceAppKey` as uppercase hex) and `case '72'` (2-byte temp/10 → `htSensorTemperature`) in `commandsReadingHelper.ts`; other devices' existing handling on those bytes is preserved. **Keep-alive:** `vickiPayloadParser` now exposes `d2dCommunicationReliable` (byte 8 bit 2, previously reserved). `VickiKeepAliveData` type updated. Existing keepalive snapshot tests updated to include the new field (all `false` since byte 8 = `0x30`). 8 new tests added (3 decoder + 5 encoder). 314/314 passing.\n- **2026-05-19** — Thermostat-family audit (WirelessThermostat, FanCoilThermostat, T-Valve) against official cheat-sheets. **WirelessThermostat** (`WirelessThermostatCommands.ts`): added 5 commands — `0x55`/`0x56` `setSensorCompensationTemperature`/`getSensorCompensationTemperature` (sign-byte + abs\*10), `0x5d`/`0x5e` `setTemperatureMeasurementPeriod`/`getTemperatureMeasurementPeriod` (minutes 1–255), and `0xa5` `restartDevice`. **FanCoilThermostat** (`FanCoilThermostatCommands.ts`): added 6 commands — `0x2f` `getTargetTemperature`, `0x3b` `setExtTemperatureSensor1C` (int 1–99°C), `0x3c` `setExtTemperatureSensor` (0.1–99.9°C, 2-byte payload), `0x3e` `getExtTemperatureSensor`, `0x74` `getModeChangedByAutoChangeover`, `0x75` `getPowerModuleCommunicationStatus`. Also fixed two pre-existing `BaseCommand`-name bugs in FCT: the `0x77` get-method emitted name `'SetHeatingCoolingTargetTempRangesUnoccupied'` (now `'Get…'`) and `0x79` emitted `'getFanOffDelayTime'` (now `'GetFanOffDelayTime'`). **T-Valve** (`TValveCommands.ts`): added `0x0b` `deactivateDevice`. Matching Zod schemas + type exports added in `schemas.ts`; 14 new tests added (encode + zod-fail where applicable). **Out of scope** for this batch: `Thermostat` (T-Ring) and `MelissaLorawan` — no public cheat-sheets exist at `docs.mclimate.eu` for these two; their command sets are bespoke (TRing uses 6-byte fixed-format commands, Melissa only has IR recording at `0x09`) and verifying against firmware would require the internal MClimate spec, not the public docs.
+- **2026-06-18** — PIR Mini FW ≥1.4 additions (per `MClimate-pir-new.pdf`). Audited the new datasheet against the code: the embedded JS decoder/encoder in the PDF is **stale** (it shows RGB LED brightness and demo mode at `0x3A`/`0x3B`), but the authoritative human-readable command table + per-command examples confirm the **existing** code is correct — LED brightness is a single value (`0x21`/`0x22`, e.g. `0x212F`), demo mode is `0x3C`/`0x3D`, and `0x3A`/`0x3B` are the uplink-only PIR occupancy events. **Keep-alive payload is unchanged** (same 10-byte layout); `lux` stays a raw numeric value. **Encoder** (`PirMiniCommands.ts`): added `setPIROperationMode` (`0x3E`, mode 0–3: Occupancy/Triggered Occupancy/Trigger/Count), `getPIROperationMode` (`0x3F`), `setPIRBlindTime` (`0x41`, 2-byte seconds, 10–65535), `getPIRBlindTime` (`0x42`), `setPIRCounterResetFlag` (`0x43`, 0/1), `getPIRCounterResetFlag` (`0x44`). **Decoder** (`commandsReadingHelper.ts`): added `PirMini`-guarded branches to shared cases `0x3F` → `pirOperationMode`, `0x40` → `{ event: 'pirTrigger' }` (uplink-only PIR Trigger Event, mirrors `0x3A`/`0x3B` + appended keep-alive), `0x42` → `pirBlindTime` (2 bytes), `0x44` → `pirCounterResetFlag`; other devices' handling on those bytes preserved. **Keep-alive** (`pirMiniPayloadParser.ts`): `lux` remains a raw numeric 16-bit value (`number`). Per spec, `0x0000`–`0xFFFA` is the valid range, `0xFFFF` = disabled, `0xFFFC`–`0xFFFE` = sensor error; these sentinels are documented via a code comment and left for the consumer to interpret (no string return). **Schemas** (`schemas.ts`): 6 new entries + 6 type exports + `setPIROperationMode`/`setPIRCounterResetFlag` enums. 15 new tests (9 encoder + 6 decoder); 339/339 passing. Reinforces gotcha §9: trust the human-readable cheat-sheet over the PDF's embedded JS when they disagree on command IDs.

package/dist/decoders/commandsReadingHelper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commandsReadingHelper.d.ts","sourceRoot":"","sources":["../../src/decoders/commandsReadingHelper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAG5D,eAAO,MAAM,qBAAqB,YAAa,MAAM,iBAAiB,MAAM,cAAc,UAAU,mBA2zFnG,CAAA"}
+{"version":3,"file":"commandsReadingHelper.d.ts","sourceRoot":"","sources":["../../src/decoders/commandsReadingHelper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAG5D,eAAO,MAAM,qBAAqB,YAAa,MAAM,iBAAiB,MAAM,cAAc,UAAU,mBAo4FnG,CAAA"}

package/dist/decoders/commandsReadingHelper.js

@@ -1405,6 +1405,11 @@ const commandsReadingHelper = (hexData, payloadLength, deviceType) => {
                             const data = { integralValue: parseInt(`${commands[i + 1]}${commands[i + 2]}`, 16) / 10 };
                             Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
                         }
+                        else if (deviceType === types_1.DeviceType.PirMini) {
+                            command_len = 1;
+                            const data = { pirOperationMode: parseInt(commands[i + 1], 16) };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
                         else {
                             command_len = 1;
                             const data = { pirSensorSensitivity: parseInt(commands[i + 1], 16) };
@@ -1425,9 +1430,16 @@ const commandsReadingHelper = (hexData, payloadLength, deviceType) => {
             case '40':
                 {
                     try {
-                        command_len = 1;
-                        const data = { piRunPeriod: parseInt(commands[i + 1], 16) };
-                        Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        if (deviceType === types_1.DeviceType.PirMini) {
+                            command_len = 0;
+                            const data = { event: 'pirTrigger' };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
+                        else {
+                            command_len = 1;
+                            const data = { piRunPeriod: parseInt(commands[i + 1], 16) };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
                     }
                     catch (e) {
                         throw new utils_1.CustomError({
@@ -1461,9 +1473,16 @@ const commandsReadingHelper = (hexData, payloadLength, deviceType) => {
             case '42':
                 {
                     try {
-                        command_len = 1;
-                        const data = { tempHysteresis: parseInt(commands[i + 1], 16) / 10 };
-                        Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        if (deviceType === types_1.DeviceType.PirMini) {
+                            command_len = 2;
+                            const data = { pirBlindTime: (parseInt(commands[i + 1], 16) << 8) | parseInt(commands[i + 2], 16) };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
+                        else {
+                            command_len = 1;
+                            const data = { tempHysteresis: parseInt(commands[i + 1], 16) / 10 };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
                     }
                     catch (e) {
                         throw new utils_1.CustomError({
@@ -1497,9 +1516,16 @@ const commandsReadingHelper = (hexData, payloadLength, deviceType) => {
             case '44':
                 {
                     try {
-                        command_len = 2;
-                        const data = { extSensorTemperature: parseInt(`${commands[i + 1]}${commands[i + 2]}`, 16) / 10 };
-                        Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        if (deviceType === types_1.DeviceType.PirMini) {
+                            command_len = 1;
+                            const data = { pirCounterResetFlag: parseInt(commands[i + 1], 16) };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
+                        else {
+                            command_len = 2;
+                            const data = { extSensorTemperature: parseInt(`${commands[i + 1]}${commands[i + 2]}`, 16) / 10 };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
                     }
                     catch (e) {
                         throw new utils_1.CustomError({
@@ -2306,6 +2332,15 @@ const commandsReadingHelper = (hexData, payloadLength, deviceType) => {
                             command_len = 2;
                             data = { overheatingRecoveryTime: (parseInt(commands[i + 1], 16) << 8) | parseInt(commands[i + 2], 16) };
                         }
+                        else if (deviceType === types_1.DeviceType.Vicki) {
+                            command_len = 16;
+                            data = {
+                                d2dNotificationDeviceAppKey: commands
+                                    .slice(i + 1, i + 17)
+                                    .join('')
+                                    .toUpperCase(),
+                            };
+                        }
                         Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
                     }
                     catch (e) {
@@ -2356,6 +2391,12 @@ const commandsReadingHelper = (hexData, payloadLength, deviceType) => {
                             command_len = 1;
                             data = { overcurrentRecoveryTemp: parseInt(commands[i + 1], 16) };
                         }
+                        else if (deviceType === types_1.DeviceType.Vicki) {
+                            command_len = 2;
+                            data = {
+                                htSensorTemperature: ((parseInt(commands[i + 1], 16) << 8) | parseInt(commands[i + 2], 16)) / 10,
+                            };
+                        }
                         Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
                     }
                     catch (e) {
@@ -3008,6 +3049,46 @@ const commandsReadingHelper = (hexData, payloadLength, deviceType) => {
                     }
                 }
                 break;
+            case 'aa':
+                {
+                    try {
+                        if (deviceType === types_1.DeviceType.HTSensor) {
+                            command_len = 1;
+                            const data = { d2dCommunicationState: parseInt(commands[i + 1], 16) === 1 };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
+                    }
+                    catch (e) {
+                        throw new utils_1.CustomError({
+                            message: `Failed to process command 'aa'`,
+                            hexData,
+                            command,
+                            deviceType,
+                            originalError: e,
+                        });
+                    }
+                }
+                break;
+            case 'ac':
+                {
+                    try {
+                        if (deviceType === types_1.DeviceType.HTSensor) {
+                            command_len = 1;
+                            const data = { d2dCommunicationPeriod: parseInt(commands[i + 1], 16) };
+                            Object.assign(resultToPass, Object.assign({}, resultToPass), Object.assign({}, data));
+                        }
+                    }
+                    catch (e) {
+                        throw new utils_1.CustomError({
+                            message: `Failed to process command 'ac'`,
+                            hexData,
+                            command,
+                            deviceType,
+                            originalError: e,
+                        });
+                    }
+                }
+                break;
             default:
                 decodeKeepalive(commands, payloadLength, deviceType);
                 commands.splice(i, commands.length);