dsc-itv2-client 1.0.29 → 2.0.0

package/README.md

@@ -1,21 +1,18 @@
 # 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.
+Reverse engineered, completely unofficial Node.js library for communicating with DSC alarm panels (Neo series) using the ITV2 protocol over TL280/TL280E communicators. Zero external dependencies - uses only Node.js built-ins.
 
-## Features
-
-**Event-Driven Architecture** - Subscribe to zone changes with EventEmitter
-
-**Full Protocol Implementation** - Complete ITV2 handshake with Type 1 and 2 encryption
-
-**Real-Time Notifications** - Automatic zone status updates from panel
+Not affiliated with DSC, Johnson Controls, or Tyco in any way. Use at your own risk.
 
-**Partition Control** - Arm and disarm partitions
-
-**Encrypted Communication** - AES-128-ECB with dynamic key exchange
+## Features
 
-**Auto-Reconnect** - Graceful handling of disconnections
+- **Real-Time Zone Monitoring** - Open/close, tamper, alarm, bypass events via push notifications
+- **Partition Control** - Arm stay/away/night, disarm with real-time confirmation
+- **Async Status Querying** - Query zone status, partition status, system capabilities on demand
+- **Trouble Detail Parsing** - Human-readable trouble notifications from official SDK enums
+- **Encrypted Communication** - AES-128-ECB with automatic Type 1/Type 2 key exchange
+- **Event-Driven Architecture** - Subscribe to events with EventEmitter
+- **Automatic Session Setup** - Capabilities query, initial status pull, heartbeat keepalive
 
 ## Quick Start
 
@@ -25,64 +22,54 @@ Not affiliated with DSC or DSC Alarm in any way, shape or form. Use at your own
 npm install dsc-itv2-client
 ```
 
-### Basic Zone Monitoring
+### Basic Usage
 
 ```javascript
 import { ITV2Client } from 'dsc-itv2-client';
 
 const client = new ITV2Client({
-  integrationId: '250228754543',
-  accessCode: '28754543',
-  port: 3073
+  integrationId: '250228754543',  // Section [851][422]
+  accessCode: '28754543',         // Section [851][423]
+  masterCode: '5555',             // User code for arm/disarm
+  port: 3072,                     // TCP port (panel connects to us)
 });
 
