Communication - Generic User Protocol

Today we are going to write about a protocol which basically doesn´t do anything. :)

You´ll learn what you can use it for and the reason this protocol was created for.


Generic User Protocol was implemented in D2000 in the year 2015. The idea of its use is pretty straightforward. Let´s imagine one of the simple protocols, which producers of different single-purpose devices create for communication with such a device. And then, let’s imagine that we need to communicate with this device from D2000.

What options do we have?


The first option is an implementation by developers of D2000. The second is writing the protocol as a dynamic library using the KomApi interface. And finally, the third option is an implementation of the protocol in D2000 Event environment in ESL or Java programming language.

What are the advantages and disadvantages of each of these options?


Implementation of protocol directly in process D2000 is perhaps the least flexible from the OEM partners’ view. On the other side, this option offers the best integration and it is able to utilize all possibilities which D2000 KOM process offers.


Implementation of protocol as a dynamic library (OEM protocol) allows to use different languages (such as C or C++). The authors can be OEM partner’s programmers, so there is no need to wait for developers of D2000. OEM protocol programmers have to be able to master KomApi interface.


The third option became possible thanks to the Generic User Protocol. The first step is to configure objects of line, station, and I/O tag types. Generic User Protocol supports wide variety of lines - serial (simple, line redundant and system redundant), SerialOverUDP (again, variants with redundant devices, line redundant and system redundant), MOXA IP Serial Library, and TCP (simple as well as redundant). In case of TCP only the client mode is supported so far (connecting to a specified IP address/addresses).


Configuration of the communication station is simple - basically only the Generic User protocol has to be configured. Only a single station should be configured on one line.


Picture 1: configuration of station with Generic User protocol


I/O tags can be of input and output type. In a basic configuration, two I/O tags are used - one input with the IN address and one output with the OUT address. Both of these I/O tags points are text-based (of TxtI and TxtO types).


Picture 2: Configuration of input I/O tag with an IN address



So how does the Generic User Protocol work? A text string written to an I/O tag with an OUT address is sent to the communication - via a serial line, as a UDP packet or TCP data - according to the line type.


Values received from the communication are written to input I/O tag  with IN address - so it´s possible to create a server script using ON CHANGE clause or a trigger script launched by a change of I/O tag’s value.


Use of Generic User Protocols is therefore simple - script writes challenges into OUT I/O tag and I/O tag IN reads the answers from communication partner. The author of the script has to handle the timeouts (e.g. no or incomplete response to the challenge) and the correctness of the received data as well as its further processing.


For redundant lines, the Generic User Protocol also supports redundant input and output points. These have IN_A and IN_B addresses for redundant lines (Serial Line Redundant, SerialOverUDP Line Redundant, TCP / IP-TCP Redundant), or IN_A, IN_B, IN_C, and IN_D for system and line redundant lines (Serial System&Line Redundant, SerialOverUDP System&Line Redundant). Similarly,it is possible to control writing to individual redundant lines via output I/O tags with OUT_A and OUT_B addresses, or for system and line redundant lines also with OUT_C and OUT_D addresses.


In configuration of communication line , it is possible to configure several parameters that affect protocol behavior.


Parameter Read Wait Timeout (RT)  determines the waiting between individual readings from the communication. If some data has already been received but during RT time no additional data has arrived, received data are published into input I/O tag. If data arrives, they are added to the input buffer until RT timeout is reached or the input buffer becomes full. Size of the input buffer is defined by another parameter - Read Size. If more input data are received, they are published in several blocks of “Read Size” size. Then it´s possible to concatenate the data in ESL script.


The parameter Log Each Read causes the described mechanism to be switched off. Data is published (and optionally logged in the line log) immediately upon receipt.


Remaining parameters only affect the logging method. It is possible to set the text or hexadecimal format of received data listing in logs (parameter Log Format) and for redundant lines it is possible to enable logging of all data into one file (parameter Single Log). Usually, a separate log file is created for the primary line and for the secondary line or alternatively for system redundant lines a separate log file for the primary/secondary line of A/B system.


An example of usage is parsing of data received from Garmin GPS receiver. Garmin communicates using a text-oriented NMEA-0183 protocol, which consists of "sentences" separated by CR and LF characters (a sequence for a new line). Garmin sends sentences one after another and automatically, without a need of a request (so the OUT I/O tag is not needed).



Picture 3: Example of NMEA sentence. Sentence type (GPRMC) is the first parameter,

the parameters are separated by a comma, sentence ends with CR LF sequence.



Picture 4: Test configuration - Garmin GPS receiver, Moxa NPort and a power supply. The data goes from the GPS receiver via serial line to NPort converter and from there through the ethernet cable to D2000 server.


In the example, the SerialOverUDP Line Redundant line, a station with communication protocol Generic User Protocol  and a single I/O tag of Txtl type (text input) with the IN address were used.


Data received by KOM process and published into the value of input I/O tag named M.GENUSR_IN were in picture’s script copied to the input buffer. Subsequently, complete sentences (separated by CR LF sequence, i.e. hexadecimal 13 and 10) were located in the buffer. Each of input sentences has been analyzed. When it was a GRPMC type of sentence, data of geographic location, current time and date were extracted. When it was a GPCGA type of sentence, data of number of visible satellites was extracted. Data were then displayed in the picture.


Picture 5: A picture showing buffer with data from communication, last analyzed sentence
and individual data found from communication (GPS receiver status, number of satellites, hemisphere,
latitude and longitude, and a timestamp in hhmiss ddmmyy format).


Script was implemented directly in a picture as an example of analysis. In production environment, the picture would only be used to view data, and analysis would be performed by a server script within an EVH process running directly on the server (to run continuously). Obtained data would be stored in user variables or in items of structured variable. 

Additionally, it would be necessary to handle the correctness of the input (e.g. data conversion to numbers) and indicate the loss of communication (no value was received for a few seconds).


In case of communication with multiple device (i.e., if there were multiple lines, each with station and I/O tags), it would be useful to link the I/O tags to items of a structured variable into column of Object type and modify the script to work with structures so that it would not be necessary to make script copies that would only differ by using different I/O tags. If intensive communication required it, it would be possible to run multiple instances of server script using the OPENEVENT action, with each instance handling one line of structure.


Picture 6: Implementation of NMEA-0183 protocol in the ESL script environment.

Without handling timeouts and incorrect inputs, the code has 33 rows..


The advantage of this way of protocol implementation is implementation speed, ease of debugging directly via ESL means (connection to running scripting and stepping) and implementation without the need of knowledge of programming in C or C ++  and without knowledge of KomApi interface.


When using a TCP/IP-TCP line type, it is even possible to work with devices supporting telnet protocol and control them or change their configuration from ESL. Turning communication off by a tell command STSTAT will cause end of communication and closing of TCP connection.


What can be added at the end? Perhaps an interesting fact that the first use of the protocol was in the passive mode for capturing and logging serial communication using multiple ports of Moxa NPort server. And the next use was handling of a barcode USB reader LS2208 from Symbol Technologies in Linux.



Picture 7: Data processing from LS2208 barcode reader in evaluated tag using extended syntax
of expressions - the aim is to filter out non-numeric characters from I/O tag .BCR_IN.


August the 3rd 2018, Ing. Peter Humaj,



Topics: D2000, communication

For IPESOFT written by

Peter Humaj

Peter Humaj