dsc-itv2-client 1.0.7

package/src/response-parsers.js

@@ -0,0 +1,185 @@
+/**
+ * DSC ITV2 Protocol Response Parsers
+ * Based on decompiled SDK structures
+ */
+
+/**
+ * Parse Zone Status response (0x0811)
+ * Each zone status is a single byte with bit fields
+ */
+export function parseZoneStatus(statusByte) {
+  return {
+    zoneNumber: null, // Set by caller
+    open: (statusByte & 0x01) !== 0,           // Bit 0: Open/Closed
+    tamper: (statusByte & 0x02) !== 0,         // Bit 1: Tamper
+    fault: (statusByte & 0x04) !== 0,          // Bit 2: Fault
+    lowBattery: (statusByte & 0x08) !== 0,     // Bit 3: Low Battery
+    delinquency: (statusByte & 0x10) !== 0,    // Bit 4: Communication issue
+    alarm: (statusByte & 0x20) !== 0,          // Bit 5: Alarm
+    alarmInMemory: (statusByte & 0x40) !== 0,  // Bit 6: Alarm memory
+    bypassed: (statusByte & 0x80) !== 0,       // Bit 7: Bypassed
+    rawByte: statusByte
+  };
+}
+
+/**
+ * Format zone status as human-readable string
+ */
+export function formatZoneStatus(zone) {
+  const state = zone.open ? 'OPEN' : 'CLOSED';
+  const flags = [];
+
+  if (zone.alarm) flags.push('ALARM');
+  if (zone.tamper) flags.push('TAMPER');
+  if (zone.fault) flags.push('FAULT');
+  if (zone.bypassed) flags.push('BYPASSED');
+  if (zone.lowBattery) flags.push('LOW-BATT');
+  if (zone.delinquency) flags.push('COMM-ERR');
+  if (zone.alarmInMemory) flags.push('ALARM-MEM');
+
+  const flagStr = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
+  return `Zone ${zone.zoneNumber}: ${state}${flagStr}`;
+}
+
+/**
+ * Parse Partition Status response (0x0812)
+ * Status is encoded across multiple bytes using bit fields
+ */
+export function parsePartitionStatus(statusBytes) {
+  if (!statusBytes || statusBytes.length < 3) {
+    return null;
+  }
+
+  // Helper: Check bit at specific index
+  const checkBit = (bitIndex) => {
+    const byteOffset = Math.floor(bitIndex / 8);
+    const bitMask = 1 << (bitIndex % 8);
+    return byteOffset < statusBytes.length && (statusBytes[byteOffset] & bitMask) !== 0;
+  };
+
+  // Armed state is encoded in bits 0-3 (lower nibble of first byte)
+  const armedValue = statusBytes[0] & 0x0F;
+  const armedStates = {
+    1: 'Disarmed',
+    2: 'Armed Away',
+    3: 'Armed Stay',
+    4: 'Armed Stay (No Entry)',
+    5: 'Armed Stay (Instant)',
+    6: 'Armed Away (Instant)'
+  };
+
+  return {
+    partitionNumber: null, // Set by caller
+    armedState: armedStates[armedValue] || `Unknown (${armedValue})`,
+    armedValue: armedValue,
+    ready: checkBit(0) || checkBit(1) || checkBit(2),  // Bits 0-2: Ready state
+    alarm: checkBit(8),                   // Bit 8: Alarm
+    trouble: checkBit(9),                 // Bit 9: Trouble
+    bypass: checkBit(10),                 // Bit 10: Bypass active
+    busy: checkBit(11),                   // Bit 11: Busy (processing)
+    alarmMemory: checkBit(12),            // Bit 12: Alarm in memory
+    audibleBell: checkBit(14),            // Bit 14: Siren/bell
+    buzzer: checkBit(15),                 // Bit 15: Buzzer
+    blank: checkBit(19),                  // Bit 19: Display blank
+    rawBytes: Buffer.from(statusBytes).toString('hex')
+  };
+}
+
+/**
+ * Format partition status as human-readable string
+ */
+export function formatPartitionStatus(partition) {
+  const flags = [];
+
+  if (partition.alarm) flags.push('ALARM');
+  if (partition.trouble) flags.push('TROUBLE');
+  if (partition.bypass) flags.push('BYPASS');
+  if (partition.busy) flags.push('BUSY');
+  if (partition.audibleBell) flags.push('SIREN');
+  if (partition.buzzer) flags.push('BUZZER');
+  if (partition.alarmMemory) flags.push('ALARM-MEM');
+
+  const readyStr = partition.ready ? 'Ready' : 'Not Ready';
+  const flagStr = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
+
+  return `Partition ${partition.partitionNumber}: ${partition.armedState} - ${readyStr}${flagStr}`;
+}
+
+/**
+ * Parse COMMAND_RESPONSE (0x0502)
+ * Response code indicates success/failure
+ */
+export function parseCommandResponse(responseCode) {
+  const codes = {
+    0x00: 'Success',
+    0x01: 'Informational/Success',
+    0x02: 'Invalid Command',
+    0x03: 'Invalid Parameter',
+    0x04: 'Access Denied',
+    0x05: 'Busy',
+    0x06: 'Not Ready',
+    0x07: 'Timeout',
+    0xFF: 'General Error'
+  };
+
+  return {
+    code: responseCode,
+    message: codes[responseCode] || `Unknown (0x${responseCode.toString(16).padStart(2, '0')})`,
+    success: responseCode === 0x00 || responseCode === 0x01
+  };
+}
+
+/**
+ * Parse COMMAND_ERROR (0x0501)
+ */
+export function parseCommandError(errorData) {
+  if (!errorData || errorData.length < 2) {
+    return { message: 'Unknown error', rawData: errorData?.toString('hex') || 'none' };
+  }
+
+  const errorCode = (errorData[0] << 8) | errorData[1];
+
+  const errorCodes = {
+    0x0002: 'Authentication required / Access denied',
+    0x1002: 'Global status query not supported or auth required',
+    0x1102: 'Zone status query not supported or auth required',
+    0x1202: 'Partition status query not supported or auth required',
+    0x1302: 'Invalid capabilities query',
+    0x1402: 'Invalid panel status query',
+    0x0C01: 'Invalid buffer sizes',
+    0x1100: 'Invalid zone number',
+    0x1200: 'Invalid partition number'
+  };
+
+  return {
+    code: errorCode,
+    message: errorCodes[errorCode] || `Error code 0x${errorCode.toString(16).padStart(4, '0')}`,
+    rawData: errorData.toString('hex')
+  };
+}
+
+/**
+ * Extract variable-length value from buffer
+ */
+export function parseVarLengthValue(buffer, offset = 0) {
+  if (offset >= buffer.length) return null;
+
+  const firstByte = buffer[offset];
+
+  // Determine size based on first byte
+  if (firstByte < 0xFD) {
+    // 1-byte value
+    return { value: firstByte, bytesRead: 1 };
+  } else if (firstByte === 0xFD && offset + 2 < buffer.length) {
+    // 2-byte value
+    const value = (buffer[offset + 1] << 8) | buffer[offset + 2];
+    return { value, bytesRead: 3 };
+  } else if (firstByte === 0xFE && offset + 4 < buffer.length) {
+    // 4-byte value
+    const value = (buffer[offset + 1] << 24) | (buffer[offset + 2] << 16) |
+                  (buffer[offset + 3] << 8) | buffer[offset + 4];
+    return { value, bytesRead: 5 };
+  }
+
+  return null;
+}

