Advancis WinGuard
From Zenitel Wiki
Contents
General
WinGuard is the PSIM software from Advancis. Integration between WinGuard and ICX-AlphaCom or AlphaCom XE system is via the ACDP protocol (AlphaNet Data Protocol), using the link type Simple Link Layer. The following paragraphs give a short setup guide of the system, for more details please contact Advancis directly.
Licenses
In the ICX System the following license is required in order to enable the ACDP protocol: 1002602400 - ILI-IF Interface enabling
ICX and AlphaCom Setup
AlphaPro
Configure the ACDP port to be used towards WinGuard.
From the AlphaPro main menu, select Exchange & System > Serial Ports, and select one of the available ACDP links and program as follows:
- Port Type: TCP/IP server
- Link Type: Stentofon Simple Link Layer
- Broadcast: Enabled
- Port: Enter a TCP/IP port nr on which WinGuard and ICX/AlphaCom will communicate, default for WinGuard is 4001
- Keep Alive: Enabled
Web settings
From the web interface of the ICX-AlphaCom or AlphaCom XE, make certain that the TCP/IP port as selected above is defined and enabled in the Filter-page.
WinGuard Settings
Overview
The interface module AlphaCom.dll allows WinGuard to couple with an ICX-AlphaCom or AlphaCom XE Intercom server.
By the use of an INI file the interface configuration can be widely customized.
In the current version of the interface module only the ACDP protocol is supported.
Installation
The interface module and its associated files are located in an own module folder which is subordinate to the mod folder of the WinGuard installation directory and whose name is the interface name in lowercase letters, i. e. {modulefolder}.
As of WinGuard X4 Build 6, WinGuard interfaces are managed via packages. A manual change in the mod folder is no longer possible. To install interface modules, the Setup or UpdateManager must be used. If necessary, additional files ("Additions") must also be installed and distributed via the UpdateManager. The corresponding packages can be downloaded from the Partner Portal or obtained on request from Advancis.
For details on how to install or update individual interface modules via the UpdateManager, please refer to the WinGuard Manual (Chapter Update).
If you would like to use a customized INI file or LNG language file for your project, you should place your customized copy of the file concerned in the corresponding file folder of your WinGuard project directory.
Installed interface modules are now available in WinGuard and can be added as new interfaces using the System|Interfaces… menu command.
Once you have defined the interface, you should set it up.
The file folder used by interface modules
The customized INI file as well as LNG language files of an interface module must be placed in an own file (sub)folder within the Data subfolder of your WinGuard project directory. To do this, a file folder with the same name as the corresponding interface module folder must be created within the Data subfolder first.
As of WinGuard X4, creating interface file folders and inserting the customized INI/LNG files must be done with the WinGuard file explorer! For details on how to modify INI/LNG files, please refer to the WinGuard Manual (Chapter Data Supply).
Please also keep in mind that you should use the special tool Localizer to edit the LNG language files.
Settings
For interface setup click the Settings icon in the toolbar of DB: Interfaces table view to open the AlphaCom Interface Settings dialog. Following options can be specified there:
Connection type
COM / TCP/IP
Select the connection type you are using.
Interface parameters
For the connection type "COM"
Comport Settings
In the input field, enter the port and the transmission parameters for serial communication in this format:
<COM-port>:<Baudrate>,<Parity>,<Databits>,<Stopbits>
Default is COM1:9600,N,8,1 for using COM1 with 9600 baud, no parity, 8 databits and 1 stopbit. Adapt these settings to your demands if necessary.
Hardware handshake
This option defines whether communication should be controlled via RTS/CTS handshake lines.
For the connection type "TCP/IP"
IP Address : Port
Enter the IP address and port number of the ICX/AlphaCom device here.
Communication parameters
Byte timeout … ms
Specify the maximum allowed time interval between two consecutive characters while receiving telegram. If this time is exceeded, the characters received till then will be discarded. Default is 1000 ms (=1 seconds).
Message timeout … sec
If the interface module has not received any telegram from the AlphaCOM device after the time given here expired, an error message will be generated on the Internal datapoint. In this way, the device connection is monitored, since the on-going ping/pong exchange between the interface module and the Anlage panel results in a continuous telegram transmission. If this field is left blank, the communication is not monitored. Default is 40 seconds.
Command pause … ms
Some actions require a time interval between sending two commands. Here this waiting time can be defined in milliseconds.
Priorities
Alarm, Fault, Warning, Message
The priorities of events of these types can here be defined globally for all datapoints of this interface, but can be overridden individually for each single datapoint if desired.
AlphaCom Protocol
Local node, Local device
To ensure faultless functioning, please specify the node and device number of your local AlphaCOM device here, i.e. the device that is directly connected to WinGuard.
Message class for inputs … hex
The AlphaCOM device can report the status of its inputs to WinGuard. These status messages, like other event messages, can be displayed via corresponding datapoints in WinGuard. Here you should specify the so-called message class which has been programmed in AlphaCOM for these status messages. Default is 7C01 hex.
Message class for faults … hex
The AlphaCOM device can also report connection faults of its intercom stations to the interface module, which then will be handled and displayed in WinGuard correspondingly. Here you should specify the message class which has been defined in AlphaCOM for these connection fault messages. Default is 7C06 hex.
Min. number length
Here a minimum number of digits can be specified for the call numbers given in the commands. A shorter number should be padded with leading zeros. Since all call numbers are stored as numerical values within the system, this option is particularly necessary in some cases that the call numbers are given with leading zeros.
Special Functions
String after start
Specify the string that will be sent to the AlphaCOM device directly after the interface module restart.
String for * key‚ String for # key
The strings specified here will be sent to the AlphaCOM device when the corresponding key is pressed in WinGuard.
Other
Log ping/pong
If this option is set, the ping/pong exchange for permanent monitoring of the device connection will be recorded in the Interface Log, too.
Log metadata to System Log
If this option is set, the call setup is logged in the System Log.
Start and Restart
Once the interface module has been added to your WinGuard project and set up, you should start it by clicking the Module Restart icon in the toolbar. And also after adding, editing or deleting datapoints linked to this interface, a module restart is necessary for the changes to take effect.
Changes made to the configuration of the connected system may also require a module restart in WinGuard.
Upon restart, the interface module is reset to its initial state first, and then WinGuard will start replicating the states with the AlphaCOM device. After the interface module has been restarted, the states and events of the AlphaCom datapoints in WinGuard should be the same as those in the AlphaCOM device itself.
On each WinGuard workstation where it should be possible to operate a local AlphaCOM intercom station, you should assign this station as a Local station to the workstation (To do this: Open WinGuard Menu item System|Settings… –> Intercom). Before doing so, you have to define an Intercom datapoint for the local station first, and it has to be marked as Control station (See Define Datapoints).
Define Datapoints
When defining datapoints for intercom stations, make sure that you also select the Datapoint Category "Intercom" because this is the only way to access relevant system functionality via the Intercom property tab. As the datapoint Name you should use the station number, so that it can be directly dialed from the Intercom event list.
In the Link section of the DB: Datapoints form view, besides the selection of Interface and Datatype, the Node and Address must be specified for linking the datapoint definitely to the corresponding object in the AlphaCOM device. For the datatype Input additional settings are available on its own property tab. The relevant datapoint settings are described as follows:
Link
Datatype
Here the datatype for the datapoint you are defining is selected. The available datatypes are Intercom, Input, and Internal. The special datatype Internal is used for executing general commands as well as monitoring faults in interface communications.
Node
Enter the node number of the object (intercom station, input), for which you are defining this datapoint, For the Internal datapoint leave this field blank.
Address
For the Internal datapoint leave this field blank. For other datatypes enter here the number of the corresponding object (intercom station, input).
Address 2
This Field always remains empty.
Hint: While defining the Intercom datapoint for the Local station (see Start and Restart), please make sure that it is selected as Control station in its Intercom tab.
Datatype property tab: Input
Value: Event | (Event) Text | Priority | State + | State –
Here you can specify how to handle different input status values (currently 0 – 4). in WinGuard. With the entries in Event, Text and Priority a corresponding WinGuard event message can be generated; with State + and State – to set or clear the corresponding datapoint state. The different states such as "Alarm", "Message" etc. can be displayed in graphics etc. correspondingly.
Hint: If the event type "Silence" is not selected for any status value, so the possible event messages for the other status values are always marked as "without end" immediately.
Examples
A datapoint for intercom station 101 at node 1 should be defined as:
- Datatype: Intercom
- Node: 1
- Address: 101
Select also the datapoint Category "Intercom".
A datapoint for displaying a fault on input 12 at node 3 should be defined as:
- Datatype: Input
- Node: 3
- Address: 12
In the datatype property tab Input select the event type "Fault" for the status value 1 and "Silence" for 0.
The datapoint for monitoring interface communications should be defined as follows:
- Datatype: Internal
- Node: Leave this field blank
- Address: Leave this field blank
Functionality
In the current version of interface module following datatypes and their possible commands are available:
| Datatype | Command | Description |
| Intercom | Connect | Enter the number of the called station in Parameter 1. |
| Disconnect | ||
| Input | Lock | Locks or unlocks this Input datapoint WinGuard-internally. |
| Unlock | Status change of a locked datapoint will not be handled by WinGuard. | |
| Internal | SimInput | Simulates the receipt of the telegram entered in Parameter 1 (for testing purposes). |
| SendDeviceInfo | Sends device info telegram (for testing purposes). | |
| Dial | Sends $DD and then the contents of Parameter 1. | |
| SendString | Sends the contents of Parameter 1 and thus allows freely defined commands. | |
| SendPong | Sends a pong (for testing purposes). | |
In addition, the interface module uses a number of commands which, however, are only implicitly available via the Intercom Control Panel as well as with corresponding buttons in the event list in the Intercom mode.
The Configuration File (INI File)
By use of the AlphaCom.ini file the interface module's configuration can be widely customized. Furthermore, some of the texts used by the interface module can be changed and e.g. translated in this way.
Hinweis: Die INI-Datei muss entweder in ANSI- oder in UTF-16LE-Codierung gespeichert werden.
Explanations for AlphaCom.ini
The AlphaCom.ini file is divided into the following sections:
[DATATYPES]
In this section the AlphaCom datatypes are defined in WinGuard and their available commands are assigned to them. The text for the displayed datatype name (<Name>) is freely definable. User's own intercom datatypes with individual commands can be defined using <Datatype-No> between 100 and 149. The interface module will treat these special intercom datatypes like the normal intercom datatype with No. 1. If the entry of a <Command-No> is marked with an "E", this command is – on condition that it is available in the context menu of the corresponding datapoint in the Datapoint Explorer Window – executable via the events of the same datapoint. This means the command can also be accessed via the Commands symbol in the Event Window after the event to be processed has been selected in the event list.
[COMMANDS]
In this section all in WinGuard available commands for AlphaCom interface are defined, which can then be assigned to the datatypes in the section [DATATYPES]. The text for the displayed command name (<Name>) is freely definable. All commands with <Command-No> between 1 and 99 have determined internal meaning and must not be changed. Further special commands can be defined with numbers between 100 and 999, for each of them a command string can be specified individually.
[CALLS]
In this section how to handle incoming calls in WinGuard is defined. Each line defines a handling rule in the following format:
<PrioFrom>,<PrioTo>,<CallType>,<State>,<EventType>,<EventText>,<EventPrio>
| # | Parameter | Beschreibung |
|---|---|---|
| 1 | PrioFrom | Specifies a priority range for an incoming call, within which this handling rule applies. |
| 2 | PrioTo | |
| 3 | CallType | Specifies the type of the call to be handled. Possible types are [CALL] and [EMERGENCY]. According to the type specified here, calls within the given priority range are treated as call or emergency call in WinGuard, shown in the Intercom Control Panel. |
| 4 | State | A status that is set to the Intercom-Datapoint while a call within the specified priority range is pending. |
| 5 | EventType | For a call within the specified priority range an event message according to these settings will be shown in WinGuard. The text entry for <EventText> is freely definable. |
| 6 | EventText | |
| 7 | EventPrio | Set the priority for the event created. If left blank, the corresponding default setting is applied. |
Hint: For all freely definable text entries (<Name> and <EventText>) in the INI file, a so-called string Id can be used instead of entering text directly. The string Id is given in square brackets, e.g. [alphacom.datatype.intercom], and will then be replaced by the text assigned to it in the current LNG language file during runtime. In this way the INI file can be defined language-independently, i.e. the translation is completely done by use of the language files. The names of datatypes and commands can be changed via the LNG file as well.
Further details concerning the different sections and the exact format of the definition lines are given in the comments at the beginning of each section in the INI file itself. If you have edited the INI and/or LNG files for a particular project, make sure that the customized files are added to the related file folder of your WinGuard project directory as described in the WinGuard Manual.
Controlling the ICX/AlphaCom Device
The AlphaCom interface offers the possibility to send commands to the device via the Internal datapoint. The actions are carried out via graphic objects in WinGuard.
Configure graphic object for a single command
Create an appropriate graphic object as described in the WinGuard Manual. Set the following options on the Action tab in its Graphic Properties window:
- Option - Selection/Entry
- Command - Control datapoint
- Datapoint - The Internal datapoint of the AlphaCom interface
- Command - SendString
- Param 1: - The command to send, e.g. „$DD <LS> L84“ for the action "Group call to the group 84"
Configure graphic object for two commands (Param 1 and Param 2) with a pause in between
Some actions require two commands with a pause in between.
An example for call forwarding: $DD <LS> G2 → Pause → $DD <LS> G9556.
- G2 - command for call forwarding
- Pause - the waiting time between two commands.
- G9556 - the station/group to be called
To do this, set the following options on the Action tab in the Graphic Properties window of the graphic object:
- Option - Selection/Entry - Description
- Command - Control datapoint
- Datapoint - The Internal datapoint of the AlphaCom interface
- Command - SendString
- Param 1 - $DD <LS> G2 - The first command to execute (call forwarding)
- Param 2 - $DD <LS> G9556 - The second command to execute (call G9556)
Note: A break with the Command pause specified in the Settings dialog is inserted between the two commands.
Command Examples
| Action | Command Param 1 | Command Param 2 | Note | Examples |
|---|---|---|---|---|
| Alarm | $ALRM L84 L8191 | Station or group - L8191 Alarm message | $ALRM L84 L8191; $ALRM L8191 local station | |
| End alarm | $ALRM L84 L8190 | Station or group - L8190 ends the alarm | $ALRM L84 L8190; $ALRM L8191 local station | |
| Conference | $ODC L84 L8301 | Group - L8301 starts the conference | $ODC L84 L8301 starts the conference with the group 84 | |
| End conference | $ODC L84 L8300 | Group - L8300 ends the conference | $ODC L84 L8300 ends the conference with the group 84 | |
| Call forwarding | $DD G2 | $DD G9556 | Station 1 to station 2 | |
| Call transfer | $TRF L150 "I9556" | Station 1 to station 2 | $TRF L150 "I9556" from station 150 to station 9556; $TRF "I200" from local station to station 9556 | |
| End call transfer | $TRF L150 "" | Station 1 | ||
| Park | $INQ L101 | Station | $INQ L101 parks the station 101 (Only for about 5 seconds – device-specific) | |
| Group call | $DD L84 | Station or group | $DD L84 Group call to the group 84 | |
| Unpark | $UNPARK L101 | Station | $UNPARK L101 - Station 101 is being unparked. | |
Miscellaneous
AlphaCom test
In case no AlphaCOM events are shown in WinGuard, even though "something" has been added to the Interface Log, you should always test first to see if the "right" calls (must be "CallRequests") come in.
Here a simple test (provided that AlphaCom interface module has been set up in WinGuard and the local station in WinGuard displays states such as "active" etc. for connections):
- Dial the number 623 at the control station, followed by the number of the local station – In this way a CallRequest is sent to the local station.
If everything in WinGuard has been configured correctly, the action above will cause a message in WinGuard (The CallRequest can be queried using the number sequence "70". Then the connection can be established with an "8", and enter "0" to delete the request.
If this message is generated in WinGuard (it should be so in most cases, since the configuration of the interface module and its datapoints in WinGuard is not very extensive), but the calls from other intercom stations are not displayed as event messages, it is very likely due to the configuration of the AlphaCOM device – more precisely due to the configuration of its individual intercom stations. So it is advisable to find out "how" a concerned intercom station is calling. Keyword: "CallRequest".
How to display connection faults of the intercom stations in WinGuard
In order to display the fault messages of the intercom stations in WinGuard, the corresponding AlphaCOM message class for faults must be specified in the AlphaCom Interface Settings dialog. The default setting is M7C06, and this must be programmed specifically in the ICX or AlphaCom server in the Event Handler.
Create a new Event with the following settings
@01FF M7C06 %1.REF U%3.CHG(1,0)
Where the @01FF is the broadcast port for Node 1. If your Winguard is connected to another node, please edit the numbers to the correct node number.