VS-SDK for AlphaCom

Introduction

ICX-500 and ICX-Core software are fully compatible with the VS-SDK for AlphaCom. In the rest of this article ICX (for ICX -500 and ICX-Core) can be read for AlphaCom; only when there is a noticeable difference between ICX and AlphaCom, ICX will be referred to separately. The SDK name itself will remain VS-SDK for AlphaCom for the time being.
The SDK provides dll's, helpfiles and some sample software to make integration of 3rd party software with ICX as easy as possible. Three sample applications are delivered including source code. These 3 samples cover many (if not all) aspects of what normally is expected from an integration with ICX. Users of the SDK are allowed to freely use parts of the sample source code in their own software.

The information in this article is relevant for the SDK release 2.1.3.1 and higher. For releases 1.3.3.2 and earlier, please refer to the manual which was included in the SDK package.

Licensing

The possibility to retrieve intercom station state information from the exchange is a licensed feature, and requires the presence of an ‘API/OPC interface’ license in the ICX or AlphaCom for at least as many stations of which the status has to be retrieved.

ICX

With ICX it is possible to purchase a single Product Key which covers all stations connected to all ICX's in a network. ICX licenses can be stacked, i.e. 1x 1002602306 + 2x 1002602309 gives 1088 API licenses which can be used on 2 or more ICXs.

• 1002602306 - ILI-API64 - API License Supporting 64 Stations
• 1002602309 - ILI-API512 - API License Supporting 512 Stations

AlphaCom E/XE

Every AlphaCom in an AlphaNet requires a license.

• 1009649901 - STENTOFON API License Supporting 40 Stations
• 1009649902 - STENTOFON API License Supporting 80 Stations
• 1009649903 - STENTOFON API License Supporting 160 Stations
• 1009649904 - STENTOFON API License Supporting 240 Stations
• 1009649905 - STENTOFON API License Supporting 320 Stations
• 1009649906 - STENTOFON API License Supporting 400 Stations
• 1009649907 - STENTOFON API License Supporting 552 Stations

Installation

VS-SDK for AlphaCom is distributed as a zip-file containing 2 windows installer packages

• VS-SDK for AlphaCom_Setup_Vx.x.x.x.msi
• AlphaNetServiceProviderService_Setup_Vx.x.x.x.msi

The package VS-SDK for AlphaCom_Setup_Vx.x.x.x.msi contains the SDK files. The files are by default installed to C:\Program Files(x86)\Vingtor Stentofon\VS-SDK for AlphaCom\, with links on the User Program folder (All Programs) "Vingtor Stentofon". The setup will install the following:

• The latest release of the Stentofon.AlphaCom.* libraries
• The latest compiled help files from the libraries
• The latest bundle of example applications including source code

For more information about AlphaNetServiceProviderService_Setup_Vx.x.x.x.msi, see below and the article AlphaNetServiceProvider.

DLL description

Stentofon.AlphaCom.AlphaNet.dll

The Stentofon.AlphaCom.AlphaNet.dll implements the AlphaCom Data Protocol and handles the communication with the AlphaCom XE exchanges. It raises events and exposes methods to be able to receive data from, and send commands to the exchange. The .dll supports auto-discovery of the complete AlphaCom XE network configuration. This makes the system very easy to configure and set up. In addition, the .dll will track and report all state changes in the AlphaCom XE network which the 3rd program subscribes to. The .dll supports the STENTOFON AlphaNet. This means that all AlphaCom XE exchanges and stations in a network can be addressed by having an IP connection to just one of the AlphaCom XE exchanges. The .dll requires Microsoft .NET 4.6.2 The DLL contains three name spaces:

• Messages
• Client
• Config

The AlphaNetClient object in Stentofon.AlphaCom.AlphaNet.dll maintains a database (named Stations), which stores the stationstate. The database is updated automatically by the AlphaNetClient. The Stations database is available when the AlphaNetClient is created

