123
Senior Member
Overview
This document describes how to use ElkM1::Control, and custom scripts, to control and monitor an ElkM1 without the use of a Home Automation (HA) program.
Introduction
Many commercial HA applications (i.e. CQC, HomeSeer, HouseBot, PowerHome, etc) provide a means to monitor and control an Elk M1 via a driver. The driver can be an integral, optional, or a user-contributed component of the HA application. An effective M1 driver must create an Application Programming Interface (API) between the HA application and the M1. The API is considered complete if it encompasses all capabilities described in Elk's "ASCII Protocol RS-232 Interface Specification" document.
Normally, an M1 driver is used exclusively with its native HA application. In most cases, the driver is an extension of the HA program and cannot function without it. However, thanks to Neil Cherry's posting in the MisterHouse mailing list, I learned of an M1 API that is not tied to a specific HA program. Early in 2006, James A. Russo created a new project on Sourceforge, called ElkM1::Control, providing a standalone API to the M1.
Developed in Perl, an interpreted language, ElkM1::Control provides most of the capabilities described in Elk's "ASCII Protocol" document. Its source code is freely available to everyone and, by virtue of Perl, can be used on Windows or Linux PCs. Unfortunately, only one version (0.02) was ever posted but it was amply documented, well-designed, and included commented code.
What can ElkM1::Control do for me?
ElkM1::Control is a Perl-based API to the ELK M1 and is a natural complement to MisterHouse (also written in Perl). However, it can be used to create useful applications without MisterHouse or any other HA program. For example, you can write standalone Perl scripts to:
It is easy to see what this command does:
$elk->disarm(code => 1234);
Here are the commands to turn off output 9, pause for ten seconds, and then turn on output 10 for ten minutes (600 seconds):
$elk->controlOutputOff(output => 9);
sleep 10;
$elk->controlOutputOn(output => 10, timeout => 600);
Here's how to get, and print, the temperature recorded by the second keypad:
$elk->requestTemperature(group => 1, device => 2);
my $msg = $elk->readMessage;
print "Temperature is ".$msg->getTemperature" if (ref($msg) eq 'ElkM1::Control::Message::TemperatureReply');
Here are the commands to activate a task and turn on device C5:
$elk->activateTask(task => 1);
$elk->turnOnPLCDevice(house => 'C', unit => 5);
What do I need to use it?
You will need the following hardware:
You will need the following software:
In order to simplify your life, my installation instructions have cut a few corners. James Russo designed ElkM1::Control to support encrypted communications, using Secure Socket Layers (SSL), via port 2601. However, this capability is lost if you follow my installation instructions.
Some Perl modules, such as ElkM1::Control, can be installed by simply copying them to the \perl\site\lib folder. However, other modules must first be "built" using tools that are not commonly found on a typical Windows PC (i.e. C compiler, C libraries, nmake utility, etc).
Proper installation of the IO::Socket::SSL module is a complicated affair because it depends on other modules that must be compiled. To avoid this headache, I cheated by creating a version of IO::Socket::SSL that is simply a copy of an existing module: IO::Socket::INET. This trick serves to satisfy the Perl interpreter, lets us talk to the M1 on an unencrypted port (2101), but eliminates the ability to successfully communicate via an encrypted port.
If you absolutely require encrypted communications, see the following article: "How to Add Support for Encrypted Communications" (posted below).
How do I use it?
Copy example #1 into your favourite text editor.
perl saytime.pl
Copy example #2 into a text editor, revise the IP address, and save it as readmsg.pl.
Run readmsg.pl at the command prompt. Nothing may be displayed for awhile unless you create some activity (i.e. violate a zone) or simply wait for the next Ethernet Module Test message (sent every 30 seconds).
Have fun!
This document describes how to use ElkM1::Control, and custom scripts, to control and monitor an ElkM1 without the use of a Home Automation (HA) program.
Introduction
Many commercial HA applications (i.e. CQC, HomeSeer, HouseBot, PowerHome, etc) provide a means to monitor and control an Elk M1 via a driver. The driver can be an integral, optional, or a user-contributed component of the HA application. An effective M1 driver must create an Application Programming Interface (API) between the HA application and the M1. The API is considered complete if it encompasses all capabilities described in Elk's "ASCII Protocol RS-232 Interface Specification" document.
Normally, an M1 driver is used exclusively with its native HA application. In most cases, the driver is an extension of the HA program and cannot function without it. However, thanks to Neil Cherry's posting in the MisterHouse mailing list, I learned of an M1 API that is not tied to a specific HA program. Early in 2006, James A. Russo created a new project on Sourceforge, called ElkM1::Control, providing a standalone API to the M1.
Developed in Perl, an interpreted language, ElkM1::Control provides most of the capabilities described in Elk's "ASCII Protocol" document. Its source code is freely available to everyone and, by virtue of Perl, can be used on Windows or Linux PCs. Unfortunately, only one version (0.02) was ever posted but it was amply documented, well-designed, and included commented code.
What can ElkM1::Control do for me?
ElkM1::Control is a Perl-based API to the ELK M1 and is a natural complement to MisterHouse (also written in Perl). However, it can be used to create useful applications without MisterHouse or any other HA program. For example, you can write standalone Perl scripts to:
- Arm/Disarm the M1.
- Enable/Disable an Output.
- Read the temperature from a keypad, thermostat, or probe.
- Perform an action when a zone is violated.
- Monitor the M1's messages.
Code:
use ElkM1::Control;
my $elk = ElkM1::Control->new(host => '192.168.0.251', port => 2101);
$elk->armAway(code => 1234);
$elk->disconnect();$elk->disarm(code => 1234);
Here are the commands to turn off output 9, pause for ten seconds, and then turn on output 10 for ten minutes (600 seconds):
$elk->controlOutputOff(output => 9);
sleep 10;
$elk->controlOutputOn(output => 10, timeout => 600);
Here's how to get, and print, the temperature recorded by the second keypad:
$elk->requestTemperature(group => 1, device => 2);
my $msg = $elk->readMessage;
print "Temperature is ".$msg->getTemperature" if (ref($msg) eq 'ElkM1::Control::Message::TemperatureReply');
Here are the commands to activate a task and turn on device C5:
$elk->activateTask(task => 1);
$elk->turnOnPLCDevice(house => 'C', unit => 5);
What do I need to use it?
You will need the following hardware:
- Elk M1
- Elk M1XEP Ethernet Module
- PC connected to the M1XEP via a LAN.
You will need the following software:
- ActiveState's Perl interpreter (free).
- The attached zip archive.
- James Russo's ElkM1::Control files in the \ElkM1 folder.
- IO:Socket::SSL file in the \IO folder.
- A reference document, in MS Word 2003 format, for ElkM1::Control.
- Download and install ActiveState's Perl interpreter in "c:\perl" (accept all defaults).
- Unzip Perl_Modules.zip and copy the \Elk and \IO folders to "c:\perl\site\lib". Put the reference document in a convenient place on your hard-drive.
In order to simplify your life, my installation instructions have cut a few corners. James Russo designed ElkM1::Control to support encrypted communications, using Secure Socket Layers (SSL), via port 2601. However, this capability is lost if you follow my installation instructions.
Some Perl modules, such as ElkM1::Control, can be installed by simply copying them to the \perl\site\lib folder. However, other modules must first be "built" using tools that are not commonly found on a typical Windows PC (i.e. C compiler, C libraries, nmake utility, etc).
Proper installation of the IO::Socket::SSL module is a complicated affair because it depends on other modules that must be compiled. To avoid this headache, I cheated by creating a version of IO::Socket::SSL that is simply a copy of an existing module: IO::Socket::INET. This trick serves to satisfy the Perl interpreter, lets us talk to the M1 on an unencrypted port (2101), but eliminates the ability to successfully communicate via an encrypted port.
If you absolutely require encrypted communications, see the following article: "How to Add Support for Encrypted Communications" (posted below).
How do I use it?
Copy example #1 into your favourite text editor.
Code:
# Example 1: Say the current time
use ElkM1::Control;
my $elk = ElkM1::Control->new(host => '192.168.0.251', port => 2101);
$elk->speakPhrase(phrase => 238);
$elk->disconnect();- Replace the host address (192.168.0.251) with the IP address of your M1XEP.
- Save the file on your Desktop as saytime.pl.
- Open the Command Prompt (Start | Run, type cmd and press the Enter key).
- At the command prompt, type:
cd desktop
saytime.pl
The M1 should say the current time. If you see "unable to connect", the M1's port 2101 may be closed or perhaps there's a network connectivity problem. If Windows does not know how to execute the file it means the ".pl" extension is not associated with ActiveState's Perl interpreter. A quick solution to this problem is to execute the file like so:saytime.pl
perl saytime.pl
Copy example #2 into a text editor, revise the IP address, and save it as readmsg.pl.
Code:
# Example 2: Display all M1 messages
use ElkM1::Control;
my $elk = ElkM1::Control->new(host => '192.168.0.251', port => 2101);
while (1) { # Loop forever
while (my $msg = $elk->readMessage) { # Read the M1's messages
print $msg->toString; # Print the messages
}
}Run readmsg.pl at the command prompt. Nothing may be displayed for awhile unless you create some activity (i.e. violate a zone) or simply wait for the next Ethernet Module Test message (sent every 30 seconds).
Have fun!
