View source for OPC UA for Zenitel Connect Pro

{{C}}

This article describes a Node-RED implementation (flow) for an OPC-UA server integration with the '''Zenitel Connect Pro Platform'''. The Node-RED flow makes it possible to connect OPC-UA clients to the ZCP.

For installation of Node-RED see the article: [[Node-Red - Installation]]

__TOC__

<br>
==Installation==
The following section describes the setup of the OPC-UA Server on ZCP VM (VM VirtualBox).<br>

#Install the ZCP Virtual Machine (VM) image: Zenitel_Connect_VBox_x.y.z. The package is available from Jenkins. After a successful installation configure the ZCP system with stations.
#Install the Node-RED package for ZCP VM image: Zenitel_Connect_VM_x.y.z-node-red.swu. The package is available from Jenkins. Maybe you need to use FireFox for accessing the ZCP SW update page.
#Update the firewall in the ZCP. Port 1880 is used for accessing Node-RED GUI from a Browser. Port 53880 is use as the OPC-UA Server endpoint (Listening port). Port 4840 is used by OPC-UA Device Discovery.
#Connect to Node-RED GUI using a browser: <ZCP IP-address>:1880
#From the "Manage Palette" install:
##node-red-contrib-zenitel-opcua.
##node-red-contrib-zenitel-wamp-auth.
##node-red-dashboard.
#Download the OPC-UA Server implementation flow for WAMP from (https://github.com/Zenitel-AS/) and import the flow to Node-RED.

<br>
If the Node-RED package for ZCP is installed it will appear in the container status list accessible via the ZCP GUI. 
[[File:Node-Red Package Installed.jpg|thumb|left|700px|ZCP Node-RED Package]]
<br style="clear:both;" />

The firewall of the ZCP should allow port 1880, 53880 and 4840. 1880 and 4840 are fixed while 53880 is user selectable. This port will in this setup be used as the OPC-UA endpoint (listening port). 
[[File:Node-RED OPC-UA Ports_V02.jpg|thumb|left|500px|Ports Opened for Node-RED OPC-UA]]
<br style="clear:both;" />

The picture below shows the necessary libraries for the OPC-UA Server
[[File:InstallFromPalette.jpg|thumb|left|500px|Libraries Installed from Palette]]
<br style="clear:both;" />
<br>

==Configuration==
<br>
When setting up an OPC-UA Client/Server system a OPC UA Discovery Server has to be installed too. The OPC-UA Discovery Server can conveniently be installed on the same host as the OPC-UA Server.
OPC-UA Server needs to register at an OPC-UA Discover Server in order to make it visible to OPC-UA Clients. An OPC-UA Client may then ask the OPC-UA Discovery Server if any OPC-UA server is available on the desired port and the level of security supported by the OPC-UA server. 
The OPC-UA Discovery Server Node is available in the node-red-contrib-zenitel-opcua library.<br>
For a .Net solution an OPC-UA Discovery Server may also be downloaded from the OPC Foundation Home Page. In that case the Node-RED OPC-UA Discovery Server should be disabled.
<br>
[[File:OPC_UA_Discovery.jpg|thumb|left|300px|OPC-UA Discovery]]
<br style="clear:both;" />
<br>

===Wamp Library Setup===
<br>
Some of the WAMP library nodes need to be configured.<br>
Double on the node "com.zenitel.calls"

[[File:ConfigureComZenitelCalls.jpg|thumb|left|300px|Confifuration of com.zenitel.calls]]
<br style="clear:both;" />
<br>

Press the button with pencil icon for edit:

[[File:ConfigureWampClientNode.jpg|thumb|left|300px|Confuguration of wamp.client.node]]
<br style="clear:both;" />
<br>
The first line is the IP-address of the ZCP. Change this if required. The protocol "wss" and port 8086 MUST not be changed.<br>
The realm "zenitel" MUST not be changed.<br>
Set user name and password as next. The user/password must be defined as a Link-User in ZCP.<br>

