dsc-itv2-client 2.0.3 → 2.0.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsc-itv2-client",
   "author": "fajitacat",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "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

@@ -270,6 +270,11 @@ export class ITV2Client extends EventEmitter {
             } catch (_) {}
 
             throw new Error('Arm/disarm not confirmed - panel may have open zones or troubles');
+        } finally {
+            // Arm/disarm clears zone bypass state — refresh zone status after a brief settle
+            setTimeout(() => {
+                this.queryZoneStatus().catch(() => {});
+            }, 2000);
         }
     }
 
@@ -309,9 +314,122 @@ export class ITV2Client extends EventEmitter {
         return this._sendArmCommand(packet, partition, 'ARMED');
     }
 
-    // TODO: Zone bypass commands (0x074A) require a programming mode flow
-    // (ITV2_ProgModeInfo) that hasn't been fully reverse-engineered.
-    // Bypass STATUS monitoring works via 0x0820 notifications and zone:bypass events.
+    /**
+     * Bypass a zone (exclude from monitoring).
+     * Uses config mode: 0x0704 → 0x074A → 0x0701.
+     * @param {number} zone - Zone number to bypass
+     * @param {number} [partition=1] - Partition number
+     * @param {string} [code] - User/master code (defaults to masterCode)
+     * @returns {Promise<object>} Resolves with bypass confirmation
+     */
+    async bypassZone(zone, partition = 1, code) {
+        return this._sendBypassCommand(zone, partition, true, code);
+    }
+
+    /**
+     * Unbypass a zone (restore monitoring).
+     * @param {number} zone - Zone number to unbypass
+     * @param {number} [partition=1] - Partition number
+     * @param {string} [code] - User/master code (defaults to masterCode)
+     * @returns {Promise<object>} Resolves with unbypass confirmation
+     */
+    async unbypassZone(zone, partition = 1, code) {
+        return this._sendBypassCommand(zone, partition, false, code);
+    }
+
+    /**
+     * Send a zone bypass/unbypass command.
+     * Flow: 0x0704 (enter config mode) → wait for 0x0702 → 0x074A (bypass) → 0x0701 (exit)
+     * @private
+     */
+    async _sendBypassCommand(zone, partition, bypass, code, timeout = 10000) {
+        if (!this._checkEstablished()) {
+            throw new Error('Session not established');
+        }
+
+        const accessCode = code || this.masterCode;
+        const action = bypass ? 'BYPASS' : 'UNBYPASS';
+
+        // Step 1: Enter config mode (type=3 = zone bypass, mode=1 = user code)
+        const enterPacket = this.session.buildEnterConfigMode(partition, 3, accessCode, 1);
+        this._sendPacket(enterPacket);
+
+        // Step 2: Wait for 0x0702 config status confirmation (COMMAND_RESPONSE is intermediate)
+        await this._waitForConfigReady(5000);
+
+        // Step 3: Send zone bypass write
+        const bypassPacket = this.session.buildZoneBypass(partition, zone, bypass);
+
+        try {
+            const result = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { cleanup(); reject(new Error('timeout')); }, timeout);
+
+                const onBypass = (data) => {
+                    if (data.zone === zone) { cleanup(); resolve(data); }
+                };
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    this.removeListener('zone:bypass', onBypass);
+                };
+
+                this.on('zone:bypass', onBypass);
+                this._sendPacket(bypassPacket);
+            });
+
+            // Step 4: Exit config mode
+            const exitPacket = this.session.buildExitConfigMode(partition);
+            this._sendPacket(exitPacket);
+
+            return result;
+        } catch (e) {
+            // Always try to exit config mode
+            try {
+                const exitPacket = this.session.buildExitConfigMode(partition);
+                this._sendPacket(exitPacket);
+            } catch (_) {}
+
+            if (e.message !== 'timeout') throw e;
+
+            // No 0x0820 confirmation — query zone status to check
+            try {
+                const zones = await this.queryZoneStatus();
+                const zoneStatus = zones.find(z => z.zoneNumber === zone);
+                if (zoneStatus && zoneStatus.bypassed === bypass) {
+                    return { zone, bypassed: bypass, fromQuery: true };
+                }
+            } catch (_) {}
+
+            throw new Error(`Zone ${zone} ${action} not confirmed - check access code and zone number`);
+        }
+    }
+
+    /**
+     * Wait for 0x0702 (config status) notification confirming config mode is ready.
+     * COMMAND_RESPONSE to 0x0704 is an intermediate ack — the real confirmation is 0x0702.
+     * @private
+     */
+    _waitForConfigReady(timeout = 10000) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => { cleanup(); resolve(); }, timeout);
+            const origRoute = this._routePacket.bind(this);
+
+            const interceptor = (parsed, skipAck) => {
+                if (parsed.command === 0x0702) {
+                    cleanup();
+                    this._logMinimal('[Config] Config mode ready (0x0702)');
+                    resolve();
+                }
+                origRoute(parsed, skipAck);
+            };
+
+            const cleanup = () => {
+                clearTimeout(timer);
+                this._routePacket = origRoute;
+            };
+
+            this._routePacket = interceptor;
+        });
+    }
 
     /**
      * Disarm partition
@@ -1328,6 +1446,12 @@ export class ITV2Client extends EventEmitter {
                 const bypassed = fullPayload[offset] === 1;
 
                 this._logMinimal(`[Zone ${zone.value}] ${bypassed ? 'BYPASSED' : 'UNBYPASSED'}`);
+
+                // Update cached zone state
+                if (this.eventHandler) {
+                    this.eventHandler.handleZoneBypass(zone.value, bypassed);
+                }
+
                 this.emit('zone:bypass', { zone: zone.value, bypassed });
             } catch (e) {
                 this._log(`[Bypass Status] Parse error: ${e.message}`);

package/src/constants.js

@@ -47,6 +47,9 @@ export const Commands = {
   PARTITION_BYPASS_STATUS: 0x0240,
 
   // Configuration (0x07xx)
+  CONFIG_EXIT: 0x0701,
+  CONFIG_ENTER: 0x0704,
+  SINGLE_ZONE_BYPASS_WRITE: 0x074A,
   ZONE_ASSIGNMENT_CONFIG: 0x0770,
   CONFIGURATION: 0x0771,
   PARTITION_ASSIGNMENT_CONFIG: 0x0772,

package/src/event-handler.js

@@ -104,6 +104,33 @@ export class EventHandler {
     return status;
   }
 
+  /**
+   * Update zone bypass state from 0x0820 notification
+   * @param {number} zoneNum - Zone number
+   * @param {boolean} bypassed - true if bypassed
+   */
+  handleZoneBypass(zoneNum, bypassed) {
+    const existing = this.zoneStates.get(zoneNum);
+    if (existing) {
+      existing.bypassed = bypassed;
+      existing.rawStatus = bypassed
+        ? (existing.rawStatus | 0x80)
+        : (existing.rawStatus & ~0x80);
+      existing.timestamp = new Date();
+    } else {
+      // Zone not yet seen — create minimal state
+      this.zoneStates.set(zoneNum, {
+        zoneNumber: zoneNum,
+        open: false, tamper: false, fault: false,
+        lowBattery: false, delinquency: false,
+        alarm: false, alarmInMemory: false,
+        bypassed: bypassed,
+        rawStatus: bypassed ? 0x80 : 0x00,
+        timestamp: new Date()
+      });
+    }
+  }
+
   /**
    * Process zone alarm notification
    */