-// Subscribe to events
-client.on('session:established', () => {
-  console.log('Connected to panel!');
+client.on('session:established', () => console.log('Connected!'));
+client.on('zone:open', (zone) => console.log(`Zone ${zone} opened`));
+client.on('zone:closed', (zone) => console.log(`Zone ${zone} closed`));
+client.on('partition:arming', ({ partition, modeName }) => {
+  console.log(`Partition ${partition}: ${modeName}`);
 });
 
-client.on('zone:open', (zoneNumber) => {
-  console.log(`Zone ${zoneNumber} opened`);
-});
+// Status is automatically queried on connect
+client.on('status:ready', async ({ zones, partition }) => {
+  console.log(`${zones.length} zones loaded`);
 
-client.on('zone:closed', (zoneNumber) => {
-  console.log(`Zone ${zoneNumber} closed`);
+  // Query on demand anytime
+  const current = await client.queryZoneStatus();
+  const part = await client.queryPartitionStatus(1);
 });
 
-// Start listening
 await client.start();
 ```
 
-### Arm/Disarm Control
+### Arm/Disarm
 
 ```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');
+client.armStay(1, '5555');   // Arm partition 1 in stay mode
+client.armAway(1, '5555');   // Arm partition 1 in away mode
+client.armNight(1, '5555');  // Arm partition 1 in night mode
+client.disarm(1, '5555');    // Disarm partition 1
 ```
 
-## Examples
-
-Run the included examples:
+### Examples
 
 ```bash
-# Basic zone monitoring
-npm run example:basic
-
-# Arm/disarm control
-npm run example:control
-
-# Full interactive CLI
-npm run example:cli
+npm run example:basic      # Zone monitoring
+npm run example:control    # Arm/disarm demo
+npm run example:cli        # Interactive CLI with querying
 ```
 
-See [src/examples/README.md](src/examples/README.md) for detailed examples and usage.
-
 ## API Reference
 
 ### Constructor
@@ -91,256 +78,191 @@ See [src/examples/README.md](src/examples/README.md) for detailed examples and u
 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'
-});
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `integrationId` | string | required | 12-digit panel integration ID (section [851][422]) |
+| `accessCode` | string | required | 8-digit code (section [851][423]) or 32-hex (section [851][700]) |
+| `masterCode` | string | `'5555'` | User code for arm/disarm operations |
+| `port` | number | `3072` | TCP port to listen on (panel connects to us) |
+| `logLevel` | string | `'minimal'` | `'silent'`, `'minimal'`, or `'verbose'` |
+| `encryptionType` | number | `null` | `null` = auto-detect, `1` = Type 1, `2` = Type 2 |
 
 ### 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 |
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `start()` | `Promise` | Start TCP server, wait for panel connection |
+| `stop()` | `Promise` | Send END_SESSION, close connection |
+| `armStay(partition, code)` | void | Arm partition in stay mode |
+| `armAway(partition, code)` | void | Arm partition in away mode |
+| `armNight(partition, code)` | void | Arm partition in night mode |
+| `armNoEntryDelay(partition, code)` | void | Arm with no entry delay |
+| `disarm(partition, code)` | void | Disarm partition |
+| `queryCapabilities()` | `Promise<object>` | Query system capabilities (max zones, partitions) |
+| `queryZoneStatus()` | `Promise<Array>` | Query all zone statuses |
+| `queryPartitionStatus(n)` | `Promise<object>` | Query partition status |
+| `queryTroubleStatus()` | `Promise<Array>` | Query system troubles |
+| `getZones()` | `Array` | Get cached zone states |
+| `getPartitions()` | `Array` | Get cached partition states |
 
 ### Events
 
-#### Session Events
+#### Session
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `listening` | `{ address, port }` | UDP server started |
+| `listening` | `{ address, port }` | TCP server started |
 | `session:connecting` | - | Panel initiated connection |
-| `session:established` | `{ encryptionType, sendKey, recvKey }` | Handshake complete |
+| `session:established` | `{ encryptionType, sendKey, recvKey }` | Encrypted session active |
+| `session:ready` | - | Initial notification burst complete |
+| `status:ready` | `{ zones, partition, capabilities }` | Initial status pull done |
 | `session:closed` | - | Session ended |
-| `session:error` | `Error` | Handshake failed |
 
-#### Zone Events
+#### Zone
 
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `zone:open` | `zoneNumber` | Zone opened |
 | `zone:closed` | `zoneNumber` | Zone closed |
-| `zone:status` | `zoneNumber, status` | Full zone status |
+| `zone:status` | `zoneNumber, statusObject` | Full zone status update |
 
-**Status Object:**
+Zone status object:
 ```javascript
-{
-  open: boolean,
-  tamper: boolean,
-  fault: boolean,
-  lowBattery: boolean,
-  delinquency: boolean,
-  alarm: boolean,
-  alarmInMemory: boolean,
-  bypassed: boolean,
-  statusByte: number
-}
+{ open, tamper, fault, lowBattery, delinquency, alarm, alarmInMemory, bypassed, rawStatus }
 ```
 
-#### Partition Events
+#### Partition
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `partition:armed` | `partition, mode` | Partition armed |
-| `partition:disarmed` | `partition` | Partition disarmed |
+| `partition:arming` | `{ partition, armMode, modeName, method }` | Arming state changed |
+| `partition:ready` | `{ partition, isReady }` | Partition ready state |
+| `partition:trouble` | `{ partition, troubleFlags }` | Partition trouble |
 
-#### Error Events
+#### Trouble
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `error` | `Error` | General error |
-| `command:error` | `{ code, message, rawData }` | Panel rejected command |
+| `trouble:detail` | `Array<TroubleRecord>` | Detailed trouble notification |
 
-## 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.
+Trouble record:
+```javascript
+{ deviceType, deviceTypeName, deviceNumber, troubleType, troubleTypeName, troubleState, troubleStateName }
+```
 
-**Default:** `250228754543`
+#### Error
 
-#### 2. Access Code (Section [423] for Type 1)
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `error` | `Error` | General error |
+| `command:error` | `{ failedCommand, nackCode, message }` | Panel NACK response |
 
-An 8-digit numeric code used for encryption key derivation in Type 1 encryption.
+## Panel Configuration
 
-**Default:** `28754543`
+### TL280/TL280E Setup
 
-#### 3. Integration Access Code (Section [700] for Type 2)
+Reference: [Johnson Controls TL280 Configuration Guide](https://docs.johnsoncontrols.com/dsc/api/khub/documents/TBs~T4HbUlFAb5fFkKsJGQ/content)
 
-A 32-digit hexadecimal code used for Type 2 encryption. Less common than Type 1.
+#### 1. Enable Alternate Communicator
 
-**Example:** `25022875250228752502287525022875`
+**Section 382** - Enable option 5 (Alternate Communicator). Use star key to toggle. Hash back once.
 
-#### 4. Integration Polling Port (Section [430])
+**Section 300** - Receiver 1: set to Alternate Com Receiver 1. Hash back once.
 
-The UDP port where your server listens for panel connections.
+**Section 380** - Ensure comms are enabled (should be on by default). Hash once.
 
-**Default:** `3073` (0x0C01)
+**Section 310** - Enter a 4-digit system account code. Scroll right and enter the same matching code in the partition account code. Hash back once.
 
-### TL280R Communicator Setup
+#### 2. Configure Communicator (Section 851)
 
-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)
+**Network Settings:**
+- For static IP: enter sections 001, 002, 003, 007, and 008
+- For DHCP: skip to section 005
 
-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
+**851 > 005** - Enable option 3 (option 6 should already be enabled). Hash once.
 
-4. **Test connection:**
-   - TL280R should initiate connection to your server
-   - Panel will send OPEN_SESSION to start handshake
+**851 > 010** - Enable video verification (good practice even if not using it).
 
-### Finding Your Panel Configuration
+**851 > 100** - Turn on option 2.
 
-If you don't know your Integration ID and Access Code:
+**851 > 104** - Verify it reads 0BF5.
 
-- **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)
+#### 3. Integration Settings
 
-### Network Requirements
+**851 > 425** - Enable options 3 and 5.
 
-- **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
+**851 > 426** - Turn on option 3 (required for real-time notifications).
 
-### Encryption Type Detection
+**851 > 428** - Enter your server IP address (the machine running this library).
 
-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.
+**851 > 422** - Read the 12-digit Integration ID (two groups of 6 digits, written in blocks of 3). Scroll 6 times right for the second group. This is your `integrationId`.
 
-## Protocol Notes
+**851 > 423** - Read the 8-digit Access Code. This is your `accessCode`.
 
-### Push Notification Model
+**851 > 101** - Enter a unique identifier.
 
-The DSC panel uses **push notifications**, not query/response:
+#### 4. Reboot Communicator
 
-- ✅ 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
+**851 > 999** - Enter 55 to reboot the communicator. Hash out 3 times. A trouble condition on the keypad is normal during reboot.
 
-### Session Establishment
+### Network Requirements
 
-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
+- **TCP port 3072** must be reachable from the panel to your server
+- Panel and server must be on the same network (or routable)
+- Static IP recommended for the server
+- The panel initiates the TCP connection to your server (outbound from panel)
 
-### Tested On
+### Finding Your Credentials
 
-- DSC TL280R Communicator
-- DSC Neo Panel (firmware 2905)
-- Protocol version 6202
+If the panel is already configured, enter installer programming (*8 + installer code) and read:
+- **Section [851][422]** — Integration ID (12 digits)
+- **Section [851][423]** — Access Code (8 digits, Type 1)
+- **Section [851][700]** — Integration Access Code (32 hex, Type 2)
 
 ## Configuration
 
-Use environment variables to configure:
+Use environment variables:
 
 ```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
+PORT=3072 \
+LOG_LEVEL=minimal \
 npm run example:cli
 ```
 
 ## Troubleshooting
 
-### No zone events
+### Panel won't connect
 
-- Panel only sends notifications when zones **change state**
-- Open/close a door or window to trigger notifications
-- Ensure session is established first
+- Verify server IP is set correctly in section [851][428]
+- Ensure TCP port 3072 is open in firewall
+- Check panel and server are on the same network
+- Reboot communicator: section [851][999], enter 55
 
 ### 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
+- Verify `integrationId` matches section [851][422]
+- Verify `accessCode` matches section [851][423]
+- Enable `logLevel: 'verbose'` for full protocol details
+
+### Zone queries fail
+
+- System capabilities must be queried first (automatic on connect)
+- Zone count must match panel's actual zone count (automatic when using `queryZoneStatus()`)
+
+### Arm/disarm not working
+
+- Verify `masterCode` is a valid user code on the panel
+- Check partition number is correct (usually 1)
+- Panel sends confirmation via `partition:arming` event
 
-### Authentication/command errors
+## Tested On
 
-- Verify `masterCode` is correct
-- Panel may require specific access codes
-- Some commands may not be supported by all panel firmware versions
+- DSC Neo Panel (HS2032/HS2064/HS2128)
+- TL280/TL280E Communicator
+- Type 1 encryption (most common)
 
 ## License
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsc-itv2-client",
   "author": "fajitacat",
-  "version": "1.0.29",
-  "description": "Reverse engineered DSC ITV2 Protocol Client Library for TL280R Communicator - Monitor and control DSC alarm panels",
+  "version": "2.0.0",
+  "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",
   "exports": {
@@ -31,7 +31,8 @@
     "itv2",
     "alarm",
     "security",
-    "tl280r",
+    "tl280",
+    "tl280e",
     "event-emitter",
     "monitoring",
     "home-automation",