Jan 31, 2017

Issuing an HTTP GET Request to a RESTful Server with the U-CON Driver

Posted by Brent Dube

In October 2015, Kepware released the IoT Gateway advanced plug-in. Leveraging the 150+ drivers within the KEPServerEX® connectivity platform, the IoT Gateway streams real-time industrial data directly into Big Data and analytic software applications. It extends KEPServerEX connectivity to include web-based client applications and helps users create a more connected enterprise. 

Since the release of the IoT Gateway, we’ve received questions about its ability to issue an HTTP GET request from our RESTful Client and retrieve data from a RESTful Server within KEPServerEX. Although this functionality is not included in the IoT Gateway, you can retrieve data from a RESTful server for use in KEPServerEX via Kepware's User Configurable (U-CON) driver.

RESTful Interfaces in KEPServerEX 

The IoT Gateway supports several interface types—including a RESTful interface—and enables KEPServerEX to act as either a RESTful Client or a RESTful Server. 

The KEPServerEX RESTful Server interface enables the client to browse KEPServerEX for tags, read the value of a particular tag, and write a value to a particular tag. The IoT Gateway’s RESTful Client interface lets users POST or PUT data from KEPServerEX to a RESTful Server. Using the IoT Gateway for KEPServerEX, these HTTP methods can be utilized through the platform’s wizard-based configuration tool.

Constructing GET Commands with the U-CON Driver

The U-CON driver for KEPServerEX gives users the ability to create custom device drivers when an off-the-shelf option is not available. It is typically used when device communication protocol manuals are available and describe easily consumable response messages and/or easily constructible transmitted messages, such as HTTP messages.

The HTTP payload is constructed by a series of ASCII strings separated by a few spaces, carriage returns, and line feeds. The figure below is an example of issuing a GET to a KEPServerEX-created RESTful Server hosted on the Local Host on port 39320:

Hypertext Transfer Protocol

When following the TCP stream in Wireshark (as in the example above), you see a very readable portrayal of the actual HTTP payload. New lines are created by carriage returns and line feeds. For example:

example wireshark lines.png

The U-CON driver is the perfect tool to recreate this string of ASCII characters. The Transaction Editor (located in the Device Properties of the U-CON driver configuration) simply builds the ASCII message to be sent by this custom built driver to the target RESTful Server. 

U-CON code

The RESTful Server interprets the request and responds appropriately. In this example, the RESTful Server responds to the GET method with the following string (viewed in Wireshark’s “Follow TCP Stream” viewer):

The response contains the data sent by the RESTful Server to the U-CON driver in response to the GET request—in this case, as a JSON object. The driver then interprets this response to ultimately update tag values. Adding "Read Response" and "Update Tag" commands within the Transaction Editor to configure this interpretation will define the response message length and the desired tag data location within the response. Understanding the length and format of the RESTful Server response will help define these values within the project.

Within the "Read Response" command properties, the messages' length (Frame type) can be defined by:

  • a fixed known length
  • a series of known characters within the message
  • a data length field within the message.
Within this particular response message there is a defined “Content-Length” field, making this response ideal for utilizing the “Frame contains data length field” Frame type. If the response message always terminates by a unique series of characters, utilizing the “Frame is terminated by stop characters” Frame type also suffices.

Ultimately, the "Read Response" command creates a "Read Buffer" when the RESTful Server responds to the GET (defined by the Frame type). Creating an "Update Tag" command enables users to parse the "Read Buffer" into meaningful atomic sections.

The image below shows the configuration of the "Update Tag" command. The tag named “Value” is being updated with the 200th byte of the JSON object contained within the "Read Buffer." This is a very straightforward implementation of the tool; many more complex parsing strategies could be implemented.

This character can be rendered as a Word through the "Tag Properties" (located in the Transaction Editor), as shown below. 

Reviewing the Returned Tag

The OPC Quick Client provides a clear review of the returned tag value. An internal OPC DA tool, it quickly and easily displays the name, value, quality, and timestamp of any available tags from the server. Simply browse to the newly created tag to review the results. 

Learn More

Here at Kepware, we are always looking for new ways to support our customers' needs. As we continue to expand and enhance our software capabilities, being creative with already existing products can sometimes be an effective approach. By utilizing the U-CON driver and IoT Gateway, you can issue a simple RESTful Client GET method to return RESTful server data. 

Download a free trial of KEPServerEX and our template for this project configuration to give it a try. And as always, we’re here to help if you have any questions along the way.

Download HTTP GET Request in a RESTful Server Project Template