Summary:	ASTERISK-01758: [patch] New app: Ademco Contact ID alarm receiver
Reporter:	hwstar (hwstar)	Labels:
Date Opened:	2004-06-03 23:15:31	Date Closed:	2008-01-15 15:00:01.000-0600
Priority:	Major	Regression?	No
Status:	Closed/Complete	Components:	Core/General
Versions:		Frequency of Occurrence
Related Issues:
Environment:		Attachments:	( 0) alarmreceiver.conf ( 1) alarmreceiver.conf ( 2) app_alarmreceiver.c ( 3) app_alarmreceiver.c
Description:	Here's something which you might find useful, a software-based Ademco (SIA) Contact ID alarm receiver implemented as an Asterisk APP. I wrote this to monitor my alarm at my vacation home. To install, copy the app_alarmreceiver.c file into the apps directory, and edit the Makefile in the apps directory to add the application name. Recompile Asterisk, and add some lines to your extensions.conf to call the app. I'm looking for testing feedback and comments on additional features, please leave them as bugnotes here. BTW: Disclaimer is on file with Digium. ****** ADDITIONAL INFORMATION ****** To test at human speeds, use the following alarmreceiver.conf settings: [general] eventcmd = cat > /tmp/events2.txt fdtimeout = 6000 sdtimeout = 3000 loudness = 4096 ~ Ademco Contact ID DTMF format: AAAA MM EEEE PP ZZZ C AAAA = Account Number MM = Message type (Either 18 or 98) EEEE = Event Qualifier PP = Partition Number C = Checksum The calculation of the checksum is unique. See the code. Examples: 1234 18 1131 01 015 8 1234 18 3131 01 015 6 The complete spec can be obtained from the Security Industry Association publication SIA DC-05-01999.09
Comments:	By: Brian West (bkw918) 2004-06-04 19:06:14 what alarm do you have?  I would love to cut out my monitoring expense. bkw By: mhardeman (mhardeman) 2004-06-04 19:17:58 Almost every panel out there that has any kind of communicator supports the Contact ID protocol.  It's just a matter of getting access to the panel's installer level access and then entering the proper configuration parameters. By: mhardeman (mhardeman) 2004-06-04 19:22:51 Oh... I would like to point out, however, that monitoring is more than the machine at the other end of the line that answers the call and decodes the signals. It's a human operator who makes verification calls to the premises and then personally notifies a human at the appropriate public safety organization. It is illegal in almost all municipalities to have any kind of automated device call 911 or even the non-emergency lines for the purpose of reporting an alarm.  Many people feel that this was to provide a monopoly to the alarm stations.  This is not the case.  It's about resource utilization and error checking.  Do you want  cops jumping around left and right at the whim of a recorded message, or does it make more sense for a human to at least try (very quickly) to determine if there is a false alarm?  That's up for debate, but most of the legislators out there say only pass an alarm to public safety after a human has checked for false alarm by dialing premesis and demanding a passcode. By: Brian West (bkw918) 2004-06-04 19:28:27 Cops never show up when my alarm company calls so its kinda pointless to call them.  Plus my city charges you 45.00/yr if you have an alarm.  I can just have it call me when i'm away. :) By: mhardeman (mhardeman) 2004-06-04 19:41:59 The truth is that sometimes that actually (what you've just described) works better.  :-)  Usually law enforcement will not ignore a direct complaint delivered by a human by phone... So if you get the alarm notice and called your local cops...  They might actually roll a cruiser your way. By: hwstar (hwstar) 2004-06-04 21:35:37 I coded this because I needed a way for my alarm at my vacation home to call into my system and report trouble. I really couldn't justify another $110/yr or so for a new monitoring account just for the vacation home. What mhardeman says is true. Your alarm or other device can't call the cops, but you can have it call Asterisk and then have Asterisk call you at work, email you page you, etc. For some people this is all they need. As for alarm panels, most of the Non-ademco ones built after 1999 support Ademco Contact ID. Ademco has supported Contact ID on their panels since the late 80's I beleive. The other reason I coded this is because alarm receivers are expensive, and one could conceivably have a quite a few of them by just hooking a T1 up to Asterisk and then having Asterisk do all the decoding and handshaking then send the events to some future open source central station monitoring software project. Steve. edited on: 06-04-04 21:20 edited on: 06-04-04 21:21 By: mhardeman (mhardeman) 2004-06-04 22:57:38 While I think the idea of a software based central station monitoring product is very nice, I'm afraid it wouldn't make it into commercial use on any decent scale (at least no time soon). Central Stations tend to covet their UL certifications, which require UL certified equipment and software (even firmware builds are tested and approved) from the line interface all the way to the desks of the central station dispatchers. The costs of certification are astronomical, the requirements extreme, the time to get certified is horrible. Aside from all this, the event loggers deployed at the central stations are quite rugged and very resilient to poor electrical conditions and serve a very different environment from *'s normal turf. I do, however, think this is a very neat app that has merit in the corporate environment.  Imagine a business with a number of remote locations who have alarm systems at each site which report up to their own centralized asterisk system.  From there, an application outside asterisk (or implemented in asterisks extensions logic, or any number of other ways) takes the signals, gives a centralized person the ability to edit / change / suppress / etc, and further handle the alarm. To really make this concept interesting, the reverse end of the transaction should be implemented.  Imagine an app that takes the event data and zone/user data and calls a central station to report as if asterisk were the alarm panel. In conjunction with the scenario I mentioned above, this could be a failover for events not being handled by corporate security - i.e. unhandled events could be dialed on through to a real central station and reported.  This potentially has some caveats and may require some cooperation on the part of the central station as many modern central stations are authenticating monitoring accounts against both account code as reported AND the callerid of the call coming into the station.  Actually, I know of at least one central station that completely ignores the account code transmitted in favor of using the callerid as the unique key for the account.  I cannot imagine running a central station with that limitation... but...  apparently someone did... Oh, one more note...  The SIA does maintain and publish this specification but the standard was originally proprietary and written by ADEMCO.  It may be best to drop the SIA name from the Contact ID processor's format name, as people referring to the "SIA Format" are generally talking about a less popular, though technically superior and more recently developed format more formally known as SIA FSK (Frequency Shift Keying).  Heh...  Be kinda slick to see someone write the processor for that one..  Actually, it can't be that much harder than encoding/decoding callerid... By: hwstar (hwstar) 2004-06-04 23:27:12 I don't know if all Central Stations are UL certified. Some of the ones which serve homeowners directly may not be. Also UL may not apply to applications outside of the US, so this could still be used in countries which don't care about UL recognition. You're right about panels being able to support dual reporting though. The issue here is who owns the panel and what the service contract terms are with the alarm company. Actually I toyed with the idea of writing the communicator part to "consolidate" the events from my vacation home into my current monitoring account. One could do this be rewriting the account code and zone fields of the event. I don't think the monitoring company would be pleased if they found out people were doing this as it reduces their potential business. The only issue with writing the communicator part is technical. It would require the use of dsp.c to decode the 1400Hz and 2300Hz tones. This would require some mods to dsp.c to support which is outside the scope of my asterisk coding skills for now. In regards to your question about dropping SIA, the code identifies the format as ADEMCO_CONTACT_ID. Lastly, the FSK formats could be supported, but I don't know if it would be best to implement them as they won't be as bulletproof as  DTMF over a voip channel such as IAX.  Contact ID Alarm event reporting over IAX should be reliable as the DTMF tones are transmitted out of band. I have a small swath of DID numbers provided to me over IAX and I will use one of these as an alarm receiver number. Steve. By: mhardeman (mhardeman) 2004-06-05 00:05:48 There are a number of small monitoring operations in the US which don't bear the UL certification, but their scalability is quite limited as the insurance companies in the US will typically not give any coverage discounts except to customers being monitored at UL certified stations.  Canada has the CUL (I think) and I imagine Europe has a similar pseudo-regulatory agency. The consolidation of events is not something that the central stations care about for one simple reason:  You still only have one account code with them, and that account code (regardless of zone) is tied to a particular (single) physical address.  So, when the signals begin to pour in, regardless of the fact that the zone description on file may be "Lakehouse Breakin Front Door" the physical address to call over to the police will be your primary home address.  It is possible, under special terms with a central station, to have special accounts with zones essentially divided into subaccounts with multiple addresses.  However, in those cases, you've cut a deal with the monitoring station, they're in on it, and have given it their blessing (and likely adjusted your rate accordingly).   Ordinarilly though, they'd just give you a separate account number for the other location. Maybe someone out there will pick up writing the communicator portion of the code.  It would be a nice addition...  Make it full circle... As for the VOIP issue...  I do have some concerns there.  I never imagined when this was posted that someone would try to do even Contact ID over a voip link.  While in ULAW it would definately work without any trouble, I have some concerns about doing the DTMF part out of band.  It's been a long time since I looked at the specifications for Contact ID, but I seem to recall that there are particular constraints on minimum and maximum durations of the DTMF codes played, as well as constraints as to minimum and maximum timing for spacing between each DTMF digit played, as well as a general time limit on each even message/signal's exchange.  If that is the case (and I'm pretty sure it is) I have concerns as to whether or not out of band dtmf properly conveys that information (tone duration, spacing between tones) will be reliably carried over out of band DTMF...  I would almost think this has a better chance of working in ULAW with inband DTMF. As for the SIA FSK format.. It is highly unlikely that it would work in any but ideal voip scenarios. I just can't say that routing this type of signalling over VOIP is advisable anyway.  Clearly, the industry has spoken volumes on that matter by the route that they have taken:  all the newer mid-to-high end residential systems and pretty much all the newer commercial systems have easy to integrate modules for doing direct TCP/IP reporting as a primary method, with end-to-end encryption and delivery confirmation.  If the message doesn't make it via TCP/IP, the panel fails over to standard analog dialout. By: hwstar (hwstar) 2004-06-05 00:20:57 DTMF burst is 50msec min., 60msec max. DTMF interdigit silence is 50msec min., 60msec max. With IAX, the Asterisk box connected to the DID trunks does the DTMF decode, then sends the digits as a subframe on the IAX channel as part of the stream over the internet. The Asterisk box on the receiving end does not do any DTMF decoding, it just passes the digits to the endpoint doing the processing. This is much more reliable then even ULAW. Regarding multiple sites, I did discuss this with several monitoring stations, they prefer to handle it as 2 separate accounts. Probably less fuss for them. I was not aware of the TCP-IP enabled panels, but since they encrypt the data stream, these would virtually unusable by anyone outside the industry. Steve. By: mhardeman (mhardeman) 2004-06-05 00:47:19 Actually, the encryption end-to-end is more for privacy and message integrity than  to create a barrier to entry for someone to decode.  Industry standards, after all, still require an analog backup line for most purposes.  The TCP/IP stuff is just for a cheaper and possibly faster way to get the signal there.  The underlying TCP/IP networks are considered too unreliable even in a managed WAN situation to completely satisfy requirements.  The manufacturers probably would let out the underlying format of their messages under certain terms...  As it is, many central stations haven't upgraded their side of the equation to this technology yet anyway, so it's not a real issue yet. Yes, definately 2 accounts is better suited for this purposes...  I've seen it done the other way though for campus type scenarios where there are multiple physical addresses for a single entity's buildings over the course of a few blocks with a centralized alarm system that reported different zone numbers for different zones in different buildings...  Convoluted, but as the reports were all coming out of one large system, the station would set it up that way.  More recently, the nicer commercial systems allow different account numbers for different groups of zones even served from one panel. I'm still worried about the DTMF issue.  I have no doubt that a number of DTMF events will get triggered and sent through to the far end.  I also agree that this is much more reliable than inband ULAW if and only if you don't care about interdigit timing & duration of the DTMF events.  In theory, this code may fail the specs in not enforcing the form of the DTMF events received.  Regardless, it's still very useful and definately sufficient for home and small business use. There is one other issue that is less than ideal in this code with respect to its handling of multi-round reporting (that is to say--the receipt of multiple events in one phone call).  Commercial receivers are expected to stream decoded signals on into the dispatch processing system at or near real time (that is, as soon as the individual signal has been decoded and verified for checksum & such), rather than queueing signals for processing at call end.  It's a very minor issue for a small residential use, but would be a big deal at a central station.  Maybe it would be appropriate to raise a manager interface event upon signal decoding?  This would at least provide an accessible mechanism for outside software to receive alarm events in near real time. By: hwstar (hwstar) 2004-06-05 13:17:52 mhardeman - Thanks for sharing all of your knowledge about the Alarm Monitoring Industry. I have never worked in this field so I don't have details about how the business is run or how it operates. (Alarm systems have always been an interest of mine, along with phone systems). As far as I can read form the SIA spec, the DTMF digit timing is only controlled to ensure speedy delivery of the events. (Allthough, it may be also controlled to prevent malicious users from sending false events to an alarm receiver.) My digit collection routine allows the digit ackquisition times to be adjusted. This is there for those cases where the UDP network connection introduces delays which would prevent the digits from arriving in a uniform time interval. Regarding the issue in the last paragraph, I suppose I could add some code to fork off another process and send the events one-by-one during the 200msec delay between receiving the checksum digit and sending the kissoff tone. Would this be better than storing up all the events till the caller hung up, or maybe I should support both methods? Steve. By: Mark Spencer (markster) 2004-06-05 22:57:51 This is a pretty interesting application.  Before it can be merged it will need to have a sample configuration file -- and a README would be super but not required. Secondly, is there a reason you did your own tone generation routine rather than using the playtones stuff?  If not, can you try it and make sure it works okay to avoid duplication of code? Last but not least, for some reason, I remember having trouble with "popen" before, and we had to get it out of app_voicemail because of some signalling races.  Any chance you might write something to a file and then run the command on the file?  That also might be able to create a history, independent of actually executing anything. Thanks very much for this contribution! By: hwstar (hwstar) 2004-06-05 23:17:36 Mark, No problem on the config file. I'll upload one when I complete the changes you requested below. The reason I didn't use the playtones stuff, was that the timing of the 1400 and 2300 hz tones has to be pretty tight (100msec +/-5%). When I looked at the playtones function there was something in the function which I thought added a timing uncertainty (?wiggle room). If this info is erroneous about playtones, then I will modify the code to use it. Yes, let's loose popen(). I can change the code to write to a file, then optionally call a command with the file as its argumment. Maybe build random a file name and then dump the file to a user-defined spool directory? Any problems with fork() in an app I need to know about? Steve. By: hwstar (hwstar) 2004-06-06 18:52:26 Made changes as follows: Added eventspooldir config option to specify a spool directory to write the event files into. Changed the event file code to create a random and unique event file name for a group of events, or single events as selectable by the new config option logindividualevents. Made the format of the timestamp user-specifyable with the timestampformat config option. The eventcmd option now executes a user-specified command if at least one event is received. The command is invoked using the ast_safe_system() call. Eliminated the use of popen() system call. Created and uploaded a sample configuration file. By: hwstar (hwstar) 2004-06-09 00:19:20 More changes and enhancements: ====> new app_alarmreceiver.c and alarmreceiver.conf files. Did some testing with an Ademco Vista 10SE panel purchased off of Ebay. Found a shortcoming in the design having to do with the sending of an ACK tone sequence. It seems my IAX2 connection from my DID provider can occasionally drop bits of audio here and there in the return path. (I guess that's what you get when you use a cable modem). With IAX2 gsm connections to my machine, audio dropouts which occur during the ACK tone sequence were causing the alarm panel to miss the ACK tone sequence. To address this, I added a retry mechanism for re-sending the ACK tone sequence. Changed the defaults: Loudness to 8192, first digit timeout to 2000 msec. Added a db-family configuration variable to alarmreceiver.conf. When db-family is defined, a small number of statistics variables will be kept in astDB like the number of calls received, checsum errors, and ACK retries. Steve. By: Brian West (bkw918) 2004-06-09 00:21:20 I can't unlock my panel on my system to set it up.  Oh well guess i'll have to look up my alarm guys number. bkw By: hwstar (hwstar) 2004-06-09 00:26:12 bkw- What panel do you have? If it's an Ademco Vista 10SE or 20P I might have some things to try. I have the manuals for these two panels. Steve. edited on: 06-09-04 00:11 By: cmslaght (cmslaght) 2004-06-10 09:42:54 If another panel comes up, email me off list. I have a client that is an alarm company and they may be willing to tell me. Email is my name @ issohio . com By: Mark Spencer (markster) 2004-06-21 14:35:22 Is this ready to be merged? By: hwstar (hwstar) 2004-06-21 14:56:54 Mark, I was hoping a second party would come along and also affirm it is working. I tested it with some hardware on my end and it is working correctly. I suppose the risk for incorporation is small, since the change doesn't affect other Asterisk modules, and it could be merged as is. Steve. By: Mark Spencer (markster) 2004-06-21 15:43:36 Added to CVS By: Digium Subversion (svnbot) 2008-01-15 15:00:01.000-0600 Repository: asterisk Revision: 3264 U   trunk/apps/Makefile A   trunk/apps/app_alarmreceiver.c A   trunk/configs/alarmreceiver.conf.sample ------------------------------------------------------------------------ r3264 | markster | 2008-01-15 15:00:00 -0600 (Tue, 15 Jan 2008) | 2 lines Add app_alarmreceiver (bug ASTERISK-1758) ------------------------------------------------------------------------ http://svn.digium.com/view/asterisk?view=rev&revision=3264