elk-message
v1.1.0
Published
A message parsing and generation library for the Elk M1 security system ASCII protocol
Downloads
20
Readme
elk-message
A module for parsing and generating messages for the Elk M1 security system.
Fully* implements the Elk M1 RS232 ASCII protocol revision 1.84 (Feb 26, 2016).
*Section 4.3 describes a message called "Send ASCII String To IP Address", with the command "AP". Upper-case commands are supposed to be responses from the M1, but the documentation for this makes it sound like this is a command that can be sent to the M1. I've decided to include it as a response, but haven't fully implemented it because of the unclear documentation.
Usage
Install with NPM or Yarn
npm install elk-message
// or
yarn add elk-messageimport {
Arm,
ArmingLevel,
EthernetModuleTest,
UnknownElkResponse,
parse,
} from 'elk-message';
// Parse a message
const message = parse('16XK2636115020605110006F\r\n');
if (message instanceof EthernetModuleTest) {
// EthernetModuleTest is sent every 30 seconds by the M1
console.log(`M1 ping @ ${message.date}`);
} else if (message instanceof UnknownElkResponse) {
console.warn(`Recieved unknown command "${message.command}" from M1!`);
}
// Create a message to arm area 1 using code "3456"
const arm = new Arm(ArmingLevel.ArmedAway, 1, '3456');API
The base interface for all messages sent to or received from the Elk M1 implement ElkMessage.
Messages are either "commands" (ElkCommand) sent to the control panel, or "responses"
(ElkResponse) received from it.
See the API documentation for more details on each type of message. Each message in the documentation also includes the section in the protocol specification document where it is officially documented.
Commands
Commands are instantiated directly with specific parameters depending on the type of command. Some commands expect the control panel to return a response, others do not.
AlarmByZoneRequestAlarmReportAcknowledgeAlarmReportTestAcknowledgeArmArmingStatusRequestAudioCommandIncomingAudioDataRequestControlOutputOffControlOutputOnControlOutputStatusRequestControlOutputToggleCounterValueReadCounterValueWriteCustomValueReadCustomValueWriteCustomValuesReadAllDisplayTextOnScreenElkCommandEthernetModuleTestAcknowledgeInsteonLightingDeviceProgramRequestInsteonLightingDeviceStatusRequestKeypadAreaAssigmentsRequestKeypadFunctionKeyPressRequestKeypadFunctionKeyStatusRequestLightingDeviceStatusRequestOmnistat2RequestPlcDeviceControlPlcDeviceOffPlcDeviceOnPlcDeviceStatusRequestPlcDeviceToggleRealTimeClockDataRequestRealTimeClockDataWriteSpeakPhraseSpeakWordSystemLogDataReadRequestSystemLogDataWriteRequestSystemTroubleStatusRequestTaskActivationTemperatureDataRequestTemperatureRequestTextDescriptionRequestThermostatDataRequestThermostatSetThermostatSetCoolSetPointThermostatSetFanThermostatSetHeatSetPointThermostatSetHoldThermostatSetModeUserCodeAreasRequestUserCodeChangeRequestVersionNumberRequestZoneBypassRequestZoneDefinitionRequestZonePartitionRequestZoneStatusRequestZoneTriggerZoneVoltageRequest
Responses
Responses are parsed from their raw packet data (as described in section 4 of the specification document.
A parse function is exported that will parse a packet and return it's associated response.
import { parse } from 'elk-message';
const dataPacket = '16XK2636115020605110006F';
// parse will return an instance of `EthernetModuleTest`
const ethernetModuleTest = parse(dataPacket);
assert(ethernetModuleTest instanceof EthernetModuleTest);The parse function will return a UnknownElkResponse if the response type was unknown or could not
be determined for some reason (malformed packet, undocumented response, etc...)
AlarmByZoneReportAlarmMemoryUpdateAlarmReportAlarmReportTestArmingStatusReportAudioCommandOutgoingAudioDataReplyControlOutputStatusReportCounterValueReplyCustomValueReplyElkResponseElkRPConnectedEmailSendTriggerEntryExitTimerEthernetModuleResetEthernetModuleTestInstallerModeExitedInsteonLightingDeviceProgrammedInsteonLightingDeviceStatusReplyKeypadAreaAssignmentsKeypadFunctionKeyPressReplyKeypadKeyChangeLightingDeviceDataReplyOmnistat2ReplyOutputChangeUpdatePlcChangeUpdatePlcDeviceStatusReplyRealTimeClockDataReplySendASCIIStringToIPAddressSystemLogDataUpdateSystemTroubleStatusReplyTaskChangeUpdateTemperatureDataTemperatureReplyTextDescriptionReplyThermostatDataUnknownElkResponseUserCodeAreasReplyUserCodeChangeReplyUserCodeEntryVersionNumberReplyZoneBypassReplyZoneChangeUpdateZoneDefinitionDataZonePartitionReportZoneStatusReportZoneVoltageData