Basic Usage

UaGateway can be connected to servers using multiple protocols: OPC UA TCP, OPC DA, OPC AE and OPC XML-DA. All these connections are published to other clients as OPC UA TCP, OPC DA and OPC AE servers. UaGateway comes with a graphical user interface and with it connections to servers and server endpoints can be configured. Next, I will present two common use cases with UaGateway.

Use case #1

In the first use case, an OPC UA client is connected to traditional OPC DA or AE servers and to an OPC UA server through a firewall. This is a common use case when trend data and process event messages need to be transferred from the process to higher level information systems, such as Manufacturing Execution Systems (MES). Traditional OPC uses DCOM for communication between computer nodes. Firewall configuration is complex for DCOM communication, because DCOM dynamically assigns port numbers for connections. Therefore it is best to use OPC UA to communicate through firewall, because OPC UA uses only one TCP port for communication. In this use case, only one UaGateway is needed to aggregate data from three servers. UaGateway eliminates the need for other products that would combine data from multiple OPC servers.

Use case #2

In the second use case, an OPC DA client is connected to an OPC DA server over Internet. OPC DA uses DCOM to communicate and communication with DCOM over Internet cannot be done efficiently. Fortunately, OPC UA uses single port TCP communication which can be used over Internet with ease. OPC DA nodes can be connected to separate UaGateways which communicate with OPC UA to each other. In the OPC UA Security Model, asymmetric encryption and authentication methods are introduced, which assure safe and confidential communication over Internet.

Summary

UaGateway is a simple solution to start upgrading your systems to using OPC Unified Architecture. With it, the pitfalls of traditional OPC can be avoided. It allows you to use your old systems in harmony with newer ones. There is no question of either/or, with UaGateway, both OPC UA and traditional OPC can co-exist in an industrial communication system.

This tutorial will concentrate on development for Android phones, so we will be using Android 2.3, but everything here also applies to the tablet world (Android 3.x) pretty well. Haven’t tested on 4.0 yet, but should run okay there as well.

Gearing up

To begin, you will need the Prosys OPC UA Java SDK. You can request an evaluation edition or purchase it on our website at http://www.prosysopc.com/. With the same credentials, you can download the demo project discussed here from https://www.prosysopc.com/opcua/JavaSDK/samples/AndroidSampleProject.zip

