dsc-itv2-client 2.0.1 → 2.0.4

package/package.json

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

@@ -218,49 +218,221 @@ export class ITV2Client extends EventEmitter {
         this.emit('session:closed');
     }
 
+    /**
+     * Send an arm/disarm command and wait for confirmation.
+     * Resolves when partition:arming or partition:exitDelay event arrives.
+     * Rejects on timeout (panel silently refused, e.g. open zones).
+     * @returns {Promise<object>} The arming/exitDelay event data
+     */
+    async _sendArmCommand(packet, partition, expectedMode, timeout = 5000) {
+        if (!this._checkEstablished()) {
+            throw new Error('Session not established');
+        }
+
+        // Wait for arming/exitDelay confirmation
+        try {
+            return await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { cleanup(); reject(new Error('timeout')); }, timeout);
+
+                const onArming = (data) => {
+                    if (data.partition === partition) { cleanup(); resolve(data); }
+                };
+                const onDelay = (data) => {
+                    if (data.partition === partition) { cleanup(); resolve(data); }
+                };
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    this.removeListener('partition:arming', onArming);
+                    this.removeListener('partition:exitDelay', onDelay);
+                };
+
+                this.on('partition:arming', onArming);
+                this.on('partition:exitDelay', onDelay);
+                this._sendPacket(packet);
+            });
+        } catch (e) {
+            if (e.message !== 'timeout') throw e;
+
+            // No confirmation — query partition status to check current state
+            try {
+                const status = await this.queryPartitionStatus(partition);
+                if (status) {
+                    const state = status.awayArmed ? 'AWAY' :
+                        status.stayArmed ? 'STAY' :
+                        status.nightArmed ? 'NIGHT' :
+                        status.armed ? 'ARMED' : 'DISARMED';
+
+                    // If already in the requested state, treat as success
+                    if (state === expectedMode) {
+                        return { partition, modeName: state, fromQuery: true };
+                    }
+                }
+            } catch (_) {}
+
+            throw new Error('Arm/disarm not confirmed - panel may have open zones or troubles');
+        }
+    }
+
     /**
      * Arm partition in stay mode (mode 1)
+     * @returns {Promise} Resolves with arming confirmation, rejects if panel refuses
      */
     armStay(partition, code) {
-        if (!this._checkEstablished()) return;
         const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.STAY, code || this.masterCode);
-        this._sendPacket(packet);
+        return this._sendArmCommand(packet, partition, 'STAY');
     }
 
     /**
      * Arm partition in away mode (mode 2)
+     * @returns {Promise} Resolves with arming confirmation, rejects if panel refuses
      */
     armAway(partition, code) {
-        if (!this._checkEstablished()) return;
         const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.AWAY, code || this.masterCode);
-        this._sendPacket(packet);
+        return this._sendArmCommand(packet, partition, 'AWAY');
     }
 
     /**
      * Arm partition in night mode (mode 4)
+     * @returns {Promise} Resolves with arming confirmation, rejects if panel refuses
      */
     armNight(partition, code) {
-        if (!this._checkEstablished()) return;
         const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.NIGHT, code || this.masterCode);
-        this._sendPacket(packet);
+        return this._sendArmCommand(packet, partition, 'NIGHT');
     }
 
     /**
      * Arm partition with no entry delay (mode 3)
+     * @returns {Promise} Resolves with arming confirmation, rejects if panel refuses
      */
     armNoEntryDelay(partition, code) {
-        if (!this._checkEstablished()) return;
         const packet = this.session.buildPartitionArm(partition, ITv2Session.ARM_MODE.NO_ENTRY_DELAY, code || this.masterCode);
-        this._sendPacket(packet);
+        return this._sendArmCommand(packet, partition, 'ARMED');
+    }
+
+    /**
+     * 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
+     * @returns {Promise} Resolves with disarm confirmation, rejects if panel refuses
      */
     disarm(partition, code) {
-        if (!this._checkEstablished()) return;
         const packet = this.session.buildPartitionDisarm(partition, code || this.masterCode);
-        this._sendPacket(packet);
+        return this._sendArmCommand(packet, partition, 'DISARMED');
     }
 
     // ==================== Status Query Methods ====================
