zigbee-herdsman 4.3.2 → 4.4.1

package/package.json

@@ -63,7 +63,7 @@
     "type": "git",
     "url": "git+https://github.com/Koenkk/zigbee-herdsman.git"
   },
-  "version": "4.3.2",
+  "version": "4.4.1",
   "scripts": {
     "build": "tsc",
     "build:watch": "tsc -w",

package/src/adapter/deconz/driver/constants.ts

@@ -127,6 +127,7 @@ export const stackParameters = [
     {id: ParamId.STK_PREDEFINED_PANID, type: DataType.U8},
     {id: ParamId.STK_NETWORK_KEY, type: [DataType.U8, DataType.SecKey], readArg: 1}, // index, key
     {id: ParamId.STK_LINK_KEY, type: [DataType.U64, DataType.SecKey], readArg: 1}, // mac addess, key
+    {id: ParamId.STK_ENDPOINT, type: DataType.Custom},
     {id: ParamId.DEV_WATCHDOG_TTL, type: DataType.U32},
     {id: ParamId.STK_PERMIT_JOIN, type: DataType.U8},
     {id: ParamId.NWK_EXTENDED_PANID, type: DataType.U64},
@@ -141,7 +142,7 @@ interface Request {
     commandId: FirmwareCommand;
     networkState: NetworkState;
     parameterId: ParamId;
-    parameter?: Buffer | number | bigint;
+    parameter?: Buffer | number | bigint | undefined;
     seqNumber: number;
     // biome-ignore lint/suspicious/noExplicitAny: API
     resolve: (value: any) => void;
@@ -196,7 +197,6 @@ interface ReceivedDataResponse {
 }
 
 interface GpDataInd {
-    rspId: number;
     seqNr: number;
     id: number;
     options: number;

package/src/adapter/deconz/driver/driver.ts

@@ -4,6 +4,7 @@ import events from "node:events";
 import net from "node:net";
 
 import slip from "slip";
+import {Buffalo} from "../../../buffalo";
 import type {Backup} from "../../../models";
 import {logger} from "../../../utils/logger";
 import {SerialPort} from "../../serialPort";
@@ -112,6 +113,10 @@ class Driver extends events.EventEmitter {
     public paramCurrentChannel = 0;
     public paramNwkPanid = 0;
     public paramNwkKey = Buffer.alloc(16);
+    public paramEndpoint0: Buffer | undefined;
+    public paramEndpoint1: Buffer | undefined;
+    public fixParamEndpoint0: Buffer;
+    public fixParamEndpoint1: Buffer;
     public paramNwkUpdateId = 0;
     public paramChannelMask = 0;
     public paramProtocolVersion = 0;
@@ -130,6 +135,50 @@ class Driver extends events.EventEmitter {
         this.writer = new Writer();
         this.parser = new Parser();
 
+        this.fixParamEndpoint0 = Buffer.from([
+            0x00, // index
+            0x01, // endpoint,
+            0x04, // profileId
+            0x01,
+            0x05, // deviceId
+            0x00,
+            0x01, // deviceVersion
+            0x05, // in cluster count
+            0x00, // basic
+            0x00,
+            0x06, // on/off
+            0x00,
+            0x0a, // time
+            0x00,
+            0x19, // ota
+            0x00,
+            0x01, // ias ace
+            0x05,
+            0x04, // out cluster count
+            0x01, // power configuration
+            0x00,
+            0x20, // poll control
+            0x00,
+            0x00, // ias zone
+            0x05,
+            0x02, // ias wd
+            0x05,
+        ]);
+
+        this.fixParamEndpoint1 = Buffer.from([
+            0x01, // index
+            0xf2, // endpoint,
+            0xe0, // profileId
+            0xa1,
+            0x64, // deviceId
+            0x00,
+            0x01, // deviceVersion
+            0x00, // in cluster count
+            0x01, // out cluster count
+            0x21, // green power
+            0x00,
+        ]);
+
         this.tickTimer = setInterval(() => {
             this.tick();
         }, 100);
@@ -366,6 +415,16 @@ class Driver extends events.EventEmitter {
             return false;
         }
 
+        if (!this.paramEndpoint0 || this.fixParamEndpoint0.compare(this.paramEndpoint0) !== 0) {
+            logger.debug("Endpoint[0] doesn't match configuration", NS);
+            return false;
+        }
+
+        if (!this.paramEndpoint1 || this.fixParamEndpoint1.compare(this.paramEndpoint1) !== 0) {
+            logger.debug("Endpoint[1] doesn't match configuration", NS);
+            return false;
+        }
+
         if ((this.deviceStatus & DEV_STATUS_NET_STATE_MASK) !== NetworkState.Connected) {
             return false;
         }
@@ -521,55 +580,19 @@ class Driver extends events.EventEmitter {
             await this.writeParameterRequest(ParamId.STK_NETWORK_KEY, Buffer.from([0x0, ...this.networkOptions.networkKey]));
         }
 
-        // now reconnect, this will also store configuration in nvram
-        await this.changeNetworkStateRequest(NetworkState.Connected);
+        // check current endpoint configuration
+        if (!this.paramEndpoint0 || this.fixParamEndpoint0.compare(this.paramEndpoint0) !== 0) {
+            this.paramEndpoint0 = this.fixParamEndpoint0;
+            await this.writeParameterRequest(ParamId.STK_ENDPOINT, this.paramEndpoint0);
+        }
 
-        // TODO(mpi): Endpoint configuration should be written like other network parameters and subject to `changed`.
-        // It should happen before NET_CONNECTED is set.
-        // Therefore read endpoint configuration, compare, swap if needed.
-
-        // TODO(mpi): The following code only adjusts first endpoint, with a fixed setting.
-        // Ideally also second endpoint should be configured like deCONZ does.
-
-        // write endpoints
-        /* Format of the STK.Endpoint parameter:
-            {
-                u8 endpointIndex // index used by firmware 0..2
-                u8 endpoint // actual zigbee endpoint
-                u16 profileId
-                u16 deviceId
-                u8 deviceVersion
-                u8 serverClusterCount
-                u16 serverClusters[serverClusterCount]
-                u8 clientClusterCount
-                u16 clientClusters[clientClusterCount]
-            }
-            */
-        //[ sd1   ep    proId       devId       vers  #inCl iCl1        iCl2        iCl3        iCl4        iCl5        #outC oCl1        oCl2        oCl3        oCl4      ]
-        //
-        // const sd = [
-        //     0x00, // index
-        //     0x01, // endpoint
-        //     0x04, 0x01, // profileId
-        //     0x05, 0x00, // deviceId
-        //     0x01, // deviceVersion
-        //     0x05, // serverClusterCount
-        //     0x00, 0x00, // Basic
-        //     0x00, 0x06, // On/Off        TODO(mpi): This is wrong byte order! should be 0x06 0x00
-        //     0x0a, 0x00, // Time
-        //     0x19, 0x00, // OTA
-        //     0x01, 0x05, // IAS ACE
-        //     0x04, // clientClusterCount
-        //     0x01, 0x00, // Power Configuration
-        //     0x20, 0x00, // Poll Control
-        //     0x00, 0x05, // IAS Zone
-        //     0x02, 0x05 // IAS WD
-        // ];
-        // // TODO(mpi) why is it reversed? That result in invalid endpoint configuration.
-        // // Likely the command gets discarded as it results in endpointIndex = 0x05.
-        // const sd1 = sd.reverse();
-        // await this.driver.writeParameterRequest(PARAM.PARAM.STK.Endpoint, Buffer.from(sd1));
+        if (!this.paramEndpoint1 || this.fixParamEndpoint1.compare(this.paramEndpoint1) !== 0) {
+            this.paramEndpoint1 = this.fixParamEndpoint1;
+            await this.writeParameterRequest(ParamId.STK_ENDPOINT, this.paramEndpoint1);
+        }
 
+        // now reconnect, this will also store configuration in nvram
+        await this.changeNetworkStateRequest(NetworkState.Connected);
         return;
     }
 
@@ -593,6 +616,8 @@ class Driver extends events.EventEmitter {
                 this.readParameterRequest(ParamId.APS_CHANNEL_MASK),
                 this.readParameterRequest(ParamId.STK_PROTOCOL_VERSION),
                 this.readParameterRequest(ParamId.STK_FRAME_COUNTER),
+                this.readParameterRequest(ParamId.STK_ENDPOINT, Buffer.from([0])),
+                this.readParameterRequest(ParamId.STK_ENDPOINT, Buffer.from([1])),
             ])
                 .then(
                     ([
@@ -609,6 +634,8 @@ class Driver extends events.EventEmitter {
                         channelMask,
                         protocolVersion,
                         frameCounter,
+                        ep0,
+                        ep1,
                     ]) => {
                         this.paramFirmwareVersion = fwVersion;
                         this.paramCurrentChannel = currentChannel as number;
@@ -623,6 +650,13 @@ class Driver extends events.EventEmitter {
                         if (frameCounter !== null) {
                             this.paramFrameCounter = frameCounter as number;
                         }
+                        if (ep0 !== null) {
+                            this.paramEndpoint0 = ep0 as Buffer;
+                        }
+
+                        if (ep1 !== null) {
+                            this.paramEndpoint1 = ep1 as Buffer;
+                        }
 
                         // console.log({fwVersion, mac, panid, apsUseExtPanid, currentChannel, nwkKey, nwkUpdateId, channelMask, protocolVersion, frameCounter});
 
@@ -927,7 +961,7 @@ class Driver extends events.EventEmitter {
         });
     }
 
-    public readParameterRequest(parameterId: ParamId, parameter?: Buffer | undefined): Promise<unknown> {
+    public readParameterRequest(parameterId: ParamId, parameter?: Buffer | number | bigint): Promise<unknown> {
         const seqNumber = this.nextSeqNumber();
         return new Promise((resolve, reject): void => {
             //logger.debug(`push read parameter request to queue. seqNr: ${seqNumber} paramId: ${parameterId}`, NS);
@@ -1027,14 +1061,29 @@ class Driver extends events.EventEmitter {
         });
     }
 
-    private sendReadParameterRequest(parameterId: ParamId, seqNumber: number): CommandResult {
-        /* command id, sequence number, 0, framelength(U16), payloadlength(U16), parameter id */
-        // TODO(mpi): refactor so this proper supports arguments
-        if (parameterId === ParamId.STK_NETWORK_KEY) {
-            return this.sendRequest(Buffer.from([FirmwareCommand.ReadParameter, seqNumber, 0x00, 0x09, 0x00, 0x02, 0x00, parameterId, 0x00]));
+    private sendReadParameterRequest(parameterId: ParamId, seqNumber: number, arg?: Buffer | number | bigint): CommandResult {
+        let frameLength = 8; // starts with min. frame length
+        let payloadLength = 1; // min. parameterId
+
+        if (arg instanceof Buffer) {
+            payloadLength += arg.byteLength;
+            frameLength += arg.byteLength;
+        }
+
+        const buf = new Buffalo(Buffer.alloc(frameLength));
+
+        buf.writeUInt8(FirmwareCommand.ReadParameter);
+        buf.writeUInt8(seqNumber);
+        buf.writeUInt8(0); // reserved, shall be 0
+        buf.writeUInt16(frameLength);
+        buf.writeUInt16(payloadLength);
+        buf.writeUInt8(parameterId);
+
+        if (arg instanceof Buffer) {
+            buf.writeBuffer(arg, arg.byteLength);
         }
 
-        return this.sendRequest(Buffer.from([FirmwareCommand.ReadParameter, seqNumber, 0x00, 0x08, 0x00, 0x01, 0x00, parameterId]));
+        return this.sendRequest(buf.getBuffer());
     }
 
     private sendWriteParameterRequest(parameterId: ParamId, value: Buffer | number | bigint, seqNumber: number): CommandResult {
@@ -1184,7 +1233,7 @@ class Driver extends events.EventEmitter {
                 switch (req.commandId) {
                     case FirmwareCommand.ReadParameter:
                         logger.debug(`send read parameter request from queue. parameter: ${ParamId[req.parameterId]} seq: ${req.seqNumber}`, NS);
-                        this.sendReadParameterRequest(req.parameterId, req.seqNumber);
+                        this.sendReadParameterRequest(req.parameterId, req.seqNumber, req.parameter);
                         break;
                     case FirmwareCommand.WriteParameter:
                         if (req.parameter === undefined) {

package/src/adapter/deconz/driver/frameParser.ts

@@ -81,6 +81,13 @@ function parseReadParameterResponse(view: DataView): Command | null {
             result = view.getUint8(pos);
             break;
         }
+        case ParamId.STK_ENDPOINT: {
+            result = Buffer.alloc(view.byteLength - pos);
+            for (let i = 0; pos < view.byteLength; i++, pos++) {
+                result[i] = view.getUint8(pos);
+            }
+            break;
+        }
         case ParamId.APS_CHANNEL_MASK: {
             result = view.getUint32(pos, littleEndian);
             break;
@@ -438,43 +445,141 @@ function parseDeviceStateChangedNotification(view: DataView): number | null {
     }
 }
 
+// The ApplicationID sub-field contains the information about the application used by the GPD.
+// ApplicationID = 0b000 indicates the GPD_ID field has the length of 4B and contains the GPD SrcID.
+// ApplicationID = 0b010 indicates the GPD_ID field has the length of 8B and contains the GPD IEEE address.
+enum GpApplicationId {
+    SrcId4B = 0,
+    Lped = 1,
+    Ieee8B = 2,
+}
+
+enum GpSecurityLevel {
+    NoSecurity = 0,
+    // TODO(mpi): "Reserved" is noted in the available spec but the code defined it as follows:
+    Reserved = 1, // 0b01 1LSB of frame counter and short (2B) MIC only
+    FrameCounter4BMic4B = 2,
+    EncryptionFrameCounter4BMic4B = 3,
+}
+
+enum ZgpConstants {
+    GpNwkProtocolVersion = 3,
+    GpNwkDataFrame = 0,
+    GpNwkMaintenanceFrame = 1,
+    GpMinMsduSize = 1,
+    GpAutoCommissioningFlag = 1 << 6,
+    GpNwkFrameControlExtensionFlag = 1 << 7,
+}
+
 function parseGreenPowerDataIndication(view: DataView): GpDataInd | null {
     try {
-        let id: number;
-        let rspId: number;
-        let options: number;
-        let srcId: number;
-        let frameCounter: number;
-        let commandId: number;
-        let commandFrameSize: number;
-        let commandFrame: Buffer;
-        const seqNr = view.getUint8(1);
-
-        if (view.byteLength < 30) {
-            logger.debug("GP data notification", NS);
-            id = 0x00; // 0 = notification, 4 = commissioning
-            rspId = 0x01; // 1 = pairing, 2 = commissioning
-            options = 0;
-            view.getUint16(7, littleEndian); // frame ctrl field(7) ext.fcf(8)
-            srcId = view.getUint32(9, littleEndian);
-            frameCounter = view.getUint32(13, littleEndian);
-            commandId = view.getUint8(17);
-            commandFrameSize = view.byteLength - 18 - 6; // cut 18 from begin and 4 (sec mic) and 2 from end (cfc)
-            commandFrame = Buffer.from(view.buffer.slice(18, commandFrameSize + 18));
-        } else {
-            logger.debug("GP commissioning notification", NS);
-            id = 0x04; // 0 = notification, 4 = commissioning
-            rspId = 0x01; // 1 = pairing, 2 = commissioning
-            options = view.getUint16(14, littleEndian); // opt(14) ext.opt(15)
-            srcId = view.getUint32(8, littleEndian);
-            frameCounter = view.getUint32(36, littleEndian);
-            commandId = view.getUint8(12);
-            commandFrameSize = view.byteLength - 13 - 2; // cut 13 from begin and 2 from end (cfc)
-            commandFrame = Buffer.from(view.buffer.slice(13, commandFrameSize + 13));
+        let srcId = 0;
+        let frameCounter = 0;
+        let commandId = 0;
+        let commandFrameSize = 0;
+        let commandFrame: Buffer | undefined;
+
+        const buf = new Buffalo(Buffer.from(view.buffer));
+
+        const _fwCommandId = buf.readUInt8();
+        const seqNr = buf.readUInt8();
+        const fwStatus = buf.readUInt8();
+
+        if (fwStatus !== CommandStatus.Success) {
+            return null;
+        }
+
+        const _frameLength = buf.readUInt16();
+        const _payloadLength = buf.readUInt16();
+
+        // payload
+
+        // implementation ported from deCONZ GP code
+        const nwkFrameControl = buf.readUInt8();
+
+        // check frame type
+        const frameType = nwkFrameControl & 0x03;
+
+        if (frameType !== ZgpConstants.GpNwkDataFrame && frameType !== ZgpConstants.GpNwkMaintenanceFrame) {
+            return null;
+        }
+
+        // check green power protocol version
+        if (((nwkFrameControl >> 2) & 0x03) !== ZgpConstants.GpNwkProtocolVersion) {
+            return null;
+        }
+
+        // extended frame control
+        let nwkExtFrameControl = 0;
+        const hasExtensionFlag = nwkFrameControl & ZgpConstants.GpNwkFrameControlExtensionFlag;
+        if (hasExtensionFlag) {
+            nwkExtFrameControl = buf.readUInt8();
+        }
+
+        const options = nwkExtFrameControl | (nwkFrameControl << 8);
+
+        const applicationId = nwkExtFrameControl & 7;
+        const securityLevel = (nwkExtFrameControl >> 3) & 3;
+
+        if (applicationId !== GpApplicationId.SrcId4B && applicationId !== GpApplicationId.Ieee8B) {
+            return null; // NOTE: GpApplicationId.Lped (1) should be dropped as per spec
+        }
+
+        // The GPDSrcID field is present if the Frame Type sub-field is set to 0b00 and the ApplicationID sub-
+        // field of the Extended NWK Frame Control field is set to 0b000 (or not present).
+        if (
+            applicationId === GpApplicationId.SrcId4B &&
+            frameType === ZgpConstants.GpNwkDataFrame /*|| (frameType === ZgpConstants.GpNwkMaintenanceFrame && hasExtensionFlag) */
+        ) {
+            srcId = buf.readUInt32();
+        }
+        // TODO(mpi): for applicationId == GpApplicationId.Ieee8B:
+        // currently Ieee addresses aren't supported, do they actually appear?!
+        // these need be extracted from MAC header which we don't have here (this is only the NWK payload).
+
+        // frame counter filed
+        frameCounter = 0;
+        let micSize = 0;
+
+        if (hasExtensionFlag && frameType === ZgpConstants.GpNwkDataFrame) {
+            if (applicationId === GpApplicationId.Ieee8B) {
+                const _endpoint = buf.readUInt8();
+            }
+            // If the SecurityLevel is set to 0b00, the SecurityKey sub-field is ignored on reception, and the
+            // fields Security frame counter and MIC are not present.
+            if (securityLevel === GpSecurityLevel.Reserved) {
+                micSize = 2; // TODO(mpi) does this actually exists? Check recent specs!
+            } else if (securityLevel === GpSecurityLevel.FrameCounter4BMic4B || securityLevel === GpSecurityLevel.EncryptionFrameCounter4BMic4B) {
+                frameCounter = buf.readUInt32();
+                micSize = 4;
+            }
+        }
+
+        if (!buf.isMore()) {
+            return null;
+        }
+
+        if (applicationId === GpApplicationId.SrcId4B || applicationId === GpApplicationId.Ieee8B) {
+            commandId = buf.readUInt8();
+            commandFrameSize = buf.getBuffer().length - buf.getPosition() - micSize;
+            //logger.debug(`GPD payload length: ${commandFrameSize}, mic size: ${micSize}`, NS);
+            if (commandFrameSize < 0) {
+                logger.error(`GPD payload length < 0: ${commandFrameSize}`, NS);
+                return null;
+            }
+            commandFrame = Buffer.from(buf.readBuffer(commandFrameSize)); // copy
+        }
+
+        // NOTE(mpi): The old adapter treated (view.byteLength < 30) as notification, larger as commissioning?!
+        // The controller thus rejected commissioning frames.
+        const id = 0; // 0 = notification, 4 = commissioning
+
+        if (commandFrame === undefined) {
+            logger.debug("GPD discard frame since commandFrame is null?!", NS);
+            return null;
         }
 
         const ind: GpDataInd = {
-            rspId,
             seqNr,
             id,
             options,
@@ -485,6 +590,7 @@ function parseGreenPowerDataIndication(view: DataView): GpDataInd | null {
             commandFrame,
         };
 
+        // TODO(mpi): This only tracks one frame, might be a bit optimistic
         if (!(lastReceivedGpInd.srcId === srcId && lastReceivedGpInd.commandId === commandId && lastReceivedGpInd.frameCounter === frameCounter)) {
             lastReceivedGpInd.srcId = srcId;
             lastReceivedGpInd.commandId = commandId;
@@ -503,6 +609,7 @@ function parseGreenPowerDataIndication(view: DataView): GpDataInd | null {
         return null;
     }
 }
+
 function parseMacPollCommand(_view: DataView): number {
     //logger.debug("Received command MAC_POLL", NS);
     return FirmwareCommand.MacPollIndication;

package/src/controller/controller.ts

@@ -18,6 +18,7 @@ import Database from "./database";
 import type * as Events from "./events";
 import GreenPower from "./greenPower";
 import {ZclFrameConverter} from "./helpers";
+import {checkInstallCode, parseInstallCode} from "./helpers/installCodes";
 import {Device, Entity} from "./model";
 import {InterviewState} from "./model/device";
 import Group from "./model/group";
@@ -246,34 +247,12 @@ export class Controller extends events.EventEmitter<ControllerEventMap> {
     }
 
     public async addInstallCode(installCode: string): Promise<void> {
-        const aqaraMatch = installCode.match(/^G\$M:.+\$A:(.+)\$I:(.+)$/);
-        const pipeMatch = installCode.match(/^(.+)\|(.+)$/);
-        let ieeeAddr: string;
-        let keyStr: string;
-
-        if (aqaraMatch) {
-            ieeeAddr = aqaraMatch[1];
-            keyStr = aqaraMatch[2];
-        } else if (pipeMatch) {
-            ieeeAddr = pipeMatch[1];
-            keyStr = pipeMatch[2];
-        } else {
-            assert(
-                installCode.length === 95 || installCode.length === 91,
-                `Unsupported install code, got ${installCode.length} chars, expected 95 or 91`,
-            );
-            const keyStart = installCode.length - (installCode.length === 95 ? 36 : 32);
-            ieeeAddr = installCode.substring(keyStart - 19, keyStart - 3);
-            keyStr = installCode.substring(keyStart, installCode.length);
-        }
-
-        ieeeAddr = `0x${ieeeAddr}`;
-        // match valid else asserted above
-        // biome-ignore lint/style/noNonNullAssertion: ignored using `--suppress`
+        // will throw if code cannot be parsed
+        const [ieeeAddr, keyStr] = parseInstallCode(installCode);
+        // biome-ignore lint/style/noNonNullAssertion: valid from above parsing
         const key = Buffer.from(keyStr.match(/.{1,2}/g)!.map((d) => Number.parseInt(d, 16)));
-
         // will throw if code cannot be fixed and is invalid
-        const [adjustedKey, adjusted] = ZSpec.Utils.checkInstallCode(key, true);
+        const [adjustedKey, adjusted] = checkInstallCode(key, true);
 
         if (adjusted) {
             logger.info(`Install code was adjusted for reason '${adjusted}'.`, NS);

package/src/controller/helpers/installCodes.ts

@@ -0,0 +1,107 @@
+import {INSTALL_CODE_CRC_SIZE, INSTALL_CODE_SIZES} from "../../zspec/consts";
+import {crc16X25} from "../../zspec/utils";
+
+/**
+ * Parse the given code using known formats:
+ * - 95 or 91-length
+ * - Widely adopted (Ubisys, Danfoss, Inovelli, Ledvance): ...Z:<ieee>$I:<key>...
+ * - Pipe-separated (Muller-Licht, Innr): <ieee>|<key>
+ * - Aqara: G$M:...$A:<ieee>$I:<key>
+ * - Hue: HUE:Z:<key> M:<ieee>...
+ * @param installCode
+ * @returns
+ *   - the IEEE address
+ *   - the raw key
+ */
+export function parseInstallCode(installCode: string): [ieeeAddr: string, key: string] {
+    const widelyAdoptedMatch = installCode.match(/Z:([a-zA-Z0-9]{16})\$I:([a-zA-Z0-9]+)/);
+
+    if (widelyAdoptedMatch) {
+        return [`0x${widelyAdoptedMatch[1].toLowerCase()}`, widelyAdoptedMatch[2]];
+    }
+
+    const pipeMatch = installCode.match(/^([a-zA-Z0-9]{16})\|([a-zA-Z0-9]+)$/);
+
+    if (pipeMatch) {
+        return [`0x${pipeMatch[1].toLowerCase()}`, pipeMatch[2]];
+    }
+
+    const aqaraMatch = installCode.match(/^G\$M:.+\$A:([a-zA-Z0-9]{16})\$I:([a-zA-Z0-9]+)$/);
+
+    if (aqaraMatch) {
+        return [`0x${aqaraMatch[1].toLowerCase()}`, aqaraMatch[2]];
+    }
+
+    const hueMatch = installCode.match(/^HUE:Z:([a-zA-Z0-9]+) M:([a-zA-Z0-9]{16})/);
+
+    if (hueMatch) {
+        return [`0x${hueMatch[2].toLowerCase()}`, hueMatch[1]];
+    }
+
+    if (installCode.length === 95 || installCode.length === 91) {
+        const keyStart = installCode.length - (installCode.length === 95 ? 36 : 32);
+
+        return [`0x${installCode.substring(keyStart - 19, keyStart - 3).toLowerCase()}`, installCode.substring(keyStart, installCode.length)];
+    }
+
+    throw new Error(`Unsupported install code, got ${installCode.length} chars, expected 95 or 91 chars, or known format`);
+}
+
+/**
+ * Check if install code (little-endian) is valid, and if not, and requested, fix it.
+ *
+ * WARNING: Due to conflicting sizes between 8-length code with invalid CRC, and 10-length code missing CRC, given 8-length codes are always assumed to be 8-length code with invalid CRC (most probable scenario).
+ *
+ * @param code The code to check. Reference is not modified by this procedure but is returned when code was valid, as `outCode`.
+ * @param adjust If false, throws if the install code is invalid, otherwise try to fix it (CRC)
+ * @returns
+ *   - The adjusted code, or `code` if not adjusted.
+ *   - If adjust is false, undefined, otherwise, the reason why the code needed adjusting or undefined if not.
+ *   - Throws when adjust=false and invalid, or cannot fix.
+ */
+export function checkInstallCode(code: Buffer, adjust = true): [outCode: Buffer, adjusted: "invalid CRC" | "missing CRC" | undefined] {
+    const crcLowByteIndex = code.length - INSTALL_CODE_CRC_SIZE;
+    const crcHighByteIndex = code.length - INSTALL_CODE_CRC_SIZE + 1;
+
+    for (const codeSize of INSTALL_CODE_SIZES) {
+        if (code.length === codeSize) {
+            // install code has CRC, check if valid, if not, replace it
+            const crc = crc16X25(code.subarray(0, -2));
+            const crcHighByte = (crc >> 8) & 0xff;
+            const crcLowByte = crc & 0xff;
+
+            if (code[crcLowByteIndex] !== crcLowByte || code[crcHighByteIndex] !== crcHighByte) {
+                // see WARNING above, 8 is smallest valid length, so always ends up here
+                if (adjust) {
+                    const outCode = Buffer.from(code);
+                    outCode[crcLowByteIndex] = crcLowByte;
+                    outCode[crcHighByteIndex] = crcHighByte;
+
+                    return [outCode, "invalid CRC"];
+                }
+
+                throw new Error(`Install code ${code.toString("hex")} failed CRC validation`);
+            }
+
+            return [code, undefined];
+        }
+
+        if (code.length === codeSize - INSTALL_CODE_CRC_SIZE) {
+            if (adjust) {
+                // install code is missing CRC
+                const crc = crc16X25(code);
+                const outCode = Buffer.alloc(code.length + INSTALL_CODE_CRC_SIZE);
+
+                code.copy(outCode, 0);
+                outCode.writeUInt16LE(crc, code.length);
+
+                return [outCode, "missing CRC"];
+            }
+
+            throw new Error(`Install code ${code.toString("hex")} failed CRC validation`);
+        }
+    }
+
+    // never returned from within the above loop
+    throw new Error(`Install code ${code.toString("hex")} has invalid size`);
+}