Event Management Subsystem
The Event Management Subsystem is a method by which a user can specify actions to be taken when certain events occur, such as transitions in receive and transmit keying, presence and modes of links, and external inputs, such as GPIO pins on the URI (or similar USB devices) or the parallel port.
This also includes the ability to set the condition of external devices, such as output pins on a URI (or similar USB devices), or a parallel port. See the Manipulating GPIO page for more information on how to configure GPIO.
The actions to be taken and the methods and steps required for doing so are specified in the rpt.conf
file under the [events]
stanza (or other named sections, defined with the events=
option).
Event Variables
This subsystem utilizes Asterisk channel variables (or global variables if you dare) to indicate the state of various signals and modes and are named as follows:
Variable Name | Decription |
---|---|
RPT_RXKEYED | Set to 1 when the node's main (RF) receiver is receiving a valid signal |
RPT_TXKEYED | Set to 1 when the node's main (RF) transmitter is transmitting |
RPT_NUMLINKS | Count of links currently connected to the node |
RPT_LINKS | List of Node numbers currently linked to this node and their mode and receive keying status, as follows: <NUMLINKS>,<MODE><NODEMUM>[,<MODE><NODEMUM>...] . For example: 2,T2000,R2001 would indicate that there are two nodes linked currently, the first one is node 2000 in Transceive mode, and the second one is node 2001 in Receive-only (monitor) mode. |
RPT_NUMALINKS | Count of adjacent links currently connected to the node |
RPT_ALINKS | List of node numbers currently linked adjacent to this node, their mode, and receive keying status as follows: <NUMALINKS>,<NODEMUM><MODE><RXKEYED>[,<NODEMUM><MODE><RXKEYED>...] . For example: 2,2000TU,2001RK would indicate that there are two adjacent nodes linked currently, the first one is node 2000 in Transceive mode, and is not presently sending a keying signal (U) towards this node; the second one is node 2001 in Receive-Only (monitor) mode, and is presently sending a keying signal (K) towards this node. |
Adjacent Nodes
Adjacent nodes are ones that are directly connected to this node. This differs from the RPT_LINKS
in that the RPT_LINKS
is a list of all nodes, whether connected directly, or connected through a node that is connected directly. The keying information is not given with the RPT_LINKS
because in that context, it is meaningless.
There may also be other variables included from external devices/sources, such as the URI (or similar USB devices), or a parallel port that will appear if so configured (within the configuration for that particular device), such as:
Variable Name | Decription |
---|---|
RPT_URI_GPIO1 | This would be the GPIO 1 pin, if configured as an input. |
RPT_URI_GPIO4 | This would be the GPIO 4 pin, if configured as an input. |
RPT_PP12 | This would be the parallel port, pin 12 (input) |
These are set to 0
or 1
(the state of the input pin).
[events]
Stanza
Each line of the [events]
stanza is specified as follows:
<action-spec> = <action>|<type>|<var-spec>
actions
:
-
If the
action
isv
(for "setting variable"), then theaction-spec
is the variable being set. -
If the
action
isg
(for "setting global variable"), then theaction-spec
is the global variable being set. -
If the
action
isf
(for "function"), then theaction-spec
is a DTMF function to be executed (if the result is1
). -
If the
action
isc
(for "rpt command"), then theaction-spec
is a rawrpt command
to be executed (if the result is1
). -
If the
action
iss
(for "shell command"), then theaction-spec
is a shell command to be executed (if the result is1
).
types
:
-
If
type
ise
(for "evaluate statement" (or perhaps "equals")), thevar-spec
is a full statement containing expressions, variables and operators per the expression evaluation built into Asterisk. -
If
type
ist
(for "going True"), thevar-spec
is a single (already-defined) variable name, and the result will be1
if the variable has just gone from0
to1
. -
If
type
isf
(for "going False"), thevar-spec
is a single (already-defined) variable name, and the result will be1
if the varible has just gone from1
to0
. -
If
type
isn
(for "no change"), thevar-spec
is a single (already-defined) variable name, and the result will be1
if the variable has not changed.
Examples:
Set the channel variable MYVAR
true if main receiver has valid signal and transmitter is not transmitting. Presumably, this variable will be used in a later statement for something.
MYVAR = v|e|${RPT_RXKEYED} & !${RPT_TXKEYED}
Have the system give the time of day after all links are disconnected. This performs the specified rpt command
when the RPT_NUMLINKS
variable goes from true
to false
, and therefore happens when all links are disconnected (if and only if some were connected previously).
status,2 = c|f|RPT_NUMLINKS
Boolean Evaluation
Although RPT_NUMLINKS
is an integer count of links, it can also be treated as a boolean, since non-zero values evaluate to the same as 1
.
Execute the DTMF command *1234
(whatever the heck that is) when node 2000
connects to this node.
TEMPVAR = v|e|${RPT_LINKS} =~ "\",2000.\""
*1234 = f|t|TEMPVAR
Note
We are interested in executing the function ONLY when the node connects. Therefore, you must define a variable the meets the condition you are looking for in general (in this case, node 2000 being connected), then you have to execute the desired function when that variable goes from 1
to 0
(changes to false
).
Any time you are using regex to look for a node number int the RPT_LINKS
variable, you must put a comma in front of the qualifying string to make sure that it does not match some other node number that has the desired information (in this case, the digits 2000
) within a longer node number.
Get a detailed directory listing of the /tmp
directory, and put its output into the file /tmp/example.txt
every time node 2001
is connected to, and stops indicating keying towards our node (not that anyone would ever really want to do that... it's just an example).
TEMPVAR = v|e|${RPT_ALINKS} =~ "\",2001[TRC]K\""
ls -l /tmp > /tmp/example.txt = s|f|TEMPVAR
CLI Commands
If you wish to set channel variable(s) for a node from the Asterisk CLI, use the following command:
*CLI> rpt set variable <nodenum> <name=value> [<name=value>...]
For example, this would set the MYVAR
variable to 1
for node 2000
:
*CLI> rpt setvar 2000 MYVAR=1
If you wish to display all the variables for a node, use the following command:
*CLI> rpt show variables <nodenum>
Also, a channel variable for a node may be set from the Asterisk dialplan as follows:
rpt(<nodenum>,V,<name=value>)
For example, for extension 1234
priority 5
, set variable MYVAR
to 0
for node 2000
:
exten => 1234,5,rpt(2000,V,MYVAR=0)
Granted, there may very well be some things (such as interesting information that can be expressed within this subsystem) that has been overlooked, and any suggestions and/or comments regarding this whole thing would be much appreciated.
This also opens a completely new avenue of customization and individual creativity for each system implementer. There are many innovative things that can be done with this. Also, there are many just plain silly ones, such as connecting your doorbell to one the input pins on the URI, and having the system connect to your favorite Echolink node or something when someone rings the doorbell.