res_alarmsystem: Add self-contained alarm system module.

res_alarmsystem is a module that can be used to implement
an alarm system within Asterisk. The basic functionality
is split into "client" and "server" roles, although
the "server" role is technically optional. This allows
the average home user with an Asterisk server at home
and off-site to have a professional-grade alarm system
with custom monitoring and reporting, all for the cost
of any sensors required.

WARNING: This module comes with ABSOLUTELY NO WARRANTY.
Use of it is solely at your own risk.

PHREAKSCRIPT-32 #close

README.md

@@ -70,6 +70,9 @@ PhreakScript installs:
       - ``PhreakNetDial``
       - ``SIPAddParameter``
       - ``IRCSendMessage``
+      - ``AlarmSensor``
+      - ``AlarmKeypad``
+      - ``AlarmEventReceiver`` (not to be confused with ``AlarmReceiver``)
       - ``Softmodem`` (third-party, with compiler fixes and enhancements, including TDD modem)
       - ``TddRx``, ``TddTx`` (third-party)
    - Adds the following functions:

configs/samples/res_alarmsystem.conf

@@ -0,0 +1,83 @@
+; res_alarmsystem.conf
+
+; This configuration allows configuring an alarm system using Asterisk. There are two roles
+; that exist, client and server. Clients receive input from one or more sensors and
+; report alarm events to a server. Typically, these will be different Asterisk servers,
+; with clients at individual sites and a single, centralized server receiving events from them,
+; but they could also both run on the same server if desired.
+; However, it is RECOMMENDED that the server role not be at a location with sensors.
+; This way, if someone were to sabotage the alarm system at the client side prior to
+; the breach event, the alarm server will still be aware that something has gone wrong.
+
+; WARNING WARNING WARNING This alarm system implementation comes with absolutely no warranty,
+; use it at your own risk!
+
+; *** Server configuration
+
+[general]
+bindport=4589 ; UDP port to which alarm server will bind, if any servers are enabled.
+;bindaddr=0.0.0.0
+
+[myserver] ; Defines an alarm server to which alarm clients can report.
+type = server
+ip_loss_tolerance = 60 ; Number of seconds the server will tolerate not receiving pings from clients before considering
+                       ; IP connectivity to a client to have been lost (which will trigger the internet_lost alarm).
+contexts = myserver-contexts ; A config section which defines dialplan contexts to execute for each alarm event
+logfile = /var/log/asterisk/alarm_server.log ; Log file for this server
+
+[clients] ; Special section defining clients authorized to report to this server
+;A101 = 1D7B ; one entry for each client, with client ID as the key and client PIN as the value
+
+; *** Client configuration
+
+[myclient] ; Each alarm client is defined in its own section
+type = client
+client_id = A101 ; Unique, telenumeric ID (0-9,A-D) for this client. Should be unique across all clients that report to a server.
+                 ; Note that there is no security mechanism to restrict reporting aside from the client ID.
+				 ; Therefore, if the alarm server is exposed to the Internet, you may wish to use long, hard-to-guess client IDs
+				 ; to prevent spoofed reports, or lock down your firewall accordingly.
+;client_pin=1D794B61 ; PIN, if required by server for authentication
+server_ip = 127.0.0.1:4589 ; IP/port to reach alarm server over IP
+server_dialstr = DAHDI/g1/*70w18005551212 ; A dial string for "POTS phone failover" to reach alarm server if unable to by IP. If you need to use dial options, use a Local channel to encapsulate the Dial() call.
+   ; The server should call AlarmEventReceiver() (NOT AlarmReceiver() !!!) when receiving such a call.
+   ; NOTE: When reporting an alarm trigger, the line will stay open until disarm_delay has been reached, to avoid making multiple calls in succession
+phone_hangup_delay = 45 ; Number of seconds to keep phone failover line open upon reporting event for reporting further events in that time.
+                        ; It is recommended this setting be at least 10-15 seconds, so that if phone failover is being used,
+                        ; a single phone call is sufficient to report sensor trigger and alarm disarm events, rather than dialing up a second time to report this event.
+                        ; You may want to tweak this based on the cost of each call, cost per minute, and the acceptable amount of delay in setting up a call. Default is 45.
+ping_interval = 4 ; How often to ping the server
+egress_delay = 15 ; number of seconds grace period to exit without re-triggering alarm
+contexts = myclient-contexts ; A config section which defines dialplan contexts to execute for each alarm event
+logfile = /var/log/asterisk/alarm_myclient.log ; Log file to which to log alarm events.
+
+[myclient-contexts]
+type = contexts
+; In this section, the key is the name of the alarm event for which the specified dialplan will be executed,
+; and the value is the dialplan [exten@]context to execute. If exten is omitted, s will be used. The priority will always be 1.
+;
+; okay = okay@myclientalarm ; Normal initialization
+; triggered = triggered@myclientalarm ; Sensor has triggered alarm
+; restored = restored@myclientalarm ; Sensor restored to normal (will not auto-disarm pending alarm)
+; disarmed = disarmed@myclientalarm ; Alarm disarmed by user
+; tempdisarmed = tempdisarmed@myclientalarm ; Alarm temporarily disarmed by user
+; breach = breach@myclientalarm ; Breach (failure to disarm active alarm) has occured
+; internet_lost = iplost@myclientalarm ; Internet connectivity to alarm peer lost
+; internet_restored = iprestored@myclientalarm ; Internet connectivity to alarm peer restored
+
+[door] ; Section defining a door sensor
+type = sensor
+sensor_id = 1 ; Unique, numeric ID for this sensor. Should be unique across all sensors belongng to all clients that report to a server.
+client = myclient ; Client associated with this sensor
+device = DAHDI/23 ; if specified, then arg2 to AlarmSensor is optional since we can use the channel to determine which sensor was activated
+                   ; (This way, the same context can be specified for all sensors, using immediate=yes in chan_dahdi.conf)
+disarm_delay = 45 ; Number of seconds grace period permitted to disarm an active alarm after this sensor triggers before it is considered a breach.
+                  ; Default is 60.
+
+[keypad] ; Section defining alarm keypad settings. An alarm keypad can be instantiated by using AlarmKeypad()
+type = keypad
+client = myclient ; Client associated with these keypad settings
+keypad_device = PJSIP/Polycom ; dial string for alarm keypad endpoints to autodial when alarm is triggered. Use a Local channel for predial options to autoanswer.
+pin = 1234 ; Hardcoded PIN which must be entered to disarm the alarm. Multiple PINs can be permitted by providing multiple comma-separated PINs.
+audio = custom/siren ; An optional audio file to play while waiting for the alarm to be disarmed. By default, a tone is played.
+cid_num = DISARM SYSTEM NOW ; Caller ID number to use for outgoing calls to the keypad device
+cid_name = ALARM PANEL ; Caller ID name to use for outgoing calls to the keypad device

phreaknet.sh

@@ -1856,6 +1856,7 @@ phreak_patches() { # $1 = $PATCH_DIR, $2 = $AST_SRC_DIR
 
 	phreak_tree_module "configs/samples/verify.conf.sample" "1" # will fail for obsolete versions of Asterisk b/c of different directory structure, okay.
 	phreak_tree_module "configs/samples/irc.conf.sample" "1" # will fail for obsolete versions of Asterisk b/c of different directory structure, okay.
+	phreak_tree_module "configs/samples/res_alarmsystem.conf.sample" "1"
 
 	phreak_tree_module "funcs/func_dbchan.c"
 	phreak_tree_module "funcs/func_dtmf_flash.c"
@@ -1873,6 +1874,7 @@ phreak_patches() { # $1 = $PATCH_DIR, $2 = $AST_SRC_DIR
 		phreak_tree_module "res/res_deadlock.c" # this is not possibly useful to non-developers
 	fi
 
+	phreak_tree_module "res/res_alarmsystem.c"
 	phreak_tree_module "res/res_digitmap.c"
 	phreak_tree_module "res/res_irc.c"
 	phreak_tree_module "res/res_msp.c"