In addition, you’ll need Eclipse and the Android SDK, available from (http://www.eclipse.org/ and http://developer.android.com/) respectively. Install Eclipse and the Android SDK after that. The ADT plugin for Eclipse is also very useful, please see instructions for installing it http://developer.android.com/sdk/eclipse-adt.html#installing/. I assume here that you have some level of familiarity with Eclipse and Java in general. Also check out the SDK tutorials (especially the Client tutorial) to get a grip on how the SDK is meant to be used. Of course, you could also just dive right in and start off by examining the demo project, which is a simple GUI client for reading the time off a server.

Creating your project

After installing the Android SDK, Android projects are added to the New Project wizard in Eclipse. When you create your project, you will need to specify the version of Android you’re developing for. If you have an Android device available for testing, try to match its version, otherwise you can just select 2.3.1 (API version 9). If you want to use an emulator (handy even if you have a real device you’re developing for), you can create one using the SDK Manager that comes with the Android SDK. Select New… and simply enter a name and a target, you can leave the rest of the parameters as they are.

You will need to add the four .jars (bcprov, log4j, Opc.Ua.Stack and the SDK jar itself) in the Java SDK to your project’s build path. Optionally, in order to use SDK’s inbuilt logging, you can also add log4j-over-slf4j. The SDK uses log4j, whereas Android uses slf4j and thus this kind of bridge is needed. This way you can view the SDK’s output in DDMS along with other Android logging. log4j-over-slf4j is available at http://www.slf4j.org as part of the slf4j download package.

You’ll also need to modify the Android manifest to allow your application to create a connection. This is done by modifying AndroidManifest.xml, you can insert

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

just below uses-sdk in the manifest file. Similarly, if your application at some point requires file write permissions, position data etc. they all have to be declared here. When installing the application, the user gets notified of these required permissions and so this is a nice security and transparency feature in Android.

Writing an OPC UA Client

Now that you’ve created your project and added the necessary libraries, it’s time to write your app. I won’t go through every detail here, see the (well-commented) example project for those, but rather share some general pointers and insight for Android development. I suggest you go through the example code, copy things to your own project and change details here and there and just play around with it. The main parts of creating an Android application are

1. Creating an UI
2. Creating your application logic
3. Binding these two together

I’ll go through each of these steps shortly to get you on your way.

Creating an UI

Using Eclipse it’s very easy to design the layout of your application using the WYSIWYG editor. Layout files are at res/layout, and one file has been pre-generated for you, main.xml. Using the editor, you can simply drag and drop components to the layout, or if you prefer, edit the XML file directly.

For the sample app, one textfield and one button should be enough. Remember to give some good ids for the components, you can do this in the component tree view by right-clicking and selecting “Edit ID…”. I gave them ids “timeBox” and “readButton”, and also changed the text on the button to “Read” by selecting “Edit text”. Create a new string resource by clicking “New String…” and give it an id like “read_button” and a value of “Read”. String resources are stored in res/values/strings.xml, if you want to edit them directly without the GUI.

That’s it for the UI part, easy, isn’t it!

Creating your application logic

This is the part where you get to use our SDK and see how simple it really can be to use OPC UA.

Since reading the time is a long-running activity, we won’t be doing it on the UI thread to avoid freezing up the UI. Instead, we want to run it in the background and just present the results once they are available. To achieve this, we’ll be creating a class that inherits from AsyncTask (see the example project for the exact syntax). The two methods that interest us are doInBackground() and onPostExecute(). doInBackground() will do the heavy lifting in the background, and once it’s done, it’ll store the results in a field. Upon completion of the task, onPostExecute() will be called using the UI thread of the application, allowing us to modify UI components (by calling setUITime() on our Activity) and display the result.

You’ll need to set some information into the UaClient object, but as you can see in the sample project, it’s not too hard. And besides, once that’s done, you can simply start communicating!

Doing the binding

Now we have our UI and the logic for reading the time, but we still need to make the magic happen. For this, we’ll need to make the button start up the read task and also write an implementation for setUITime(). We can get handles to the UI components by calling findViewById in the onCreate method of our activity. The ids for the UI components are listed in R.id, so you can get a handle to readButton by calling (Button)findViewById(R.id.readButton). You can store them as fields in your Activity. After this, it’s easy to write an implementation for setUITime() – but remember, you’ll have to ensure that it’s only called from the UI thread, otherwise you’ll get an exception.

At this point, all we’ll have to do is make the Read button work. We’ll do this by making a click listener for it and making it create a ReadTask. We’ll pass our Activity along as a parameter, so the task can update the time field once it’s done.

That’s it, we’re done! Now you can test the application by firing it up in an emulator. The example project is configured to connect to SampleConsoleServer on the host machine, so simply start that up before firing up your Android app.

Good to know

One important bit here is that if you’re running the application in an Android emulator, you can connect to the host machine (your computer) using the IP address 10.0.2.2. So, if you want to connect to the SampleConsoleServer provided with the SDK, you can use the URI opc.tcp://10.0.2.2:52520/OPCUA/SampleConsoleServer. On the other hand, if you’re developing on a device and don’t have an OPC UA server handy, you can connect to our demo server at opc.tcp://uademo.prosysopc.com:52520.

The source code for the app is available from the link mentioned earlier, so you can double-check on the details or simply just jump in and start making your own app using the example as a base. All in all, Android is a very good platform to develop on (even if you’re not doing OPC UA ) and I expect that there will be interesting UA applications especially on tablet hardware in the future. We’ll keep on developing our SDK and also we’ll be releasing the full version of the Android handset client soon, so do check back often!

I am mostly referring to the parameters with names that are available in the UaClient object of Prosys OPC UA Java SDK. Most of these are reflecting the parameters defined in the OPC UA Specifications, but some of them are only related to the internal behavior of UaClient. In UaClient, the parameters are available via the setter and getter methods, as usual, e.g. Timeout is used via getTimeout() and setTimeout().

Sessions

All UA communications are done through sessions, which must be alive all the time in normal cases. Both the server and client can monitor the state of the session so that they will notice problems early enough and can perform proper clean up even if sessions are not not closed properly.

SessionTimeout

Sessions should not timeout very easily, so a timeout value of one hour is a good default value (the default also in UaClient). It is there just that the server can close sessions that have not been active (no message of any type from the client received for a longer period than SessionTimeout), because the client has died or is no longer connected to the server .

Timeout (i.e. service call timeout)

For individual service calls, you may use Timeout. It is typically used to check if the connection breaks, but you may also get timeouts if the server takes more time to process a service call. 10 s (10000 ms) is OK, but if your server gets loaded you may need to increase that. By default, the timeout is 0 (not used). In this case, however, the default timeout of the Java stack (2 minutes) will become effective.

StatusCheckTimeout

UaClient is monitoring the connection status to the server constantly with StatusChecks, i.e. it is polling the ServerStatus variable from the server and determining if the connection is alive and if the server is all right.

You can use the ServerStatusListener to monitor changes in the status (see below) or check the value of ServerStatus or ServerState (which is the most useful part of ServerStatus).

StatusCheckTimeout is separate from the default Timeout: it defines the timeout for the status reads only. If you get a timeout for that, ServerState is changed to CommunicationFault. Reconnect is then needed, either automatically or manually (see below).

Subscriptions

Subscriptions are used to define data acquisition from the server. The subscriptions are only loosely coupled to sessions: if the session timeouts, for example, the subscriptions can be transferred to a new session. The UaClient will perform this automatically, but you can use a few parameters to define how the subscriptions are monitored.

The most important parameters, PublishingInterval and SamplingInterval are used to define data sampling, but there are also parameters to define subscriptions status monitoring.

PublishingInterval

PublishingInterval defines how often the server checks if there are notification packages (publish responses) for a Subscription to be sent back to the client. A typical value is 1000 (ms). It should not be -1 nor 0.

Instead of using very small PublishingInterval, consider using a smaller SamplingInterval. The server may also increase the PublishingInterval to a default minimum.

SamplingInterval and QueueSize

If you wish to record samples at a faster rate than PublishingInterval, you should use the SamplingInterval of the monitored items. You will also need to reserve a longer QueueSize, to be able to keep all the samples in the server. The server can send all the samples in the queue in one notification – which is sent every PublishingInterval.

KeepAliveCount

If there is no data to send after the next PublishingInterval, the server will skip it. But KeepAlive defines how many intervals may be skipped, before an empty notification is sent anyway: to give the client a hint that the subscription is still alive in the server and that  there just has not been any data arriving to the client.

LifeTimeCount

The client’s responsibility is to send PublishRequests to the server, in order to enable the server to send PublishResponses back. The PublishResponses are used to deliver the notifications: but if there are no PublishRequests, the server cannot send a notification to the client.

The server will also verify that the client is alive by checking that new PublishRequests are received – LifeTimeCount defines the number of PublishingIntervals to wait for a new PublishRequest, before realizing that the client is no longer active. The Subscription is then removed from the server.

Republish

The notification packets are identified with a SequenceNumber. The UaClient can use these to detect if it has missed some of the notifications. If that happens, the client can make a RepublishRequest to request notifications that were missed during a communication break, for example. The server must keep the sent notifications to be able to resend, until the client has acknowledged that they were received.

PublishRequestFactor

UaClient will send several PublishRequests to the server when the first subscription is created. The server can use these, to fill in PublishResponses with new notifications. When the client receives the responses, it will send out new PublishRequests.

PubishRequestFactor determines how many requests are sent to the server: it is multiplied by the number of subscriptions to give the final number. The default value 2.

Communication breaks

If communication breaks, the server can still record new notifications, assuming that it has got enough PublishRequests in advance from the client.

In case you have 5 subscriptions and PublishRequestFactor=10, the client will send 50 PublishRequests to the server. In case of a communication break the server can send 50 PublishResponses back to the client in a normal rate. Considering a PublishingInterval of 1 s, the server can send 10 notifications for each subscription, if their items are really changing. But if the break is longer than 10 s, the server will start losing data. Unless the monitored items have a QueueSize long enough to record more samples.

Once communication is restored, the client will first call Republish to get the missing samples: after that it can send more PublishRequests and the server can continue generating new PublishResponses.

Reconnect

UaClient.reconnect() will make sure that once communication is restored, the old session is used whenever possible and that Susbcription data is not missed. You may choose to use AutoReconnect (true by default) or do it manually. AutoReconnect will make the UaClient to try to reconnect to the server every second, once the communication is broken. If you do it manually, you must be prepared to do it until it succeeds.

Queueing During Communication Break

In case of reconnect, you will also need to consider the sampling parameters such that the queues can hold all the values during the whole communication breakdown. Considering that it may easily take  half a minute to restore the connection even if it breaks down shortly, and you are sampling several times per second, you should be prepared to use QueueSize over hundred or even more for your items.

The servers will typically only use the queue as much as necessary and QueueSize defines the maximum size allowed in worst case. So you should be pretty safe to use longer queue than you need in normal circumstances.

Of course, this all is necessary only if you need to ensure that all samples are recorded in the client. If you are only interested in the current value, you can do with a QueueSize=1 and PublishRequestFactor=2 (default), which make sure that you get notified of the new value with a response time of max PublishingInterval.

Monitoring changes in your client application

UaClient defines various listener interfaces, which are used your application about these status changes.

Please, note that all the listeners are typically called asynchronously from worker threads, immediately when the respective information is available.

ServerStatusListener

The UaClient is checking the server status every StatusCheckInterval. It is doing this with a synchronous Read to the ServerStatus variable. If the read succeeds, ServerStatus is changed accordingly (ServerState is the most interesting part of ServerStatus). If the read fails (or timeouts with StatusCheckTimeout), the UaClient changes the ServerStatus to null, but provides ServerState=ServerState.CommunicationFault.

UaClient will notify about changes in these variables to every ServerStatusListener, so that you don’t need to poll it yourself. In case of a reconnect, the listeners are notified the same, whether you call reconnect() yourself or if AutoReconnect is used.

SubscriptionNotificationListener

The SubscriptionNotificationListener provides you the notification data. StatusChange is also a notification from the server that the status of the subscription has changed. For example, when the subscription is transferred to a new session, a StatusChange notification is sent to the old session.

SubscriptionAliveListener

The SubscriptionAliveListener notifies your client about the keep-alive messages and timeouts, noticed at the client side.

Our experts are thrilled to publish their first articles about OPC & OPC UA technologies. In the near future, you will be reading an extremely interesting post by Otso Palonen about OPC UA Android development, from which we have had loads of inquiries during the past 6 months. Our head of Software Development, Jouni Aro, will guide you to the secrets of handling various issues you face when developing your OPC UA servers or clients.

We have also opened Prosys OPC Support Forums today. Please do not hesitate to start discussions about the topics you find interesting, or ask our specialists if you find yourself in trouble with OPC or OPC UA technology, or our products. There are support sections for each of our OPC & OPC UA products, sections for OPC, OPC UA and Gateway technology, and a General discussion section in which you can discuss about more general topics. You can find a link to Forums in the header of this page, below “Prosys Blog”.

To stay informed, please follow us in Twitter. You will receive the information about the latest blog posts and interesting news and events related to OPC & OPC UA. Our Twitter name is ProsysOPC.

I hope you will enjoy our blog and support forums. If there’s some particular topic you would find interesting to read about, please let us know.