Event Handler

The AlphaCom Event Handler

The AlphaCom exchange is an intercom exchange of which the main task is to enable uni- and bi-directional speech. In order to be able to meet as many customer requirements as possible when it comes to special features an 'Event Handler' has been implemented. The underlying idea is that by customer-programming this event handler functionality can be implemented which is not part of the standard feature list. The event handler is unique in the world of intercom. It is what gives the exchange its flexibility and makes it possible to meet most, if not all, customer requirements. The Event Handler is based on the software concept that when the intercom functions run, they report 'events' to a part of the software called the Event Handler. The event can be described as a trigger that sets off an action in the system depending on the information entered in AlphaPro, the programming tool for the AlphaCom exchange. In this way, the Event Handler provides a powerful engineering tool for configuring system behaviour to meet requirements from customers. The basic idea can be illustrated as follows:

Actions can be simple, just to operate a relay under certain circumstances. Actions can also be programmed using a scripting language and can include conditional statements. An action can itself trigger a new event, making it possible to start a chain of actions.

Contents of the Event Handler technical description - The principal - Events

Event triggers which have a station as event owner - Audio : type 01 - Door opening – During connection : type 02 - Door opening – Automatic lock : type 03 - Station in use : type 04 - Microphone open : type 05 - Priority mail present : type 06 - Conversation – Incoming : type 07 - Conversation – Outgoing : type 08 - Private ringing mode : type 09 - Received mail : type 10 - Call requester mode : type 11 - Priority mail in idle : type 12 - Faulty station line : type 13 - Event Trigger Feature : type 15 - Simplex Conference Audio : type 16 - Simplex Conference Member : type 17 - Open Duplex Conf. Ringing : type 18 - Open Duplex Conf. Connection : type 19 - Mail Timeout : type 20 - Event Timeout : type 21 - New Current mail in station queue : type 23 - New first mail in station queue : type 24 - Event Trigger with User Parameter : type 25 - Event Trigger Start with User Parameter : type 26 - System Event : type 27

Scheduling

Event actions - RCO - Action strings - Commands - Parameters and macro operations - Statements

Event Handler technical description

The principal An event has an owner, the source which triggers the event. The following possible owners are defined:

A station. It is possible to group stations together by a UDP-flag in order to give such a group common behaviour. The scheduler, the internal AlphaCom clock which generates a ‘tick’ every minute. In the case of the scheduler the event is the ‘minute tick’. Stations can trigger many different types of event. Many events can trigger an action when the event is activated and when the event is de-activated, for instance event type 07: Conversation – Incoming. The On/Off action can be differentiated by the ‘When Change To’ flag. Events can be, but don't have to be, related to a specific directory number or a group of stations, for instance:

Owner: Station 1 Event: Conversation - Outgoing Related to: Directory number 102 When change to: ON Action: RCO 2 ON In this case the relay connected to RCO 2 will only be activated if 'Station 1' is in conversation with a station with directory nr 102, AND if Station 1 was the station which made the call. If 'Related to' was not specified, that same relay would be activated on any call which Station 1 would make.

Events An event is a trigger that sets off an action in the system. An event can be:

An internal audio event in the program An event triggered by some external device An exchange feature An internal error report (for instance 'station disconnected') A data protocol command An event can set off an action that can control:

