dsc-itv2-client 1.0.30 → 2.0.0

package/src/itv2-session.js

@@ -91,11 +91,13 @@ export const CMD = {
   ZONE_STATUS: 0x0811,
   PARTITION_STATUS: 0x0812,
   ZONE_BYPASS_STATUS: 0x0813,
-  SYSTEM_TROUBLE_STATUS: 0x0814,
+  SYSTEM_TROUBLE_STATUS: 0x0822,       // New trouble status (0x0814 is deprecated)
+  SYSTEM_TROUBLE_STATUS_OLD: 0x0814,  // Deprecated
   ALARM_MEMORY_INFO: 0x0815,
   BUS_STATUS: 0x0816,
-  TROUBLE_DETAIL: 0x0817,
+  TROUBLE_DETAIL: 0x0823,
   DOOR_CHIME_STATUS: 0x0819,
+  MULTIPLE_MESSAGE: 0x0623,
   // Module Control commands
   PARTITION_ARM: 0x0900,
   PARTITION_DISARM: 0x0901,
@@ -298,6 +300,22 @@ function buildHeader(senderSeq, receiverSeq, command = null, appSeq = null, comm
  * - Type 2: Uses Access Code (32 hex digits) → 16 bytes directly
  */
 export class ITv2Session {
+  /**
+   * Arming mode values (from neohub ArmingMode enum)
+   */
+  static ARM_MODE = {
+    DISARM: 0,
+    STAY: 1,
+    AWAY: 2,
+    NO_ENTRY_DELAY: 3,
+    NIGHT: 4,
+    QUICK: 5,
+    USER: 6,
+    STAY_NO_ENTRY: 7,
+    AWAY_NO_ENTRY: 8,
+    NIGHT_NO_ENTRY: 9,
+  };
+
   constructor(integrationId, accessCode, log = console.log) {
     this.integrationId = integrationId;      // 12-digit ID for packet header
     this.accessCode = accessCode;            // 8-digit (Type 1) or 32-hex (Type 2) for encryption
@@ -368,12 +386,13 @@ export class ITv2Session {
       this.log(`[Session] Encrypted framed: ${framed.toString('hex')}`);
     }
 
-    // Byte stuff the payload
+    // Byte stuff header and payload (neohub stuffs both independently)
+    const stuffedHeader = stuffBytes(Buffer.from(this.integrationId, 'ascii'));
     const stuffedPayload = stuffBytes(framed);
 
-    // Build full packet WITHOUT integration ID
-    // The panel sends WITH integration ID, but SDK sends WITHOUT it
+    // Full packet: [stuffed integration ID][0x7E][stuffed payload][0x7F]
     return Buffer.concat([
+      stuffedHeader,
       Buffer.from([0x7E]),
       stuffedPayload,
       Buffer.from([0x7F]),
@@ -513,21 +532,10 @@ export class ITv2Session {
 
   /**
    * Build OPEN_SESSION message (echo back panel's session info)
-   * NOTE: OPEN_SESSION does NOT have an app sequence byte - it goes directly to payload
+   * OpenSession IS a CommandMessageBase in neohub - it has a CommandSequence byte
    */
   buildOpenSessionResponse(openSessionData) {
-    this.localSequence = (this.localSequence + 1) & 0xFF;
-
-    // OPEN_SESSION format: [sender][receiver][cmd 2B][payload...] - NO app sequence!
-    const message = buildHeader(
-      this.localSequence,
-      this.remoteSequence,
-      CMD.OPEN_SESSION,
-      null,  // NO app sequence for OPEN_SESSION
-      openSessionData
-    );
-
-    return this.buildPacket(message);
+    return this.buildCommand(CMD.OPEN_SESSION, openSessionData);
   }
 
   /**
@@ -759,25 +767,44 @@ export class ITv2Session {
   // ==================== VarBytes Encoding ====================
 
   /**
-   * Encode a value as VarBytes (DSC protocol variable-length integer)
-   * Format: [length byte][value bytes in little-endian]
+   * Encode a value as CompactInteger (DSC protocol variable-length integer)
+   * Format: [length byte][value bytes in big-endian]
+   * Matches neohub CompactIntegerSerializer: strips leading zero bytes, stores BE
    * @param {number} value - Value to encode
-   * @returns {Buffer} - VarBytes encoded buffer
+   * @returns {Buffer} - CompactInteger encoded buffer
    */
   encodeVarBytes(value) {
     if (value < 0x100) {
-      // 1 byte value
       return Buffer.from([0x01, value & 0xFF]);
     } else if (value < 0x10000) {
-      // 2 byte value (little-endian)
-      return Buffer.from([0x02, value & 0xFF, (value >> 8) & 0xFF]);
+      return Buffer.from([0x02, (value >> 8) & 0xFF, value & 0xFF]);
     } else if (value < 0x1000000) {
-      // 3 byte value (little-endian)
-      return Buffer.from([0x03, value & 0xFF, (value >> 8) & 0xFF, (value >> 16) & 0xFF]);
+      return Buffer.from([0x03, (value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF]);
     } else {
-      // 4 byte value (little-endian)
-      return Buffer.from([0x04, value & 0xFF, (value >> 8) & 0xFF, (value >> 16) & 0xFF, (value >> 24) & 0xFF]);
+      return Buffer.from([0x04, (value >> 24) & 0xFF, (value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF]);
+    }
+  }
+
+  /**
+   * Decode a CompactInteger from a buffer
+   * Format: [length byte][value bytes in big-endian]
+   * @param {Buffer} buffer - Buffer to read from
+   * @param {number} offset - Starting offset
+   * @returns {{ value: number, bytesRead: number }}
+   */
+  static decodeVarBytes(buffer, offset = 0) {
+    if (offset >= buffer.length) {
+      throw new Error('Buffer too short for CompactInteger');
+    }
+    const length = buffer[offset];
+    if (offset + 1 + length > buffer.length) {
+      throw new Error(`Buffer too short for CompactInteger value (need ${length}, have ${buffer.length - offset - 1})`);
+    }
+    let value = 0;
+    for (let i = 0; i < length; i++) {
+      value = (value << 8) | buffer[offset + 1 + i];
     }
+    return { value, bytesRead: 1 + length };
   }
 
   /**
@@ -818,24 +845,20 @@ export class ITv2Session {
 
   /**
    * Build a 0x0800 Command Request wrapper
-   * This wraps inner commands for status queries - required by the DSC protocol
-   * Format: [AppSeqNum 1B][CommandToRequest 2B LE][InnerPayload...]
+   * Neohub wire format: [CommandSequence 1B][InnerCommand 2B BE][InnerPayload...]
+   * CommandSequence is provided by buildCommand as the appSequence byte - NOT duplicated here.
    * @param {number} innerCommand - The command code to request (e.g., 0x0811)
    * @param {Buffer} innerPayload - The payload for the inner command
    * @returns {Buffer} - Complete packet ready to send
    */
   buildCommandRequest(innerCommand, innerPayload = Buffer.alloc(0)) {
-    // Get next application sequence number
-    const appSeq = this.appSequence;
-    this.appSequence = (this.appSequence + 1) & 0xFF;
-
-    // Build 0x0800 payload: [AppSeqNum][CommandToRequest LE][InnerPayload]
-    const payload = Buffer.alloc(3 + innerPayload.length);
-    payload[0] = appSeq;
-    payload.writeUInt16LE(innerCommand, 1);  // Command in little-endian
-    innerPayload.copy(payload, 3);
+    // Build payload: [InnerCommand 2B BE][InnerPayload]
+    // The CommandSequence is added by buildCommand as the appSequence byte
+    const payload = Buffer.alloc(2 + innerPayload.length);
+    payload.writeUInt16BE(innerCommand, 0);
+    innerPayload.copy(payload, 2);
 
-    this.log(`[Session] Building 0x0800 Command Request: innerCmd=0x${innerCommand.toString(16)}, appSeq=${appSeq}`);
+    this.log(`[Session] Building 0x0800 Command Request: innerCmd=0x${innerCommand.toString(16)}`);
     this.log(`[Session] Inner payload: ${innerPayload.toString('hex')}`);
 
     return this.buildCommand(CMD.STATUS_REQUEST, payload);
@@ -843,6 +866,24 @@ export class ITv2Session {
 
   // ==================== Status Query Methods (0x0800 Wrapped) ====================
 
+  /**
+   * Build system capabilities request (0x0613 wrapped in 0x0800)
+   * Neohub queries this FIRST on connect to get max zones/partitions/etc.
+   */
+  buildCapabilitiesRequest() {
+    // ConnectionSystemCapabilities: 6 CompactInteger fields, all default 0
+    // Each CompactInt(0) = [0x01, 0x00]
+    const payload = Buffer.from([
+      0x01, 0x00, // MaxZones = 0
+      0x01, 0x00, // MaxUsers = 0
+      0x01, 0x00, // MaxPartitions = 0
+      0x01, 0x00, // MaxFOBs = 0
+      0x01, 0x00, // MaxProxTags = 0
+      0x01, 0x00, // MaxOutputs = 0
+    ]);
+    return this.buildCommandRequest(CMD.SYSTEM_CAPABILITIES, payload);
+  }
+
   /**
    * Build global status request (0x0810 wrapped in 0x0800)
    */
@@ -857,7 +898,8 @@ export class ITv2Session {
    * @param {number} numZones - Number of zones to query (default 128)
    */
   buildZoneStatusRequest(startZone = 0, numZones = 128) {
-    // 0x0811 payload: [ZoneNumber VarBytes][NumberOfZones VarBytes]
+    // 0x0811 request payload: [ZoneStart CompactInt][ZoneCount CompactInt]
+    // StatusSizeInBytes and ZoneStatusBytes are response-only fields
     const zoneBytes = this.encodeVarBytes(startZone);
     const countBytes = this.encodeVarBytes(numZones);
     const payload = Buffer.concat([zoneBytes, countBytes]);
@@ -869,11 +911,12 @@ export class ITv2Session {
    * @param {number} partition - Partition number (0 = all partitions)
    * @param {number} numPartitions - Number of partitions to query (default 8)
    */
-  buildPartitionStatusRequest(partition = 0, numPartitions = 8) {
-    // 0x0812 payload: [Partition VarBytes][NumberOfPartitions VarBytes]
+  buildPartitionStatusRequest(partition = 1) {
+    // 0x0812 payload (from neohub ModulePartitionStatus):
+    // [Partition CompactInt][PartitionStatus LeadingLengthArray(empty)]
     const partBytes = this.encodeVarBytes(partition);
-    const countBytes = this.encodeVarBytes(numPartitions);
-    const payload = Buffer.concat([partBytes, countBytes]);
+    const emptyArray = Buffer.from([0x00]); // LeadingLengthArray with 0 length
+    const payload = Buffer.concat([partBytes, emptyArray]);
     return this.buildCommandRequest(CMD.PARTITION_STATUS, payload);
   }
 
@@ -964,16 +1007,22 @@ export class ITv2Session {
 
   /**
    * Build POLL command for keepalive
+   * ConnectionPoll is IMessageData (no CommandSequence) — just command code, no payload
    */
   buildPoll() {
-    return this.buildCommand(CMD.POLL);
+    this.localSequence = (this.localSequence + 1) & 0xFF;
+    const message = buildHeader(this.localSequence, this.remoteSequence, CMD.POLL);
+    return this.buildPacket(message);
   }
 
   /**
    * Build END_SESSION command to gracefully close the session
+   * No CommandSequence, no payload — just the command code
    */
   buildEndSession() {
-    return this.buildCommand(CMD.END_SESSION);
+    this.localSequence = (this.localSequence + 1) & 0xFF;
+    const message = buildHeader(this.localSequence, this.remoteSequence, CMD.END_SESSION);
+    return this.buildPacket(message);
   }
 
   /**
@@ -993,25 +1042,33 @@ export class ITv2Session {
     }
 
     const partition = data[0];
-    const statusByte = data[1];
+    // From neohub ModulePartitionStatus PartitionStatus1/2/3:
+    const status1 = data[1];
+    const status2 = data.length > 2 ? data[2] : 0;
+    const status3 = data.length > 3 ? data[3] : 0;
 
-    // Status byte bit meanings (based on DSC protocol):
+    const armedValue = status1 & 0x1F;
     const status = {
       partition,
-      armed: !!(statusByte & 0x01),        // Bit 0: Armed
-      stayArmed: !!(statusByte & 0x02),    // Bit 1: Stay Armed
-      awayArmed: !!(statusByte & 0x04),    // Bit 2: Away Armed
-      alarm: !!(statusByte & 0x08),        // Bit 3: Alarm
-      trouble: !!(statusByte & 0x10),      // Bit 4: Trouble
-      ready: !!(statusByte & 0x20),        // Bit 5: Ready
-      exitDelay: !!(statusByte & 0x40),    // Bit 6: Exit Delay
-      entryDelay: !!(statusByte & 0x80),   // Bit 7: Entry Delay
-      rawStatus: statusByte,
+      armed: !!(status1 & 0x01),
+      stayArmed: armedValue === 0x03,
+      awayArmed: armedValue === 0x05,
+      nightArmed: armedValue === 0x09,
+      exitDelay: !!(status1 & 0x20),
+      entryDelay: !!(status1 & 0x40),
+      quickExit: !!(status1 & 0x80),
+      alarm: !!(status2 & 0x01),
+      trouble: !!(status2 & 0x02),
+      bypass: !!(status2 & 0x04),
+      alarmMemory: !!(status2 & 0x10),
+      audibleBell: !!(status2 & 0x40),
+      buzzer: !!(status2 & 0x80),
+      firePreAlert: !!(status3 & 0x01),
+      rawStatus: status1,
     };
 
-    // Additional bytes may contain more info
-    if (data.length > 2) {
-      status.additionalData = data.slice(2);
+    if (data.length > 4) {
+      status.additionalData = data.slice(4);
     }
 
     return status;
@@ -1029,17 +1086,17 @@ export class ITv2Session {
     const zone = data[0];
     const statusByte = data[1];
 
-    // Zone status bit meanings:
+    // Zone status bit meanings (from neohub ModuleZoneStatus.ZoneStatusEnum):
     const status = {
       zone,
-      open: !!(statusByte & 0x01),         // Bit 0: Zone Open
-      tamper: !!(statusByte & 0x02),       // Bit 1: Tamper
-      fault: !!(statusByte & 0x04),        // Bit 2: Fault
-      lowBattery: !!(statusByte & 0x08),   // Bit 3: Low Battery
-      supervision: !!(statusByte & 0x10),  // Bit 4: Supervision Loss
-      alarm: !!(statusByte & 0x20),        // Bit 5: In Alarm
-      bypassed: !!(statusByte & 0x40),     // Bit 6: Bypassed
-      armed: !!(statusByte & 0x80),        // Bit 7: Armed
+      open: !!(statusByte & 0x01),           // Bit 0: Open
+      tamper: !!(statusByte & 0x02),         // Bit 1: Tamper
+      fault: !!(statusByte & 0x04),          // Bit 2: Fault
+      lowBattery: !!(statusByte & 0x08),     // Bit 3: Low Battery
+      delinquency: !!(statusByte & 0x10),    // Bit 4: Delinquency
+      alarm: !!(statusByte & 0x20),          // Bit 5: Alarm
+      alarmInMemory: !!(statusByte & 0x40),  // Bit 6: Alarm Memory
+      bypassed: !!(statusByte & 0x80),       // Bit 7: Bypass
       rawStatus: statusByte,
     };
 
@@ -1072,11 +1129,12 @@ export class ITv2Session {
   /**
    * Build PARTITION_ARM command
    * @param {number} partition - Partition number (1-8)
-   * @param {number} armMode - Arming mode:
-   *   0 = Stay (perimeter only)
-   *   1 = Away (full arm)
-   *   2 = No Entry Delay
-   *   3 = Force Arm (bypass open zones)
+   * @param {number} armMode - Arming mode (use ITv2Session.ARM_MODE):
+   *   1 = Stay (perimeter only)
+   *   2 = Away (full arm)
+   *   3 = No Entry Delay
+   *   4 = Night
+   *   5 = Quick Arm
    * @param {string} accessCode - Master/user code (e.g., "5555")
    */
   buildPartitionArm(partition, armMode, accessCode) {

package/src/response-parsers.js

@@ -46,41 +46,50 @@ export function formatZoneStatus(zone) {
  * Status is encoded across multiple bytes using bit fields
  */
 export function parsePartitionStatus(statusBytes) {
-  if (!statusBytes || statusBytes.length < 3) {
+  if (!statusBytes || statusBytes.length < 1) {
     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;
-  };
+  // From neohub ModulePartitionStatus PartitionStatus1/2/3 enums:
+  const status1 = statusBytes[0] || 0;
+  const status2 = statusBytes.length > 1 ? statusBytes[1] : 0;
+  const status3 = statusBytes.length > 2 ? statusBytes[2] : 0;
 
-  // Armed state is encoded in bits 0-3 (lower nibble of first byte)
-  const armedValue = statusBytes[0] & 0x0F;
+  // Status1 byte: armed state is a composite value, not individual bits
+  // Armed=0x01, StayArmed=0x03, ArmedAway=0x05, NightArmed=0x09,
+  // ArmedNoEntry=0x11, ExitDelay=0x20, EntryDelay=0x40, QuickExit=0x80
+  const armedValue = status1 & 0x1F; // Lower 5 bits for armed state
   const armedStates = {
-    1: 'Disarmed',
-    2: 'Armed Away',
-    3: 'Armed Stay',
-    4: 'Armed Stay (No Entry)',
-    5: 'Armed Stay (Instant)',
-    6: 'Armed Away (Instant)'
+    0x00: 'Disarmed',
+    0x01: 'Armed',
+    0x03: 'Armed Stay',
+    0x05: 'Armed Away',
+    0x09: 'Armed Night',
+    0x11: 'Armed (No Entry Delay)',
   };
 
   return {
     partitionNumber: null, // Set by caller
-    armedState: armedStates[armedValue] || `Unknown (${armedValue})`,
+    armedState: armedStates[armedValue] || `Unknown (0x${armedValue.toString(16)})`,
     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
+    armed: !!(status1 & 0x01),
+    stayArmed: armedValue === 0x03,
+    awayArmed: armedValue === 0x05,
+    nightArmed: armedValue === 0x09,
+    exitDelay: !!(status1 & 0x20),
+    entryDelay: !!(status1 & 0x40),
+    quickExit: !!(status1 & 0x80),
+    // Status2 byte flags
+    alarm: !!(status2 & 0x01),
+    trouble: !!(status2 & 0x02),
+    bypass: !!(status2 & 0x04),
+    programmingMode: !!(status2 & 0x08),
+    alarmMemory: !!(status2 & 0x10),
+    doorChime: !!(status2 & 0x20),
+    audibleBell: !!(status2 & 0x40),
+    buzzer: !!(status2 & 0x80),
+    // Status3 byte flags
+    firePreAlert: !!(status3 & 0x01),
     rawBytes: Buffer.from(statusBytes).toString('hex')
   };
 }