dsc-itv2-client 1.0.7

package/src/event-handler.js

@@ -0,0 +1,323 @@
+/**
+ * Event Handler for ITV2 Protocol
+ *
+ * Manages zone and partition state based on panel notifications.
+ * The DSC panel uses an event-driven model - status arrives via
+ * unsolicited notifications, not request-responses.
+ */
+
+export class EventHandler {
+  constructor(log = console.log) {
+    this.log = log;
+    this.listeners = new Map();
+    this.zoneStates = new Map();
+    this.partitionStates = new Map();
+    this.systemInfo = {};
+  }
+
+  // ============ Event Listener Management ============
+
+  /**
+   * Register an event listener
+   * @param {string} event - Event name (e.g., 'zone:status', 'partition:armed')
+   * @param {function} callback - Callback function
+   */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event).push(callback);
+  }
+
+  /**
+   * Remove an event listener
+   */
+  off(event, callback) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      const index = callbacks.indexOf(callback);
+      if (index !== -1) {
+        callbacks.splice(index, 1);
+      }
+    }
+  }
+
+  /**
+   * Emit an event to all listeners
+   */
+  emit(event, data) {
+    const callbacks = this.listeners.get(event) || [];
+    callbacks.forEach(cb => {
+      try {
+        cb(data);
+      } catch (err) {
+        this.log(`[EventHandler] Error in listener for ${event}: ${err.message}`);
+      }
+    });
+  }
+
+  // ============ Zone Status Handling ============
+
+  /**
+   * Process zone status notification from panel
+   * @param {number} zoneNum - Zone number
+   * @param {number} statusByte - Status byte from panel
+   * @returns {object} Parsed zone status
+   */
+  handleZoneStatus(zoneNum, statusByte) {
+    const status = {
+      zoneNumber: zoneNum,
+      open: !!(statusByte & 0x01),
+      tamper: !!(statusByte & 0x02),
+      fault: !!(statusByte & 0x04),
+      bypassed: !!(statusByte & 0x08),
+      trouble: !!(statusByte & 0x10),
+      alarm: !!(statusByte & 0x20),
+      lowBattery: !!(statusByte & 0x40),
+      supervisionLoss: !!(statusByte & 0x80),
+      rawStatus: statusByte,
+      timestamp: new Date()
+    };
+
+    const previousState = this.zoneStates.get(zoneNum);
+    this.zoneStates.set(zoneNum, status);
+
+    // Log change
+    this.log(`[Zone ${zoneNum}] Status: ${status.open ? 'OPEN' : 'CLOSED'} ` +
+      `${status.bypassed ? '[BYPASSED]' : ''} ${status.alarm ? '[ALARM]' : ''} ` +
+      `${status.trouble ? '[TROUBLE]' : ''}`);
+
+    // Emit events
+    this.emit('zone:status', status);
+
+    if (previousState && previousState.open !== status.open) {
+      this.emit('zone:change', { zone: zoneNum, wasOpen: previousState.open, isOpen: status.open });
+    }
+
+    if (status.alarm) {
+      this.emit('zone:alarm', status);
+    }
+
+    return status;
+  }
+
+  /**
+   * Process zone alarm notification
+   */
+  handleZoneAlarm(zoneNum, alarmType) {
+    const alarm = {
+      zoneNumber: zoneNum,
+      alarmType: alarmType,
+      timestamp: new Date()
+    };
+
+    this.log(`[Zone ${zoneNum}] ALARM! Type: ${alarmType}`);
+    this.emit('zone:alarm', alarm);
+
+    return alarm;
+  }
+
+  /**
+   * Get current zone state
+   */
+  getZoneState(zoneNum) {
+    return this.zoneStates.get(zoneNum);
+  }
+
+  /**
+   * Get all zones with status
+   */
+  getAllZones() {
+    return Array.from(this.zoneStates.values());
+  }
+
+  /**
+   * Get all open zones
+   */
+  getOpenZones() {
+    return this.getAllZones().filter(z => z.open);
+  }
+
+  // ============ Partition Status Handling ============
+
+  /**
+   * Process partition arming notification
+   * @param {number} partitionNum - Partition number
+   * @param {number} armedState - Armed state code
+   */
+  handlePartitionArming(partitionNum, armedState) {
+    const armedStates = {
+      0x00: 'DISARMED',
+      0x01: 'ARMED_STAY',
+      0x02: 'ARMED_AWAY',
+      0x03: 'ARMED_NIGHT',
+      0x04: 'ARMED_NO_ENTRY',
+      0x05: 'ARMED_FORCE',
+      0x06: 'EXIT_DELAY',
+      0x07: 'ENTRY_DELAY'
+    };
+
+    const status = {
+      partitionNumber: partitionNum,
+      armedState: armedState,
+      armedStateName: armedStates[armedState] || `UNKNOWN(${armedState})`,
+      isArmed: armedState >= 0x01 && armedState <= 0x05,
+      inDelay: armedState === 0x06 || armedState === 0x07,
+      timestamp: new Date()
+    };
+
+    const previousState = this.partitionStates.get(partitionNum);
+    this.partitionStates.set(partitionNum, status);
+
+    this.log(`[Partition ${partitionNum}] ${status.armedStateName}`);
+    this.emit('partition:status', status);
+
+    if (previousState?.armedState !== status.armedState) {
+      this.emit('partition:change', {
+        partition: partitionNum,
+        previousState: previousState?.armedStateName,
+        newState: status.armedStateName
+      });
+    }
+
+    return status;
+  }
+
+  /**
+   * Process partition ready status
+   */
+  handlePartitionReady(partitionNum, isReady) {
+    const existing = this.partitionStates.get(partitionNum) || {};
+    const status = {
+      ...existing,
+      partitionNumber: partitionNum,
+      ready: isReady,
+      timestamp: new Date()
+    };
+
+    this.partitionStates.set(partitionNum, status);
+    this.log(`[Partition ${partitionNum}] ${isReady ? 'READY' : 'NOT READY'}`);
+    this.emit('partition:ready', status);
+
+    return status;
+  }
+
+  /**
+   * Process partition trouble status
+   */
+  handlePartitionTrouble(partitionNum, troubleFlags) {
+    const existing = this.partitionStates.get(partitionNum) || {};
+    const status = {
+      ...existing,
+      partitionNumber: partitionNum,
+      trouble: troubleFlags !== 0,
+      troubleFlags: troubleFlags,
+      timestamp: new Date()
+    };
+
+    this.partitionStates.set(partitionNum, status);
+    if (troubleFlags !== 0) {
+      this.log(`[Partition ${partitionNum}] TROUBLE: 0x${troubleFlags.toString(16)}`);
+      this.emit('partition:trouble', status);
+    }
+
+    return status;
+  }
+
+  /**
+   * Get current partition state
+   */
+  getPartitionState(partitionNum) {
+    return this.partitionStates.get(partitionNum);
+  }
+
+  /**
+   * Get all partitions with status
+   */
+  getAllPartitions() {
+    return Array.from(this.partitionStates.values());
+  }
+
+  // ============ System Info ============
+
+  /**
+   * Store system capabilities
+   */
+  setSystemCapabilities(caps) {
+    this.systemInfo.capabilities = caps;
+    this.emit('system:capabilities', caps);
+  }
+
+  /**
+   * Get system info
+   */
+  getSystemInfo() {
+    return this.systemInfo;
+  }
+
+  // ============ Status Summary ============
+
+  /**
+   * Get complete system status summary
+   */
+  getStatusSummary() {
+    const zones = this.getAllZones();
+    const partitions = this.getAllPartitions();
+
+    return {
+      zones: {
+        total: zones.length,
+        open: zones.filter(z => z.open).length,
+        bypassed: zones.filter(z => z.bypassed).length,
+        alarm: zones.filter(z => z.alarm).length,
+        trouble: zones.filter(z => z.trouble).length,
+        list: zones
+      },
+      partitions: {
+        total: partitions.length,
+        armed: partitions.filter(p => p.isArmed).length,
+        ready: partitions.filter(p => p.ready).length,
+        list: partitions
+      },
+      lastUpdate: new Date()
+    };
+  }
+
+  /**
+   * Print status summary to console
+   */
+  printStatus() {
+    const summary = this.getStatusSummary();
+
+    console.log('\n========================================');
+    console.log('SYSTEM STATUS SUMMARY');
+    console.log('========================================');
+
+    console.log(`\nZones (${summary.zones.total} total):`);
+    if (summary.zones.list.length === 0) {
+      console.log('  No zone status received yet');
+    } else {
+      summary.zones.list.forEach(z => {
+        const flags = [];
+        if (z.open) flags.push('OPEN');
+        if (z.bypassed) flags.push('BYPASSED');
+        if (z.alarm) flags.push('ALARM');
+        if (z.trouble) flags.push('TROUBLE');
+        console.log(`  Zone ${z.zoneNumber}: ${flags.length > 0 ? flags.join(', ') : 'OK'}`);
+      });
+    }
+
+    console.log(`\nPartitions (${summary.partitions.total} total):`);
+    if (summary.partitions.list.length === 0) {
+      console.log('  No partition status received yet');
+    } else {
+      summary.partitions.list.forEach(p => {
+        console.log(`  Partition ${p.partitionNumber}: ${p.armedStateName || 'UNKNOWN'} ${p.ready ? '[READY]' : '[NOT READY]'}`);
+      });
+    }
+
+    console.log('========================================\n');
+  }
+}
+
+export default EventHandler;