[[File:ConfigureEventSubscriberHandler.jpg|thumb|left|300px|Configuration of Event Subscription Handler]]
<br style="clear:both;" />

The second parameter of the "Event Subscription Handler" must be "msg.topic". Users of this node will handle the URL of the event which should be monitored.
<br>
<br>

===OPC-UA Library Setup===
<br>
The configuration OPC-UA library is shown below. Double click on the shown node and change the parameters. From here it is possible to configure the level of security that should be supported by the OPC-UA Server.

[[File:OPC_UA_Server.jpg|thumb|left|700px|OPC-UA Server Configuration]]
<br style="clear:both;" />

The "Write Client" is used for updating the OPC-UA Server.
[[File:WriteClient.jpg|thumb|left|700px|Write Client]]
<br style="clear:both;" />
<br>
The OpcUa-Client node is used for implementing subcription of changes of OPC-UA variables (nodes),
[[File:OPC_UA_HandleSubscription.jpg|thumb|left|700px|OPC-UA Handle Subscription]]
<br style="clear:both;" />
<br>

==Connecting a OPC-UA Test Client==
<br>
The free-ware OPC-UA client from UAExpert is used for testing connectivity of an OPC-UA client. It can be downloaded from "https://www.unified-automation.com/downloads.html".
Connecting the client to a server is initiated by selecting the "Project" tab (or "Project" folder if the tab is not available) and right-click "Server" and select "Add".
<br>

[[File:UAExpert.jpg|thumb|left|700px|UaExpert Start Up]]
<br style="clear:both;" />

Select "Custom Discovery" and "Add Server". Enter IP-address and port number for the OPC-UA Server endpoint and press "OK"
[[File:AddServer.jpg|thumb|left|700px|Add a Server]]
<br style="clear:both;" />

If the following pop-up windows is shown - just accept and press "Yes"
[[File:GetEndPoint.jpg|thumb|left|300px|GetEndPoints Fails]]
<br style="clear:both;" />

Also, the following pop-up window should be closed by pressing "Yes".
[[File:Hostname.jpg|thumb|left|300px|Replace Hostname]]
<br style="clear:both;" />

Select signature and encryption for the connection.
[[File:SelectSignAndEncryption.jpg|thumb|left|700px|Select Signature and Encryption]]
<br style="clear:both;" />

If the follwing pop-up window is shown press "OK".
[[File:RecentlyUsed.jpg|thumb|left|300px|Recently Used]]
<br style="clear:both;" />

Select the configured server and press the "Connect" button.
[[File:ConnectServer.jpg|thumb|left|700px|Connect Server]]
<br style="clear:both;" />

Set check mark in "Accept the server certificate ..." and press "Continue".
[[File:BadCertificateUntrusted.jpg|thumb|left|300px|Certificate Validation]]
<br style="clear:both;" />

Close this pop-up window by pressing "Ignore".
[[File:BadCertificateHostNameInvalid.jpg|thumb|left|300px|Bad Certificate Host Name]]
<br style="clear:both;" />

Select "View" from the tool bar and "Address Space".
[[File:ShowAddressSpace.jpg|thumb|left|500px|Select Address Space]]
<br style="clear:both;" />

The Zenitel Connect Pro folder is now available.
[[File:Folder_ZenitelConnectPro.jpg|thumb|left|500px|Zenitel Connect Pro Folder]]
<br style="clear:both;" />
<br>
<br>

==Operation==
This section describes how to used the OPC-UA Server to access the ZCP. The provided functionality is identical with the Zenitel Link interface and has the same structure as shown on the Swagger Page.<br>
<br>

===System===
Selecting the System folder you will see the available functions.
<br>
[[File:Operation_System.jpg|thumb|left|300px|System Folder Operations]]
<br style="clear:both;" />
<br>

To request and retrieve the System Platform Version you select the request (left-click) "GET System Platform Version" and drag it to the "Data Access View" tile, double click the "Value" column, set the "get_value" check mark and push the "Write" button.
<br>