package/src/utils.js

@@ -0,0 +1,240 @@
+/**
+ * Utility functions for ITV2 protocol
+ */
+
+import { writeFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LOGS_DIR = join(__dirname, '..', 'logs');
+
+// Ensure logs directory exists
+if (!existsSync(LOGS_DIR)) {
+  mkdirSync(LOGS_DIR, { recursive: true });
+}
+
+/**
+ * Convert buffer to hex string with optional spacing
+ */
+export function toHex(buffer, separator = ' ') {
+  if (!buffer || buffer.length === 0) return '';
+  return Array.from(buffer)
+    .map(b => b.toString(16).padStart(2, '0').toUpperCase())
+    .join(separator);
+}
+
+/**
+ * Convert hex string to buffer
+ */
+export function fromHex(hexString) {
+  const clean = hexString.replace(/\s+/g, '');
+  const bytes = [];
+  for (let i = 0; i < clean.length; i += 2) {
+    bytes.push(parseInt(clean.substr(i, 2), 16));
+  }
+  return Buffer.from(bytes);
+}
+
+/**
+ * Format buffer for display with ASCII representation
+ */
+export function hexDump(buffer, bytesPerLine = 16) {
+  const lines = [];
+  for (let i = 0; i < buffer.length; i += bytesPerLine) {
+    const slice = buffer.slice(i, Math.min(i + bytesPerLine, buffer.length));
+    const hex = toHex(slice, ' ').padEnd(bytesPerLine * 3 - 1);
+    const ascii = Array.from(slice)
+      .map(b => (b >= 32 && b <= 126) ? String.fromCharCode(b) : '.')
+      .join('');
+    lines.push(`${i.toString(16).padStart(4, '0')}  ${hex}  |${ascii}|`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Get timestamp for logging
+ */
+export function timestamp() {
+  return new Date().toISOString();
+}
+
+/**
+ * Log to console and file
+ */
+export function log(message, data = null) {
+  const ts = timestamp();
+  const logLine = `[${ts}] ${message}`;
+  console.log(logLine);
+
+  if (data) {
+    if (Buffer.isBuffer(data)) {
+      console.log(hexDump(data));
+    } else {
+      console.log(data);
+    }
+  }
+
+  // Append to log file
+  const logFile = join(LOGS_DIR, `capture_${new Date().toISOString().split('T')[0]}.log`);
+  let fileContent = logLine + '\n';
+  if (data) {
+    if (Buffer.isBuffer(data)) {
+      fileContent += hexDump(data) + '\n';
+    } else if (typeof data === 'object') {
+      fileContent += JSON.stringify(data, null, 2) + '\n';
+    } else {
+      fileContent += data + '\n';
+    }
+  }
+  appendFileSync(logFile, fileContent);
+}
+
+/**
+ * Log raw packet data to binary file for later analysis
+ */
+export function logRawPacket(direction, data) {
+  const ts = Date.now();
+  const filename = join(LOGS_DIR, `packets_${new Date().toISOString().split('T')[0]}.bin`);
+
+  // Format: [timestamp 8 bytes][direction 1 byte][length 2 bytes][data]
+  const header = Buffer.alloc(11);
+  header.writeBigInt64BE(BigInt(ts), 0);
+  header.writeUInt8(direction === 'TX' ? 0x01 : 0x02, 8);
+  header.writeUInt16BE(data.length, 9);
+
+  appendFileSync(filename, Buffer.concat([header, data]));
+}
+
+/**
+ * CRC-16 calculation with configurable polynomial and seed
+ */
+export function crc16(data, polynomial = 0x1021, seed = 0xFFFF, reflectInput = false, reflectOutput = false, xorOut = 0x0000) {
+  let crc = seed;
+
+  for (let i = 0; i < data.length; i++) {
+    let byte = data[i];
+    if (reflectInput) {
+      byte = reflect8(byte);
+    }
+
+    crc ^= (byte << 8);
+
+    for (let j = 0; j < 8; j++) {
+      if (crc & 0x8000) {
+        crc = ((crc << 1) ^ polynomial) & 0xFFFF;
+      } else {
+        crc = (crc << 1) & 0xFFFF;
+      }
+    }
+  }
+
+  if (reflectOutput) {
+    crc = reflect16(crc);
+  }
+
+  return (crc ^ xorOut) & 0xFFFF;
+}
+
+/**
+ * Reflect bits in a byte
+ */
+function reflect8(value) {
+  let result = 0;
+  for (let i = 0; i < 8; i++) {
+    if (value & (1 << i)) {
+      result |= (1 << (7 - i));
+    }
+  }
+  return result;
+}
+
+/**
+ * Reflect bits in a 16-bit value
+ */
+function reflect16(value) {
+  let result = 0;
+  for (let i = 0; i < 16; i++) {
+    if (value & (1 << i)) {
+      result |= (1 << (15 - i));
+    }
+  }
+  return result;
+}
+
+/**
+ * Try multiple CRC algorithms to find matching one
+ */
+export function tryCrcAlgorithms(data, expectedCrc) {
+  const algorithms = [
+    { name: 'CRC-16-CCITT', poly: 0x1021, seed: 0xFFFF, refIn: false, refOut: false, xorOut: 0x0000 },
+    { name: 'CRC-16-CCITT-FALSE', poly: 0x1021, seed: 0xFFFF, refIn: false, refOut: false, xorOut: 0x0000 },
+    { name: 'CRC-16-XMODEM', poly: 0x1021, seed: 0x0000, refIn: false, refOut: false, xorOut: 0x0000 },
+    { name: 'CRC-16-IBM', poly: 0x8005, seed: 0x0000, refIn: true, refOut: true, xorOut: 0x0000 },
+    { name: 'CRC-16-MODBUS', poly: 0x8005, seed: 0xFFFF, refIn: true, refOut: true, xorOut: 0x0000 },
+    { name: 'CRC-16-USB', poly: 0x8005, seed: 0xFFFF, refIn: true, refOut: true, xorOut: 0xFFFF },
+    { name: 'CRC-16-MAXIM', poly: 0x8005, seed: 0x0000, refIn: true, refOut: true, xorOut: 0xFFFF },
+    { name: 'CRC-16-DNP', poly: 0x3D65, seed: 0x0000, refIn: true, refOut: true, xorOut: 0xFFFF },
+  ];
+
+  const matches = [];
+  for (const alg of algorithms) {
+    const calc = crc16(data, alg.poly, alg.seed, alg.refIn, alg.refOut, alg.xorOut);
+    if (calc === expectedCrc) {
+      matches.push({ ...alg, calculated: calc });
+    }
+  }
+  return matches;
+}
+
+/**
+ * Byte unstuffing (HDLC-like)
+ * Escape byte 0x7D followed by XOR'd byte
+ */
+export function byteUnstuff(data, escapeChar = 0x7D, xorValue = 0x20) {
+  const result = [];
+  let i = 0;
+  while (i < data.length) {
+    if (data[i] === escapeChar && i + 1 < data.length) {
+      result.push(data[i + 1] ^ xorValue);
+      i += 2;
+    } else {
+      result.push(data[i]);
+      i++;
+    }
+  }
+  return Buffer.from(result);
+}
+
+/**
+ * Byte stuffing (HDLC-like)
+ */
+export function byteStuff(data, escapeChar = 0x7D, xorValue = 0x20, specialChars = [0x7E, 0x7D]) {
+  const result = [];
+  for (const byte of data) {
+    if (specialChars.includes(byte)) {
+      result.push(escapeChar);
+      result.push(byte ^ xorValue);
+    } else {
+      result.push(byte);
+    }
+  }
+  return Buffer.from(result);
+}
+
+/**
+ * Parse a 16-bit command code
+ */
+export function parseCommand(high, low) {
+  return (high << 8) | low;
+}
+
+/**
+ * Create a 16-bit command code
+ */
+export function makeCommand(code) {
+  return {
+    high: (code >> 8) & 0xFF,
+    low: code & 0xFF,
+  };
+}