package/src/examples/README.md

@@ -0,0 +1,287 @@
+# DSC ITV2 Client - Examples
+
+This directory contains example applications demonstrating how to use the `dsc-itv2-client` library.
+
+## Quick Start
+
+### 1. Basic Zone Monitoring
+
+The simplest example - just monitor when zones open and close:
+
+```bash
+npm run example:basic
+```
+
+**Code:**
+```javascript
+import { ITV2Client } from 'dsc-itv2-client';
+
+const client = new ITV2Client({
+  integrationId: '250228754343',
+  accessCode: '28754543'
+});
+
+client.on('zone:open', (zone) => console.log(`Zone ${zone} opened!`));
+client.on('zone:closed', (zone) => console.log(`Zone ${zone} closed!`));
+
+await client.start();
+```
+
+### 2. Arm/Disarm Control
+
+Interactive example for controlling partitions:
+
+```bash
+npm run example:control
+```
+
+Features:
+- Arm partition in STAY or AWAY mode
+- Disarm partition
+- View current status
+- Real-time zone monitoring
+
+### 3. Full Interactive CLI (server.js)
+
+The original full-featured CLI with all commands:
+
+```bash
+npm run server
+```
+
+## Library Usage
+
+### Installation
+
+```javascript
+import { ITV2Client } from './src/index.js';
+```
+
+### Configuration
+
+```javascript
+const client = new ITV2Client({
+  integrationId: '250228754343',  // Your panel's integration ID
+  accessCode: '28754543',         // 8-digit code (Type 1) or 32-hex (Type 2)
+  masterCode: '5555',             // Master/user code for arm/disarm
+  port: 3073,                     // UDP port (default: 3073)
+  encryptionType: null,           // null=auto-detect, 1=Type 1, 2=Type 2
+  logLevel: 'minimal'             // 'silent', 'minimal', 'verbose'
+});
+```
+
+#### Log Levels
+
+- **'silent'** - No console output
+- **'minimal'** (default) - Key events only (session established, zone changes)
+- **'verbose'** - Full protocol details (packets, crypto, handshake steps)
+
+Use `LOG_LEVEL=verbose` environment variable for debugging.
+
+#### Type 1 vs Type 2 Encryption
+
+**Type 1 (most common):**
+- Uses 8-digit access code: `'28754543'`
+- 48-byte initializer exchange
+- Asymmetric key derivation (panel uses Integration ID, client uses Access Code)
+- Auto-detected from panel's REQUEST_ACCESS
+
+**Type 2 (less common):**
+- Uses 32-hex access code: `'25022875250228752502287525022875'`
+- 16-byte initializer exchange
+- Symmetric key derivation (same transform for both sides)
+- Auto-detected from panel's REQUEST_ACCESS
+
+**Auto-Detection (Recommended):**
+```javascript
+// Leave encryptionType as null (default)
+const client = new ITV2Client({
+  integrationId: '250228754343',
+  accessCode: '28754543'  // Will auto-detect Type 1 or Type 2
+});
+```
+
+**Force Type 2:**
+```javascript
+const client = new ITV2Client({
+  integrationId: '250228754343',
+  accessCode: '25022875250228752502287525022875',  // 32-hex for Type 2
+  encryptionType: 2  // Force Type 2
+});
+```
+
+### Events
+
+#### Session Events
+
+```javascript
+client.on('listening', (address) => {
+  // UDP server is listening
+  console.log(`Listening on ${address.port}`);
+});
+
+client.on('session:connecting', () => {
+  // Panel has initiated connection
+});
+
+client.on('session:established', (info) => {
+  // Handshake complete, session ready
+  // info = { encryptionType, sendKey, recvKey }
+  console.log(`Connected! Using Type ${info.encryptionType} encryption`);
+});
+
+client.on('session:closed', () => {
+  // Session ended
+});
+
+client.on('session:error', (error) => {
+  // Handshake or protocol error
+  console.error(error);
+});
+```
+
+#### Zone Events
+
+```javascript
+client.on('zone:open', (zoneNumber) => {
+  // Zone opened (door/window opened, motion detected, etc.)
+  console.log(`Zone ${zoneNumber} is open`);
+});
+
+client.on('zone:closed', (zoneNumber) => {
+  // Zone closed/restored
+  console.log(`Zone ${zoneNumber} is closed`);
+});
+
+client.on('zone:status', (zoneNumber, status) => {
+  // Full zone status with all flags
+  // status = { open, tamper, fault, lowBattery, delinquency, alarm, alarmInMemory, bypassed }
+  if (status.alarm) {
+    console.log(`ALARM on zone ${zoneNumber}!`);
+  }
+});
+```
+
+#### Partition Events
+
+```javascript
+client.on('partition:armed', (partition, mode) => {
+  // Partition armed (mode: 'stay', 'away', etc.)
+  console.log(`Partition ${partition} armed in ${mode} mode`);
+});
+
+client.on('partition:disarmed', (partition) => {
+  // Partition disarmed
+  console.log(`Partition ${partition} disarmed`);
+});
+```
+
+#### Error Events
+
+```javascript
+client.on('error', (error) => {
+  // General errors
+  console.error('Error:', error.message);
+});
+
+client.on('command:error', (error) => {
+  // Command rejected by panel
+  // error = { code, message, rawData }
+  console.log(`Panel rejected command: ${error.message}`);
+});
+```
+
+### Control Methods
+
+```javascript
+// Arm partition in STAY mode
+client.armStay(partition, code);
+
+// Arm partition in AWAY mode
+client.armAway(partition, code);
+
+// Disarm partition
+client.disarm(partition, code);
+
+// Get current zone states
+const zones = client.getZones();
+// Returns: { '1': { open: false, ... }, '2': { open: true, ... } }
+
+// Get current partition states
+const partitions = client.getPartitions();
+// Returns: { '1': { armedState: 'Disarmed', ready: true, ... } }
+```
+
+### Lifecycle
+
+```javascript
+// Start listening for panel
+await client.start();
+
+// Gracefully close session
+await client.stop();
+```
+
+## Protocol Notes
+
+### Push Notification Model
+
+The DSC panel uses a **push notification** architecture, not query/response:
+
+- ✅ Panel **pushes** zone status changes automatically (0x0210 LIFESTYLE_ZONE_STATUS)
+- ✅ Panel sends keepalive POLL messages every 10 seconds (0x0600)
+- ❌ Status queries (0x0810, 0x0811, 0x0812) are **not supported** by most panels
+- ❌ You cannot query current status - you must wait for notifications
+
+### Session Establishment
+
+1. Panel sends OPEN_SESSION (plaintext)
+2. Client responds with COMMAND_RESPONSE
+3. Handshake exchange (OPEN_SESSION, REQUEST_ACCESS)
+4. Encryption keys exchanged via Type 1 initializers
+5. Session established with AES-128-ECB encryption enabled
+6. All post-handshake communication is encrypted
+
+### Zone Status Values
+
+From 0x0210 notifications:
+- `0` or `1` = Zone CLOSED
+- `2` = Zone OPEN
+
+## Environment Variables
+
+All examples support environment variable configuration:
+
+```bash
+INTEGRATION_ID=250228754343 \
+ACCESS_CODE=28754543 \
+MASTER_CODE=5555 \
+UDP_PORT=3073 \
+DEBUG=true \
+npm run example:basic
+```
+
+## Troubleshooting
+
+### No zone events
+
+- Panel only sends notifications when zones **change state**
+- Try opening/closing a door or window
+- Panel must be connected and session established
+
+### Authentication errors
+
+- Verify `masterCode` is correct
+- Some panels require specific access levels
+- Try with a valid user code instead of master code
+
+### Session won't establish
+
+- Check `integrationId` and `accessCode` match panel configuration
+- Ensure panel is configured to connect to your server IP
+- Check firewall allows UDP port 3073
+- Use `debug: true` to see detailed protocol messages
+
+##Further Reading
+
+For the full handshake implementation and protocol details, see the main `server.js` file which contains the complete CLI application with all debugging output.