@@ -578,6 +750,9 @@ export class ITV2Client extends EventEmitter {
             case CMD.NOTIFICATION_PARTITION_TROUBLE:
                 this._handlePartitionTroubleNotification(parsed);
                 break;
+            case CMD.SINGLE_ZONE_BYPASS_STATUS:
+                this._handleZoneBypassNotification(parsed);
+                break;
             case CMD.MULTIPLE_MESSAGE:
                 this._handleMultipleMessagePacket(parsed);
                 break;
@@ -1254,6 +1429,32 @@ export class ITV2Client extends EventEmitter {
 
     // ==================== Notification Handlers ====================
 
+    _handleZoneBypassNotification(parsed) {
+        // 0x0820 SingleZoneBypassStatus (from neohub):
+        // [CompactInt:ZoneNumber][BypassState:1B]  (0=not bypassed, 1=bypassed)
+        const fullPayload = this._reconstructPayload(parsed);
+        if (fullPayload && fullPayload.length >= 3) {
+            try {
+                let offset = 0;
+                const zone = ITv2Session.decodeVarBytes(fullPayload, offset);
+                offset += zone.bytesRead;
+                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}`);
+            }
+        }
+        this._ack();
+    }
+
     _handleExitDelayNotification(parsed) {
         // 0x0230 NotificationExitDelay (from neohub):
         // [CompactInt:Partition][DelayFlags:1B][CompactInt:DurationInSeconds]

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

@@ -76,6 +76,23 @@ client.on('partition:ready', ({ partition, isReady }) => {
   prompt();
 });
 
+client.on('zone:bypass', ({ zone, bypassed }) => {
+  console.log(`\n  Zone ${zone}: ${bypassed ? 'BYPASSED' : 'UNBYPASSED'}`);
+  prompt();
+});
+
+client.on('partition:exitDelay', ({ partition, duration, active }) => {
+  if (active) console.log(`\n  Partition ${partition}: exit delay ${duration}s`);
+  prompt();
+});
+
+client.on('trouble:detail', (troubles) => {
+  for (const t of troubles) {
+    console.log(`\n  Trouble: ${t.deviceTypeName} #${t.deviceNumber}: ${t.troubleTypeName} (${t.troubleStateName})`);
+  }
+  prompt();
+});
+
 // command:error events are protocol-level noise (intermediate acks), not actionable
 
 client.on('error', (err) => {
@@ -145,13 +162,14 @@ rl.on('line', async (line) => {
 
       case 'trouble':
       case 't': {
-        const troubles = await client.queryTroubleStatus();
-        if (!troubles || troubles.length === 0) {
-          console.log('No active troubles');
+        // Trouble detail comes from 0x0823 notifications (not queryable)
+        // Check partition status for trouble flag
+        const ps = await client.queryPartitionStatus(1);
+        if (ps && ps.trouble) {
+          console.log('Partition 1 has active troubles');
+          console.log('(Detailed trouble info arrives via 0x0823 notifications - see trouble:detail event)');
         } else {
-          for (const t of troubles) {
-            console.log(`  Device ${t.deviceType}: troubles [${t.troubles.join(', ')}]`);
-          }
+          console.log('No active troubles on partition 1');
         }
         break;
       }
@@ -179,7 +197,10 @@ rl.on('line', async (line) => {
         const part = parseInt(args[0] || '1');
         const code = args[1] || config.masterCode;
         console.log(`Arming partition ${part} STAY...`);
-        client.armStay(part, code);
+        try {
+          const r = await client.armStay(part, code);
+          console.log(r.duration ? `Exit delay: ${r.duration}s` : `Partition ${part}: ${r.modeName}`);
+        } catch (e) { console.log(e.message); }
         break;
       }
 
@@ -187,7 +208,10 @@ rl.on('line', async (line) => {
         const part = parseInt(args[0] || '1');
         const code = args[1] || config.masterCode;
         console.log(`Arming partition ${part} AWAY...`);
-        client.armAway(part, code);
+        try {
+          const r = await client.armAway(part, code);
+          console.log(r.duration ? `Exit delay: ${r.duration}s` : `Partition ${part}: ${r.modeName}`);
+        } catch (e) { console.log(e.message); }
         break;
       }
 
@@ -195,7 +219,10 @@ rl.on('line', async (line) => {
         const part = parseInt(args[0] || '1');
         const code = args[1] || config.masterCode;
         console.log(`Arming partition ${part} NIGHT...`);
-        client.armNight(part, code);
+        try {
+          const r = await client.armNight(part, code);
+          console.log(r.duration ? `Exit delay: ${r.duration}s` : `Partition ${part}: ${r.modeName}`);
+        } catch (e) { console.log(e.message); }
         break;
       }
 
@@ -203,7 +230,35 @@ rl.on('line', async (line) => {
         const part = parseInt(args[0] || '1');
         const code = args[1] || config.masterCode;
         console.log(`Disarming partition ${part}...`);
-        client.disarm(part, code);
+        try {
+          const r = await client.disarm(part, code);
+          console.log(`Partition ${part}: ${r.modeName}`);
+        } catch (e) { console.log(e.message); }
+        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;
       }
 
@@ -231,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
@@ -97,6 +98,8 @@ export const CMD = {
   BUS_STATUS: 0x0816,
   TROUBLE_DETAIL: 0x0823,
   DOOR_CHIME_STATUS: 0x0819,
+  SINGLE_ZONE_BYPASS_STATUS: 0x0820,
+  SINGLE_ZONE_BYPASS_WRITE: 0x074A,
   MULTIPLE_MESSAGE: 0x0623,
   // Module Control commands
   PARTITION_ARM: 0x0900,
@@ -1191,6 +1194,59 @@ export class ITv2Session {
     return this.buildCommand(CMD.PARTITION_DISARM, 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} type - Programming type (3 = zone bypass)
+   * @param {string} accessCode - Master/user code (e.g., "1234")
+   * @param {number} mode - Access mode (1 = user code)
+   */
+  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),
+      Buffer.from([type]),
+      this.encodeByteArray(codeBytes),
+      Buffer.from([mode]),
+    ]);
+
+    this.log(`[Session] ENTER_CONFIG_MODE: partition=${partition}, type=${type}, mode=${mode}`);
+    return this.buildCommand(CMD.CONFIG_ENTER, payload);
+  }
+
+  /**
+   * 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.encodeVarBytes(partition),
+      this.encodeVarBytes(zone),
+      Buffer.from([bypass ? 0x01 : 0x00]),
+    ]);
+
+    this.log(`[Session] ZONE_BYPASS 0x074A: partition=${partition}, zone=${zone}, bypass=${bypass}`);
+    return this.buildCommand(CMD.SINGLE_ZONE_BYPASS_WRITE, payload);
+  }
+
   /**
    * Build command output activation (PGM trigger)
    * @param {number} partition - Partition number