dsc-itv2-client 1.0.30 → 2.0.0

package/src/ITV2Client.js

@@ -1,985 +1,1408 @@
-/**
- * DSC ITV2 Protocol Client
- * Event-driven client for DSC alarm panels using the ITV2 protocol
- */
-
-import {EventEmitter} from 'events';
-import dgram from 'dgram';
-import net from 'net';
-import {ITv2Session, CMD, CMD_NAMES} from './itv2-session.js';
-import {parseType1Initializer, type2InitializerTransform} from './itv2-crypto.js';
-import {EventHandler} from './event-handler.js';
-import {parseCommandError} from './response-parsers.js';
-
-/**
- * ITV2Client - Main library class
- * Handles DSC panel communication and emits events for status updates
- */
-export class ITV2Client extends EventEmitter {
-    constructor(options = {}) {
-        super();
-
-        // Configuration
-        this.integrationId = options.integrationId;
-        this.accessCode = options.accessCode;
-        this.masterCode = options.masterCode || '5555';
-        this.port = options.port || 3073;  // UDP polling port
-        this.tcpPort = options.tcpPort || 3072;  // TCP notification port
-        this.logLevel = options.logLevel || (options.debug === true ? 'verbose' : 'minimal'); // 'silent', 'minimal', 'verbose'
-        this.encryptionType = options.encryptionType || null; // null = auto-detect, 1 = Type 1, 2 = Type 2
-
-        // Internal state
-        this.server = null;  // UDP server
-        this.tcpServer = null;  // TCP server
-        this.tcpClients = new Map();  // Active TCP connections
-        this.session = null;
-        this.eventHandler = new EventHandler();
-        this.handshakeState = 'WAITING';
-        this.panelAddress = null;
-        this.panelPort = null;
-        this.detectedEncryptionType = null; // Set during handshake
-        this._lastTransport = 'udp';  // Track last packet source
-        this._lastTcpSocket = null;  // Track TCP socket for responses
-
-        // Bind methods
-        this._handlePacket = this._handlePacket.bind(this);
-        this._handleError = this._handleError.bind(this);
-        this._boundShutdown = null; // Track signal handler for cleanup
-    }
-
-    /**
-     * Start the client and listen for panel connection
-     */
-    async start() {
-        return new Promise((resolve, reject) => {
-            this.server = dgram.createSocket('udp4');
-
-            this.server.on('error', (err) => {
-                this._log(`[Error] UDP server error: ${err.message}`);
-                this.emit('error', err);
-                reject(err);
-            });
-
-            this.server.on('message', (msg, rinfo) => {
-                this.panelAddress = rinfo.address;
-                this.panelPort = rinfo.port;
-                this._handlePacket(msg);
-            });
-
-            this.server.on('listening', () => {
-                const address = this.server.address();
-                this._log(`[UDP] Server listening on ${address.address}:${address.port}`);
-                this.emit('listening', address);
-                resolve();
-            });
-
-            this.server.bind(this.port, '0.0.0.0');
-
-            // Start TCP server for notification port
-            this._startTcpServer();
-
-            // Register signal handlers (only once)
-            if (!this._boundShutdown) {
-                this._boundShutdown = async () => {
-                    await this.stop();
-                    process.exit(0);
-                };
-                process.on('SIGINT', this._boundShutdown);
-                process.on('SIGTERM', this._boundShutdown);
-            }
-        });
-    }
-
-    /**
-     * Start TCP server for notification port (3072)
-     */
-    _startTcpServer() {
-        this.tcpServer = net.createServer((socket) => {
-            const clientId = `${socket.remoteAddress}:${socket.remotePort}`;
-            this._logMinimal(`[TCP] Client connected: ${clientId}`);
-            this.tcpClients.set(clientId, socket);
-
-            // Store panel address from TCP connection too
-            if (!this.panelAddress) {
-                this.panelAddress = socket.remoteAddress;
-            }
-
-            let buffer = Buffer.alloc(0);
-
-            socket.on('data', (data) => {
-                this._logMinimal(`[TCP] Received ${data.length} bytes from ${clientId}`);
-                this._logMinimal(`[TCP] Raw data: ${data.toString('hex')}`);
-
-                // Accumulate data in buffer
-                buffer = Buffer.concat([buffer, data]);
-
-                // Try to parse complete packets (look for 0x7E...0x7F framing)
-                this._processTcpBuffer(buffer, socket, (remaining) => {
-                    buffer = remaining;
-                });
-            });
-
-            socket.on('close', () => {
-                this._logMinimal(`[TCP] Client disconnected: ${clientId}`);
-                this.tcpClients.delete(clientId);
-            });
-
-            socket.on('error', (err) => {
-                this._log(`[TCP] Socket error for ${clientId}: ${err.message}`);
-                this.tcpClients.delete(clientId);
-            });
-        });
-
-        this.tcpServer.on('error', (err) => {
-            this._log(`[TCP] Server error: ${err.message}`);
-            this.emit('error', err);
-        });
-
-        this.tcpServer.listen(this.tcpPort, '0.0.0.0', () => {
-            this._logMinimal(`[TCP] Server listening on port ${this.tcpPort}`);
-            this.emit('tcp:listening', { port: this.tcpPort });
-        });
-    }
-
-    /**
-     * Process TCP buffer looking for complete ITV2 packets
-     */
-    _processTcpBuffer(buffer, socket, callback) {
-        // Look for Integration ID prefix followed by 0x7E
-        const idLength = 12; // Integration ID is 12 ASCII chars
-
-        while (buffer.length > idLength + 2) {
-            // Find start marker (0x7E) after integration ID
-            const startIdx = buffer.indexOf(0x7E, idLength - 1);
-            if (startIdx === -1) {
-                // No start marker found, keep last 12 bytes in case ID is split
-                callback(buffer.slice(Math.max(0, buffer.length - idLength)));
-                return;
-            }
-
-            // Find end marker (0x7F)
-            const endIdx = buffer.indexOf(0x7F, startIdx + 1);
-            if (endIdx === -1) {
-                // No end marker yet, wait for more data
-                callback(buffer);
-                return;
-            }
-
-            // Extract complete packet (including ID prefix)
-            const packetStart = Math.max(0, startIdx - idLength);
-            const packet = buffer.slice(packetStart, endIdx + 1);
-
-            this._logMinimal(`[TCP] Complete packet (${packet.length} bytes): ${packet.toString('hex')}`);
-
-            // Process the packet same as UDP
-            this._handlePacket(packet, 'tcp', socket);
-
-            // Continue with remaining buffer
-            buffer = buffer.slice(endIdx + 1);
-        }
-
-        callback(buffer);
-    }
-
-    /**
-     * Stop the client and close the session gracefully
-     */
-    async stop() {
-        if (this.session && this.handshakeState === 'ESTABLISHED') {
-            try {
-                const endSessionPacket = this.session.buildEndSession();
-                this._sendPacket(endSessionPacket);
-                this._log('[Shutdown] END_SESSION sent to panel');
-            } catch (err) {
-                this._log(`[Shutdown] Error sending END_SESSION: ${err.message}`);
-            }
-        }
-
-        if (this.server) {
-            await new Promise((resolve) => {
-                this.server.close(() => {
-                    this._log('[Shutdown] UDP server closed');
-                    resolve();
-                });
-            });
-            this.server = null;
-        }
-
-        // Close TCP server
-        if (this.tcpServer) {
-            // Close all TCP client connections
-            for (const [clientId, socket] of this.tcpClients) {
-                socket.destroy();
-            }
-            this.tcpClients.clear();
-
-            await new Promise((resolve) => {
-                this.tcpServer.close(() => {
-                    this._log('[Shutdown] TCP server closed');
-                    resolve();
-                });
-            });
-            this.tcpServer = null;
-        }
-
-        // Clear session and encryption state to prevent stale keys on reconnect
-        if (this.session) {
-            this.session.disableAes();
-            this.session = null;
-        }
-        this.handshakeState = 'WAITING';
-        this.panelAddress = null;
-        this.panelPort = null;
-        this.detectedEncryptionType = null;
-
-        // Remove signal handlers to prevent stacking on restart
-        if (this._boundShutdown) {
-            process.removeListener('SIGINT', this._boundShutdown);
-            process.removeListener('SIGTERM', this._boundShutdown);
-            this._boundShutdown = null;
-        }
-
-        this.emit('session:closed');
-    }
-
-    /**
-     * Arm partition in stay mode
-     */
-    armStay(partition, code) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.STAY, code || this.masterCode);
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Arm partition in away mode
-     */
-    armAway(partition, code) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.AWAY, code || this.masterCode);
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Arm partition in night mode
-     */
-    armNight(partition, code) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.NIGHT, code || this.masterCode);
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Disarm partition
-     */
-    disarm(partition, code) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildPartitionDisarm(partition, code || this.masterCode);
-        this._sendPacket(packet);
-    }
-
-    // ==================== Status Query Methods ====================
-
-    /**
-     * Query global system status (0x0810)
-     * Note: May not be supported by all panels
-     */
-    queryGlobalStatus() {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildGlobalStatusRequest();
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Query zone status (0x0811)
-     * @param {number} zone - Zone number (0 = all zones)
-     * Note: May not be supported by all panels
-     */
-    queryZoneStatus(zone = 0) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildZoneStatusRequest(zone);
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Query partition status (0x0812)
-     * @param {number} partition - Partition number (0 = all partitions)
-     * Note: May not be supported by all panels
-     */
-    queryPartitionStatus(partition = 0) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildPartitionStatusRequest(partition);
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Query zone bypass status (0x0813)
-     * @param {number} zone - Zone number (0 = all zones)
-     * Note: May not be supported by all panels
-     */
-    queryZoneBypassStatus(zone = 0) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildZoneBypassStatusRequest(zone);
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Query system trouble status (0x0814)
-     * Note: May not be supported by all panels
-     */
-    queryTroubleStatus() {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildTroubleStatusRequest();
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Send a raw command directly (not wrapped in 0x0800)
-     * Useful for testing different query formats
-     * @param {number} command - Command code (e.g., 0x0812)
-     * @param {Buffer} [payload] - Optional payload data
-     */
-    sendDirect(command, payload = null) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildCommand(command, payload);
-        this._logMinimal(`[Direct] Sending command 0x${command.toString(16).padStart(4, '0')} ${payload ? 'with ' + payload.length + ' bytes payload' : 'no payload'}`);
-        this._sendPacket(packet);
-    }
-
-    // ==================== Authentication Methods ====================
-
-    /**
-     * Authenticate with access code - simple format (0x0400)
-     * Uses 6-digit ASCII format matching interactive CLI
-     * @param {string} code - User/master code (e.g., "5555")
-     */
-    authenticate(code) {
-        if (!this._checkEstablished()) return;
-        const codeStr = (code || this.masterCode).toString().padStart(6, '0').slice(0, 6);
-        const payload = Buffer.from(codeStr, 'ascii');
-        const packet = this.session.buildCommand(0x0400, payload);
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Authenticate with access code - extended format (0x0400)
-     * Includes partition and access level metadata
-     * @param {number} partition - Partition number (1-8, or 0 for all)
-     * @param {string} code - User/master code (e.g., "5555")
-     * @param {number} accessLevel - 0=User, 1=Installer, 2=Master
-     */
-    authenticateExtended(partition = 1, code, accessLevel = 0) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildAccessLevelEnter(
-            code || this.masterCode,
-            partition,
-            accessLevel,
-            'bcd'
-        );
-        this._sendPacket(packet);
-    }
-
-    /**
-     * Exit authenticated access level (0x0401)
-     * @param {number} partition - Partition number
-     */
-    deauthenticate(partition = 1) {
-        if (!this._checkEstablished()) return;
-        const packet = this.session.buildAccessLevelExit(partition);
-        this._sendPacket(packet);
-    }
-
-    // ==================== State Accessors ====================
-
-    /**
-     * Get current zone states
-     */
-    getZones() {
-        return this.eventHandler.getAllZones();
-    }
-
-    /**
-     * Get current partition states
-     */
-    getPartitions() {
-        return this.eventHandler.getAllPartitions();
-    }
-
-    // ==================== Internal Methods ====================
-
-    _checkEstablished() {
-        if (this.handshakeState !== 'ESTABLISHED') {
-            this.emit('error', new Error('Session not established'));
-            return false;
-        }
-        return true;
-    }
-
-    _sendPacket(packet) {
-        // Use the same transport that the last packet came from
-        if (this._lastTransport === 'tcp' && this._lastTcpSocket) {
-            this._log(`\n[TCP] TX (${packet.length} bytes)`);
-            if (this.debug) {
-                this._hexDump(packet);
-            }
-            this._lastTcpSocket.write(packet);
-        } else {
-            // UDP (default)
-            if (!this.panelAddress || !this.panelPort) {
-                this._log('[Error] No panel address/port set');
-                return;
-            }
-
-            this._log(`\n[UDP] TX to ${this.panelAddress}:${this.panelPort} (${packet.length} bytes)`);
-            if (this.debug) {
-                this._hexDump(packet);
-            }
-            this.server.send(packet, this.panelPort, this.panelAddress);
-        }
-    }
-
-    _handlePacket(data, transport = 'udp', tcpSocket = null) {
-        try {
-            if (!this.session) {
-                // Create session with appropriate logger based on log level
-                const logger = this.logLevel === 'verbose' ? this._log.bind(this) : () => {
-                };
-                this.session = new ITv2Session(this.integrationId, this.accessCode, logger);
-            }
-
-            const parsed = this.session.parsePacket(data);
-            if (!parsed) {
-                this._log('[Error] Failed to parse packet');
-                return;
-            }
-
-            // Store transport info for responses
-            this._lastTransport = transport;
-            this._lastTcpSocket = tcpSocket;
-
-            // Verbose logging
-            const source = transport === 'tcp' ? 'TCP' : `UDP ${this.panelAddress}:${this.panelPort}`;
-            this._log(`\n[${transport.toUpperCase()}] RX from ${source} (${data.length} bytes)`);
-            this._hexDump(data);
-            this._log(`[Packet] Integration ID: ${parsed.integrationId}`);
-            this._log(`[Packet] Sender Seq: ${parsed.senderSequence}, Receiver Seq: ${parsed.receiverSequence}`);
-            this._log(`[Packet] Command: ${CMD_NAMES[parsed.command] || parsed.command}`);
-            if (parsed.appSequence !== null) {
-                this._log(`[Packet] App Seq: ${parsed.appSequence}`);
-            }
-            if (parsed.commandData) {
-                this._log(`[Packet] Data (${parsed.commandData.length} bytes): ${parsed.commandData.toString('hex').toUpperCase().match(/.{1,2}/g).join(' ')}`);
-            }
-
-            // Route based on command
-            this._routePacket(parsed);
-
-        } catch (err) {
-            // During WAITING state, parse errors are expected (stale encrypted packets from previous session)
-            if (this.handshakeState === 'WAITING') {
-                this._log(`[Recovery] Ignoring malformed packet while waiting for fresh handshake: ${err.message}`);
-                // Reset session to ensure we start fresh on next valid packet
-                if (this.session) {
-                    this.session.disableAes();
-                    this.session = null;
-                }
-                return;
-            }
-
-            this._log(`[Error] ${err.message}`);
-            this.emit('error', err);
-
-            // Reset on parse errors during handshake
-            if (this.handshakeState !== 'SENT_CMD_RESPONSE_1') {
-                this._log('[Recovery] Parse error, resetting to wait for panel restart');
-                if (this.session) {
-                    this.session.disableAes();
-                    this.session = null;
-                }
-                this.handshakeState = 'WAITING';
-            }
-        }
-    }
-
-    _routePacket(parsed) {
-        const cmd = parsed.command;
-
-        // Handle ACKs
-        if (cmd === null || cmd === undefined || cmd === CMD.SIMPLE_ACK) {
-            this._handleSimpleAck(parsed);
-            return;
-        }
-
-        // Route based on command type
-        switch (cmd) {
-            case CMD.OPEN_SESSION:
-                this._handleOpenSession(parsed);
-                break;
-            case CMD.REQUEST_ACCESS:
-                this._handleRequestAccess(parsed);
-                break;
-            case CMD.COMMAND_RESPONSE:
-                this._handleCommandResponse(parsed);
-                break;
-            case CMD.COMMAND_ERROR:
-                this._handleCommandError(parsed);
-                break;
-            case CMD.POLL:
-                this._handlePoll(parsed);
-                break;
-            case CMD.LIFESTYLE_ZONE_STATUS:
-                this._handleLifestyleZoneStatus(parsed);
-                break;
-            case CMD.TIME_DATE_BROADCAST:
-                this._handleTimeDateBroadcast(parsed);
-                break;
-            case CMD.ZONE_STATUS:
-                this._handleZoneStatusResponse(parsed);
-                break;
-            case CMD.PARTITION_STATUS:
-                this._handlePartitionStatusResponse(parsed);
-                break;
-            case CMD.GLOBAL_STATUS:
-                this._handleGlobalStatusResponse(parsed);
-                break;
-            case CMD.SYSTEM_TROUBLE_STATUS:
-                this._handleTroubleStatusResponse(parsed);
-                break;
-            default:
-                if (this.handshakeState === 'ESTABLISHED') {
-                    const cmdHex = cmd ? '0x' + cmd.toString(16).padStart(4, '0') : 'null';
-                    const cmdName = CMD_NAMES[cmd] || 'UNKNOWN';
-                    this._logMinimal(`[Session] Received command ${cmdName} (${cmdHex})`);
-                    if (parsed.commandData && parsed.commandData.length > 0) {
-                        this._logMinimal(`[Session] Data (${parsed.commandData.length} bytes): ${parsed.commandData.toString('hex')}`);
-                    }
-                    this._sendPacket(this.session.buildSimpleAck());
-                }
-                break;
-        }
-    }
-
-    // ==================== Handshake Handlers ====================
-
-    _handleOpenSession(parsed) {
-        const data = parsed.commandData;
-        if (!data || data.length < 14) {
-            this._log('[Error] Invalid OPEN_SESSION data');
-            return;
-        }
-
-        const deviceType = data[0];
-        const deviceId = data.readUInt16BE(1);
-        const firmware = data.readUInt16BE(3);
-        const protocol = data.readUInt16BE(5);
-        const txBuffer = data.readUInt16BE(7);
-        const rxBuffer = data.readUInt16BE(9);
-        const encryptionType = data[13];
-
-        this._log(`[Session] OPEN_SESSION received:`);
-        this._log(`  Device Type: ${deviceType}`);
-        this._log(`  Encryption Type: ${encryptionType}`);
-
-        // Emit connecting event now that we have a valid OPEN_SESSION
-        this.emit('session:connecting');
-        this._logMinimal(`[Session] Panel connecting from ${this.panelAddress}`);
-        this._logMinimal('[Handshake] Starting session establishment...');
-
-        // Handle panel restart mid-handshake
-        if (this.handshakeState !== 'WAITING' && this.handshakeState !== 'SENT_CMD_RESPONSE_1') {
-            this._log(`[Session] Panel restarting handshake (was in state ${this.handshakeState}), resetting session`);
-            this.session = new ITv2Session(this.integrationId, this.accessCode, this._log.bind(this));
-        }
-
-        // Send COMMAND_RESPONSE echoing device type
-        this._log(`[Handshake] Sending COMMAND_RESPONSE success (echoing device type ${deviceType})`);
-        const response = this.session.buildCommandResponseWithAppSeq(deviceType, 0x00);
-        this._sendPacket(response);
-        this.handshakeState = 'SENT_CMD_RESPONSE_1';
-    }
-
-    _handleSimpleAck(parsed) {
-        const expectedSeq = this.session.localSequence;
-        this._log(`[Handshake] Got ACK ${parsed.receiverSequence}, state=${this.handshakeState}`);
-
-        if (this.handshakeState === 'SENT_CMD_RESPONSE_1') {
-            // Panel ACKed our first COMMAND_RESPONSE, send OPEN_SESSION
-            this._log(`[Handshake] Got ACK 1, sending our OPEN_SESSION`);
-            const openSessionPayload = Buffer.from([
-                0x01, 0x80, 0x00, 0x00, // Device ID/type
-                0x02, 0x01,             // Firmware
-                0x02, 0x41,             // Protocol version
-                0x02, 0x00,             // TX buffer
-                0x02, 0x00,             // RX buffer
-                0x00, 0x01, 0x01        // Capabilities/encryption
-            ]);
-            const packet = this.session.buildOpenSessionResponse(openSessionPayload);
-            this._sendPacket(packet);
-            this.handshakeState = 'SENT_OPEN_SESSION';
-        } else if (this.handshakeState === 'WAITING_TO_SEND_REQUEST_ACCESS') {
-            // Panel ACKed our COMMAND_RESPONSE to their REQUEST_ACCESS
-            this._log(`[Handshake] Got ACK, now sending our REQUEST_ACCESS`);
-
-            // Enable encryption with SEND key
-            this.session.sendAesActive = true;
-            this.session.sendAesKey = this.session.derivedSendKey;
-            this._log(`[Handshake] Encrypting REQUEST_ACCESS with SEND key`);
-
-            // Build REQUEST_ACCESS based on detected encryption type
-            let reqAccessPacket;
-            if (this.detectedEncryptionType === 2) {
-                this._log(`[Handshake] Using Type 2 REQUEST_ACCESS`);
-                reqAccessPacket = this.session.buildRequestAccessType2();
-            } else {
-                this._log(`[Handshake] Using Type 1 REQUEST_ACCESS`);
-                reqAccessPacket = this.session.buildRequestAccessType1();
-            }
-
-            this._sendPacket(reqAccessPacket);
-
-            // Enable receive encryption
-            this.session.receiveAesActive = true;
-            this.session.receiveAesKey = this.session.pendingReceiveKey;
-            this._log(`[Handshake] Enabled receive encryption`);
-
-            this.handshakeState = 'SENT_REQUEST_ACCESS';
-        } else if (this.handshakeState === 'SENT_REQUEST_ACCESS') {
-            // Panel ACKed our REQUEST_ACCESS - session established!
-            this.handshakeState = 'ESTABLISHED';
-            this._logMinimal(`[Handshake] Session established (Type ${this.detectedEncryptionType} encryption)`);
-            this._log(`[Handshake] *** SESSION ESTABLISHED ***`);
-            this._log(`[Handshake] Encryption Type: ${this.detectedEncryptionType}`);
-            this._log(`[Handshake] SEND key: ${this.session.derivedSendKey?.toString('hex')}`);
-            this._log(`[Handshake] RECV key: ${this.session.pendingReceiveKey?.toString('hex')}`);
-
-            this.emit('session:established', {
-                encryptionType: this.detectedEncryptionType,
-                sendKey: this.session.derivedSendKey?.toString('hex'),
-                recvKey: this.session.pendingReceiveKey?.toString('hex')
-            });
-        }
-    }
-
-    _handleRequestAccess(parsed) {
-        const data = parsed.commandData;
-        if (!data || data.length < 17) {
-            this._log('[Error] Invalid REQUEST_ACCESS data');
-            return;
-        }
-
-        const initType = data[0];
-        const initializer = data.slice(1);
-
-        this._log(`[Handshake] Got panel's REQUEST_ACCESS`);
-        this._log(`[Handshake] Processing panel's REQUEST_ACCESS (panel goes first)`);
-
-        // Determine encryption type based on initializer length
-        if (initializer.length === 48) {
-            // Type 1 encryption
-            this.detectedEncryptionType = 1;
-            this._log(`[Handshake] Encryption Type 1 (48-byte initializer)`);
-
-            const sendKey = parseType1Initializer(this.accessCode, initializer, this.integrationId, this.logLevel === 'verbose');
-            this._logMinimal('[Handshake] Type 1 encryption negotiated');
-            this._log(`[Handshake] Type 1 SEND key derived`);
-            this.session.derivedSendKey = sendKey;
-
-        } else if (initializer.length === 16) {
-            // Type 2 encryption
-            this.detectedEncryptionType = 2;
-            this._log(`[Handshake] Encryption Type 2 (16-byte initializer)`);
-
-            // Type 2: Symmetric transform with 32-hex access code
-            let accessCode32 = this.accessCode;
-            if (accessCode32.length === 8) {
-                accessCode32 = accessCode32 + accessCode32 + accessCode32 + accessCode32;
-            }
-
-            const sendKey = type2InitializerTransform(accessCode32, initializer);
-            this._logMinimal('[Handshake] Type 2 encryption negotiated');
-            this._log(`[Handshake] Type 2 SEND key derived`);
-            this.session.derivedSendKey = sendKey;
-
-        } else {
-            this._log(`[Error] Unknown initializer length: ${initializer.length}`);
-            return;
-        }
-
-        // Send plaintext COMMAND_RESPONSE
-        this._log(`[Handshake] Sending PLAINTEXT COMMAND_RESPONSE to panel's REQUEST_ACCESS`);
-        const appSeq = parsed.appSequence;
-        const response = this.session.buildCommandResponseWithAppSeq(appSeq, 0x00);
-        this._sendPacket(response);
-
-        // Send our REQUEST_ACCESS immediately (panel doesn't ACK our COMMAND_RESPONSE)
-        this._logMinimal('[Handshake] Sending our REQUEST_ACCESS...');
-
-        // Enable encryption with SEND key
-        this.session.sendAesActive = true;
-        this.session.sendAesKey = this.session.derivedSendKey;
-        this._log(`[Handshake] Encrypting REQUEST_ACCESS with SEND key`);
-
-        // Build REQUEST_ACCESS based on detected encryption type
-        let reqAccessPacket;
-        if (this.detectedEncryptionType === 2) {
-            this._log(`[Handshake] Using Type 2 REQUEST_ACCESS`);
-            reqAccessPacket = this.session.buildRequestAccessType2();
-        } else {
-            this._log(`[Handshake] Using Type 1 REQUEST_ACCESS`);
-            reqAccessPacket = this.session.buildRequestAccessType1();
-        }
-
-        this._sendPacket(reqAccessPacket);
-
-        // Enable receive encryption
-        this.session.receiveAesActive = true;
-        this.session.receiveAesKey = this.session.pendingReceiveKey;
-        this._log(`[Handshake] Enabled receive encryption`);
-
-        this.handshakeState = 'SENT_REQUEST_ACCESS';
-    }
-
-    _handleCommandResponse(parsed) {
-        const data = parsed.commandData;
-        const responseCode = data?.[0] || 0;
-        const appSeqAsEcho = parsed.appSequence;
-
-        this._log(`[Session] Got COMMAND_RESPONSE (app_seq: ${appSeqAsEcho}, response_code: ${responseCode})`);
-
-        // Log full data in established state for debugging query responses
-        if (this.handshakeState === 'ESTABLISHED' && data && data.length > 1) {
-            this._logMinimal(`[Command Response] Response code: ${responseCode}, data (${data.length} bytes): ${data.toString('hex')}`);
-            this.emit('command:response', { responseCode, appSequence: appSeqAsEcho, data });
-        }
-
-        const ack = this.session.buildSimpleAck();
-        this._sendPacket(ack);
-
-        if (this.handshakeState === 'SENT_OPEN_SESSION') {
-            // Panel accepted our OPEN_SESSION
-            this.handshakeState = 'WAITING_REQUEST_ACCESS';
-        } else if (this.handshakeState === 'SENT_REQUEST_ACCESS') {
-            // Panel accepted our REQUEST_ACCESS - session established!
-            this.handshakeState = 'ESTABLISHED';
-            this._logMinimal(`[Handshake] Session established (Type ${this.detectedEncryptionType} encryption)`);
-            this.emit('session:established', {
-                encryptionType: this.detectedEncryptionType,
-                sendKey: this.session.derivedSendKey?.toString('hex'),
-                recvKey: this.session.pendingReceiveKey?.toString('hex')
-            });
-        }
-    }
-
-    _handleCommandError(parsed) {
-        const errorData = parsed.commandData;
-        const error = parseCommandError(errorData);
-
-        this._log(`[Error] COMMAND_ERROR: ${error.message} (${error.rawData})`);
-        this.emit('command:error', error);
-
-        // Send ACK
-        this._sendPacket(this.session.buildSimpleAck());
-    }
-
-    _handlePoll(parsed) {
-        this._log(`[Session] Got POLL, sending ACK`);
-        this._sendPacket(this.session.buildSimpleAck());
-    }
-
-    // ==================== Notification Handlers ====================
-
-    _handleLifestyleZoneStatus(parsed) {
-        // If we receive encrypted zone data, session is established (even if we missed the final ACK)
-        if (this.handshakeState === 'SENT_REQUEST_ACCESS') {
-            this.handshakeState = 'ESTABLISHED';
-            this._logMinimal(`[Handshake] Session established (Type ${this.detectedEncryptionType} encryption)`);
-            this.emit('session:established', {
-                encryptionType: this.detectedEncryptionType,
-                sendKey: this.session.derivedSendKey?.toString('hex'),
-                recvKey: this.session.pendingReceiveKey?.toString('hex')
-            });
-        }
-
-        const data = parsed.commandData;
-
-        if (data && data.length >= 2) {
-            const zoneNum = data[0];
-            const statusValue = data[1];
-
-            // Update internal state and get full parsed status
-            const fullStatus = this.eventHandler.handleZoneStatus(zoneNum, statusValue);
-
-            // Emit events with full status object
-            this.emit('zone:status', zoneNum, fullStatus);
-
-            if (fullStatus.open) {
-                this.emit('zone:open', zoneNum);
-                this._log(`[Zone ${zoneNum}] OPEN (status: ${statusValue})`);
-            } else {
-                this.emit('zone:closed', zoneNum);
-                this._log(`[Zone ${zoneNum}] CLOSED (status: ${statusValue})`);
-            }
-        }
-
-        this._sendPacket(this.session.buildSimpleAck());
-    }
-
-    _handleTimeDateBroadcast(parsed) {
-        const data = parsed.commandData;
-        if (data && data.length >= 5) {
-            this._log(`[Time/Date] Received broadcast`);
-            this.emit('notification:timeDate', data);
-        }
-        this._sendPacket(this.session.buildSimpleAck());
-    }
-
-    // ==================== Status Query Response Handlers ====================
-
-    _handleZoneStatusResponse(parsed) {
-        const data = parsed.commandData;
-        this._logMinimal(`[Zone Status] Received zone status response`);
-        this._log(`[Zone Status] Raw data (${data?.length || 0} bytes): ${data?.toString('hex') || 'none'}`);
-
-        if (data && data.length >= 3) {
-            // Response format: [ZoneNumber 2B BE][StatusByte 1B][...more zones...]
-            const zoneNum = data.readUInt16BE(0);
-            const statusByte = data[2];
-
-            // Update internal state
-            const fullStatus = this.eventHandler.handleZoneStatus(zoneNum, statusByte);
-
-            this._logMinimal(`[Zone Status] Zone ${zoneNum}: ${fullStatus.open ? 'OPEN' : 'CLOSED'} (0x${statusByte.toString(16)})`);
-
-            // Emit event with full status
-            this.emit('zone:statusResponse', zoneNum, fullStatus);
-            this.emit('zone:status', zoneNum, fullStatus);
-        } else {
-            this._log(`[Zone Status] Empty or invalid response`);
-        }
-
-        this._sendPacket(this.session.buildSimpleAck());
-    }
-
-    _handlePartitionStatusResponse(parsed) {
-        const data = parsed.commandData;
-        this._logMinimal(`[Partition Status] Received partition status response`);
-        this._log(`[Partition Status] Raw data (${data?.length || 0} bytes): ${data?.toString('hex') || 'none'}`);
-
-        if (data && data.length >= 3) {
-            // Response format: [PartitionNumber 2B BE][StatusBytes...]
-            const partitionNum = data.readUInt16BE(0);
-            const statusBytes = data.slice(2);
-
-            this._logMinimal(`[Partition Status] Partition ${partitionNum}: status bytes ${statusBytes.toString('hex')}`);
-
-            // Emit raw event - let consumers parse the detailed status
-            this.emit('partition:statusResponse', partitionNum, statusBytes);
-        } else {
-            this._log(`[Partition Status] Empty or invalid response`);
-        }
-
-        this._sendPacket(this.session.buildSimpleAck());
-    }
-
-    _handleGlobalStatusResponse(parsed) {
-        const data = parsed.commandData;
-        this._logMinimal(`[Global Status] Received global status response`);
-        this._log(`[Global Status] Raw data (${data?.length || 0} bytes): ${data?.toString('hex') || 'none'}`);
-
-        if (data && data.length > 0) {
-            // Emit raw event with full data
-            this.emit('global:statusResponse', data);
-
-            // Log byte breakdown for debugging
-            this._log(`[Global Status] Byte breakdown:`);
-            for (let i = 0; i < data.length && i < 32; i++) {
-                this._log(`  Byte ${i}: 0x${data[i].toString(16).padStart(2, '0')} (${data[i]})`);
-            }
-        } else {
-            this._log(`[Global Status] Empty response`);
-        }
-
-        this._sendPacket(this.session.buildSimpleAck());
-    }
-
-    _handleTroubleStatusResponse(parsed) {
-        const data = parsed.commandData;
-        this._logMinimal(`[Trouble Status] Received trouble status response`);
-        this._log(`[Trouble Status] Raw data (${data?.length || 0} bytes): ${data?.toString('hex') || 'none'}`);
-
-        if (!data || data.length === 0) {
-            this._logMinimal(`[Trouble Status] No active troubles`);
-            this.emit('trouble:statusResponse', []);
-            this._sendPacket(this.session.buildSimpleAck());
-            return;
-        }
-
-        // Try to parse as VarBytes device/trouble list:
-        // [VarByte:DeviceType][Count][VarByte:TroubleType]... repeated
-        const troubles = [];
-        let offset = 0;
-
-        try {
-            while (offset < data.length) {
-                const device = ITv2Session.decodeVarBytes(data, offset);
-                offset += device.bytesRead;
-
-                const troubleCount = data[offset];
-                offset += 1;
-
-                const troubleTypes = [];
-                for (let i = 0; i < troubleCount; i++) {
-                    const trouble = ITv2Session.decodeVarBytes(data, offset);
-                    offset += trouble.bytesRead;
-                    troubleTypes.push(trouble.value);
-                }
-
-                troubles.push({ deviceType: device.value, troubles: troubleTypes });
-                this._logMinimal(`[Trouble Status] Device ${device.value}: troubles [${troubleTypes.join(', ')}]`);
-            }
-        } catch (e) {
-            this._logMinimal(`[Trouble Status] Parse error at offset ${offset}: ${e.message}`);
-            this._logMinimal(`[Trouble Status] Raw hex: ${data.toString('hex')}`);
-        }
-
-        this.emit('trouble:statusResponse', troubles);
-        this._sendPacket(this.session.buildSimpleAck());
-    }
-
-    // ==================== Utility Methods ====================
-
-    _handleError(error) {
-        this._log(`[Error] ${error.message}`);
-        this.emit('error', error);
-    }
-
-    _log(message) {
-        if (this.logLevel === 'verbose') {
-            const timestamp = new Date().toISOString();
-            console.log(`dsc itv2: [${timestamp}] ${message}`);
-        }
-    }
-
-    _logMinimal(message) {
-        if (this.logLevel === 'minimal' || this.logLevel === 'verbose') {
-            console.log(`dsc itv2: ${message}`);
-        }
-    }
-
-    _hexDump(buffer) {
-        if (this.logLevel !== 'verbose') return;
-
-        for (let i = 0; i < buffer.length; i += 16) {
-            const chunk = buffer.slice(i, i + 16);
-            const hex = Array.from(chunk)
-                .map((b) => b.toString(16).padStart(2, '0').toUpperCase())
-                .join(' ');
-            const ascii = Array.from(chunk)
-                .map((b) => (b >= 32 && b <= 126 ? String.fromCharCode(b) : '.'))
-                .join('');
-
-            const offset = i.toString(16).padStart(4, '0').toUpperCase();
-            console.log(`dsc itv2: ${offset}  ${hex.padEnd(48)}  |${ascii}|`);
-        }
-    }
-}
+/**
+ * DSC ITV2 Protocol Client
+ * Event-driven client for DSC alarm panels using the ITV2 protocol
+ */
+
+import {EventEmitter} from 'events';
+import net from 'net';
+import {ITv2Session, CMD, CMD_NAMES} from './itv2-session.js';
+import {parseType1Initializer, type2InitializerTransform} from './itv2-crypto.js';
+import {EventHandler} from './event-handler.js';
+import {parseCommandError} from './response-parsers.js';
+
+/**
+ * ITV2Client - Main library class
+ * Handles DSC panel communication and emits events for status updates
+ */
+export class ITV2Client extends EventEmitter {
+    constructor(options = {}) {
+        super();
+
+        // Configuration
+        this.integrationId = options.integrationId;
+        this.accessCode = options.accessCode;
+        this.masterCode = options.masterCode || '5555';
+        this.port = options.port || 3072;  // TCP port (panel connects to us)
+        this.logLevel = options.logLevel || (options.debug === true ? 'verbose' : 'minimal'); // 'silent', 'minimal', 'verbose'
+        this.encryptionType = options.encryptionType || null; // null = auto-detect, 1 = Type 1, 2 = Type 2
+
+        // Internal state
+        this.tcpServer = null;  // TCP server
+        this.tcpSocket = null;  // Active panel TCP connection
+        this.session = null;
+        this.eventHandler = new EventHandler();
+        this.handshakeState = 'WAITING';
+        this.panelAddress = null;
+        this.detectedEncryptionType = null; // Set during handshake
+        this._panelOpenSessionData = null; // Saved panel OPEN_SESSION payload for echoing
+        this._heartbeatInterval = null;  // Heartbeat timer
+        this._sessionReady = false;  // True after initial message burst subsides
+        this._readyTimer = null;  // Timer for session readiness detection
+        this._pendingRequests = new Map();  // command code → { resolve, reject, timer }
+        this._capabilities = null;  // Cached from initial capabilities query
+
+        // Bind methods
+        this._handlePacket = this._handlePacket.bind(this);
+        this._handleError = this._handleError.bind(this);
+        this._boundShutdown = null; // Track signal handler for cleanup
+    }
+
+    /**
+     * Start the TCP server and listen for panel connection
+     * The panel initiates a TCP connection to us on port 3072 (default)
+     */
+    async start() {
+        return new Promise((resolve, reject) => {
+            this.tcpServer = net.createServer((socket) => {
+                const clientId = `${socket.remoteAddress}:${socket.remotePort}`;
+                this._logMinimal(`[TCP] Panel connected: ${clientId}`);
+
+                this.panelAddress = socket.remoteAddress;
+                this.tcpSocket = socket;
+
+                let buffer = Buffer.alloc(0);
+
+                socket.on('data', (data) => {
+                    this._log(`[TCP] Received ${data.length} bytes from ${clientId}`);
+
+                    // Accumulate data in buffer
+                    buffer = Buffer.concat([buffer, data]);
+
+                    // Parse complete packets (0x7E...0x7F framing)
+                    buffer = this._processTcpBuffer(buffer);
+                });
+
+                socket.on('close', () => {
+                    this._logMinimal(`[TCP] Panel disconnected: ${clientId}`);
+                    this.tcpSocket = null;
+                    this.handshakeState = 'WAITING';
+                    if (this.session) {
+                        this.session.disableAes();
+                        this.session = null;
+                    }
+                    this.emit('session:closed');
+                });
+
+                socket.on('error', (err) => {
+                    this._log(`[TCP] Socket error for ${clientId}: ${err.message}`);
+                    this.tcpSocket = null;
+                });
+            });
+
+            this.tcpServer.on('error', (err) => {
+                this._log(`[Error] TCP server error: ${err.message}`);
+                this.emit('error', err);
+                reject(err);
+            });
+
+            this.tcpServer.listen(this.port, '0.0.0.0', () => {
+                const address = this.tcpServer.address();
+                this._logMinimal(`[TCP] Server listening on port ${address.port}`);
+                this.emit('listening', address);
+                resolve();
+            });
+
+            // Register signal handlers (only once)
+            if (!this._boundShutdown) {
+                this._boundShutdown = async () => {
+                    await this.stop();
+                    process.exit(0);
+                };
+                process.on('SIGINT', this._boundShutdown);
+                process.on('SIGTERM', this._boundShutdown);
+            }
+        });
+    }
+
+    /**
+     * Process TCP buffer looking for complete ITV2 packets
+     * Returns remaining unprocessed buffer
+     */
+    _processTcpBuffer(buffer) {
+        while (buffer.length > 2) {
+            // Find start marker (0x7E)
+            const startIdx = buffer.indexOf(0x7E);
+            if (startIdx === -1) {
+                // No start marker, keep last 12 bytes in case integration ID is split
+                return buffer.slice(Math.max(0, buffer.length - 12));
+            }
+
+            // Find end marker (0x7F) after start
+            const endIdx = buffer.indexOf(0x7F, startIdx + 1);
+            if (endIdx === -1) {
+                // No end marker yet, wait for more data
+                // Keep from the integration ID prefix (up to 12 bytes before 0x7E)
+                return buffer.slice(Math.max(0, startIdx - 12));
+            }
+
+            // Extract complete packet (integration ID prefix + 0x7E...0x7F)
+            const packetStart = Math.max(0, startIdx - 12);
+            const packet = buffer.slice(packetStart, endIdx + 1);
+
+            this._log(`[TCP] Complete packet (${packet.length} bytes)`);
+            this._handlePacket(packet);
+
+            // Continue with remaining buffer
+            buffer = buffer.slice(endIdx + 1);
+        }
+
+        return buffer;
+    }
+
+    /**
+     * Stop the client and close the session gracefully
+     */
+    async stop() {
+        if (this.session && this.handshakeState === 'ESTABLISHED') {
+            try {
+                const endSessionPacket = this.session.buildEndSession();
+                this._sendPacket(endSessionPacket);
+                this._log('[Shutdown] END_SESSION sent to panel');
+            } catch (err) {
+                this._log(`[Shutdown] Error sending END_SESSION: ${err.message}`);
+            }
+        }
+
+        // Close panel socket
+        if (this.tcpSocket) {
+            this.tcpSocket.destroy();
+            this.tcpSocket = null;
+        }
+
+        // Close TCP server
+        if (this.tcpServer) {
+            await new Promise((resolve) => {
+                this.tcpServer.close(() => {
+                    this._log('[Shutdown] TCP server closed');
+                    resolve();
+                });
+            });
+            this.tcpServer = null;
+        }
+
+        // Clear heartbeat
+        if (this._heartbeatInterval) {
+            clearInterval(this._heartbeatInterval);
+            this._heartbeatInterval = null;
+        }
+        if (this._readyTimer) {
+            clearTimeout(this._readyTimer);
+            this._readyTimer = null;
+        }
+        this._sessionReady = false;
+
+        // Clear pending requests
+        for (const [, pending] of this._pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Session closed'));
+        }
+        this._pendingRequests.clear();
+
+        // Clear session and encryption state to prevent stale keys on reconnect
+        if (this.session) {
+            this.session.disableAes();
+            this.session = null;
+        }
+        this.handshakeState = 'WAITING';
+        this.panelAddress = null;
+        this.detectedEncryptionType = null;
+        this._panelOpenSessionData = null;
+
+        // Remove signal handlers to prevent stacking on restart
+        if (this._boundShutdown) {
+            process.removeListener('SIGINT', this._boundShutdown);
+            process.removeListener('SIGTERM', this._boundShutdown);
+            this._boundShutdown = null;
+        }
+
+        this.emit('session:closed');
+    }
+
+    /**
+     * Arm partition in stay mode (mode 1)
+     */
+    armStay(partition, code) {
+        if (!this._checkEstablished()) return;
+        const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.STAY, code || this.masterCode);
+        this._sendPacket(packet);
+    }
+
+    /**
+     * Arm partition in away mode (mode 2)
+     */
+    armAway(partition, code) {
+        if (!this._checkEstablished()) return;
+        const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.AWAY, code || this.masterCode);
+        this._sendPacket(packet);
+    }
+
+    /**
+     * Arm partition in night mode (mode 4)
+     */
+    armNight(partition, code) {
+        if (!this._checkEstablished()) return;
+        const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.NIGHT, code || this.masterCode);
+        this._sendPacket(packet);
+    }
+
+    /**
+     * Arm partition with no entry delay (mode 3)
+     */
+    armNoEntryDelay(partition, code) {
+        if (!this._checkEstablished()) return;
+        const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.NO_ENTRY_DELAY, code || this.masterCode);
+        this._sendPacket(packet);
+    }
+
+    /**
+     * Disarm partition
+     */
+    disarm(partition, code) {
+        if (!this._checkEstablished()) return;
+        const packet = this.session.buildPartitionDisarm(partition, code || this.masterCode);
+        this._sendPacket(packet);
+    }
+
+    // ==================== Status Query Methods ====================
+
+    /**
+     * Send a 0x0800 command request and wait for the response.
+     * @param {number} expectedCmd - The inner command code we expect back (e.g., 0x0811)
+     * @param {Buffer} packet - The built packet to send
+     * @param {number} timeout - Timeout in ms (default 10000)
+     * @returns {Promise<object>} Parsed response data
+     */
+    _sendQuery(expectedCmd, packet, timeout = 10000) {
+        if (!this._checkEstablished()) {
+            return Promise.reject(new Error('Session not established'));
+        }
+
+        this._log(`[Query] Sending 0x${expectedCmd.toString(16)}`);
+
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this._pendingRequests.delete(expectedCmd);
+                reject(new Error(`Query 0x${expectedCmd.toString(16)} timed out after ${timeout}ms`));
+            }, timeout);
+
+            this._pendingRequests.set(expectedCmd, { resolve, reject, timer });
+            this._sendPacket(packet);
+        });
+    }
+
+    /**
+     * Resolve a pending request if one exists for this command.
+     * Called from response handlers.
+     * @returns {boolean} true if a pending request was resolved
+     */
+    _resolvePendingRequest(cmd, data) {
+        const pending = this._pendingRequests.get(cmd);
+        if (pending) {
+            clearTimeout(pending.timer);
+            this._pendingRequests.delete(cmd);
+            pending.resolve(data);
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Query system capabilities (0x0613 wrapped in 0x0800)
+     * Returns max zones, partitions, users, etc.
+     * Neohub queries this FIRST on connect.
+     * @returns {Promise<object>} Capabilities object
+     */
+    queryCapabilities() {
+        const packet = this.session.buildCapabilitiesRequest();
+        return this._sendQuery(CMD.SYSTEM_CAPABILITIES, packet);
+    }
+
+    /**
+     * Query zone status (0x0811 wrapped in 0x0800)
+     * @param {number} startZone - Starting zone number (default 1)
+     * @param {number} numZones - Number of zones (uses cached capabilities if not specified)
+     * @returns {Promise<Array>} Array of zone status objects
+     */
+    queryZoneStatus(startZone = 1, numZones) {
+        const count = numZones || this._capabilities?.maxZones || 32;
+        const packet = this.session.buildZoneStatusRequest(startZone, count);
+        return this._sendQuery(CMD.ZONE_STATUS, packet);
+    }
+
+    /**
+     * Query partition status (0x0812 wrapped in 0x0800)
+     * @param {number} partition - Partition number (default 1)
+     * @returns {Promise<object>} Partition status object
+     */
+    queryPartitionStatus(partition = 1) {
+        const packet = this.session.buildPartitionStatusRequest(partition);
+        return this._sendQuery(CMD.PARTITION_STATUS, packet);
+    }
+
+    /**
+     * Query global system status (0x0810 wrapped in 0x0800)
+     * @returns {Promise<Buffer>} Raw global status data
+     */
+    queryGlobalStatus() {
+        const packet = this.session.buildGlobalStatusRequest();
+        return this._sendQuery(CMD.GLOBAL_STATUS, packet);
+    }
+
+    /**
+     * Query system trouble status (0x0822 wrapped in 0x0800)
+     * @returns {Promise<Array>} Array of trouble objects
+     */
+    queryTroubleStatus() {
+        const packet = this.session.buildTroubleStatusRequest();
+        return this._sendQuery(CMD.SYSTEM_TROUBLE_STATUS, packet);
+    }
+
+    /**
+     * Query zone bypass status (0x0813 wrapped in 0x0800)
+     * @param {number} zone - Zone number (0 = all zones)
+     * @param {number} numZones - Number of zones (default 128)
+     * @returns {Promise<object>} Bypass status data
+     */
+    queryZoneBypassStatus(zone = 0, numZones = 128) {
+        const packet = this.session.buildZoneBypassStatusRequest(zone, numZones);
+        return this._sendQuery(CMD.ZONE_BYPASS_STATUS, packet);
+    }
+
+    /**
+     * Send a raw command directly (not wrapped in 0x0800)
+     * @param {number} command - Command code (e.g., 0x0812)
+     * @param {Buffer} [payload] - Optional payload data
+     */
+    sendDirect(command, payload = null) {
+        if (!this._checkEstablished()) return;
+        const packet = this.session.buildCommand(command, payload);
+        this._logMinimal(`[Direct] Sending command 0x${command.toString(16).padStart(4, '0')} ${payload ? 'with ' + payload.length + ' bytes payload' : 'no payload'}`);
+        this._sendPacket(packet);
+    }
+
+    // ==================== Authentication Methods ====================
+
+    /**
+     * Authenticate with access code - simple format (0x0400)
+     * Uses 6-digit ASCII format matching interactive CLI
+     * @param {string} code - User/master code (e.g., "5555")
+     */
+    authenticate(code) {
+        if (!this._checkEstablished()) return;
+        const codeStr = (code || this.masterCode).toString().padStart(6, '0').slice(0, 6);
+        const payload = Buffer.from(codeStr, 'ascii');
+        const packet = this.session.buildCommand(0x0400, payload);
+        this._sendPacket(packet);
+    }
+
+    /**
+     * Authenticate with access code - extended format (0x0400)
+     * Includes partition and access level metadata
+     * @param {number} partition - Partition number (1-8, or 0 for all)
+     * @param {string} code - User/master code (e.g., "5555")
+     * @param {number} accessLevel - 0=User, 1=Installer, 2=Master
+     */
+    authenticateExtended(partition = 1, code, accessLevel = 0) {
+        if (!this._checkEstablished()) return;
+        const packet = this.session.buildAccessLevelEnter(
+            code || this.masterCode,
+            partition,
+            accessLevel,
+            'bcd'
+        );
+        this._sendPacket(packet);
+    }
+
+    /**
+     * Exit authenticated access level (0x0401)
+     * @param {number} partition - Partition number
+     */
+    deauthenticate(partition = 1) {
+        if (!this._checkEstablished()) return;
+        const packet = this.session.buildAccessLevelExit(partition);
+        this._sendPacket(packet);
+    }
+
+    // ==================== State Accessors ====================
+
+    /**
+     * Get current zone states
+     */
+    getZones() {
+        return this.eventHandler.getAllZones();
+    }
+
+    /**
+     * Get current partition states
+     */
+    getPartitions() {
+        return this.eventHandler.getAllPartitions();
+    }
+
+    // ==================== Internal Methods ====================
+
+    _checkEstablished() {
+        if (this.handshakeState !== 'ESTABLISHED') {
+            this.emit('error', new Error('Session not established'));
+            return false;
+        }
+        return true;
+    }
+
+    _sendPacket(packet) {
+        if (!this.tcpSocket || this.tcpSocket.destroyed) {
+            this._logMinimal('[Error] No panel connection');
+            return;
+        }
+        this._log(`[TCP] TX ${packet.length} bytes`);
+        this._hexDump(packet);
+        this.tcpSocket.write(packet);
+    }
+
+    _handlePacket(data) {
+        try {
+            if (!this.session) {
+                const logger = this.logLevel === 'verbose' ? this._log.bind(this) : () => {};
+                this.session = new ITv2Session(this.integrationId, this.accessCode, logger);
+            }
+
+            const parsed = this.session.parsePacket(data);
+            if (!parsed) {
+                this._log('[Error] Failed to parse packet');
+                return;
+            }
+
+            this._log(`[TCP] RX ${data.length}B cmd=${CMD_NAMES[parsed.command] || parsed.command}`);
+            this._hexDump(data);
+            this._log(`[Packet] Integration ID: ${parsed.integrationId}`);
+            this._log(`[Packet] Sender Seq: ${parsed.senderSequence}, Receiver Seq: ${parsed.receiverSequence}`);
+            this._log(`[Packet] Command: ${CMD_NAMES[parsed.command] || parsed.command}`);
+            if (parsed.appSequence !== null) {
+                this._log(`[Packet] App Seq: ${parsed.appSequence}`);
+            }
+            if (parsed.commandData) {
+                this._log(`[Packet] Data (${parsed.commandData.length} bytes): ${parsed.commandData.toString('hex').toUpperCase().match(/.{1,2}/g).join(' ')}`);
+            }
+
+            // Route based on command
+            this._routePacket(parsed);
+
+        } catch (err) {
+            // During WAITING state, parse errors are expected (stale encrypted packets from previous session)
+            if (this.handshakeState === 'WAITING') {
+                this._log(`[Recovery] Ignoring malformed packet while waiting for fresh handshake: ${err.message}`);
+                // Reset session to ensure we start fresh on next valid packet
+                if (this.session) {
+                    this.session.disableAes();
+                    this.session = null;
+                }
+                return;
+            }
+
+            this._log(`[Error] ${err.message}`);
+            this.emit('error', err);
+
+            // Reset on parse errors during handshake
+            if (this.handshakeState !== 'SENT_CMD_RESPONSE_1') {
+                this._log('[Recovery] Parse error, resetting to wait for panel restart');
+                if (this.session) {
+                    this.session.disableAes();
+                    this.session = null;
+                }
+                this.handshakeState = 'WAITING';
+            }
+        }
+    }
+
+    _routePacket(parsed, skipAck = false) {
+        this._skipAck = skipAck;
+        const cmd = parsed.command;
+
+        // Handle ACKs
+        if (cmd === null || cmd === undefined || cmd === CMD.SIMPLE_ACK) {
+            this._handleSimpleAck(parsed);
+            return;
+        }
+
+        // Route based on command type
+        switch (cmd) {
+            case CMD.OPEN_SESSION:
+                this._handleOpenSession(parsed);
+                break;
+            case CMD.REQUEST_ACCESS:
+                this._handleRequestAccess(parsed);
+                break;
+            case CMD.COMMAND_RESPONSE:
+                this._handleCommandResponse(parsed);
+                break;
+            case CMD.COMMAND_ERROR:
+                this._handleCommandError(parsed);
+                break;
+            case CMD.POLL:
+                this._handlePoll(parsed);
+                break;
+            case CMD.LIFESTYLE_ZONE_STATUS:
+                this._handleLifestyleZoneStatus(parsed);
+                break;
+            case CMD.TIME_DATE_BROADCAST:
+                this._handleTimeDateBroadcast(parsed);
+                break;
+            case CMD.ZONE_STATUS:
+                this._handleZoneStatusResponse(parsed);
+                break;
+            case CMD.PARTITION_STATUS:
+                this._handlePartitionStatusResponse(parsed);
+                break;
+            case CMD.GLOBAL_STATUS:
+                this._handleGlobalStatusResponse(parsed);
+                break;
+            case CMD.SYSTEM_CAPABILITIES:
+                this._handleCapabilitiesResponse(parsed);
+                break;
+            case CMD.SYSTEM_TROUBLE_STATUS:
+            case CMD.SYSTEM_TROUBLE_STATUS_OLD:
+                this._handleTroubleStatusResponse(parsed);
+                break;
+            case CMD.TROUBLE_DETAIL:
+                this._handleTroubleDetail(parsed);
+                break;
+            case CMD.NOTIFICATION_ARMING:
+                this._handleArmingNotification(parsed);
+                break;
+            case CMD.NOTIFICATION_PARTITION_READY:
+                this._handlePartitionReadyNotification(parsed);
+                break;
+            case CMD.NOTIFICATION_PARTITION_TROUBLE:
+                this._handlePartitionTroubleNotification(parsed);
+                break;
+            case CMD.MULTIPLE_MESSAGE:
+                this._handleMultipleMessagePacket(parsed);
+                break;
+            default:
+                if (this.handshakeState === 'ESTABLISHED') {
+                    const cmdHex = cmd ? '0x' + cmd.toString(16).padStart(4, '0') : 'null';
+                    const cmdName = CMD_NAMES[cmd] || 'UNKNOWN';
+                    this._logMinimal(`[Session] Received command ${cmdName} (${cmdHex})`);
+                    if (parsed.commandData && parsed.commandData.length > 0) {
+                        this._logMinimal(`[Session] Data (${parsed.commandData.length} bytes): ${parsed.commandData.toString('hex')}`);
+                    }
+                    this._ack();
+                }
+                break;
+        }
+    }
+
+    // ==================== Handshake Handlers ====================
+
+    _handleOpenSession(parsed) {
+        const data = parsed.commandData;
+        if (!data || data.length < 14) {
+            this._log('[Error] Invalid OPEN_SESSION data');
+            return;
+        }
+
+        const deviceType = data[0];
+        const encryptionType = data[13];
+
+        this._log(`[Session] OPEN_SESSION received:`);
+        this._log(`  Device Type: ${deviceType}`);
+        this._log(`  Encryption Type: ${encryptionType}`);
+
+        // Emit connecting event now that we have a valid OPEN_SESSION
+        this.emit('session:connecting');
+        this._logMinimal(`[Session] Panel connecting from ${this.panelAddress}`);
+        this._logMinimal('[Handshake] Starting session establishment...');
+
+        // Handle panel restart mid-handshake
+        if (this.handshakeState !== 'WAITING' && this.handshakeState !== 'SENT_CMD_RESPONSE_1') {
+            this._log(`[Session] Panel restarting handshake (was in state ${this.handshakeState}), resetting session`);
+            const logger = this.logLevel === 'verbose' ? this._log.bind(this) : () => {};
+            this.session = new ITv2Session(this.integrationId, this.accessCode, logger);
+        }
+
+        // Save panel's OpenSession payload for echoing back
+        this._panelOpenSessionData = data;
+
+        // Send COMMAND_RESPONSE echoing the command's appSequence (NOT deviceType)
+        // OpenSession is a CommandMessageBase - appSequence is the CommandSequence
+        const cmdSeq = parsed.appSequence;
+        this._log(`[Handshake] Sending COMMAND_RESPONSE (echoing cmdSeq=${cmdSeq})`);
+        const response = this.session.buildCommandResponseWithAppSeq(cmdSeq, 0x00);
+        this._sendPacket(response);
+        this.handshakeState = 'SENT_CMD_RESPONSE_1';
+    }
+
+    _handleSimpleAck(parsed) {
+        this._log(`[Handshake] Got ACK ${parsed.receiverSequence}, state=${this.handshakeState}`);
+
+        if (this.handshakeState === 'SENT_CMD_RESPONSE_1') {
+            // Panel ACKed our first COMMAND_RESPONSE, send our OPEN_SESSION
+            // Echo back the panel's OpenSession data (neohub echoes the same message)
+            this._log(`[Handshake] Got ACK 1, sending our OPEN_SESSION`);
+            const payload = this._panelOpenSessionData || Buffer.from([
+                0x01, 0x80, 0x00, 0x00, 0x02, 0x01, 0x02, 0x41,
+                0x02, 0x00, 0x02, 0x00, 0x00, 0x01, 0x01
+            ]);
+            const packet = this.session.buildOpenSessionResponse(payload);
+            this._sendPacket(packet);
+            this.handshakeState = 'SENT_OPEN_SESSION';
+        } else if (this.handshakeState === 'WAITING_TO_SEND_REQUEST_ACCESS') {
+            // Panel ACKed our encrypted COMMAND_RESPONSE to their REQUEST_ACCESS
+            // Now send our REQUEST_ACCESS (also encrypted, send key already enabled)
+            this._log(`[Handshake] Got ACK, now sending our REQUEST_ACCESS`);
+
+            let reqAccessPacket;
+            if (this.detectedEncryptionType === 2) {
+                this._log(`[Handshake] Using Type 2 REQUEST_ACCESS`);
+                reqAccessPacket = this.session.buildRequestAccessType2();
+            } else {
+                this._log(`[Handshake] Using Type 1 REQUEST_ACCESS`);
+                reqAccessPacket = this.session.buildRequestAccessType1();
+            }
+
+            this._sendPacket(reqAccessPacket);
+
+            // Enable receive encryption
+            this.session.receiveAesActive = true;
+            this.session.receiveAesKey = this.session.pendingReceiveKey;
+            this._log(`[Handshake] Enabled receive encryption`);
+
+            this.handshakeState = 'SENT_REQUEST_ACCESS';
+        } else if (this.handshakeState === 'SENT_REQUEST_ACCESS') {
+            // Panel ACKed our REQUEST_ACCESS - session established!
+            this._onSessionEstablished();
+        }
+    }
+
+    _onSessionEstablished() {
+        this.handshakeState = 'ESTABLISHED';
+        this._logMinimal(`[Handshake] Session established (Type ${this.detectedEncryptionType} encryption)`);
+        this._log(`[Handshake] *** SESSION ESTABLISHED ***`);
+        this._log(`[Handshake] Encryption Type: ${this.detectedEncryptionType}`);
+        this._log(`[Handshake] SEND key: ${this.session.derivedSendKey?.toString('hex')}`);
+        this._log(`[Handshake] RECV key: ${this.session.pendingReceiveKey?.toString('hex')}`);
+
+        this.emit('session:established', {
+            encryptionType: this.detectedEncryptionType,
+            sendKey: this.session.derivedSendKey?.toString('hex'),
+            recvKey: this.session.pendingReceiveKey?.toString('hex')
+        });
+
+        // Start heartbeat timer (neohub sends ConnectionPoll every 100 seconds)
+        this._startHeartbeat();
+
+        // Start session readiness timer (neohub discards notifications for first 2s)
+        this._sessionReady = false;
+        this._resetReadyTimer();
+    }
+
+    _startHeartbeat() {
+        if (this._heartbeatInterval) clearInterval(this._heartbeatInterval);
+        this._heartbeatInterval = setInterval(() => {
+            if (this.handshakeState === 'ESTABLISHED' && this.session) {
+                this._log('[Heartbeat] Sending POLL');
+                const packet = this.session.buildPoll();
+                this._sendPacket(packet);
+            }
+        }, 100_000); // 100 seconds, matching neohub
+    }
+
+    _resetReadyTimer() {
+        if (this._readyTimer) clearTimeout(this._readyTimer);
+        this._readyTimer = setTimeout(() => {
+            if (!this._sessionReady) {
+                this._sessionReady = true;
+                this._logMinimal('[Session] Ready - initial message burst complete');
+                this.emit('session:ready');
+                // Pull initial status like neohub's PanelConfigurationHandler
+                this._pullInitialStatus();
+            }
+        }, 2000); // 2 seconds of silence, matching neohub
+    }
+
+    async _pullInitialStatus() {
+        this._logMinimal('[Status] Pulling initial status (neohub sequence)...');
+
+        let caps = null;
+        let zones = [];
+        let partStatus = null;
+
+        // Step 1: Query capabilities first (neohub does this first)
+        try {
+            caps = await this.queryCapabilities();
+            this._logMinimal(`[Status] Capabilities: ${caps.maxZones} zones, ${caps.maxPartitions} partitions`);
+        } catch (e) {
+            this._logMinimal(`[Status] Capabilities query failed: ${e.message}`);
+        }
+
+        const maxZones = caps?.maxZones || 128;
+        const maxPartitions = caps?.maxPartitions || 8;
+
+        // Step 2: Query partition status
+        try {
+            partStatus = await this.queryPartitionStatus(1);
+            if (partStatus) {
+                const state = partStatus.awayArmed ? 'AWAY' :
+                    partStatus.stayArmed ? 'STAY' :
+                    partStatus.nightArmed ? 'NIGHT' :
+                    partStatus.armed ? 'ARMED' : 'DISARMED';
+                this._logMinimal(`[Status] Partition 1: ${state}`);
+            }
+        } catch (e) {
+            this._logMinimal(`[Status] Partition query failed: ${e.message}`);
+        }
+
+        // Step 3: Query zone status
+        try {
+            zones = await this.queryZoneStatus(1, maxZones);
+            const openZones = zones.filter(z => z.open);
+            this._logMinimal(`[Status] ${zones.length} zones (${openZones.length} open)`);
+        } catch (e) {
+            this._logMinimal(`[Status] Zone query failed: ${e.message}`);
+        }
+
+        this.emit('status:ready', { zones, partition: partStatus, capabilities: caps });
+    }
+
+    _handleRequestAccess(parsed) {
+        const data = parsed.commandData;
+        if (!data || data.length < 17) {
+            this._log('[Error] Invalid REQUEST_ACCESS data');
+            return;
+        }
+
+        const initType = data[0];
+        const initializer = data.slice(1);
+
+        this._log(`[Handshake] Got panel's REQUEST_ACCESS`);
+        this._log(`[Handshake] Processing panel's REQUEST_ACCESS (panel goes first)`);
+
+        // Determine encryption type based on initializer length
+        if (initializer.length === 48) {
+            // Type 1 encryption
+            this.detectedEncryptionType = 1;
+            this._log(`[Handshake] Encryption Type 1 (48-byte initializer)`);
+
+            const sendKey = parseType1Initializer(this.accessCode, initializer, this.integrationId, this.logLevel === 'verbose');
+            this._logMinimal('[Handshake] Type 1 encryption negotiated');
+            this._log(`[Handshake] Type 1 SEND key derived`);
+            this.session.derivedSendKey = sendKey;
+
+        } else if (initializer.length === 16) {
+            // Type 2 encryption
+            this.detectedEncryptionType = 2;
+            this._log(`[Handshake] Encryption Type 2 (16-byte initializer)`);
+
+            // Type 2: Symmetric transform with 32-hex access code
+            let accessCode32 = this.accessCode;
+            if (accessCode32.length === 8) {
+                accessCode32 = accessCode32 + accessCode32 + accessCode32 + accessCode32;
+            }
+
+            const sendKey = type2InitializerTransform(accessCode32, initializer);
+            this._logMinimal('[Handshake] Type 2 encryption negotiated');
+            this._log(`[Handshake] Type 2 SEND key derived`);
+            this.session.derivedSendKey = sendKey;
+
+        } else {
+            this._log(`[Error] Unknown initializer length: ${initializer.length}`);
+            return;
+        }
+
+        // Enable outbound encryption BEFORE sending COMMAND_RESPONSE
+        // (neohub: "Configure outbound encryption IMMEDIATELY — step 8 is encrypted")
+        this.session.sendAesActive = true;
+        this.session.sendAesKey = this.session.derivedSendKey;
+        this._log(`[Handshake] Enabled outbound encryption`);
+
+        // Send ENCRYPTED COMMAND_RESPONSE (first encrypted message!)
+        const appSeq = parsed.appSequence;
+        this._log(`[Handshake] Sending ENCRYPTED COMMAND_RESPONSE to panel's REQUEST_ACCESS`);
+        const response = this.session.buildCommandResponseWithAppSeq(appSeq, 0x00);
+        this._sendPacket(response);
+
+        // Wait for panel's ACK before sending our REQUEST_ACCESS
+        // (neohub waits for SimpleAck at step 9 before step 10)
+        this.handshakeState = 'WAITING_TO_SEND_REQUEST_ACCESS';
+    }
+
+    _handleCommandResponse(parsed) {
+        const data = parsed.commandData;
+        const responseCode = data?.[0] || 0;
+        const appSeqAsEcho = parsed.appSequence;
+
+        this._log(`[Session] Got COMMAND_RESPONSE (app_seq: ${appSeqAsEcho}, response_code: ${responseCode})`);
+
+        // COMMAND_RESPONSE is an intermediate ack - NOT a rejection.
+        // Neohub's CommandRequestReceiver treats it as an ack and waits for the
+        // actual data message. Only COMMAND_ERROR rejects pending requests.
+        // Response codes: 0=ack, 1=success, 2+=informational (panel may still send data)
+        if (this.handshakeState === 'ESTABLISHED') {
+            this.emit('command:response', { responseCode, appSequence: appSeqAsEcho, data });
+        }
+
+        const ack = this.session.buildSimpleAck();
+        this._sendPacket(ack);
+
+        if (this.handshakeState === 'SENT_OPEN_SESSION') {
+            // Panel accepted our OPEN_SESSION
+            this.handshakeState = 'WAITING_REQUEST_ACCESS';
+        } else if (this.handshakeState === 'SENT_REQUEST_ACCESS') {
+            // Panel accepted our REQUEST_ACCESS - session established!
+            this._onSessionEstablished();
+        }
+    }
+
+    _handleCommandError(parsed) {
+        // CommandError (IMessageData, NOT CommandMessageBase):
+        // [Command 2B BE][NackCode 1B]
+        // parseHeader puts first byte into appSequence
+        const fullPayload = this._reconstructPayload(parsed);
+        const failedCmd = fullPayload.length >= 2 ? fullPayload.readUInt16BE(0) : 0;
+        const nackCode = fullPayload.length >= 3 ? fullPayload[2] : 0;
+        const nackNames = {
+            1: 'InvalidCommandLength', 2: 'InvalidCommand', 3: 'InvalidSequence',
+            4: 'PanelNotResponding', 17: 'InvalidAccessCode', 18: 'AccessCodeRequired',
+            23: 'FunctionNotAvailable', 25: 'CommandTimeout',
+        };
+        const error = {
+            failedCommand: failedCmd,
+            nackCode,
+            message: `${CMD_NAMES[failedCmd] || '0x' + failedCmd.toString(16)}: ${nackNames[nackCode] || 'NackCode ' + nackCode}`,
+        };
+
+        this._log(`[Command Error] ${error.message}`);
+        this.emit('command:error', error);
+
+        // Don't reject pending requests - panel often sends COMMAND_ERROR as an
+        // intermediate response, then sends actual data afterward.
+        // Timeout handles genuine failures.
+
+        this._ack();
+    }
+
+    _handlePoll(parsed) {
+        this._log(`[Session] Got POLL, sending ACK`);
+        if (!this._sessionReady) this._resetReadyTimer();
+        this._ack();
+    }
+
+    // ==================== Notification Handlers ====================
+
+    _handleLifestyleZoneStatus(parsed) {
+        // If we receive encrypted zone data, session is established (even if we missed the final ACK)
+        if (this.handshakeState === 'SENT_REQUEST_ACCESS') {
+            this._onSessionEstablished();
+        }
+
+        // Reset ready timer on each inbound message (matching neohub)
+        if (!this._sessionReady) this._resetReadyTimer();
+
+        // Reconstruct full payload: for non-CommandMessageBase messages,
+        // parseHeader puts the first payload byte into appSequence
+        // NotificationLifestyleZoneStatus: [CompactInt:ZoneNumber][Status:1B]
+        const fullPayload = this._reconstructPayload(parsed);
+
+        if (fullPayload && fullPayload.length >= 3) {
+            // Parse CompactInteger zone number
+            const zone = ITv2Session.decodeVarBytes(fullPayload, 0);
+            const zoneNum = zone.value;
+            const statusValue = fullPayload[zone.bytesRead];
+
+            // Update internal state and get full parsed status
+            const fullStatus = this.eventHandler.handleZoneStatus(zoneNum, statusValue);
+
+            // Emit events with full status object
+            this.emit('zone:status', zoneNum, fullStatus);
+
+            if (fullStatus.open) {
+                this.emit('zone:open', zoneNum);
+                this._log(`[Zone ${zoneNum}] OPEN (status: ${statusValue})`);
+            } else {
+                this.emit('zone:closed', zoneNum);
+                this._log(`[Zone ${zoneNum}] CLOSED (status: ${statusValue})`);
+            }
+        }
+
+        this._ack();
+    }
+
+    _handleTimeDateBroadcast(parsed) {
+        if (!this._sessionReady) this._resetReadyTimer();
+        const fullPayload = this._reconstructPayload(parsed);
+        if (fullPayload && fullPayload.length >= 5) {
+            this._log(`[Time/Date] Received broadcast`);
+            this.emit('notification:timeDate', fullPayload);
+        }
+        this._ack();
+    }
+
+    // ==================== Status Query Response Handlers ====================
+
+    _handleZoneStatusResponse(parsed) {
+        // ModuleZoneStatus (neohub format):
+        // [CompactInt:ZoneStart][CompactInt:ZoneCount][StatusSizeInBytes:1B][ZoneStatusBytes...]
+        const fullPayload = this._reconstructPayload(parsed);
+        this._logMinimal(`[Zone Status] Received zone status response`);
+        this._log(`[Zone Status] Raw data (${fullPayload?.length || 0} bytes): ${fullPayload?.toString('hex') || 'none'}`);
+
+        const zones = [];
+
+        if (fullPayload && fullPayload.length >= 4) {
+            try {
+                let offset = 0;
+                const zoneStart = ITv2Session.decodeVarBytes(fullPayload, offset);
+                offset += zoneStart.bytesRead;
+
+                const zoneCount = ITv2Session.decodeVarBytes(fullPayload, offset);
+                offset += zoneCount.bytesRead;
+
+                const statusSize = fullPayload[offset++]; // typically 1
+
+                this._logMinimal(`[Zone Status] Zones ${zoneStart.value}-${zoneStart.value + zoneCount.value - 1} (${zoneCount.value} zones, ${statusSize}B each)`);
+
+                for (let i = 0; i < zoneCount.value && offset < fullPayload.length; i++) {
+                    const zoneNum = zoneStart.value + i;
+                    const statusByte = fullPayload[offset];
+                    offset += statusSize;
+
+                    const fullStatus = this.eventHandler.handleZoneStatus(zoneNum, statusByte);
+                    zones.push(fullStatus);
+                    this.emit('zone:statusResponse', zoneNum, fullStatus);
+                    this.emit('zone:status', zoneNum, fullStatus);
+                }
+            } catch (e) {
+                this._log(`[Zone Status] Parse error: ${e.message}`);
+            }
+        }
+
+        this._resolvePendingRequest(CMD.ZONE_STATUS, zones);
+        this._ack();
+    }
+
+    _handlePartitionStatusResponse(parsed) {
+        // ModulePartitionStatus (neohub format):
+        // [CompactInt:Partition][LeadingLengthArray:PartitionStatus]
+        // PartitionStatus bytes:
+        //   Byte 0 (Status1): Armed=0x01, StayArmed=0x03, ArmedAway=0x05, NightArmed=0x09,
+        //                     ExitDelay=0x20, EntryDelay=0x40, QuickExit=0x80
+        //   Byte 1 (Status2): Alarm=0x01, Trouble=0x02, Bypass=0x04, Programming=0x08,
+        //                     AlarmMemory=0x10, DoorChime=0x20, Bell=0x40, Buzzer=0x80
+        //   Byte 2 (Status3): FirePreAlert=0x01
+        const fullPayload = this._reconstructPayload(parsed);
+        this._logMinimal(`[Partition Status] Received partition status response`);
+        this._log(`[Partition Status] Raw data (${fullPayload?.length || 0} bytes): ${fullPayload?.toString('hex') || 'none'}`);
+
+        if (fullPayload && fullPayload.length >= 3) {
+            try {
+                let offset = 0;
+                const partition = ITv2Session.decodeVarBytes(fullPayload, offset);
+                offset += partition.bytesRead;
+
+                // LeadingLengthArray: 1-byte length prefix followed by status bytes
+                const statusLength = fullPayload[offset++];
+                const statusBytes = fullPayload.slice(offset, offset + statusLength);
+
+                const partitionNum = partition.value;
+                this._logMinimal(`[Partition Status] Partition ${partitionNum}: status bytes ${statusBytes.toString('hex')}`);
+
+                // Parse status flags from neohub's enum definitions
+                const status1 = statusBytes.length > 0 ? statusBytes[0] : 0;
+                const status2 = statusBytes.length > 1 ? statusBytes[1] : 0;
+                const status3 = statusBytes.length > 2 ? statusBytes[2] : 0;
+
+                const partStatus = {
+                    partition: partitionNum,
+                    // Status1 flags
+                    armed: !!(status1 & 0x01),
+                    stayArmed: (status1 & 0x0F) === 0x03,
+                    awayArmed: (status1 & 0x0F) === 0x05,
+                    nightArmed: (status1 & 0x0F) === 0x09,
+                    noEntryDelay: (status1 & 0x1F) === 0x11,
+                    exitDelay: !!(status1 & 0x20),
+                    entryDelay: !!(status1 & 0x40),
+                    quickExit: !!(status1 & 0x80),
+                    // Status2 flags
+                    alarm: !!(status2 & 0x01),
+                    trouble: !!(status2 & 0x02),
+                    zonesBypassed: !!(status2 & 0x04),
+                    programmingMode: !!(status2 & 0x08),
+                    alarmInMemory: !!(status2 & 0x10),
+                    doorChime: !!(status2 & 0x20),
+                    audibleBell: !!(status2 & 0x40),
+                    buzzer: !!(status2 & 0x80),
+                    // Status3 flags
+                    firePreAlert: !!(status3 & 0x01),
+                    rawBytes: statusBytes.toString('hex'),
+                };
+
+                // Update event handler
+                const armedState = partStatus.awayArmed ? 0x02 :
+                    partStatus.stayArmed ? 0x01 :
+                    partStatus.nightArmed ? 0x03 :
+                    partStatus.armed ? 0x01 : 0x00;
+                this.eventHandler.handlePartitionArming(partitionNum, armedState);
+
+                this.emit('partition:statusResponse', partitionNum, partStatus);
+                this._resolvePendingRequest(CMD.PARTITION_STATUS, partStatus);
+            } catch (e) {
+                this._log(`[Partition Status] Parse error: ${e.message}`);
+            }
+        } else {
+            this._log(`[Partition Status] Empty or invalid response`);
+        }
+
+        this._ack();
+    }
+
+    _handleCapabilitiesResponse(parsed) {
+        const fullPayload = this._reconstructPayload(parsed);
+        this._logMinimal(`[Capabilities] Received system capabilities`);
+
+        const caps = {};
+        if (fullPayload && fullPayload.length >= 2) {
+            try {
+                let offset = 0;
+                const fields = ['maxZones', 'maxUsers', 'maxPartitions', 'maxFOBs', 'maxProxTags', 'maxOutputs'];
+                for (const field of fields) {
+                    if (offset >= fullPayload.length) break;
+                    const val = ITv2Session.decodeVarBytes(fullPayload, offset);
+                    caps[field] = val.value;
+                    offset += val.bytesRead;
+                }
+                this._logMinimal(`[Capabilities] ${caps.maxZones} zones, ${caps.maxPartitions} partitions, ${caps.maxUsers} users`);
+            } catch (e) {
+                this._log(`[Capabilities] Parse error: ${e.message}`);
+            }
+        }
+
+        this._capabilities = caps;
+        this._resolvePendingRequest(CMD.SYSTEM_CAPABILITIES, caps);
+        this._ack();
+    }
+
+    _handleGlobalStatusResponse(parsed) {
+        const fullPayload = this._reconstructPayload(parsed);
+        this._logMinimal(`[Global Status] Received global status response`);
+        this._log(`[Global Status] Raw data (${fullPayload?.length || 0} bytes): ${fullPayload?.toString('hex') || 'none'}`);
+
+        if (fullPayload && fullPayload.length > 0) {
+            this.emit('global:statusResponse', fullPayload);
+        }
+
+        this._resolvePendingRequest(CMD.GLOBAL_STATUS, fullPayload);
+        this._ack();
+    }
+
+    _handleTroubleStatusResponse(parsed) {
+        const fullPayload = this._reconstructPayload(parsed);
+        this._logMinimal(`[Trouble Status] Received trouble status response`);
+        this._log(`[Trouble Status] Raw data (${fullPayload?.length || 0} bytes): ${fullPayload?.toString('hex') || 'none'}`);
+
+        if (!fullPayload || fullPayload.length === 0) {
+            this._logMinimal(`[Trouble Status] No active troubles`);
+            this.emit('trouble:statusResponse', []);
+            this._resolvePendingRequest(CMD.SYSTEM_TROUBLE_STATUS, []);
+            this._ack();
+            return;
+        }
+
+        const troubles = [];
+        let offset = 0;
+
+        try {
+            while (offset < fullPayload.length) {
+                const device = ITv2Session.decodeVarBytes(fullPayload, offset);
+                offset += device.bytesRead;
+
+                const troubleCount = fullPayload[offset];
+                offset += 1;
+
+                const troubleTypes = [];
+                for (let i = 0; i < troubleCount; i++) {
+                    const trouble = ITv2Session.decodeVarBytes(fullPayload, offset);
+                    offset += trouble.bytesRead;
+                    troubleTypes.push(trouble.value);
+                }
+
+                troubles.push({ deviceType: device.value, troubles: troubleTypes });
+                this._logMinimal(`[Trouble Status] Device ${device.value}: troubles [${troubleTypes.join(', ')}]`);
+            }
+        } catch (e) {
+            this._logMinimal(`[Trouble Status] Parse error at offset ${offset}: ${e.message}`);
+            this._logMinimal(`[Trouble Status] Raw hex: ${fullPayload.toString('hex')}`);
+        }
+
+        this.emit('trouble:statusResponse', troubles);
+        this._resolvePendingRequest(CMD.SYSTEM_TROUBLE_STATUS, troubles);
+        this._ack();
+    }
+
+    _handleTroubleDetail(parsed) {
+        // 0x0823 Trouble Detail Notification (from SDK DSC_ITroubleData interface)
+        // Contains zero or more records, each:
+        //   [DeviceModuleType VarBytes][DeviceModuleNumber VarBytes][TroubleType VarBytes][TroubleState 1B]
+        const TROUBLE_TYPES = {
+            0x01: 'No Troubles', 0x02: 'Device Tamper', 0x03: 'Device Fault',
+            0x04: 'Device Low Battery', 0x05: 'Device Delinquency', 0x06: 'Failure To Communicate',
+            0x07: 'GSIP Receiver Trouble', 0x08: 'Receiver Not Available', 0x09: 'Receiver Supervision',
+            0x0A: 'Device AC Trouble', 0x0B: 'Device Low Sensitivity', 0x0C: 'Device Internal Fault',
+            0x0D: 'RF Device Not Networked', 0x0E: 'Device Mask Trouble', 0x0F: 'Power Unit Failure',
+            0x10: 'Overcurrent', 0x21: 'System Troubles Level 1', 0x22: 'Service Request',
+            0x23: 'Communications Troubles', 0x31: 'Bell Trouble', 0x36: 'RF Jam',
+            0x37: 'Fire Trouble', 0x38: 'CO Trouble', 0x3A: 'Ground Fault',
+            0x3B: 'Output Fault', 0x3C: 'TLM Trouble', 0x40: 'Time/Date Trouble',
+            0x41: 'Configuration Trouble', 0x42: 'Warm Start', 0x43: 'USB/WIFI Trouble',
+            0x44: 'Critical Shutdown', 0x51: 'SIM Lock', 0x56: 'GSM Trouble',
+            0x61: 'Ethernet Trouble', 0x81: 'Module Supervisory', 0x82: 'Module Tamper',
+            0x85: 'Module AC Trouble', 0x87: 'Module Low Battery', 0x88: 'Module Battery Missing',
+            0x89: 'Module Battery Charger', 0x8B: 'Module Bus Low Voltage', 0x8C: 'Module Bus Fault',
+            0x8D: 'Module AUX Trouble', 0x8E: 'Firmware Upgrade Fault', 0x91: 'Gas Trouble',
+            0x92: 'Heat Trouble', 0x93: 'Freeze Trouble', 0x95: 'Smoke Trouble',
+            0x96: 'Radio SIM Failure', 0x97: 'Module Battery Disconnected',
+            0x98: 'Radio Low Signal', 0x99: 'GSM Network', 0x9A: 'IP Remote Server',
+        };
+        const DEVICE_TYPES = {
+            0x01: 'System', 0x02: 'Zone', 0x03: 'Keypad', 0x04: 'Siren',
+            0x05: 'FOB', 0x07: 'Repeater', 0x11: 'AML Module', 0x12: 'IO Expander',
+            0x13: 'Zone Expander', 0x14: 'Wireless Transceiver', 0x15: 'Power Supply',
+            0x1D: 'Alternate Communicator', 0xF1: 'All Modules', 0xF2: 'Interface Module',
+            0xF3: 'IP Communicator',
+        };
+        const TROUBLE_STATES = { 0x01: 'Restored', 0x02: 'Trouble', 0x03: 'In Memory' };
+
+        const fullPayload = this._reconstructPayload(parsed);
+        const troubles = [];
+
+        if (fullPayload && fullPayload.length >= 4) {
+            let offset = 0;
+            try {
+                while (offset < fullPayload.length) {
+                    const devType = ITv2Session.decodeVarBytes(fullPayload, offset);
+                    offset += devType.bytesRead;
+                    const devNum = ITv2Session.decodeVarBytes(fullPayload, offset);
+                    offset += devNum.bytesRead;
+                    const troubleType = ITv2Session.decodeVarBytes(fullPayload, offset);
+                    offset += troubleType.bytesRead;
+                    if (offset >= fullPayload.length) break;
+                    const troubleState = fullPayload[offset++];
+
+                    troubles.push({
+                        deviceType: devType.value,
+                        deviceTypeName: DEVICE_TYPES[devType.value] || `Device 0x${devType.value.toString(16)}`,
+                        deviceNumber: devNum.value,
+                        troubleType: troubleType.value,
+                        troubleTypeName: TROUBLE_TYPES[troubleType.value] || `Trouble 0x${troubleType.value.toString(16)}`,
+                        troubleState,
+                        troubleStateName: TROUBLE_STATES[troubleState] || `State ${troubleState}`,
+                    });
+                }
+            } catch (e) {
+                this._log(`[Trouble Detail] Parse error at offset ${offset}: ${e.message}`);
+            }
+        }
+
+        for (const t of troubles) {
+            this._logMinimal(`[Trouble] ${t.deviceTypeName} #${t.deviceNumber}: ${t.troubleTypeName} (${t.troubleStateName})`);
+        }
+
+        this.emit('trouble:detail', troubles);
+        this._ack();
+    }
+
+    // ==================== Multiple Message Packet (0x0623) ====================
+
+    _handleMultipleMessagePacket(parsed) {
+        // Panel batches multiple notifications with 1-byte length prefixes.
+        // Format: [len1][cmd1 2B][payload1...][len2][cmd2 2B][payload2...]...
+        const fullPayload = this._reconstructPayload(parsed);
+        this._sendPacket(this.session.buildSimpleAck());
+
+        if (!fullPayload || fullPayload.length < 3) return;
+
+        let offset = 0;
+        while (offset < fullPayload.length) {
+            const msgLen = fullPayload[offset++];
+            if (msgLen === 0 || offset + msgLen > fullPayload.length) break;
+
+            const msgBytes = fullPayload.slice(offset, offset + msgLen);
+            offset += msgLen;
+
+            if (msgBytes.length < 2) continue;
+            const subCmd = msgBytes.readUInt16BE(0);
+            const subPayload = msgBytes.slice(2);
+
+            this._log(`[MultiMsg] Sub-message: ${CMD_NAMES[subCmd] || '0x' + subCmd.toString(16)} (${subPayload.length}B)`);
+
+            // Build a fake parsed object for re-routing
+            const subParsed = {
+                command: subCmd,
+                appSequence: subPayload.length > 0 ? subPayload[0] : null,
+                commandData: subPayload.length > 1 ? subPayload.slice(1) : null,
+                senderSequence: parsed.senderSequence,
+                receiverSequence: parsed.receiverSequence,
+            };
+
+            // Route the sub-message through existing handlers
+            // (ACK already sent for the outer 0x0623 packet)
+            this._routePacket(subParsed, true);
+        }
+    }
+
+    // ==================== Notification Handlers ====================
+
+    _handleArmingNotification(parsed) {
+        // NotificationArmDisarm (neohub format, IMessageData NOT CommandMessageBase):
+        // [CompactInt:Partition][ArmMode:1B][Method:1B][CompactInt:UserId]
+        const fullPayload = this._reconstructPayload(parsed);
+        if (!fullPayload || fullPayload.length < 4) {
+            this._ack();
+            return;
+        }
+
+        try {
+            let offset = 0;
+            const partition = ITv2Session.decodeVarBytes(fullPayload, offset);
+            offset += partition.bytesRead;
+            const armMode = fullPayload[offset++];
+            const method = fullPayload[offset++];
+            let userId = 0;
+            if (offset < fullPayload.length) {
+                const uid = ITv2Session.decodeVarBytes(fullPayload, offset);
+                userId = uid.value;
+            }
+
+            const modeNames = {
+                0: 'DISARMED', 1: 'STAY', 2: 'AWAY', 3: 'NO_ENTRY_DELAY',
+                4: 'NIGHT', 5: 'QUICK', 6: 'USER'
+            };
+            const modeName = modeNames[armMode] || `MODE_${armMode}`;
+            this._logMinimal(`[Partition ${partition.value}] ${modeName} (method=${method}, user=${userId})`);
+
+            this.eventHandler.handlePartitionArming(partition.value, armMode);
+            this.emit('partition:arming', {
+                partition: partition.value,
+                armMode,
+                modeName,
+                method,
+                userId,
+            });
+        } catch (e) {
+            this._log(`[Arming Notification] Parse error: ${e.message}`);
+        }
+
+        this._ack();
+    }
+
+    _handlePartitionReadyNotification(parsed) {
+        // NotificationPartitionReadyStatus (neohub format):
+        // [CompactInt:PartitionNumber][Status:1B]
+        // Status: 0=Reserved, 1=ReadyToArm, 2=ReadyToForceArm, 3=NotReadyToArm
+        const fullPayload = this._reconstructPayload(parsed);
+        if (!fullPayload || fullPayload.length < 3) {
+            this._ack();
+            return;
+        }
+
+        try {
+            let offset = 0;
+            const partition = ITv2Session.decodeVarBytes(fullPayload, offset);
+            offset += partition.bytesRead;
+            const readyStatus = fullPayload[offset];
+
+            const statusNames = { 1: 'READY', 2: 'FORCE_ARM_READY', 3: 'NOT_READY' };
+            const isReady = readyStatus === 1 || readyStatus === 2;
+            this._logMinimal(`[Partition ${partition.value}] ${statusNames[readyStatus] || 'UNKNOWN'}`);
+
+            this.eventHandler.handlePartitionReady(partition.value, isReady);
+            this.emit('partition:ready', { partition: partition.value, readyStatus, isReady });
+        } catch (e) {
+            this._log(`[Ready Notification] Parse error: ${e.message}`);
+        }
+
+        this._ack();
+    }
+
+    _handlePartitionTroubleNotification(parsed) {
+        const fullPayload = this._reconstructPayload(parsed);
+        if (!fullPayload || fullPayload.length < 3) {
+            this._ack();
+            return;
+        }
+
+        try {
+            let offset = 0;
+            const partition = ITv2Session.decodeVarBytes(fullPayload, offset);
+            offset += partition.bytesRead;
+            const troubleFlags = fullPayload[offset];
+
+            this._logMinimal(`[Partition ${partition.value}] Trouble: 0x${troubleFlags.toString(16)}`);
+            this.eventHandler.handlePartitionTrouble(partition.value, troubleFlags);
+            this.emit('partition:trouble', { partition: partition.value, troubleFlags });
+        } catch (e) {
+            this._log(`[Trouble Notification] Parse error: ${e.message}`);
+        }
+
+        this._ack();
+    }
+
+    // ==================== Payload Helpers ====================
+
+    _ack() {
+        if (!this._skipAck) {
+            this._sendPacket(this.session.buildSimpleAck());
+        }
+    }
+
+    /**
+     * Reconstruct full payload for non-CommandMessageBase messages.
+     * parseHeader always treats byte 4 as appSequence, but for non-command messages
+     * (notifications, status responses), that byte is actually the first payload byte
+     * (typically a CompactInteger length prefix). This method reassembles the full payload.
+     */
+    _reconstructPayload(parsed) {
+        if (parsed.appSequence !== null && parsed.commandData) {
+            return Buffer.concat([Buffer.from([parsed.appSequence]), parsed.commandData]);
+        } else if (parsed.appSequence !== null) {
+            return Buffer.from([parsed.appSequence]);
+        }
+        return parsed.commandData || Buffer.alloc(0);
+    }
+
+    // ==================== Utility Methods ====================
+
+    _handleError(error) {
+        this._log(`[Error] ${error.message}`);
+        this.emit('error', error);
+    }
+
+    _log(message) {
+        if (this.logLevel === 'verbose') {
+            const timestamp = new Date().toISOString();
+            console.log(`dsc itv2: [${timestamp}] ${message}`);
+        }
+    }
+
+    _logMinimal(message) {
+        if (this.logLevel === 'minimal' || this.logLevel === 'verbose') {
+            console.log(`dsc itv2: ${message}`);
+        }
+    }
+
+    _hexDump(buffer) {
+        if (this.logLevel !== 'verbose') return;
+
+        for (let i = 0; i < buffer.length; i += 16) {
+            const chunk = buffer.slice(i, i + 16);
+            const hex = Array.from(chunk)
+                .map((b) => b.toString(16).padStart(2, '0').toUpperCase())
+                .join(' ');
+            const ascii = Array.from(chunk)
+                .map((b) => (b >= 32 && b <= 126 ? String.fromCharCode(b) : '.'))
+                .join('');
+
+            const offset = i.toString(16).padStart(4, '0').toUpperCase();
+            console.log(`dsc itv2: ${offset}  ${hex.padEnd(48)}  |${ascii}|`);
+        }
+    }
+}