dsc-itv2-client 2.0.1 → 2.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsc-itv2-client",
   "author": "fajitacat",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "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,108 @@ 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');
     }
 
+    // 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.
+
     /**
      * 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 +637,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 +1316,26 @@ 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'}`);
+                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/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,10 @@ 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;
       }
 

package/src/itv2-session.js

@@ -97,6 +97,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 +1193,51 @@ export class ITv2Session {
     return this.buildCommand(CMD.PARTITION_DISARM, payload);
   }
 
+  /**
+   * 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.
+   * @param {number} partition - Partition number (1-8)
+   * @param {number} zone - Zone number
+   * @param {boolean} bypass - true to bypass, false to unbypass
+   * @param {string} accessCode - Master/user code (e.g., "1234")
+   */
+  buildZoneBypass(partition, zone, bypass, accessCode) {
+    // Inner 0x074A payload: [Partition VarBytes][ZoneNumber VarBytes][BypassState 1B]
+    const innerPayload = Buffer.concat([
+      this.encodeVarBytes(partition),
+      this.encodeVarBytes(zone),
+      Buffer.from([bypass ? 0x01 : 0x00]),
+    ]);
+
+    // Access code in BCD format
+    const bcdCode = this._encodeBcd(accessCode);
+
+    // 0x0703 payload (no AppSeqNum): [AccessCode ByteArray][SubCommand 2B BE][Data ByteArray]
+    const subCmd = Buffer.alloc(2);
+    subCmd.writeUInt16BE(CMD.SINGLE_ZONE_BYPASS_WRITE);
+
+    const payload = Buffer.concat([
+      this.encodeByteArray(bcdCode),       // AccessCode as ByteArray (VarBytes length + data)
+      subCmd,                               // SubCommand = 0x074A
+      this.encodeByteArray(innerPayload),   // Data as ByteArray
+    ]);
+
+    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);
+  }
+
   /**
    * Build command output activation (PGM trigger)
    * @param {number} partition - Partition number