[[File:GetSystemPlatformVersion.jpg|thumb|left|500px|Request System Platform Version]]
<br style="clear:both;" />

Click the "Software Version" in the "Address Space" tile and the ZCP response is available in the "Attribute" tile in the "Value" entry. The "Value" is the JSON string received from ZCP.
<br>
[[File:ReadSoftwareVersion.jpg|thumb|left|500px|Read System Platform Version]]
<br style="clear:both;" />
The table shown below list the available function in the "System" folder, where to request the update and where to read the received data from the ZCP.
<br>
<br>
{| class="wikitable" style="margin:left"
|+System Functions
|-
!Set Request in!!Retrieve Data from
|-
|GET Audio Messages||Audio Messages
|-
|GET Device Account||Device Accounts
|-
|GET Directory||Directory
|-
|GET Groups||Groups
|-
|GET Net Interfaces||Net Interfaces
|-
|GET System Platform||Software Version
|}
<br>

===Device===
<br>
{| class="wikitable" style="margin:left"
|+Device Functions
|-
!Set Request in!!Retrieve Data from
|-
|POST Key||No Data
|-

|}
<br>
<br>

===Call Handling===
<br>
{| class="wikitable" style="margin:left"
|+Call Handling Functions
|-
!Set Request in!!Retrieve Data from
|-
|DELETE Call Id||No Data
|-
|DELETE Calls||No Data
|-
|GET Call Legs||Call Legs List
|-
|GET Call Queues||Call Queues List
|-
|GET Calls||Calls List
|-
|POST Calls||No Data
|-
|POST Open Door||No Data
|}
<br>

===Events===
<br>
To monitor received events the "Event View" has to be added to the monitoring tile. Left click on "Document" from the menu bar and select "Add".

[[File:AddDocument.jpg|thumb|left|300px|Add Document]]
<br style="clear:both;" />
<br>

In the pop-up window select document type "Event View" and press "Add".

[[File:AddEventView.jpg|thumb|left|500px|Add Event View]]
<br style="clear:both;" />
<br>

A tile named "Event View" is now added to the UaExpert OPC-UA client. To Add the server to the Event Viewer - select "Server" from the "Address Space" tab and drag it to the "Event View" tab:

[[File:AddServerToEventView.jpg|thumb|left|500px|Add Server to Event View]]
<br style="clear:both;" />
<br>

To enable for instance TRACE Call event drag "TRACE Call" to the "Data Access View" and select "Value". Set the two input parameters "enabled" and "set_value" and push "Write"

[[File:TRACE_Call.jpg|thumb|left|500px|Enable TRACE Calls]]
<br style="clear:both;" />
<br>

Make a call from one of the stations configured in the ZCP system. The call events in connection wilt he call will be listed in the "Events" tile. The "Message" column will show the JSON formatted call event as it has been received from ZCP. 

[[File:CallEventReceived.jpg|thumb|left|500px|Call Event Received]]
<br style="clear:both;" />
<br>

To display last received call event select CallEvent-AlarmText. The JSON formatted call event is displayed in "Attribute" tile in the entry "Value".

[[File:CallEventAlarmText.jpg|thumb|left|500px|Call Event Alarm Text]]
<br style="clear:both;" />
<br>

The table below shows the available event that may be subscribed
<br>
{| class="wikitable" style="margin:left"
|+Event Subscription
|-
!Set Request in!!Retrieve Data from
|-
|TRACE Call||CallEvent
|-
|TRACE Call Leg||CallLegEvent
|-
|TRACE Device Account||DeviceAccountEvent
|-
|TRACE Device GPI||Device_GPI_Event
|-
|TRACE Device GPO||Device_GPO_Event
|-
|TRACE Open Door||OpenDoorEvent
|}
<br>

==Terms and Abbreviations==
{|
|OPC
|Open PLatform Communications
|-
|UA
|Unified Architecture
|-
|ZCP
|Zenitel Connect Pro
|}

[[Category: Zenitel Connect Pro]]
[[Category: Zenitel Connect Pro Integrations]]
[[Category: OPC]]