Some external hardware through an RCO output A defined action or a set of actions in the system software A data command to the exchange itself (this gives the possibility to use all AlphaNet dataprotocol commands to control what happens) A data command to another exchange A data command to external equipment Event triggers which have a station as event owner Audio : type 01 The audio events are intended for PA control or mobile radio keying, that is, as an extension to the audio function of the 'owner' station. Normally the action for this event is the operation of an RCO. The Audio event is divided into a number of sub-events, which are closely related to each other, and which can be combined to operate the same RCO. User Defined Properties (UDP's) cannot be used with Audio events. Audio events are not associated with a 'related to' number. In AlphaPro the sub-events can be selected after clicking the 'Details'-button.

Always: Both incoming and outgoing calls: Simplex listen (release own M-key, or conversation partner presses the M-key) Tones Sending Gong (this station makes a group call) Voice message The station state must be: Handset ON or Volume / Handset override.

Application:

Non-selective mobile radio, PA Incoming call: Incoming Simplex listen (release own M-key, or conversation partner presses the M-key) Tones The station state must be:

Incoming call Handset ON or Volume/Handset Override Note: The event is reported OFF (and stays OFF) if the user touches any key or the handset. This is called 'take down', as it is intended to transfer an incoming call from an external RCO-controlled speaker to the station’s internal speaker when the user touches any key or the handset.

Private ringing: Incoming call only: Ringing tone (on/off for each tone period) The station state must be:

Incoming call Handset ON or Volume/Handset Override Application:

Lamp for incoming call, flashing with the tone bursts Voice paging: Receiving Gong Voice Paging The station state must be:

Handset ON or Volume/Handset Override Audio program: The station state must be: Handset ON or Volume/Handset Override Program conference: Program conference, when another station feeds it with audio (M-key pressed) The station state must be:

Handset ON or Volume/Handset Override Door opening – During connection : type 02 The action is on the owner, when digit 6 is pressed on the related station. The event reports an ON and an OFF transition. ON when digit 6 is pressed on the related station, OFF after a period as set for the timer ‘RCO pulse time’. If 'Related to' is not defined, all stations can open the door. If 'Related to' is defined only the related station (either single or part of a UDP-group) can open the door.

Door opening – Automatic lock : type 03 This owner dials a directory number with feature 59 (code lock). The event reports an ON and an OFF transition. ON when the feature is dialled, OFF after a period as set for the timer ‘RCO pulse time’. This event has no ‘related to’ relationship.

Station in use : type 04 Whenever the station is busy. This event has no ‘related to’ relationship.

Microphone open : type 05 Whenever the station LED is lit. Do not use this to indicate conversation, as the event will go OFF in many situations; also, it will be ON when feeding a Group Call, Simplex Conference etc. This event has no ‘related to’ relationship.

Priority mail present : type 06 There is at least one mail with priority above 100 (programmable as a global value ‘Priority Mail Queue Indication’) in the mail queue of the owner. Notes:

The event occurs every time a mail enters the queue, that is, there are many ON events followed by one OFF. The event also stays ON during connections. Not well suited as a buzzer control. The event can be temporarily switched OFF/ON by dialling 7882 (which toggles the event). It will then stay OFF until the mail queue is emptied, and another priority mail arrives. This event has no ‘related to’ relationship.

Conversation – Incoming : type 07 This event reports ON when a connection is established and OFF on disconnection. The event is reported when the owner receives a call. The event can be related to specific calling stations.

Conversation – Outgoing : type 08 This event reports ON when a connection is established and OFF on disconnection. The event is reported when the owner makes a call. The event can be related to specific called stations.

Private ringing mode : type 09 Incoming private ringing (or call transfer ringing). The event goes ON at the start of the ringing, and OFF when the station enters conversation, or ringing stops due to time-out or C-key. The event can be related to specific calling stations.

Received mail : type 10 Occurs for each mail entering the owner station queue. The event goes ON when the mail is put into the queue, and OFF when removed from the queue. The event can be related to specific stations sending mail.

Call requester mode : type 11 Occurs when this station dials a Call Request, which sends a mail to another station’s mail queue. The event goes ON when the station has been put into the queue, and OFF when either the entry is deleted from the queue, or the station has been used for something. This event is then active while the station has voice message/flash/ringing. As the event is reported OFF as soon as the station is used for anything, even if only the C-key has been pressed, this event cannot be used to reliably indicate whether this station has originated a call request which has not been answered yet. The event can be related to specific stations in which queue the mail is put. As from AMC-software 9.05 the 'related to' parameter can be a UDP-flag.

Priority mail in idle : type 12 Behaves as ‘priority mail present’ above, but is switched OFF during connections and back ON every time the station becomes idle. As such it is well suited to switch on and off audible indicators, which should be silent during an established connection. This event has no ‘related to’ relationship.

Faulty station line : type 13 Occurs if the owner’s line monitoring has found a problem or if the whole line board becomes faulty. There is also a ‘faulty station’ indication on the exchange level, which becomes active if one or more stations are faulty. The main difference is that this event also reports the OFF status (indication that the problem has been resolved), while the report on exchange level only reports the event ON status. This event has no ‘related to’ relationship.

Event Trigger Feature : type 15 The owner station dials a directory number with feature 52 (event trigger without tone) or 85 (event trigger with cancel tone) which triggers the defined events. When the event is triggered by physically dialling the ‘related to’ directory number, the event can only report an ON status. If the event is triggered from a data protocol message, it is also possible to report an OFF status. The field ‘sub-type’ can be used to group event triggers. This field is associated with the parameter (ID) field of the feature. This means that a number of event trigger directory numbers can be defined with the same parameter. If the ‘related to’ field is set to ‘ALL’ and the ‘sub-type’ field is set to that same parameter value, all these directory numbers will trigger the same event. When used in conjunction with the data protocol message $ER, the owner does not need to be a physical station, but can be a dummy (non-existent) station. This can be useful when an RCI needs to trigger a lengthy action string, which exceeds the allowed length for the RCI action string itself. The action string for the RCI can then be an event report on a dummy station, where the real actions are performed on the event trigger on this dummy station. The event is also triggered on dialling a directory number with feature 95 (Event trigger with user parameter). In this case the event reports ON when the event directory number has been dialled and OFF when the event is ‘disconnected’. In the case of feature 95, this is useful functionality. Feature 95 directory numbers do not disconnect immediately after connection (like feature 52 or 85 directory numbers), but either time out after 20 seconds, or can be disconnected via a data protocol message $DISCON_ST. The event must be related to a directory number which triggers the event.

Simplex Conference Audio : type 16 Occurs on all stations which are members of a simplex conference, when audio is present in the conference. Normally, the event is triggered by an RCI with a $VOX data protocol message in the action string. The ‘related to’ directory number must be the directory number of the relevant simplex conference.

Simplex Conference Member : type 17 Occurs when this station joins or leaves a simplex conference.

Sub-event 0 = Audio via station line card (ASLT, etc.) Sub-event 1 = Audio via AGA conference circuit. The ‘related to’ directory number must be the directory number of the relevant simplex conference.

Open Duplex Conf. Ringing : type 18 Incoming ringing when a station is included in an Open Duplex Conference by another station. The event goes ON at the start of the ringing, and OFF when the handset is lifted, or ringing times out. The ‘related to’ directory number must be the directory number of the relevant open duplex conference.

Open Duplex Conf. Connection : type 19 During connection, i.e. conference audio open. The ‘related to’ directory number must be the directory number of the relevant open duplex conference.

Mail Timeout : type 20 A timer can be set on a mail event by using the command $SMT (SET_MAIL_TIMEOUT). When the timer expires a ‘Mail Timeout’ event is reported. The event must have an owner. The timer can be set with a ‘related to’ parameter. This parameter is reported and can be used as the %2 parameter in an action string. This event can be used for instance to higher the priority level of a call request, if the request is not ansered within a certain period. This period is set by the time-parameter of the $SMT-command.

Event Timeout : type 21 A timer can be set with the data protocol command $ST (SET_TIMER). When the timer expires, the event ‘Event Timeout’ is reported. The event must have an owner. If a time out period not intended for a specific station is required, a dummy station can be used as owner. The timer can be set with a ‘related to’ parameter. This parameter is reported and can be used as the %2 parameter in an action string.

New Current mail in station queue : type 23 An event is reported each time the current mail in a station queue is changed. Reported both when change due to manual browsing or due to a new high priority mail first in queue, or that the current mail is deleted. The ON report is sent 0,5 second after browsing to a new mail element. The event is also repeated when stopping at the end of the queue. The event is reported OFF when the current mail is left due to any reason. %1 is the queuing station, %2 is the mail sender. %TAG included. The delay on the on-report is programmable in NVRAM: timeouts.mail_event_delay

New first mail in station queue : type 24 Reported when a new mail arrives first in a stations queue. Only reported ON. Will not be reported when the second mail becomes first because the first was deleted. It can be used to start a buzzer when the first request arrives, or when a higher priority request arrives. %1 is the queuing station; %2 is the mail sender. %TAG included.

Event Trigger with User Parameter : type 25 This event can be triggered from directory numbers associated with different features. The behaviour is different for these 2 features.

Feature 95, which allows the user (the event owner) to dial a directory number as parameter: The user first dials the feature code for the event trigger. Then the user is supposed to dial a directory number. After the directory number is dialled, this event is triggered. The %1 parameter is the station where the function is dialled; %2 is the dialled directory number. The event sub-type in the Event Report is set to the value of the parameter-attribute of the Event Trigger directory number. This can be used to define several user-defined actions. The feature does not disconnect after the event has been triggered. The station just hangs silently, until it disconnects after 20 seconds. The data protocol message $DISCON_ST can be used to make the station disconnect with the selected tone. The Event Handler programmer can then control the feedback to the user, using this message in combination with the $DISPLAY_TEXT message. The user can also dial more than one directory number. An event is triggered for each directory number dialled; %2 is the dialled directory number. This can be used to make 'dynamic grouping' functions, see example. An Event Report is also generated immediately after the initial feature code is dialled: ‘Event Trigger Start with User Parameter’, see below. The Event Trigger Feature number 15 event is also reported, with the %2 parameter set to the directory number of the event trigger feature. The events reports ON when the event trigger has been dialled and OFF when the feature is disconnected (the Event sub-type is always ‘0’). Feature 105. When activating this feature all succeeding digits are reported to the event handler and trigger this event where the event sub-type is equal to the digits dialled 0-9. The event is ON as long as the station key is down and reported OFF when key is released, which can for instance be used for camera control from the station keyboard, see example. Directory numbers assigned FEAT_DIGIT_EVENT (105) with the parameter-attribute set to ‘0’ display the digit while it is held down in the second line of the station display; if the parameter-attribute is different from ‘0’ the display is not updated and can be updated by the event handler to indicate ‘left’, ‘up’, ‘on’, etc…. The features times out after 20 seconds after the last pressed digit. The digit press on a CRM4 is only reported ON for a few hundred milliseconds. The digit release is handled by the internal station software and is not dependent on the physical length of the button press. Event Trigger Start with User Parameter : type 26 An event trigger feature, triggered after dialling a directory number with feature 95. It is closely associated with the event trigger as described above. It is generated immediately after the initial feature code is dialled. The %1 parameter is the station where the function is dialled (the owner). If the station has mail in its queue, the %2 parameter is set to the sender of the current mail. Otherwise %2 is empty.

System Event : type 27 Event type 27 is triggered by system events. In the AMC software, %1 is hardcoded to physical station 1. The event does not recognise a 'related to' parameter. In AlphaPro 'When Related To' must be set to 'All'. - Sub-event 1-208 are used for device up/down reports. - Sub-events 65-68 (exchange modules) use the global timer 'start_evn_delay' (default value '1') before the event is triggered ON. There is no delay for the event OFF trigger. The ON event is triggered when all cards are scanned. - Sub-events 210-217 are used for serial ports 1-7 up/down reports, but only for ports in multi-module or AlphaNet mode.

Scheduling Scheduling is to program the AlphaCom to do actions at specified hours, weekdays or dates. Scheduling is an extension to the Event Handler and is defined as type 22. Each minute a MINUTE_TICK event is generated, with the current time as parameter. Scheduling rules consists of a time condition and a normal Event Handler action. There are two variants of time conditions:

Date and time: yy-mm-dd hh:mm. Each digit can be a wild card *, matching all tick-values in that position. Example: The rule '**-**-** 12:00' will be triggered every day at 12:00. List of weekdays and a time: mtwtfss hh:mm. In AlphaPro there is a checkbox for each weekday. Each digit in the time can be a wild card *. Example: The rule mtwtf-- **-**-** **:00 will be triggered every hour Monday to Friday. For each MINUTE_TICK event the tick time is matched against all scheduling rules. All matching rules are executed. During normal operation the minute tick is executed between 1 and 2 seconds after start of the minute. In order to not miss important actions while the exchange is down, or if the clock is moved forward, there is a time catch-up mechanism to handle this.

The last generated minute tick is stored in NVRAM. Up to 24 hours are caught up after a power off, or after the real-time clock has been set forward. -One minute tick is generated every second until the scheduling tick time has caught up with real time (can take up to 24 minutes). During this period the scheduling time is different from real time. During normal operation the MINUTE_TICK event is generated with the change-flag set to ON. During catch-up the change is set to OFF. In this way catch-up ticks can be filtered away. The %chg() parameter can be used in the action string to test if it is a normal operation or catch-up. As from AMC software version 9.05 it is possible to use the 'When Change To' flag to trigger the event depending on the type of minute tick: - ON : the event will be triggered on 'real' ticks - OFF : the event will be triggered on 'catch-up' ticks - ON or OFF : the event will be triggered on both types of ticks. If the clock is set backwards, (e.g. daylight saving time at autumn), the scheduling time is set back immediately, and the ticks are performed as normal during the overlapping period. %1.clk, %1.clkmin %1.clkhour parameters etc. will return the scheduling tick time, not the real time if used within a Scheduling action. %clk (without the '1.') will always return the real time. In AlphaPro the time and date of an event is stored in the 'ID' and 'related to' fields. In this case 'ID' and 'related to' must be viewed in a different way compared to when the owner of an event is a station. 'ID' and 'related to' are merely a convenient place to store the parameters.

Event actions There are 2 types of action:

An action string which can be entered in the ‘Command-filed’ as ASCII characters An action on an RCO RCO When an RCO is selected from the drop-down list, the event will operate that specific RCO. The RCO-status will follow the 'change'-status as follows:

'ON' selected: The RCO will be made active when the ON-action of the event is triggered 'OFF' selected: The RCO will be de-activated when the OFF-action of the event is triggered 'ON or OFF' selected: The RCO status will follow the 'change'-status; activated for ON, de-activated for OFF Action strings As an alternative to the above RCO-operation it is also possible to enter a command-string in the action-field. An action string can contain:

Command (internal commands and data protocol messages) Parameters and Macro operations Statements and Conditions Action strings are stored in multiples of 16 bytes. A new action string always starts on a 16-byte boundary. This means that if all action strings have a maximum of 16 characters, it is possible to define 2000 action strings.

Commands The commands can be internal commands and data protocol messages. The internal commands are:

PRS - Program to Station PRG - Program to Group CNG - Conference to Group MST - Mail to Station MGR - Mail to Group MPP - Mail to Pocket Pager AMS - Alarm Message to Station AMG - Alarm Message to Group RCO - set Remote Control Output EDO - send text to serial port (External Data Out) text is enclosed between "" Non printable ASCII characters can be inserted in the text: \xyy : yy is any ASCII value in HEX \r = RETURN \n = linefeed \t = tab LOG - send text to exchange’s log port (printed with date/time) IND - indicator control for CRM4 keyboard LEDs etc. OWN - modify event’s owner and related to values WUDD - WUDD index value : Command string action to write a value to User Defined Data. The value is changed immediately, before the next statement is executed. This command can only be used to change values in the local exchange. To write data in the User Defined Data area of a remote exchange, the data protocol message $WUDD should be used: $WUDD UINT2 index, UINT2 value Parameters and macro operations Parameters and macro operations in an action string are preceded by the '%'-sign. They both return a value. %xxx() macros can be nested freely, building complicated expressions. Some parameter-types are associated with the owner, the 'related to' field or the change flag; this is indicated by '%n', where 'n' can have the value 1, 2 or 3:

%1: the parameter is associated with the owner field %2: the parameter is associated with the 'related to' field %3: the parameter is associated with the change flag Parameters and macro’s:

%n.dir(length,filler) : - n can be 1 or 2 - empty () can be omitted; %n.dir is equivalent to %n.dir() - shortform: %nd %n.phy(length,filler) - n can be 1 or 2 - empty () can be omitted; %n.phy is equivalent to %n.phy() %n.nod() - n can be 1 or 2 %n.ref - n can be 1 or 2 %n.nam(length,filler) : returns the display text - n can be 1 or 2 - shortform: %nn %n.dak(DAK search string,D_10 range) - n can be 1 or 2 %n.exp : External Feature Parameter - n can be 1 or 2 %n.DEV : returns the device number (as from AMC 9.03). - n can be 1 or 2 - if n equals 2, it will work only if the 'related to' parameter is a station in the same node %n.BRD : returns the board number (as from AMC 9.03). - n can be 1 or 2 - if n equals 2, it will work only if the 'related to' parameter is a station in the same node %n.PORT : returns the port number (as from AMC 9.03). - n can be 1 or 2 - if n equals 2, it will work only if the 'related to' parameter is a station in the same node %3.chg(on_text,off_text) - %3.chg(,) can be shorted to %chg(,) %3.RFT(normal_text,refresh_text) : Action command parameter which substitutes the parameter with a text describing the on/off transition of the event. Some events can be reported many times (e.g. line errors), and it's possible to have different actions depending on if this is the first time, or a ReFresh. - can be shorted to %3r(on_text,off_text) %1.mpri : returns the priority of the mail %1.mfre : returns the free text of a station mail if it is available, otherwise '-' %1.tag : returns the mail tag %sng(station, group) : (Station Next Group). Returns the next group after group of which station is a member. Returns '0' if station is not a member of any (more) groups. %sng(station, 0) returns the first group of which station is a member. - group is 1 – 100, station is physical number 0 – 552. %gns(group, station) : (Group Next Station). Returns the next station after station which is a member of group. Returns ‘0’ if no more members in group. %gns(group, 0) returns the first station in group. - group is 1 – 100 - station is physical number 0 – 552. %sgm(station,group) (Station Group Membership). Returns '1' if station is a member of the group. - group is 1 – 100 - station is physical number 0 – 552. %UDD(index) : Command string macro to get the User Defined Data out of the location 'index'. %SEV : Returns the sub-event number (in decimal format) of the event being processed. If the sub-type of en event is defined as 255, the main event will be triggered independent on the reported sub-type. If this is used with feature 105, 'Event trigger on dialling digits', %SEV will return the dialled digit. (introduced in AMC software 9.03) %OP( , , ) : macro for numeric calculations. The general format is %OP(integer1,operator,integer2), no space is allowed between ',' and the operator. The operator can be: - + add - - subtract - * multiply - / divide - < less - <= less or equal - > greater - >= greater or equal - = equal - == equal - != not equal - << bit shift left / up - >> bit shift right / down - && logical and - || logical or - & bitwise and - | bitwise or - ! logical not of second operand - ^ bitwise xor %clk - returns current date/time 2000-11-10 12:59:35 %clkyear - returns current year: 2000 %clkmon - returns current month: 11 %clkday - returns current day: 10 %clkhour - returns current hour: 12 %clkmin - returns current minute: 59 %clksec - returns current second: 35 %clkwday - returns current day of week: 5 (1 = monday, 7 = sunday) %1.clk, %1.clkmin %1.clkhour etc. will return the scheduling tick time, not the real time if used within a Scheduling action. %GNV() : returns the value of the NVRAM-parameter, of which the address is specified in between () (as from AMC 9.05). - %GNV(1,3,54) returns the value of 'ex_profile.timeouts.th_conn_length' in AMC 9.05. Note that the address can be different in different AMC software versions. Statements

PAUSE pauses the event handler command interpreter for 100ms IF/ENDIF Conditional statement. If the text/expression after the keyword IF evaluates to ‘0’, all following commands/statements are skipped until the keyword ENDIF is encountered; IF/ENDIF statements can be nested STOP The statement STOP stops the execution of the action string. Is only useful in front of the keyword ENDIF