dsc-itv2-client 1.0.7

package/src/ITV2Client.js

@@ -0,0 +1,502 @@
+/**
+ * DSC ITV2 Protocol Client
+ * Event-driven client for DSC alarm panels using the ITV2 protocol
+ */
+
+import { EventEmitter } from 'events';
+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';
+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;
+    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;
+    this.session = null;
+    this.eventHandler = new EventHandler();
+    this.handshakeState = 'WAITING';
+    this.panelAddress = null;
+    this.panelPort = null;
+    this.detectedEncryptionType = null; // Set during handshake
+
+    // Bind methods
+    this._handlePacket = this._handlePacket.bind(this);
+    this._handleError = this._handleError.bind(this);
+  }
+
+  /**
+   * 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');
+    });
+  }
+
+  /**
+   * 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.emit('session:closed');
+  }
+
+  /**
+   * Arm partition in stay mode
+   */
+  armStay(partition, code) {
+    if (!this._checkEstablished()) return;
+    const packet = this.session.buildPartitionArm(partition, 0, code || this.masterCode);
+    this._sendPacket(packet);
+  }
+
+  /**
+   * Arm partition in away mode
+   */
+  armAway(partition, code) {
+    if (!this._checkEstablished()) return;
+    const packet = this.session.buildPartitionArm(partition, 1, 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);
+  }
+
+  /**
+   * Get current zone states
+   */
+  getZones() {
+    return this.eventHandler.getZoneStates();
+  }
+
+  /**
+   * Get current partition states
+   */
+  getPartitions() {
+    return this.eventHandler.getPartitionStates();
+  }
+
+  // ==================== Internal Methods ====================
+
+  _checkEstablished() {
+    if (this.handshakeState !== 'ESTABLISHED') {
+      this.emit('error', new Error('Session not established'));
+      return false;
+    }
+    return true;
+  }
+
+  _sendPacket(packet) {
+    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) {
+    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);
+        this.emit('session:connecting');
+        this._logMinimal(`[Session] Panel connecting from ${this.panelAddress}`);
+      }
+
+      const parsed = this.session.parsePacket(data);
+      if (!parsed) {
+        this._log('[Error] Failed to parse packet');
+        return;
+      }
+
+      // Verbose logging only
+      this._log(`\n[UDP] RX from ${this.panelAddress}:${this.panelPort} (${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) {
+      this._log(`[Error] ${err.message}`);
+      this.emit('error', err);
+
+      // Reset on parse errors
+      if (this.handshakeState !== 'WAITING' && this.handshakeState !== 'SENT_CMD_RESPONSE_1') {
+        this._log('[Recovery] Parse error, resetting to wait for panel restart');
+        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;
+      default:
+        if (this.handshakeState === 'ESTABLISHED') {
+          this._log(`[Session] Unhandled command ${CMD_NAMES[cmd] || '0x' + cmd?.toString(16)}`);
+          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}`);
+    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(`✅ 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);
+
+    this.handshakeState = 'WAITING_TO_SEND_REQUEST_ACCESS';
+  }
+
+  _handleCommandResponse(parsed) {
+    const responseCode = parsed.commandData?.[0] || 0;
+    const appSeqAsEcho = parsed.appSequence;
+
+    this._log(`[Handshake] Got COMMAND_RESPONSE (echoed app_seq: ${appSeqAsEcho}, response_code: ${responseCode}), sending ACK`);
+
+    const ack = this.session.buildSimpleAck();
+    this._sendPacket(ack);
+
+    if (this.handshakeState === 'SENT_OPEN_SESSION') {
+      // Panel accepted our OPEN_SESSION
+      this.handshakeState = 'WAITING_REQUEST_ACCESS';
+    }
+  }
+
+  _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) {
+    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());
+  }
+
+  // ==================== 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(`[${timestamp}] ${message}`);
+    }
+  }
+
+  _logMinimal(message) {
+    if (this.logLevel === 'minimal' || this.logLevel === 'verbose') {
+      console.log(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(`${offset}  ${hex.padEnd(48)}  |${ascii}|`);
+    }
+  }
+}

package/src/constants.js

@@ -0,0 +1,106 @@
+/**
+ * ITV2 Protocol Constants
+ * Based on reverse engineering of DSC Neo DLLs and TSP Interactive SDK documentation
+ */
+
+// Connection settings (per SDK documentation)
+export const DEFAULT_HOST = '192.168.0.144';  // TL280R IP (not used - it connects to us)
+export const DEFAULT_UDP_PORT = 3073;  // Integration Polling Port (section [430] = 0x0C01)
+export const DEFAULT_TCP_PORT = 3072;  // Integration Notification Port (section [429] = 0x0C00)
+export const DEFAULT_PORT = DEFAULT_TCP_PORT;  // Legacy alias
+
+// Channel functions (from SDK)
+export const ChannelFunction = {
+  NO_FUNCTION: 0,
+  POLL_ONLY: 1,
+  POLL_AND_NOTIFY: 2,
+  NOTIFICATIONS: 3,
+};
+
+// Command codes (16-bit: high byte = category, low byte = command)
+export const Commands = {
+  // Response codes (0x00xx, 0x05xx)
+  SIMPLE_ACK: 0x0000,
+  COMMAND_ERROR: 0x0501,
+  COMMAND_RESPONSE: 0x0502,
+
+  // Session management (0x06xx)
+  POLL: 0x0600,
+  OPEN_SESSION: 0x060A,
+  END_SESSION: 0x060B,
+  BUFFER_SIZES: 0x060C,
+  REQUEST_ACCESS: 0x060E,
+  SYSTEM_CAPABILITIES: 0x0613,
+
+  // Zone/Lifestyle events (0x02xx)
+  LIFESTYLE_ZONE_STATUS: 0x0210,
+  EXIT_DELAY: 0x0230,
+  ENTRY_DELAY: 0x0231,
+  ARMING_DISARMING: 0x0232,
+  ARMING_PREALERT: 0x0233,
+  PARTITION_QUICK_EXIT: 0x0238,
+  PARTITION_READY_STATUS: 0x0239,
+  PARTITION_AUDIBLE_BELL: 0x023B,
+  PARTITION_ALARM_MEMORY: 0x023C,
+  MISC_PREALERT: 0x023D,
+  PARTITION_TROUBLE_STATUS: 0x023F,
+  PARTITION_BYPASS_STATUS: 0x0240,
+
+  // Configuration (0x07xx)
+  ZONE_ASSIGNMENT_CONFIG: 0x0770,
+  CONFIGURATION: 0x0771,
+  PARTITION_ASSIGNMENT_CONFIG: 0x0772,
+
+  // Status queries (0x08xx)
+  GLOBAL_STATUS: 0x0810,
+  ZONE_STATUS: 0x0811,
+  PARTITION_STATUS: 0x0812,
+  ZONE_BYPASS_STATUS: 0x0813,
+  SINGLE_ZONE_BYPASS_STATUS: 0x0820,
+  SYSTEM_TROUBLE_STATUS: 0x0822,
+  TROUBLE_DETAIL: 0x0823,
+  ZONE_ALARM_STATUS: 0x0840,
+  MISC_ALARM_STATUS: 0x0841,
+
+  // LCD/Keypad (0x0Fxx)
+  LCD_UPDATE: 0x0F02,
+  LCD_CURSOR: 0x0F03,
+  LED_STATUS: 0x0F04,
+
+  // Access codes (0x47xx)
+  ACCESS_CODES_RESPONSE: 0x4736,
+  ACCESS_CODES_PARTITION_RESPONSE: 0x4738,
+};
+
+// Command names for logging
+export const CommandNames = Object.fromEntries(
+  Object.entries(Commands).map(([name, code]) => [code, name])
+);
+
+// Get command name from code
+export function getCommandName(code) {
+  return CommandNames[code] || `UNKNOWN_${code.toString(16).toUpperCase().padStart(4, '0')}`;
+}
+
+// CRC-16 common polynomials to try
+export const CRC16_POLYNOMIALS = {
+  CCITT: 0x1021,
+  IBM: 0x8005,
+  T10_DIF: 0x8BB7,
+  DNP: 0x3D65,
+  MODBUS: 0x8005,
+};
+
+// Common CRC-16 seeds
+export const CRC16_SEEDS = {
+  ZERO: 0x0000,
+  FFFF: 0xFFFF,
+  ONE: 0x0001,
+};
+
+// Possible frame markers (to be determined from captures)
+export const FRAME_MARKERS = {
+  POSSIBLE_START: [0x7E, 0xFE, 0xFF, 0xAA, 0x55, 0x02],
+  POSSIBLE_END: [0x7E, 0x03, 0x0D, 0x0A],
+  ESCAPE: 0x7D,
+};