Actions

VS-SDK for AlphaCom

From Zenitel Wiki

Revision as of 09:57, 23 October 2017 by Hvd (talk) (→‎Method to send ACDP messages)
AlphaCom icon 300px.png

This article is under construction. The software described here is not available yet.

Introduction

The SDK provides dll's, helpfiles and some sample software to make integration of 3rd party software with the AlphaCom 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 AlphaCom. 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.2.1 and higher. For releases 1.3.3.2 and earlier, please refer to the manual which was included in the SDK package and the article AlphaCom SDK.

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 AlphaCom XE exchange for at least as many stations as that of the status to be retrieved.
Note that every AlphaCom in an AlphaNet requires such 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 windows installer package VS-SDK for AlphaCom_Setup_Vx.x.x.x.msi. 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

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

Stentofon.AlphaCom.Data.dll

The Stentofon.AlphaCom.Data.dll is not strictly required, but it 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

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

AlphaCom has 2 communication ports available for API/OPC based software, ports 61112 and 61113. These 2 ports are independent. In an AlphaNet, it is possible to use up to 10 ports, divided over at least 5 exchanges (this AlphaNet capability is available as from AMC-IP software version 12.3.3.2). Ports 61112 and 61113 only accept a single connection.

Service provider

Sometimes there is a requirement for more connection points to an AlphaCom. As from SDK version 2.1.3.1 a 'Service provider' will be included. This 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

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

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. All AlphaNet broadcast messages will always be sent out from both these 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 two custom events which can be raised:

  • OnCustomParameter event
  • OnCustomString event

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.

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: @nnff M7F01 %1.ref %2.ref Wpar1 Wpar2 Wpar3 Wpar4 Wpar5 Where:

  • nn is the node number of the AlphaCom XE exchange to which the API connects; It can be any value from 0x01 to 0xfe, represented by 01 to FE
  • 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:

If, for any reason, the message should only be sent to either port 61112 or 61113, @nnff can be replaced by:

  • @nnC7 – for port 61112
  • @nnC4 – for port 61113

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.

OnCustomString event

With the 7 parameters which can be passed as part of the OnCustomParameter event described above, most interface requirements can be met. For those requirements which are not covered by those 7 parameters, 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

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'. The new event 'OnStationState' will do this automatically, and provides a reason for the event trigger: 'StationUpdateReason'

AlphaNet Service Provider

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

Retrieved from "https://wiki.zenitel.com/w/index.php?title=VS-SDK_for_AlphaCom&oldid=158824"