dsc-itv2-client 2.0.6 → 2.0.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsc-itv2-client",
   "author": "fajitacat",
-  "version": "2.0.6",
+  "version": "2.0.9",
   "description": "Reverse engineered DSC ITV2 Protocol Client Library for TL280/TL280E - Monitor and control DSC Neo alarm panels with real-time zone/partition status, arming, and trouble detail",
   "main": "src/index.js",
   "type": "module",

package/src/ITV2Client.js

@@ -5,6 +5,7 @@
 
 import {EventEmitter} from 'events';
 import net from 'net';
+import dgram from 'dgram';
 import {ITv2Session, CMD, CMD_NAMES} from './itv2-session.js';
 import {parseType1Initializer, type2InitializerTransform} from './itv2-crypto.js';
 import {EventHandler} from './event-handler.js';
@@ -23,12 +24,16 @@ export class ITV2Client extends EventEmitter {
         this.accessCode = options.accessCode;
         this.masterCode = options.masterCode || '5555';
         this.port = options.port || 3072;  // TCP port (panel connects to us)
+        this.udpPort = options.udpPort || null;  // UDP port (optional, panel polls 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.udpSocket = null;  // UDP socket
+        this._udpRemote = null; // { address, port } of panel over UDP
+        this._activeTransport = null; // 'tcp' or 'udp' — whichever the panel connected on
         this.session = null;
         this.eventHandler = new EventHandler();
         this.handshakeState = 'WAITING';
@@ -48,17 +53,20 @@ export class ITV2Client extends EventEmitter {
     }
 
     /**
-     * Start the TCP server and listen for panel connection
+     * Start the TCP server (and optional UDP socket) and listen for panel connection
      * The panel initiates a TCP connection to us on port 3072 (default)
+     * If udpPort is configured, also listen for UDP datagrams
      */
     async start() {
-        return new Promise((resolve, reject) => {
+        // Start TCP server
+        await 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;
+                this._activeTransport = 'tcp';
 
                 let buffer = Buffer.alloc(0);
 
@@ -75,12 +83,15 @@ export class ITV2Client extends EventEmitter {
                 socket.on('close', () => {
                     this._logMinimal(`[TCP] Panel disconnected: ${clientId}`);
                     this.tcpSocket = null;
-                    this.handshakeState = 'WAITING';
-                    if (this.session) {
-                        this.session.disableAes();
-                        this.session = null;
+                    if (this._activeTransport === 'tcp') {
+                        this._activeTransport = null;
+                        this.handshakeState = 'WAITING';
+                        if (this.session) {
+                            this.session.disableAes();
+                            this.session = null;
+                        }
+                        this.emit('session:closed');
                     }
-                    this.emit('session:closed');
                 });
 
                 socket.on('error', (err) => {
@@ -101,16 +112,60 @@ export class ITV2Client extends EventEmitter {
                 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);
-            }
+        // Start UDP socket if configured
+        if (this.udpPort) {
+            await this._startUdpSocket();
+        }
+
+        // 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 UDP socket for panel communication
+     * UDP datagrams are self-contained packets (no stream reassembly needed)
+     */
+    async _startUdpSocket() {
+        return new Promise((resolve, reject) => {
+            this.udpSocket = dgram.createSocket('udp4');
+
+            this.udpSocket.on('message', (msg, rinfo) => {
+                this._log(`[UDP] Received ${msg.length} bytes from ${rinfo.address}:${rinfo.port}`);
+
+                // Track remote for responses
+                this._udpRemote = { address: rinfo.address, port: rinfo.port };
+                this.panelAddress = rinfo.address;
+
+                // If panel is using UDP, mark it as active transport
+                if (this._activeTransport !== 'tcp') {
+                    this._activeTransport = 'udp';
+                }
+
+                // UDP datagrams are complete packets — process directly
+                this._handlePacket(msg);
+            });
+
+            this.udpSocket.on('error', (err) => {
+                this._log(`[Error] UDP socket error: ${err.message}`);
+                this.emit('error', err);
+                reject(err);
+            });
+
+            this.udpSocket.bind(this.udpPort, '0.0.0.0', () => {
+                const address = this.udpSocket.address();
+                this._logMinimal(`[UDP] Listening on port ${address.port}`);
+                this.emit('listening:udp', address);
+                resolve();
+            });
         });
     }
 
@@ -180,6 +235,18 @@ export class ITV2Client extends EventEmitter {
             this.tcpServer = null;
         }
 
+        // Close UDP socket
+        if (this.udpSocket) {
+            await new Promise((resolve) => {
+                this.udpSocket.close(() => {
+                    this._log('[Shutdown] UDP socket closed');
+                    resolve();
+                });
+            });
+            this.udpSocket = null;
+            this._udpRemote = null;
+        }
+
         // Clear heartbeat
         if (this._heartbeatInterval) {
             clearInterval(this._heartbeatInterval);
@@ -205,6 +272,7 @@ export class ITV2Client extends EventEmitter {
         }
         this.handshakeState = 'WAITING';
         this.panelAddress = null;
+        this._activeTransport = null;
         this.detectedEncryptionType = null;
         this._panelOpenSessionData = null;
 
@@ -627,6 +695,13 @@ export class ITV2Client extends EventEmitter {
     }
 
     _sendPacket(packet) {
+        if (this._activeTransport === 'udp' && this.udpSocket && this._udpRemote) {
+            this._log(`[UDP] TX ${packet.length} bytes`);
+            this._hexDump(packet);
+            this.udpSocket.send(packet, this._udpRemote.port, this._udpRemote.address);
+            return;
+        }
+
         if (!this.tcpSocket || this.tcpSocket.destroyed) {
             this._logMinimal('[Error] No panel connection');
             return;
@@ -654,9 +729,11 @@ export class ITV2Client extends EventEmitter {
             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(' ')}`);
             }
@@ -758,6 +835,9 @@ export class ITV2Client extends EventEmitter {
             case CMD.SINGLE_ZONE_BYPASS_STATUS:
                 this._handleZoneBypassNotification(parsed);
                 break;
+            case CMD.ZONE_ALARM_STATUS:
+                this._handleZoneAlarmStatus(parsed);
+                break;
             case CMD.MULTIPLE_MESSAGE:
                 this._handleMultipleMessagePacket(parsed);
                 break;
@@ -1480,6 +1560,75 @@ export class ITV2Client extends EventEmitter {
         this._ack();
     }
 
+    _handleZoneAlarmStatus(parsed) {
+        // 0x0840 ModuleStatus_Zone_Alarm_Status (from decompiled SDK):
+        // [Partition CompactInt][Count CompactInt][repeated: Zone CompactInt, AlarmType 1B, AlarmState 1B]
+        //
+        // AlarmType: 1=Unknown, 2=Burglary, 3=24HR_Supervisory, 4=Fire, 5=Fire_Supervisory,
+        //   6=CO, 7=Gas, 8=HighTemp, 9=LowTemp, 10=Medical, 11=Panic, 12=Waterflow,
+        //   13=Water_Leakage, 14=Pendant, 15=Tamper, 16=RF_Jam, 17=Hardware_Fault,
+        //   18=Duress, 19=Personal_Emergency, 20=Holdup, 21=Sprinkler
+        // AlarmState: bit 0 = 0 → NotInAlarm, bit 0 = 1 → InAlarm
+        const fullPayload = this._reconstructPayload(parsed);
+        if (!fullPayload || fullPayload.length < 6) {
+            this._ack();
+            return;
+        }
+
+        const ALARM_TYPES = {
+            1: 'Unknown', 2: 'Burglary', 3: '24HR_Supervisory', 4: 'Fire',
+            5: 'Fire_Supervisory', 6: 'CO', 7: 'Gas', 8: 'HighTemp',
+            9: 'LowTemp', 10: 'Medical', 11: 'Panic', 12: 'Waterflow',
+            13: 'Water_Leakage', 14: 'Pendant', 15: 'Tamper', 16: 'RF_Jam',
+            17: 'Hardware_Fault', 18: 'Duress', 19: 'Personal_Emergency',
+            20: 'Holdup', 21: 'Sprinkler',
+        };
+
+        try {
+            let offset = 0;
+            const partition = ITv2Session.decodeVarBytes(fullPayload, offset);
+            offset += partition.bytesRead;
+
+            const count = ITv2Session.decodeVarBytes(fullPayload, offset);
+            offset += count.bytesRead;
+
+            while (offset < fullPayload.length) {
+                const zone = ITv2Session.decodeVarBytes(fullPayload, offset);
+                offset += zone.bytesRead;
+                if (offset >= fullPayload.length) break;
+                const alarmType = fullPayload[offset++];
+                if (offset >= fullPayload.length) break;
+                const alarmState = fullPayload[offset++];
+
+                const inAlarm = !!(alarmState & 0x01);
+                const alarmTypeName = ALARM_TYPES[alarmType] || `Unknown(${alarmType})`;
+
+                this._logMinimal(`[Zone ${zone.value}] Alarm: ${inAlarm ? 'ACTIVE' : 'CLEARED'} (${alarmTypeName}, partition ${partition.value})`);
+
+                const alarmData = {
+                    zone: zone.value,
+                    partition: partition.value,
+                    alarmType,
+                    alarmTypeName,
+                    inAlarm,
+                    timestamp: new Date(),
+                };
+
+                if (inAlarm) {
+                    this.eventHandler.handleZoneAlarm(zone.value, alarmTypeName);
+                    this.emit('zone:alarm', alarmData);
+                    this.emit('partition:alarm', alarmData);
+                } else {
+                    this.emit('zone:alarm:restored', alarmData);
+                    this.emit('partition:alarm:restored', alarmData);
+                }
+            }
+        } catch (e) {
+            this._log(`[Zone Alarm Status] Parse error: ${e.message}`);
+        }
+        this._ack();
+    }
+
     _handleExitDelayNotification(parsed) {
         // 0x0230 NotificationExitDelay (from neohub):
         // [CompactInt:Partition][DelayFlags:1B][CompactInt:DurationInSeconds]