sgentry / elkmon Goto Github PK

Module for interacting with Elk M1 security panel

License: MIT License

TypeScript 100.00%

elkmon's Introduction

elkmon

elkmon is a module for interfacing with the Elk M1 security and automation control system.

Not all features have been implemented. This is something I have been experimenting with in my free time. I don't have a thermostat integrated with my home system so I haven't implemented those commands yet. However, a Thermostat Reply Message (TR) will be parsed.

Note: For users upgrading to version 1.0.0 from an earlier version, please be aware that there was a bug where the Physical and Logical status, for a zone, was incorrectly swapped. This has been fixed in version 1.0.0.

Features

Supports both secure and non-secure communication with Elk M1XEP

All received messages are parsed into an ElkMessage

Example

  {
    message: '1EAS000000001111111100000000000E', // Full message
    body: '00000000111111110000000000', // Parsed message
    type: 'AS', // Type of message
    hexLength: '1E',
    checkSum: '0E'
  }

Some messages are parsed into a specific message type. For example, ZoneStatusReport (ZS) which includes an array of zones:

{
  message: 'D6ZS33333333333333303333000000000000333300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034',
  body: '333333333333333033330000000000003333000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
  type: 'ZS',
  hexLength: 'D6',
  checkSum: '34',
  zones:
    [
      { id: 1, physicalStatus: 'Short', logicalState: 'Normal' },
      { id: 2, physicalStatus: 'Short', logicalState: 'Normal' },
      ...
    ]
}

Events are emitted when messages are received. You can listen for all (*) or by type (KC, ZD, ZC, etc).
Requests for data return a Promise and can be chained together.

Example Usage

var Elk = require('elkmon');

// Instantiate a new Elk instance (non-secure)
var elk = new Elk(
  2101, // port
  '192.168.1.100' // M1XEP address
);

// Register any event handlers
elk.on('connected', () => {
  console.log('***connected***');

  // Request arming status report
  elk.requestArmingStatus()
    .then((report) => {
      console.log(report.areas);
      // Request zones status report
      return elk.requestZoneStatusReport()
    })
    .then((report) => {
      console.log(report.zones);
      elk.speak('all clear');
  });
});

// Listen for all messages
elk.on('*', (message) => {
  console.log(message);
});

// Listen for messages by type (Zone Change)
elk.on('ZC', (message) => {
  console.log('Zone Change Report: ', message);
});

elk.connect();

// Instantiate a secure instance
var elk = new Elk(
  2601,
  '192.168.1.100', {
    secure: true,
    userName: 'SomeUser',
    password: 'YourPassword',
    keypadCode: 'YourPin',
    rejectUnauthorized: false,
    secureProtocol: 'TLSv1_method'
  }
);

API

connect()

Connects to M1XEP.

disconnect()

Closes connection to M1XEP.

arm(areaId, armMode, keypadCode)

Arm Elk in specified arming mode

disarm(areaId, keypadCode)

Disarm Elk

activateTask(taskId)

Activates a task

setOutputOn(outputId, seconds)

Turns an output on

setOutputOff(outputId)

Turns an output off

speak(message)

Command Elk panel to speak a message over it's speaker.

toggleOutput(outputId)

Toggles a control Output On/Off.

requestOutputStatusReport([timeout])

Request the Control Output Status report from Elk panel.

bypassZone(zoneId, areaId, keypadCode)

Bypass a Zone.

requestArmingStatus([timeout])

Requests an Arming Status Report.

requestAreas([timeout])

Request Keypad Area assignments

requestZoneDefinitionReport([timeout])

Requests a Zone Definition Report.

requestZonePartitionReport([timeout])

Requests a Zone Partition Report.

requestZoneVoltageReport(id, [timeout])

Requests a Zone Voltage Report.

requestZoneStatusReport([timeout])

Requests a Zone Status Report.

requestTextDescription(id, type, [timeout])

Requests a text description.

requestTextDescriptionAll(type)

Requests the configured Text Descriptions, by type.

elkmon's People

Contributors

Stargazers

Watchers

Forkers

j3rm paulw11

elkmon's Issues

SD reponse not parsed correctly

The SD response is not decoded correctly. It ignores the first digit of the zone which causes an infinite loop retrieving all zone texts where the panel has a zone >99.

Reconnect timeout needed (or eliminate reconnects)

A reconnect is attempted on a ECONNRESET without any throttling, causing a potential DOS of the elk device. This is causing downstream issues seen in homebridge-elkm1.

paulw11/homebridge-elkm1#35

I'm not sure, based on other use cases for elkmon, whether a throttle or a removal of the single use case retry would be better, but it should be consistent across errors and have a way to prevent overloading the device. Even adding a 5 second timeout before the retry would prevent most negative effects.

    // error event handler
    this.connection.on('error', (err) => {
      if (err.code === 'ECONNREFUSED') {
        this.emit('error', 'Connection to M1XEP failed!');
      } else if (err.code === 'ECONNRESET') {
        this.emit('error', err.code);
        // connection was reset, attempt to reconnect
        if (this.connection) {
          this.connection.destroy();
        }
        this.connect();
      } else {
        this.emit('error', err.code);
      }
    });

Version 1.2.4 doesn't include fix for #7

When installed via npm version 1.2.4 is installed but the index.js file that is installed does not include the latest code that fixed #7.

I suspect that there was some error in the commits prior to the npm publish

Transposition of "physical state" vs "logical state"

It seems like the physical state and logical state reported in the zoneChangeUpdate (and other zone-related messages) are reversed. The physical state should refer to the electrical state of the zone (open, shorted, EOL) while the logical state is the state of the zone in terms of the alarm (Normal, bypassed, violated).

For example, for a zone of type NC, a physical state of "Open" is a logical state of "Violated" while for an NO zone a physical state of "Open" is logical state of "Normal".

I realise that addressing this is a "breaking change", so I am not sure if you want to action it.

Connecting bug getting UnhandledPromiseRejectionWarning when using example code

While running example code with the following configuration
var elk = new Elk(
2601, // port
'192.168.39.6',
{
secure: true,
rejectUnauthorized: false,
secureProtocol: 'TLSv1_method'
}
);

I am getting UnhandledPromiseRejectionWarning even though connection appears to be successful.
connected
(node:7967) UnhandledPromiseRejectionWarning: Timout occured before Arming Status (as) was received.
(node:7967) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:7967) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

requestTextDescriptionAll times out on low power devices

When running on a Raspberry Pi, requestTextDescriptionAll times out when retrieving large amounts of text and there is no parameter to specify a larger timeout.

cn message formatted incorrectly

The time delay in the control output on (cn) message should be zero padded to 5 digits.

The lack of padding causes the output to turn off after 90 seconds or so when it should remain on.

Add Support for Zwave Lights & Thermostats

Hi,
I am a fellow developer, but JS/Node.js is not one of my languages. I'd like to help further this project by providing a environment to test these new features. If thats not something your interested in doing, I will attempt to add the features and add a pull request. Please let me know. Thanks