dsc-itv2-client 1.0.7

package/README.md

@@ -0,0 +1,342 @@
+# DSC ITV2 Client Library
+
+Reverse engineered, completely unofficial node.js library for communicating with DSC alarm panels using the ITV2 protocol over TL280R communicators.
+Not affiliated with DSC or DSC Alarm in any way, shape or form. Use at your own risk.
+
+## Features
+
+✅ **Event-Driven Architecture** - Subscribe to zone changes with EventEmitter
+✅ **Full Protocol Implementation** - Complete ITV2 handshake with Type 1 encryption
+✅ **Real-Time Notifications** - Automatic zone status updates from panel
+✅ **Partition Control** - Arm and disarm partitions
+✅ **Encrypted Communication** - AES-128-ECB with dynamic key exchange
+✅ **Auto-Reconnect** - Graceful handling of disconnections
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install dsc-itv2-client
+```
+
+### Basic Zone Monitoring
+
+```javascript
+import { ITV2Client } from 'dsc-itv2-client';
+
+const client = new ITV2Client({
+  integrationId: '250228754543',
+  accessCode: '28754543',
+  port: 3073
+});
+
+// Subscribe to events
+client.on('session:established', () => {
+  console.log('Connected to panel!');
+});
+
+client.on('zone:open', (zoneNumber) => {
+  console.log(`Zone ${zoneNumber} opened`);
+});
+
+client.on('zone:closed', (zoneNumber) => {
+  console.log(`Zone ${zoneNumber} closed`);
+});
+
+// Start listening
+await client.start();
+```
+
+### Arm/Disarm Control
+
+```javascript
+// Arm partition in STAY mode
+client.armStay(1, '5555');
+
+// Arm partition in AWAY mode
+client.armAway(1, '5555');
+
+// Disarm partition
+client.disarm(1, '5555');
+```
+
+## Examples
+
+Run the included examples:
+
+```bash
+# Basic zone monitoring
+npm run example:basic
+
+# Arm/disarm control
+npm run example:control
+
+# Full interactive CLI
+npm run example:cli
+```
+
+See [src/examples/README.md](src/examples/README.md) for detailed examples and usage.
+
+## API Reference
+
+### Constructor
+
+```javascript
+const client = new ITV2Client(options);
+```
+
+**Options:**
+- `integrationId` (string) - 12-digit panel integration ID
+- `accessCode` (string) - 8-digit (Type 1) or 32-hex (Type 2) access code
+- `masterCode` (string, optional) - Master code for arm/disarm (default: '5555')
+- `port` (number, optional) - UDP port to listen on (default: 3073)
+- `encryptionType` (number, optional) - null=auto-detect, 1=Type 1, 2=Type 2 (default: null)
+- `logLevel` (string, optional) - 'silent', 'minimal', 'verbose' (default: 'minimal')
+
+#### Encryption Types
+
+**Type 1 (default, most common):**
+```javascript
+new ITV2Client({
+  integrationId: '250228754543',
+  accessCode: '28754543'  // 8-digit code
+});
+```
+
+**Type 2 (for panels requiring 32-hex code):**
+```javascript
+new ITV2Client({
+  integrationId: '250228754543',
+  accessCode: '25022875250228752502287525022875',  // 32-hex code
+  encryptionType: 2  // Optional: auto-detected from panel
+});
+```
+
+#### Log Levels
+
+**'silent'** - No logging output at all
+**'minimal'** (default) - Key events only (session established, zone changes)
+**'verbose'** - Full protocol details including packet dumps and crypto operations
+
+```javascript
+// Minimal logging (default)
+const client = new ITV2Client({
+  integrationId: '...',
+  accessCode: '...'
+});
+
+// Verbose logging for debugging
+const client = new ITV2Client({
+  integrationId: '...',
+  accessCode: '...',
+  logLevel: 'verbose'
+});
+
+// Silent mode
+const client = new ITV2Client({
+  integrationId: '...',
+  accessCode: '...',
+  logLevel: 'silent'
+});
+```
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Start UDP server and wait for panel connection |
+| `stop()` | Gracefully close session and shutdown |
+| `armStay(partition, code)` | Arm partition in STAY mode |
+| `armAway(partition, code)` | Arm partition in AWAY mode |
+| `disarm(partition, code)` | Disarm partition |
+| `getZones()` | Get current zone states |
+| `getPartitions()` | Get current partition states |
+
+### Events
+
+#### Session Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `listening` | `{ address, port }` | UDP server started |
+| `session:connecting` | - | Panel initiated connection |
+| `session:established` | `{ encryptionType, sendKey, recvKey }` | Handshake complete |
+| `session:closed` | - | Session ended |
+| `session:error` | `Error` | Handshake failed |
+
+#### Zone Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `zone:open` | `zoneNumber` | Zone opened |
+| `zone:closed` | `zoneNumber` | Zone closed |
+| `zone:status` | `zoneNumber, status` | Full zone status |
+
+**Status Object:**
+```javascript
+{
+  open: boolean,
+  tamper: boolean,
+  fault: boolean,
+  lowBattery: boolean,
+  delinquency: boolean,
+  alarm: boolean,
+  alarmInMemory: boolean,
+  bypassed: boolean,
+  statusByte: number
+}
+```
+
+#### Partition Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `partition:armed` | `partition, mode` | Partition armed |
+| `partition:disarmed` | `partition` | Partition disarmed |
+
+#### Error Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `error` | `Error` | General error |
+| `command:error` | `{ code, message, rawData }` | Panel rejected command |
+
+## Panel Configuration
+
+To use this library, your DSC panel must be configured with the TL280R communicator module and proper integration settings.
+
+### Required Panel Settings
+
+#### 1. Integration ID (Section [422])
+
+The 12-digit Integration ID identifies your integration to the panel. This must match the `integrationId` in your client configuration.
+
+**Default:** `250228754543`
+
+#### 2. Access Code (Section [423] for Type 1)
+
+An 8-digit numeric code used for encryption key derivation in Type 1 encryption.
+
+**Default:** `28754543`
+
+#### 3. Integration Access Code (Section [700] for Type 2)
+
+A 32-digit hexadecimal code used for Type 2 encryption. Less common than Type 1.
+
+**Example:** `25022875250228752502287525022875`
+
+#### 4. Integration Polling Port (Section [430])
+
+The UDP port where your server listens for panel connections.
+
+**Default:** `3073` (0x0C01)
+
+### TL280R Communicator Setup
+
+1. **Install TL280R module** in your DSC panel
+2. **Configure network settings:**
+   - Set TL280R IP address (static recommended)
+   - Configure your server's IP address as the destination
+   - Set integration polling port (default: 3073)
+
+3. **Configure integration settings:**
+   - Enter Integration ID in section [422]
+   - Enter Access Code in section [423] (Type 1) or [700] (Type 2)
+   - Enable integration polling
+
+4. **Test connection:**
+   - TL280R should initiate connection to your server
+   - Panel will send OPEN_SESSION to start handshake
+
+### Finding Your Panel Configuration
+
+If you don't know your Integration ID and Access Code:
+
+- **Check panel programming:**
+   - Enter installer code (*8 + installer code)
+   - Navigate to integration settings
+   - Section [422] = Integration ID
+   - Section [423] = Access Code (Type 1)
+   - Section [700] = Integration Access Code (Type 2)
+
+### Network Requirements
+
+- **Firewall:** Allow UDP port 3073 inbound
+- **Network:** Panel and server must be on same network (or routable)
+- **Static IP recommended:** For the server running this library
+- **NAT:** If using NAT, configure port forwarding for UDP 3073
+
+### Encryption Type Detection
+
+The library automatically detects whether your panel uses Type 1 or Type 2 encryption.
+You don't need to configure this - it's auto-detected during the handshake.
+
+## Protocol Notes
+
+### Push Notification Model
+
+The DSC panel uses **push notifications**, not query/response:
+
+- ✅ Panel automatically pushes zone status changes (0x0210)
+- ✅ Real-time updates when zones open/close
+- ❌ Cannot query for current status on demand
+- ℹ️  Must wait for panel to send notifications
+
+### Session Establishment
+
+1. Panel sends OPEN_SESSION (plaintext)
+2. Encrypted handshake with REQUEST_ACCESS
+3. Type 1 key exchange (asymmetric encryption keys)
+4. All post-handshake communication uses AES-128-ECB encryption
+
+### Tested On
+
+- DSC TL280R Communicator
+- DSC Neo Panel (firmware 2905)
+- Protocol version 6202
+
+## Configuration
+
+Use environment variables to configure:
+
+```bash
+INTEGRATION_ID=250228754543 \
+ACCESS_CODE=28754543 \
+MASTER_CODE=5555 \
+UDP_PORT=3073 \
+npm run example:basic
+```
+
+## Development
+
+Run the full interactive CLI (includes all commands and debugging features):
+
+```bash
+npm run example:cli
+```
+
+## Troubleshooting
+
+### No zone events
+
+- Panel only sends notifications when zones **change state**
+- Open/close a door or window to trigger notifications
+- Ensure session is established first
+
+### Session won't establish
+
+- Verify `integrationId` and `accessCode` match panel configuration
+- Check panel is configured to connect to your server IP
+- Ensure UDP port 3073 is open in firewall
+- Enable `debug: true` for detailed protocol logs
+
+### Authentication/command errors
+
+- Verify `masterCode` is correct
+- Panel may require specific access codes
+- Some commands may not be supported by all panel firmware versions
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "dsc-itv2-client",
+  "author": "fajitacat",
+  "version": "1.0.7",
+  "description": "Reverse engineered DSC ITV2 Protocol Client Library for TL280R Communicator - Monitor and control DSC alarm panels",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "example:basic": "node src/examples/basic-monitoring.js",
+    "example:control": "node src/examples/arm-disarm-example.js",
+    "example:cli": "node src/examples/interactive-cli.js"
+  },
+  "files": [
+    "src/ITV2Client.js",
+    "src/itv2-session.js",
+    "src/itv2-crypto.js",
+    "src/response-parsers.js",
+    "src/event-handler.js",
+    "src/constants.js",
+    "src/utils.js",
+    "src/index.js",
+    "src/examples/",
+    "README.md"
+  ],
+  "keywords": [
+    "dsc",
+    "neo",
+    "itv2",
+    "alarm",
+    "security",
+    "tl280r",
+    "event-emitter",
+    "monitoring",
+    "home-automation",
+    "alarm-panel",
+    "dsc-alarm"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {}
+}