_client = new AlphaNetClient(…
_client.Stations

Stentofon.AlphaCom.Data.dll

The Stentofon.AlphaCom.Data.dll is not required anymore (see the paragraph above), but is available on request for backward compatibility for developers who want to upgrade from SDK 1.x.x.x. Note that Zenitel recommends that during the upgrade all references to events and methods supported by this dll are removed and that the dll is not used at all.
The Stentofon.AlphaCom.Data.dll provides a standardized way of storing and retrieving AlphaCom XE network, exchange and station information and states. Storage can be in an MSSQL database or in memory ’AlphaComStateStorages.MSSQL’ or ‘AlphaComStateStorages.IN_MEMORY’. The .dll requires Microsoft .NET 4.6.2 The DLL contains one name space:

• State

The AlphaNetClient object in Stentofon.AlphaCom.AlphaNet.dll maintains a database (named Stations) which contains the same information as AlphaComState object in Stentofon.AlphaCom.Data.dll, as shown below:

private AlphaComState _stateStorage;
  _stateStorage = new AlphaComState(AlphaComStateStorages.IN_MEMORY);

Communication with the AlphaCom XE exchange

Software based on the SDK have 2 possibilities to communicate with AlphaCom:

• Direct connection to either TCP port 61112 or 61113
• Connection via a 'Service Provider'

Also when there is an AlphaNet of multiple AlphaCom servers, it is only necessary to connect to a single AlphaCom, it does in this case not matter with which AlphaCom the connection will be established.

Direct connection

ICX-AlphaCom and AlphaCom have 2 communication ports available for API/OPC based software, ports 61112 and 61113. These 2 ports are independent.
The number of simultaneous connections that can be made to these ports depends on the AlphaCom or ICX-AlphaCom software version.

• As from ICX-AlphaCom 1.1.3.0 the TCP-server has been re-implemented; until then an API/OPC port on an ICX-AlphaCom only supported 1 connection, if more connections were required it was possible to use similar ports on other exchanges as described in the bullets below; Now the total number of connections in an AlphaNet has the limitation as below, where it is possible to use a single port on a single server to provide those connections (all servers must have the same softwarwe version):
  • 120 API connections
  • 30 OPC server connections
• As from AMC-IP software version 12.3.3.2 and ICX-AlphaCom 1.0.3.0 it is possible to use up to 10 ports (61112/61113), divided over at least 5 exchanges. Ports 61112 and 61113 only accept a single connection.
• All earlier software only allows 2 simultaneous connections, 1 to port 61112 and 1 to port 61113. In an AlphaNet, once a port is used on one AlphaCom server that same port number is blocked on the other servers

AlphaNetServiceProvider

If the number of connections needs to be expanded, please see the paragraph above, it is possible to use the AlphaNetServiceProvider. This 'Service provider' is included as from SDK version 2.1.3.1. The service provider will itself connect to either port 61112 or 61113; it will then make a single new port available which accepts multiple conections for other software to connect to. In effect the service provider acts as a port expander.

TCP communication ports

To be able to communicate with either of port 61112 or 61113, the port must be enabled in the exchange using AlphaWeb, the web server which is integrated in the AlphaCom XE. Log in to AlphaWeb and select ‘System Configuration/Filters’ and enable the required port number for the physical Ethernet port the API will connect to.

Connecting to the AlphaCom XE

At software start up it is only necessary to provide the following information:

• IP address of AlphaCom or service provider
• Port to connect to
  • 61112 or 61113 for AlphaCom
  • The port to connect to as configured for the service provider
• Information whether the connection is direct or via the service provider
  • DIRECT_TCP
  • PC_REMOTE

Calling the method _client.Connect(); will then:

• Establish the connection
• Discover all nodes which are part of the AlphaNet
• Discover all intercom stations which are configured in each of the nodes
• Handle all messages which are required to keep the connection

More information about the AlphaNetServiceProvider

The AlphaNetServiceProvider is available both as an application and as a service.
More information about the AlphaNetServiceProvider is available on AlphaNetServiceProvider.

AlphaCom Data Protocol message classes

The API communicates with AlphaCom XE via the AlphaCom Data Protocol. The ‘.Messages’-namespace provides classes for AlphaCom Data Protocol Messages.

using Stentofon.AlphaCom.AlphaNet.Messages;

Event reports

Activity inside the exchange can raise events. The following is an example. Register for some events:

// Register for some events
_client.OnStationConnect += HandleStationConnect;
_client.OnStationDisconnect += HandleStationDisconnect;

The event handlers:

#region The AlphaNet Handlers
private static void HandleStationConnect(StationConnect sc)
{
  // Use the objects internal ToString() method:
  Console.WriteLine(sc);
}
private static void HandleStationDisconnect(StationDisconnect sd)
{
  Console.WriteLine(sd);
}
#endregion

If only part of the information contained in an object is of interest, then there are a multitude of methods available to retrieve just that information, as for example:

private static void HandleStationConnect(StationConnect sc)
{
  Console.WriteLine(“ A: {0}”, sc.StationA.GetDirNo());
}

Sending commands to AlphaCom XE

Commands to the AlphaCom XE server are normally related to a station. When a guard clicks on an area on his PC screen to make a call or cancel an established call, it is just as if he presses keys on his intercom station. All information related to an intercom station is part of an object of type StationState. The StationState class also has the methods implemented to format commands to be sent to the AlphaCom XE on behalf of an intercom station. Methods where the name starts with MakeCommand, will format and store the command. The AlphaNetClient class method SendAlphaCommand sends the stored command to the exchange.

private StationState _selectedStation
  _selectedStation.MakeCommandCKey();
  _client.SendAlphaCommand(_selectedStation);

API custom events

All standard AlphaNet broadcast messages will always be sent out from all available OPC/API ports. All important activity in the exchange is reported as a broadcast message and is therefore able to raise an event in the API. But there may be a specific interface requirement which depends on an action inside the exchange for which there is no API event available, as there is no related broadcast message. To be able to support such requirements there are four custom events which can be raised:

• OnCustomParameter event
• OnCustomString event
• OnCustomStringParameter event (available as from SDK version 2.1.3.3)
• OnCustomWordStringParameter event (available as from SDK version 2.1.3.3)

The AlphaCom XE exchange features an internal event handler with trigger points on any possible action inside the exchange. By programming a custom message inside the exchange event handler related to the relevant action of the specific interface, it is possible to raise the above listed API events.
Addressing scheme:

• As from AMC-IP software version 12.3.3.1 and ICX-AlphaCom 1.0.3.0 use @*D1 - this will broadcast the message out of all open OPC/API ports in all servers in an AlphaNet.
• For previous AMC-IP software versions, the data must be sent out via specific ports using this address scheme:
  • @nnC7 – for port 61112
  • @nnC4 – for port 61113

nn is the node number and can be in the range 01-FE (1-254). TCP ports 61112 and 61113 are handled by the AlphaCom XE exchange as devices with device number 199 (0xc7) for port 61112 and 196 (0xc4) for port 61113.

The notation of the API port is mandatory between firmware versions. Below AMC 12.3.3.1 / ICX 1.0.3.0 *MUST* use @01C7 or @01C4. From AMC 12.3.3.1 / ICX 1.0.3.0 *MUST* use @*D1

OnCustomParameter event

To raise the API OnCustomParameter event, the exchange must send a message with MessageID 0x7f01 followed by 7 parameters. The first two parameters are of type NET_OBJ_REF, the other 5 parameters are of type UINT2. Most of the time, the first two parameters will be the 'owner' and the 'related to' directory numbers of the event which was triggered inside the AlphaCom XE. An example of an action in the event handler action field is:

• @*d1 M7F01 %1.ref %2.ref Wpar1 Wpar2 Wpar3 Wpar4 Wpar5

Where:

• @*d1 is the broadcast address for OPC/API ports is an AlphaNet (available as from AMC-IP software version 12.3.3.1)
• par1, par2, par3, par4 and par5 can be any value from 0 to 65535

If one of the two NET_OBJ_REF parameters is not relevant, the NULL value should be used, which is:

• U0 – NULL value for parameter type NET_OBJ_REF

Note that all parameters must be passed. NET_OBJ_REF parameters which are not relevant to the interfacing application must be set to NULL; UINT2 parameters which are not relevant can be set to any arbitrary value.

OnCustomStringParameter event

To raise the API OnCustomStringParameter event, the exchange must send a message with MessageID 0x7f02 followed by up to 7 parameters. The first two parameters are of type NET_OBJ_REF, the other 5 parameters are of type string. Most of the time, the first two parameters will be the 'owner' and the 'related to' directory numbers of the event which was triggered inside the AlphaCom XE. An example of an action in the event handler action field is:

• @*d1 M7F02 %1.ref %2.ref "str1\tstr2\tstr3\tstr4\tstr5\t"

Where:

• @*d1 is the broadcast address for OPC/API ports is an AlphaNet (available as from AMC-IP software version 12.3.3.1)
• "str1\tstr2\tstr3\tstr4\tstr5\t" combines upto 5 string parameters in one string out of the AlphaCom
  • \t separates each string parameter; note that \t must also be used after the last string parameter
  • It is possible to pass fewer than 5 string parameters

If one of the two NET_OBJ_REF parameters is not relevant, the NULL value should be used, which is:

• U0 – NULL value for parameter type NET_OBJ_REF

OnCustomWordStringParameter event

To raise the API OnCustomWordStringParameter event, the exchange must send a message with MessageID 0x7f03 followed by up to 12 parameters. The first two parameters are of type NET_OBJ_REF, followed by 5 parameters of type UINT2 and up to 5 parameters of type string. Most of the time, the first two parameters will be the 'owner' and the 'related to' directory numbers of the event which was triggered inside the AlphaCom XE. An example of an action in the event handler action field is:

• @*d1 M7F03 %1.ref %2.ref Wpar1 Wpar2 Wpar3 Wpar4 Wpar5 "str1\tstr2\tstr3\tstr4\tstr5\t"

Where:

• @*d1 is the broadcast address for OPC/API ports is an AlphaNet (available as from AMC-IP software version 12.3.3.1)
• par1, par2, par3, par4 and par5 can be any value from 0 to 65535; all 5 parameters must be passed
• "str1\tstr2\tstr3\tstr4\tstr5\t" combines upto 5 string parameters in one string out of the AlphaCom
  • \t separates each string parameter; note that \t must also be used after the last string parameter
  • It is possible to pass fewer than 5 string parameters

If one of the two NET_OBJ_REF parameters is not relevant, the NULL value should be used, which is:

• U0 – NULL value for parameter type NET_OBJ_REF

OnCustomString event

With the OnCustom...Parameter events described above, most interface requirements can be met. For those requirements which are not covered by events, it is possible to use the OnCustomString event. Any number of parameters of any type will be passed as a single string. To raise the API OnCustomString event, the exchange must send a message with MessageID 0x7f00. All following parameters will be sent as one large string, decoding of which will be application specific.

Method to send ACDP messages

The underlying protocol of the API is the AlphaCom Data Protocol. To send commands to the AlphaCom XE, specific methods (some of which are described in the sections above) have been implemented. These methods result in the API sending the appropriate ACDP command to the exchange. Sometimes it can be an advantage to send an ACDP command directly to the exchange. For this purpose, a method has been implemented which takes the ACDP command as a parameter in Simple Link Layer format.

Public bool SendAlphaCommand(String cmd)

The statement below will set up a call between stations with directory numbers 101 and 102:

SendAlphaCommand("$CALL L101 L102");

Intercom station state

By setting the flag AutoGetStationState the API will discover all intercom stations in all discovered exchanges. For each discovered station, the API will raise the OnStationStateReceived event. This can therefore be used to get an accurate overview of the connected intercom stations and their status at the time of the connection of the API to the exchange. Most applications need to be able to retrieve 'StationState' at any moment and 'Stentofon.AlphaCom.Data.dll' stores this information so it is readily available.

Sample software

Three applications, including their source code, are included in the SDK. Most events and methods which are used in the majority of applications are also used in the 'Stations-Basic' and 'CallRequest' sample applications. The 3rd application 'Stations' is a further development of the 'Stations-Basic' application but adds control for 'Multi-conferencing', an advanced mixing capability which requires AMC-IP software 12.3.3.2 or higher and VSIS-4.7 or higher.

• Stentofon.AlphaCom.Example.CallRequest
  • Connects directly to AlphaCom - select portnr 61112 or 61113
  • Autodiscovery of nodes and stations
  • Ability to select a station as master in 'Station Search/Select'
  • Shows incoming call requests
  • Accept a call request by selecting a queue entry in the dropdown box 'Selected Station Queue'
• Stentofon.AlphaCom.Example.Stations-Basic
  • Connects directly to AlphaCom or via the service provider - in the latter case, make certain that AlphaNetServiceProviderAppl.exe is running
  • Autodiscovery of nodes and stations
  • Ability to select a station as master in 'Station Selector and Status' - start typing a directory number in the text field to populate the dropdown box, select an entry in the dropdown box
  • Show status of the selected station
  • Dial digits, as if pressing digits on a keypad
  • Operate 'M' and 'C'
  • Operate 10 DAK (Direct Access Key) buttons
• Stentofon.AlphaCom.Example.Stations
  • Connects directly to AlphaCom or via the service provider - in the latter case, make certain that AlphaNetServiceProviderAppl.exe is running
  • Autodiscovery of nodes and stations
  • Ability to select a station as master in the TAB 'Station Control'
  • Show status of the selected station
  • Dial digits, as if pressing digits on a keypad
  • Operate 'M' and 'C'
  • Operate 10 DAK (Direct Access Key) buttons
  • Play voice messages to the selected station
  • Show Station RCI status
  • The TAB 'Station Matrix' allows the selection of 4 stations to view their status
  • The TAB 'Conference Control' requires in-depth knowledge of setting up Turbine stations as conference mixers

Differences between SDK versions 1.x.x.x and 2.x.x.x

Connecting to AlphaCom

Connect() replaces the separate methods StartListening() and StartMonitorThread()

Station state updates

It was required to update 'stationstate' via software on events such as 'OnStationBusyReceived', 'OnStationFreeReceived', 'OnStationConnect', 'OnStationDisconnect'. Stationstate updates are now automatic as part of the AlphaNetClient object.

AlphaNet Service Provider

Note: The use of the AlphaNet Service Provider is not necessary when using ICX-AlphaCom version 1.1.3.0 or higher, as the OPC/API ports now accept multiple connections: ICX_1.1.3.X_-_Release_Notes#ICXEL-20_Multiplexing_API_Port_61112_and_61113

AlphaCom only has ports 61112 and 61113 available for connection of API based software; these ports only accept a single connection each. The Service Provider will connect to either port 61112 or 61113 (configurable) and will make one new port available which accepts multiple connections. The connection type can be set to:

• DIRECT_TCP
• PC_REMOTE

Logging

A new dll 'Gurock.SmartInspect.dll' has been included. This dll writes logging information in a file with extension '.sil'; This file may help Zenitel in case the developer experiences issues with the communication between his/her application and the AlphaCom. The log file is placed in C:\Users\%USERNAME%\AppData\Roaming\STENTOFON\SDK\Logs