AlarmReceiver Event Translation Procedure with Email – Updated 01/09/13
The purpose of this procedure was to get my DSC Power Series 832 alarm panel to call into Asterisk, log the event, grab the latest alarm event, translate the ademco alarm code to english and to instantly send an email identifying the zone in alarm – example “family room motion” etc. If there is no ademco alarm code translation match, it will simply email the ademco code. I wanted to receive the messages on my smart phone and the procedure does this perfectly.
For the Legal Community - WARNING: This application/procedure is to be used at your own risk! This application is NOT Underwriter’s Laboratory (UL) approved and should not be used in any application where it is the primary or sole means of receiving alarm messages or events.
Assumptions:
• Prior to beginning this procedure you will need to supply dial tone to the alarm panel. I used a Linksys Pap2T. You must force the asterisk extension to use the ulaw codec. Configure the alarm panel asterisk extension using Freepbx to the following:
dtmfmode - in band audio
disallow - all
allow - ulaw
• I had MAJOR issues trying to get the alarmreceiver module to work with Asterisk 10 AND Asterisk 11.0.1 - as there are major issues with these versions of the alarmreceiver module as of 1/5/13. I was able to get everything to work using Asterisk version 1.8.18.0 which is my recommendation.
• Remember everything we do here is case sensitive. Everything in this procedure should be lower case
• You will want to disable the horn circuit on the alarm panel so you can generate alarms without having to hear the audio output from your alarm system. Your Police department and neighbors will appreciate this!!!
• Do yourself a favor and download a good free PHP editor. I use Dev-php and can be downloaded at http://sourceforge.net/projects/devphp/
• Download a good file manager if you will be transferring files back and forth from a windows machine. I use WinSCP at http://winscp.net
STEP 1 – Configure Asterisk Alarmreceiver Module using FreePBX
Custom Destinations:
A. Using FreePBX go to Tools, Custom Destinations
B. Click on Add Custom Destination
C. Enter in Custom Destination: custom-myalarmreceiver,s,1
D. In Description enter: Alarm Receiver
E. Submit Changes
LOG INTO ASTERISK COMMAND LINE:
-
Log as Root into the Asterisk system using a program like PuTTY . You should be at : root@pbx:~ $.
-
Enter: cd .. -
Enter: cd /etc/asterisk -
Edit extensions_custom.conf and add this at the bottom:
; Alarmreceiver
[custom-myalarmreceiver]
exten => s,1,NoOp(Alarm received)
exten => s,n,Answer
exten => s,n,Ringing()
exten => s,n,Wait(6)
exten => s,n,AlarmReceiver
exten => s,n,Hangup
- Reboot Asterisk
Alarm Panel Call Out Number:
You must have your Alarm Panel programmed to dial into the alarmreceiver module. The easiest way to do this is run an Asterisk trace to see what number is currently programmed into the panel. Once you know the number you will edit the extensions_custom.conf file to direct that number to the alarmreceiver module. This gets around a big problem with many not knowing the panels “Installer Code” required to change the number. If you have the panel connected to a Linksys PAP2T, there is a “Last Called Number:” field in the info screen so initiate an alarm and then go to the pap2t. Then go to step 5 below - otherwise start at 1.
- Log as Root into the Asterisk system using a program like PuTTY . You should be at : root@pbx:~ $.
- Type Asterisk –rvvv to get to the command line prompt: You will see: pbx*CLI>
- Arm the Alarm System and open a door, window etc. to get the system to dial out.
- Watch the activity at the CLI command line and watch for the number being dialed out by the alarm panel and write it down.
- Edit file extensions_custom.conf in directory: /etc/asterisk
- Add the following 2 lines to the extensions_custom.conf file: (Note that if you already have a [from-internal-custom] heading, just add the extension line to the existing heading.)
[from-internal-custom]
exten => 1800AAABBBB,1,Goto(custom-myalarmreceiver,s,1)
Change the 1800AAABBBB to the number the alarm panel dials. Asterisk will now grab all calls made to that number and route them to the alarmreceiver module.
- Reboot Asterisk
Now for the test. Telnet back into Asterisk using an application like PuTTY and once logged in type Asterisk –rvvv to get to the CLI> command line. Arm the Alarm system and trigger an alarm. The panel should dial out, Asterisk should grab the call and route it to the alarmreceiver module. Command line activity should look like the following:
*CLI>
– Executing [5085551212@from-internal:1] Goto(“SIP/4994-0a084c88”, “custom-myalarmreceiver|s|1”) in new stack
– Goto (custom-myalarmreceiver,s,1)
– Executing [s@custom-myalarmreceiver:1] NoOp(“SIP/4994-0a084c88”, “Alarm received”) in new stack
– Executing [s@custom-myalarmreceiver:2] Answer(“SIP/4994-0a084c88”, “”) in new stack
– Executing [s@custom-myalarmreceiver:3] Ringing(“SIP/4994-0a084c88”, “”) in new stack
– Executing [s@custom-myalarmreceiver:4] Wait(“SIP/4994-0a084c88”, “6”) in new stack
– Executing [s@custom-myalarmreceiver:5] AlarmReceiver(“SIP/4994-0a084c88”, “”) in new stack
== AlarmReceiver: Received Event 769418112001000C
If you don’t get an answer, make sure you have the correct number programmed in to the extensions_custom.conf file. If you don’t see anything in the trace stating myalarmreceiver and “Received Event” you need to go to a location like: http://www.freepbx.org/forum/freepbx/users/alarmreceiver-howto-get-it-to-work to figure out how to troubleshoot the alarmreceiver module.
Step 2 – Email Program
** One important note. It was brought to my attention that some Asterisk distributions use Postfix. You can only have one MTA so it is important to identify this issue prior to installing SENDMAIL. The other option is to figure out on your own how to use Postfix with this procedure.
PBX in a Flash distros (which is what i use) seem to use sendmail by default.
-
You need to have the application SENDMAIL loaded onto your asterisk server. This will be the email program we will use to push the alarm events out of Asterisk. For those that don’t know Sendmail it’s a very light and simple command line mailer that is PERFECT for this application. It is likely that it is already on your server (if using a PBX in a Flash distro) but if not you need to get it installed and operational.
-
Follow the procedure at http://fonality.com/trixbox/wiki/sendmail-voicemail to configure your sendmail program. -
I was able to verify SENDMAIL is on my server by going to the Asterisk command line and type:
sendmail -d0.1 -bt < /dev/null
You should get something like:
sendmail -d0.1 -bt < /dev/null
Version 8.13.8
Compiled with: DNSMAP HESIOD HES_GETMAILHOST LDAPMAP LOG MAP_REGEX
MATCHGECOS MILTER MIME7TO8 MIME8TO7 NAMED_BIND NETINET NETINET6
NETUNIX NEWDB NIS PIPELINING SASLv2 SCANF SOCKETMAP STARTTLS
TCPWRAPPERS USERDB USE_LDAP_INIT
============ SYSTEM IDENTITY (after readcf) ============
(short domain name) $w = pbx
(canonical domain name) $j = pbx.local
(subdomain name) $m = local
(node name) $k = pbx.local
- Verify your sendmail is configured correctly. Send an email from the Asterisk command line using the example below. Substitute [email protected] with your “from” email address, and substitute [email protected] with the “to” address.
- At the Asterisk command line type :
sendmail -v -t -f [email protected] [email protected] < /etc/asterisk/alarmreceiver.conf
I had problems with my internet provider not allowing email relays to be received. GMAIL seems to be okay with it which is what I use. Even if it appears the email goes out, if you don’t receive it, the likely cause is it has been blocked. Use your ISP provided email address for the “from” and a gmail address for the “to” and you should be okay. Again you are on your own for SENDMAIL but should not proceed with this procedure until you can send and receive an email using the command line !!!
STEP 3: Create Some Alarms
You will want to disable the horn circuit on the alarm panel so you can generate alarms without having to hear the audio output from your alarm system. Your Police department and neighbors will appreciate this!!!
- Log as Root into the Asterisk system using a program like PuTTY . You should be at : root@pbx:~ $.
- Type Asterisk –rvvv to get to the command line prompt: You will see: pbx*CLI>
- Arm the Alarm System and open a door, window etc. to create an event. Open up a few things to trigger more events. You will use these for reference later.
- You should see activity on your command line
- When the call completes and hangs up, exit out of the command line by typing exit
- You should now be at: root@pbx:~ $.
- Enter: cd /tmp
- Enter: LS -L and you should see alarm events in the folder /tmp View the files with an editor, I use NANO here for simplity – nano filename. If they are not there the alarmreceiver module is not working correctly and you need to start troubleshooting. When you open your event file it should look something like:
[metadata]
PROTOCOL=ADEMCO_CONTACT_ID
CALLINGFROM=5085551212
CALLERNAME=
TIMESTAMP=Fri Nov 23, 2012 @ 08:53:29 EST
[events]
769418132001000A
FYI - The current version of Asterisk 10.10 and 11beta has an AlarmReciever bug and it does not work – bug 20484, It has been corrected but the patch has not been pushed out to general release yet. In general the AlarmReceiver module is embedded in Asterisk and has been for YEARS. The bug and diff are detailed at https://issues.asterisk.org/jira/browse/ASTERISK-20484 : Use http://www.freepbx.org/forum/freepbx/users/alarmreceiver-howto-get-it-to-work to figure out how to troubleshoot the alarmreceiver module
** DO NOT continue with the remainder of this procedure until you have asterisk logging events to the /tmp directory. The remaining steps require the events to be present in the /tmp directory. Steps 1, 2 and 3 address standard Asterisk setup configurations for the alarmreceiver module.
Step 4: Create Required Directories and Copy attached file alarmrecever.conf
- Telenet into the Asterisk system using a program like PuTTY to get to the root directory prompt. Log in as Root
- Type CD //
- Verify you have a directory /tmp by typing DIR If you do not - create one.
- Copy the attached file alarmreceiver.conf to /etc/asterisk/
- Verify you can get to directory path: /etc/asterisk/alarm If you can not – create the required directory(s).
- Copy the attached file: latest.txt into /etc/asterisk/alarm
STEP 5: alarm.php
Now it’s time to start editing the AlarmReceiver specfic files I have created and attached. Do yourself a favor and download a good free PHP editor. I use Dev-php and can be downloaded at http://sourceforge.net/projects/devphp/
Also download a good file manager if you will be transferring files back and forth from a windows machine. I use filezilla at http://filezilla-project.org/
FYI – All alarm events are placed in the /tmp directory by the alarmreceiver module in its native ademco format. Once you start initiating alarm events you can view them in the /tmp directory. The alarm.php script file is responsible for going to the /tmp directory, sort through all the events, grab the latest alarm event and save it to /etc/asterisk/alarm/latest.txt It will then execute alarmparse.php to convert the ademco alarm code to english and send out the email.
- Open the attached file alarm.php for editing.
- Edit the “from” and “to” email addresses in the sendmail line. You should know this from step 2.
- Save the file and upload to the asterisk server to directory /etc/asterisk
- Remember everything we do in this procedure is case sensitive. Everything should be lower case.
- Once alarm.php is saved to the server, YOU MUST CHMOD THE PERMISSIONS ON THIS FILE TO 777 ON THE ASTERISK SERVER or it will not work.
STEP 6: alarmparse.php
alarmparse.php will grab the latest alarm event received from the alarm panel in file /etc/asterisk/alarm/latest.txt It will then attempt to convert the ademco alarm message to a user defined name such as “Family Room Zone 3” if there is a pattern match.
The alarmparse.php script is specific to MY system. You will need to go in with your favorite php editor and change fields to YOUR specific system.
The way this script works is it is looking for a string match and when it finds it, it will replace it with english which will ultimately be emailed to you. The Ademco contact id format seems to be consistent but the actual field positioning may be different for your specific panel. You will figure it out after reviewing a few alarms. The SSSS and 18 seem to be constant so just look for constants in the event files.
For my DSC Power Series 832 the formating is SSSS 18 QXYZ GG CCC K. The positioning may be different in your messages.
SSSS= 4 Digit subscriber ID
18 = Uniqely identifies this format to the receiver
Q = Event qualifier – 1 is a new event, 3 is a new restore or closing, 6 is a previous event.
XYZ= Event Code
GG= Group number
CCC = Zone or sensor number
K=checksum
Procedure Steps:
- You need to go to your /tmp directory and view a few events logged earlier to get YOUR alarm specific configuration. You will see the ademco formatted event look something like: 769418113101003C
In this example, the event is decoded as:
SSSS=7694
18 = 18
Q= 1
XYZ=131
GG=01
CCC=003
K=C
The last character C is the checksum. I have struggled with this as they seem to change a lot and I have simply ignored it as I was having problems with pattern matches. .
769418113101003C would have been decoded by alarmparse.php by the string below as the Front Door.
‘769418113401001’ => ’ Garage Kitchen Entry’,
‘769418113101001’ => ’ Garage Kitchen Entry’,
‘769418113101002’ => ’ Foyer Windows’,
‘769418113101003’ => ’ Front Door’,
‘769418113201004’ => ’ Foyer Motion’,
- You will need to figure out your SSSS and CCC specific to your system and edit alarmparse.php to match your system. Once you know what zone numbers are for what area you can go into the file and change the CCC and english output accordingly. FYI - My system seems to toggle the Q field as a 1 for a new event, and a 3 as a restored event. Your panel could be different.
- When you are done editing, save the file alarmparse.php to /etc/astrisk/alarm
Now for the test
4. Log in to asterisk as root and go to the /tmp directory
5. Copy an event to /etc/asterisk/alarm and name it latest.txt
6. Go to the /etc/asterisk/alarm directory and enter: php alarmparse.php
7. Now go in and view the latest.txt file and you should see the file now has your translation to english. If it looks the same and everything is working correcctly, it means it did not see a pattern match that you edited and did not change anything.
Example – this is what an example latest.txt would look like prior to running alarmparse.php
[metadata]
PROTOCOL=ADEMCO_CONTACT_ID
CALLINGFROM=5085551212
CALLERNAME=
TIMESTAMP=Sat Nov 24, 2012 @ 17:33:47 EST
[events]
7694181132010110
7694181132010110
769418113201004A
Example – this is what latest.txt will look like AFTER running alarmparse.php with a pattern match.
[metadata]
PROTOCOL=ADEMCO_CONTACT_ID
CALLINGFROM=5085551212
CALLERNAME=
TIMESTAMP=Sat Nov 24, 2012 @ 17:33:47 EST
[events]
769418113201011 Family Room Motion
769418113201011 Family Room Motion
769418113201004 Foyer Motion
Step 7 – Troubleshooting / Verification
-
Do not use Asterisk 10 or 11 as the alarmreceiver module does not work on these releases (at least for me). Use Asterisk 8.18.0
-
Verify alarmreceiver.conf is in the /etc/asterisk directory
-
Verify your modified file alarm.php is in the /etc/asterisk directory and has permissions set to 777
-
Verify latest.txt is in the /etc/asterisk/alarm directory
-
Verify your modified alarmparse.php is in the /etc/asterisk/alarm directory and you have modified the zone and system information for your specific system.
-
Reboot Asterisk once you are done with all your modifications
-
There are a lot of good references on the internet for Contact Id Format libraries should you want to add to the alarmparse file.
The attached files were created or modified for my own use and wanted to share with the community. I appreciate the fact that someone spent the time to create the alarmreceiver module and those that continue to keep the module functioning !!!
Files for Procedure:
latest.txt
[metadata]
PROTOCOL=ADEMCO_CONTACT_ID
CALLINGFROM=5085551212
CALLERNAME=<unknown>
TIMESTAMP=Mon Nov 26, 2012 @ 16:21:08 EST
[events]
769418113201004 Foyer Motion
769418113201004 Foyer Motion
769418113201004 Foyer Motion
769418113101015 Kitchen French Left Door
769418113101013 Kitchen French Right Door
769418113101003 Front Door
769418113101002 Foyer Windows
769418113101010 Family Room French Doors
769418113201011 Family Room Motion
769418113101009 Family Side Windows
alarm.php
[code]// YOU MUST CHMOD THE PERMISSIONS ON THIS FILE TO 777 ON THE ASTERISK SERVER FOR THIS TO WORK!!!
<?php cd /tmp; // changes directory to where the alarm events are stored by asterisk cp `ls -t1 | head -1` /etc/asterisk/alarm/latest.txt; //Grabs the newest alarm event and names it latest.txt php /etc/asterisk/alarm/alarmparse.php; //executes alarmparse.php which attemps to match the ademco alarm code in latest.txt and replace with english like Family Room Zone 2 sendmail -v -t -f [email protected] [email protected] < /etc/asterisk/alarm/latest.txt; // sends an email with the alarm event identified ?>[/code]
alarmparse.php
[code]<?php
//Array of alarm codes and their descriptions
$alarm_codes = array(
// System Alarms
’7694181302’ => ’ Low System Battery’,
‘7694183302’ => ’ Low System Battery Restore’,
‘7694181320’ => ’ Bell Relay Trouble’,
‘7694183320’ => ’ Bell Relay Trouble Restore’,
‘7694181316’ => ’ System Tamper’,
‘7694183316’ => ’ System Tamper’,
‘7694181350’ => ’ Communications Alarm’,
‘7694183350’ => ’ Communications Alarm’,
‘7694181351’ => ’ Telco Line Fault’,
‘7694183351’ => ’ Telco Line Fault Restore’,
‘769418160201000’ => ’ Weekly Test’,
‘769418130101000’ => ’ AC Power Failure’,
‘769418330101000’ => ’ AC Power Restore’,
// Zone Alarms
’769418113401001’ => ’ Garage Kitchen Entry’,
‘769418113101001’ => ’ Garage Kitchen Entry’,
‘769418113101002’ => ’ Foyer Windows’,
‘769418113101003’ => ’ Front Door’,
‘769418113201004’ => ’ Foyer Motion’,
‘769418113101005’ => ’ Dining Room Windows’,
‘769418113101006’ => ’ Family Room Front Windows’,
‘769418113101007’ => ’ Bulkhead Basement Door’,
‘769418113101008’ => ’ Phone Tamper’,
‘769418113101009’ => ’ Family Side Windows’,
‘769418113101010’ => ’ Family Room French Doors’,
‘769418113201011’ => ’ Family Room Motion’,
‘769418113101012’ => ’ Kitchen Window’,
‘769418113101013’ => ’ Kitchen French Right Door’,
‘769418113101014’ => ’ Cellar Windows’,
‘769418113101015’ => ’ Kitchen French Left Door’,
‘769418113101000’ => ’ Panic Button’,
‘769418112001000’ => ’ Panic Button #2’,
);
//Specify the file
$file = ‘/etc/asterisk/alarm/latest.txt’;
//Get contents of file
$contents = file_get_contents($file);
//Make replacements in content for each alarm code
foreach($alarm_codes as $code => $description)
{
$pattern = str_pad($code, 16, ‘.’);
$replacement = “{$code} {$description}”;
$contents = preg_replace("#{$pattern}#", $replacement, $contents);
}
//Write new content to file
file_put_contents($file, $contents);
?>
[/code]
alarmreceiever.conf
[code];
; alarmreceiver.conf
;
; Sample configuration file for the Asterisk alarm receiver application.
;
[general]
;
; Specify a timestamp format for the metadata section of the event files
; Default is %a %b %d, %Y @ %H:%M:%S %Z
timestampformat = %a %b %d, %Y @ %H:%M:%S %Z
;
; Specify a command to execute when the caller hangs up
;
; Default is none
;
eventcmd = /etc/asterisk/alarm.php
;
; Specify a spool directory for the event files. This setting is
required if you want the app to be useful.
; Event files written to the spool directory will be of the template
event-XXXXXX, where XXXXXX is a random
; and unique alphanumeric string.
;
; Default is none, and the events will be dropped on the floor.
;
eventspooldir = /tmp
;
; The alarmreceiver app can either log the events one-at-a-time to
individual files in the spool
; directory, or it can store them until the caller disconnects and write
them all to one file.
;
; The default setting for logindividualevents is no.
;
logindividualevents = no
;
; The timeout for receiving the first DTMF digit is adjustable from
1000 msec. to 10000 msec. The
; default is 2000 msec. Note: if you wish to test the receiver by
entering digits manually, set this
; to a reasonable time out like 10000 milliseconds.
fdtimeout = 2000
;
; The timeout for receiving subsequent DTMF digits is adjustable from
110 msec. to 4000 msec. The
; default is 200 msec. Note: if you wish to test the receiver by
entering digits manually, set this
; to a reasonable time out like 4000 milliseconds.
;
sdtimeout = 200
;
; The loudness of the ACK and Kissoff tones is adjustable from 100 to
8192. The default is 8192
; This shouldn’t need to be messed with, but is included just in case
there are problems with
; signal levels.
;
loudness = 8192
;
; The db-family setting allows the user to capture statistics on the
number of calls, and the errors
; the alarm receiver sees. The default is for no db-family name to be
defined and the database logging
; to be turned off.
;
;db-family = yourfamily:
;
; End of alarmreceiver.conf
[/code]