package/src/examples/interactive-cli.js

@@ -237,6 +237,31 @@ rl.on('line', async (line) => {
         break;
       }
 
+      // ---- Zone Bypass ----
+      case 'bypass': {
+        const z = parseInt(args[0]);
+        if (!z) { console.log('Usage: bypass <zone> [part]'); break; }
+        const part = parseInt(args[1] || '1');
+        console.log(`Bypassing zone ${z}...`);
+        try {
+          const r = await client.bypassZone(z, part);
+          console.log(`Zone ${z}: BYPASSED${r.fromQuery ? ' (verified by query)' : ''}`);
+        } catch (e) { console.log(e.message); }
+        break;
+      }
+
+      case 'unbypass': {
+        const z = parseInt(args[0]);
+        if (!z) { console.log('Usage: unbypass <zone> [part]'); break; }
+        const part = parseInt(args[1] || '1');
+        console.log(`Unbypassing zone ${z}...`);
+        try {
+          const r = await client.unbypassZone(z, part);
+          console.log(`Zone ${z}: UNBYPASSED${r.fromQuery ? ' (verified by query)' : ''}`);
+        } catch (e) { console.log(e.message); }
+        break;
+      }
+
       // ---- Auth ----
       case 'auth': {
         const code = args[0] || config.masterCode;
@@ -261,6 +286,10 @@ rl.on('line', async (line) => {
     night [part] [code] Arm partition in NIGHT mode
     disarm [part] [code] Disarm partition
 
+  ZONE BYPASS
+    bypass <zone> [part]    Bypass zone (exclude from monitoring)
+    unbypass <zone> [part]  Unbypass zone (restore monitoring)
+
   OTHER
     auth [code]         Authenticate with master/user code
     help, ?             Show this help

package/src/itv2-session.js

@@ -83,6 +83,7 @@ export const CMD = {
   SYSTEM_CAPABILITIES: 0x0613,
   PANEL_STATUS: 0x0614,
   // Configuration commands (0x07xx)
+  CONFIG_EXIT: 0x0701,
   CONFIG_ENTER: 0x0704,
   CONFIG_ACCESS_CODE_WRAPPER: 0x0703,
   // Module Status commands
@@ -1194,48 +1195,56 @@ export class ITv2Session {
   }
 
   /**
-   * Build SINGLE_ZONE_BYPASS_WRITE wrapped in ACCESS_CODE_WRAPPER (0x0703)
-   * Configuration writes require access code authentication.
-   * Wire format for 0x0703: [AccessCode ByteArray][SubCommand 2B BE][Data ByteArray]
-   * OnHasAppSeqNum returns 0 — no CommandSequence in the payload.
+   * Build ENTER_CONFIGURATION_MODE (0x0704)
+   * Must be sent before config write commands like 0x074A.
+   * Wire format: [Partition VarBytes][Type 1B][AccessCode ByteArray(bcd)][Mode 1B]
    * @param {number} partition - Partition number (1-8)
-   * @param {number} zone - Zone number
-   * @param {boolean} bypass - true to bypass, false to unbypass
+   * @param {number} type - Programming type (3 = zone bypass)
    * @param {string} accessCode - Master/user code (e.g., "1234")
+   * @param {number} mode - Access mode (1 = user code)
    */
-  buildZoneBypass(partition, zone, bypass, accessCode) {
-    // Inner 0x074A payload: [Partition VarBytes][ZoneNumber VarBytes][BypassState 1B]
-    const innerPayload = Buffer.concat([
+  buildEnterConfigMode(partition, type, accessCode, mode = 1) {
+    const codeStr = accessCode.toString();
+    // Access code as raw digit values (each digit as one byte: "1234" → [0x01,0x02,0x03,0x04])
+    const codeBytes = Buffer.from(codeStr.split('').map(d => parseInt(d, 10)));
+    const payload = Buffer.concat([
       this.encodeVarBytes(partition),
-      this.encodeVarBytes(zone),
-      Buffer.from([bypass ? 0x01 : 0x00]),
+      Buffer.from([type]),
+      this.encodeByteArray(codeBytes),
+      Buffer.from([mode]),
     ]);
 
-    // Access code in BCD format
-    const bcdCode = this._encodeBcd(accessCode);
+    this.log(`[Session] ENTER_CONFIG_MODE: partition=${partition}, type=${type}, mode=${mode}`);
+    return this.buildCommand(CMD.CONFIG_ENTER, payload);
+  }
 
-    // 0x0703 payload (no AppSeqNum): [AccessCode ByteArray][SubCommand 2B BE][Data ByteArray]
-    const subCmd = Buffer.alloc(2);
-    subCmd.writeUInt16BE(CMD.SINGLE_ZONE_BYPASS_WRITE);
+  /**
+   * Build EXIT_CONFIGURATION_MODE (0x0701)
+   * Wire format: [Partition VarBytes]
+   * @param {number} partition - Partition number (1-8)
+   */
+  buildExitConfigMode(partition) {
+    const payload = this.encodeVarBytes(partition);
+    this.log(`[Session] EXIT_CONFIG_MODE: partition=${partition}`);
+    return this.buildCommand(CMD.CONFIG_EXIT, payload);
+  }
 
+  /**
+   * Build SINGLE_ZONE_BYPASS_WRITE (0x074A) — sent directly inside config mode.
+   * Wire format: [Partition VarBytes][ZoneNumber VarBytes][BypassState 1B]
+   * @param {number} partition - Partition number (1-8)
+   * @param {number} zone - Zone number
+   * @param {boolean} bypass - true to bypass, false to unbypass
+   */
+  buildZoneBypass(partition, zone, bypass) {
     const payload = Buffer.concat([
-      this.encodeByteArray(bcdCode),       // AccessCode as ByteArray (VarBytes length + data)
-      subCmd,                               // SubCommand = 0x074A
-      this.encodeByteArray(innerPayload),   // Data as ByteArray
+      this.encodeVarBytes(partition),
+      this.encodeVarBytes(zone),
+      Buffer.from([bypass ? 0x01 : 0x00]),
     ]);
 
-    this.log(`[Session] ZONE_BYPASS via 0x0703: partition=${partition}, zone=${zone}, bypass=${bypass}`);
-
-    // 0x0703 has no AppSeqNum — send without appSequence
-    this.localSequence = (this.localSequence + 1) & 0xFF;
-    const message = buildHeader(
-      this.localSequence,
-      this.remoteSequence,
-      CMD.CONFIG_ACCESS_CODE_WRAPPER,
-      null,  // No appSequence for 0x0703
-      payload
-    );
-    return this.buildPacket(message);
+    this.log(`[Session] ZONE_BYPASS 0x074A: partition=${partition}, zone=${zone}, bypass=${bypass}`);
+    return this.buildCommand(CMD.SINGLE_ZONE_BYPASS_WRITE, payload);
   }
 
   /**