English
资源说明：A node.js module for interfacing with the Elk M1 Gold automation controller
# elkington
[](http://travis-ci.org/kevinohara80/elkington)
**elkington** is a node.js module for interfacing with the [Elk M1 Gold](http://www.elkproducts.com/product-catalog/m1-gold-cross-platform-control) automation controller.
**This is currently experimental and under development. Not all Elk messages are currently being parsed.**
## Features
* Simple API with function calls for Elk commands
* Supports many Elk commands
* Supports both secure and non-secure communication ports
## Usage
To get started, call `createConnection()` to create a new connection and register some event handlers:
```javascript
var elkington = require('elkington');
/// create a connection
var elk = elkington.createConnection({
port: 2101,
host: '192.168.1.13'
});
// register event handlers
elk.on('any', function(msg){
console.log('Incoming message: ' + msg.message);
});
```
Or a secure connection can be established...
```javascript
/// create a connection
var elk = elkington.createConnection({
port: 2601,
host: 'myelk.myhouse.com',
username: 'somebody',
password: 'yoyoyo',
useSecure: true
});
```
### Handling events
**elkington** provides a lot of commands. Some of the commands will invoke a response from the controller. You can optionally pass in a callback to these commands.
```javascript
elk.alarmByZoneRequest(function(err, resp){
if(err) {
console.log(err.message);
} else {
console.log('Got the alarm by zone response');
}
});
```
Or you can listen for the response in a separate event handler and just call the method.
```javascript
// AZ is the message type for 'Alarm by Zone Reply'
elk.on('AZ', function(msg) {
console.log('area1 arm status: ' + msg.data.area1.armStatus);
});
elk.alarmByZoneRequest();
```
### Speaking
The Elk M1 has a large library of words that it can say over it's speaker. With the **elkington** `speak()` function, you can make your Elk say all kinds of wacky (or useful) stuff...
```javascript
elk.speak('defective hottub pump');
```
...now something more useful:
```javascript
var elkington = require('elkington');
var request = require('request');
var elk = elkington.createConnection({ port: 2101 , host: '192.168.1.13'});
elk.on('connect', function() {
// say the outside temp on connection to the Elk
var opts = {
url: 'http://query.yahooapis.com/v1/public/yql',
qs: {
q: 'select item from weather.forecast where location = "48307"',
format: 'json'
}
};
request(opts, function(error, response, body) {
if(!error) {
var temp = JSON.parse(body).query.results.channel.item.condition.temp.toString();
elk.speak('outside temperature is ' + temp + ' degrees');
}
});
});
```
The speak function can even interpret numerical values
```javascript
// speaker says 'two thousand twelve'
elk.speak('2012');
```
## Event API
### on(event, callback)
Register an event listener.
## Arm/Disarm API
### disarm([callback])
Disarm the Elk. Callback is optional.
### armAway([options])
Arm the Elk in Away Mode.
### armStay([options])
Arm the Elk in Stay Mode.
### armStayInstant([options])
Arm the Elk in Stay Mode instantaneously.
### armNight([options])
Arm the Elk in Night Mode.
### armNightInstant([options])
Arm the Elk in Night Mode instantaneously.
### armVacation([options])
Arm the Elk in Vacation Mode.
### armStepAway([options])
Arm and step to next Away mode
### armStepStay([options])
Arm and step to next Stay mode
### armingStatusRequest([callback])
Request the arming statuses for all areas. Callback is optional. The callback returns the results of the Arming Status Response sent by the Elk.
## Events
**elkington** can emit the following events. With the exception of the utility `any` event, the events use the same two-character, uppercase codes from the Elk RS-232 ASCII protocol:
* `any`: Any message from the Elk
* `AR`: Alarm Reporting to Ethernet
* `AS`: Arming status report data
* `AT`: Ethernet Test to IP
* `AZ`: Alarm by zone reply
* `CC`: Control output change update
* `CR`: Custom value report data
* `CS`: Control output status report data
* `CU`: Change user code reply
* `CV`: Counter Value Data
* `DS`: Lighting Poll Response
* `DK`: Display KP LCD Data
* `EM`: Email Trigger to M1XEP
* `IC`: Send invalid user code digits
* `IE`: Installer program exited
* `IP`: M1XSP Insteon Program
* `IR`: M1XSP Insteon Read
* `KA`: Keypad areas report data
* `KC`: Keypad key change update
* `KF`: Function key pressed data
* `LD`: Log data with index
* `LW`: Reply temperature data
* `PC`: PLC change update
* `PS`: PLC status report data
* `RE`: Reset Ethernet Module
* `RP`: ELKRP connected
* `RR`: Real Time Clock Data
* `SD`: Text string description report data
* `SS`: System Trouble Status data
* `ST`: Temperature report data
* `TC`: Task change update
* `TR`: Thermostat data report
* `UA`: User code areas report data
* `VN`: Reply Version Number of M1
* `XB`: reserved by ELKRP
* `XK`: Request Ethernet test
* `ZB`: Zone bypass report data
* `ZC`: Zone change update
* `ZD`: Zone definition report data
* `ZP`: Zone partition report data
* `ZS`: Zone status report data
* `ZV`: Zone analog voltage data
## Words
The **elkington** `speak()` function supports the following words:
*custom1, custom2, custom3, custom4, custom5, custom6, custom7, custom8, custom9, custom10, zero, one, two, three, four, five, six, seven, eight, nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen, seventeen, eighteen, nineteen, twenty, thirty, forty, fifty, sixty, seventy, eighty, ninety, hundred, thousand, silence200ms, silence500ms, tone800hz, a, access, acknowledged, ac_power, activate, activated, active, adjust, air, alarm, alert, all, am, an, and, answer, any, are, area, arm, armed, at, attic, audio, auto, authorized, automatic, automation, auxiliary, away, b, back, barn, basement, bathroom, battery, bedroom, been, bell, bottom, break, breakfast, bright, building, burglar, button, by, bypassed, cabinet, call, camera, cancel, carbon_monoxide, card, center, central, change, check, chime, circuit, clear, closed, closet, code, cold, condition, connect, control, cool, cooling, corner, crawlspace, danger, day, deck, decrease, defective, degrees, delay, den, denied, detected, detector, device, dial, dialing, dim, dining_room, disable, disarm, disarmed, dock, door, doors, down, driveway, east, emergency, enable, end, energy, enrollment, enter, entering, entertainment, enter_the, entry, environment, equipment, error, evacuate, event, exercise, expander, exit, exterior, f, fail, failure, family_room, fan, feed, fence, fire, first, flood, floor, followed, force, fountain, foyer, freeze, front, full, furnace, fuse, game, garage, gas, gate, glass, go, good, goodbye, great, group, guest, gun, hall, hallway, hanging_up, hang_up, has, has_expired, have, hear_menu_options, heat, help, high, hold, home, hot, hottub, house, humidity, hvac, if, immediately, in, inches, increase, inner, input, inside, instant, interior, in_the, intruder, intruder_message, intrusion, invalid, is, is_about_to_expire, is_active, is_armed, is_canceled, is_closed, is_disarmed, is_low, is_off, is_ok, is_on, is_open, jacuzzi, jewelry, keep, key, keypad, kitchen, lamp, laundry, lawn, leak, leave, left, less, level, library, light, lights, line, living_room, loading, lobby, location, lock, low, lower, m, machine, mail, main, mains, manual, master, max, media, medical, medicine, memory, menu, message, middle, minute, missing, mode, module, monitor, more, motion, motor, next, night, no, normal, north, not, notified, now, number, nursery, of, off, office, oh, ok, on, online, only, open, operating, option, or, other, out, outlet, output, outside, over, overhead, panel, panic, parking, partition, patio, pause, perimeter, personal, phone, place, play, please, plus, pm, police, pool, porch, port, pound, pounds, power, press, pressure, problem, program, protected, pump, radio, raise, ready, rear, receiver, record, recreation, relay, remain_calm, remote, repeat, report, reporting, reset, restored, return, right, roof, room, running, safe, save, screen, second, secure, security, select, sensor, serial, service, set, setback, setpoint, setting, shed, shipping, shock, shop, shorted, shunted, side, silence, siren, sliding, smoke, someone, south, spare, speaker, sprinkler, stairs, stairway, star, start, status, stay, stock, stop, storage, storm, studio, study, sump, sun, switch, system, tamper, tank, task, telephone, television, temperature, test, thank_you, that, the, theater, thermostat, third, time, toggle, top, transformer, transmitter, trespassing, trouble, turn, twice, type, under, unit, unlocked, unoccupied, up, user, utility, vacation, valve, video, violated, visitor, wake_up, walk, wall, warehouse, warning, water, way, welcome, west, what, when, where, will, window, windows, with, work, yard, year, you, zone, zones*
## Links
- [Elk RS-232 ASCII Protocol](http://www.scribd.com/doc/50097012/Elk-m1-Rs232-Protocol)
## Todo
- Oh, man. Where do I start.
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
