UDI for Raspberry Pi GPIO

Raspberry Pi Logo.svg

The Raspberry Pi has quickly become a popular device used to prototype or become the core of an Internet of Things (IOT) component. Being a small, single board computing platform allows it to be used where conventional computers would either be too large or unable to withstand environmental forces. Yet, because it runs a variant of Linux, it is a fully functional general purpose computer.

Pi devices were designed to be modified and expanded. As such each model includes many I/O ports as well as a bank of pins called the General Purpose I/O pins or GPIO. These pins are addressable, can be configured for either input or output, and in some cases can even support serial communication. The most common use is reading and writing boolean values.

In this diagram of a Raspberry Pi 3, you can see the bank of 40 GPIO pins on the right hand side. Older models only include 26 pins, and some models arrange them differently to fit on the PCB.

The Challenge

There are many open source libraries for reading and writing GPIO pin statuses in many different languages and operating systems. But rapidly prototyping an IoT device comes with many other challenges. So our goal was to produce a driver for the OAS Platform to allow an OAS server to communicate with a Pi device and access GPIO data, all without an admin or end-user needing to write code for each deployment. In short, we wanted to create a driver that behaves like existing OAS native drivers and is configurable through the OAS Configuration tools.

The Universal Driver Interface

With the release of the OAS Universal Driver Interface (UDI) SDK, developers can now create their own custom device or data drivers which act like and live side-by-side with existing native drivers such as our Allen Bradley or Siemens PLC drivers. In addition, UDI implementations can be deployed at the data source and be configured to communicate with a remote OAS server. This ensures that the data is captured reliably from the data source and transmitted to OAS as long as a network connection can be established.

The technology that makes this possible is the .NET Core Framework, which can run on a Linux device.

The UDI for the Raspberry Pi GPIO acts as a conduit between the GPIO Data and OAS.

Remote Driver Hosting

Built-in or “native” OAS Platform drivers such as the Allen Bradley and Siemens PLC drivers are part of the OAS services that run on a Windows server. But since the UDI libraries are based on the .NET 2.0 Standard, UDI drivers can be compiled to execute on any environment that supports the .NET Core runtime. This means you can host a custom driver on a remote device or server such as a Raspberry Pi, thus making data capture more efficient and distributing the load of your solution.

Tag Configuration

Another powerful feature of the UDI is the ability to define custom tag properties based on the driver. So when a Tag’s data source is selected as your UDI driver, your custom properties are displayed in the Tag configuration screen. In the case of the Pi GPIO UDI, we expose properties to control which GPIO Pin is mapped to a tag, and the data direction (input or output).

By changing the Pin Mode, this actually alters the Pin Mode within the the Pi device itself. Selecting the BCM Pin maps the Tag to the Pin using the BCM pin numbering scheme.

Output Pins: the tag value will be set to the pin value on the device

Input Pins: the tag value will be set to the current pin value on the device, and will also allow you to set the pin value on the device by setting the Tag to a boolean True or False.

Connection and Configuration on Startup

Each deployment of the Raspberry Pi UDI can be configured using an external file. This configuration file contains fields for uniquely identifying the device, as well as setting the remote OAS server address and port. When the driver spins up, it will make a network connection to the OAS server and begin transmitting data when an OAS Tag has been configured. Additionally, a UDI can be written to actually create and configure tags on a remote server, so that a deployment does not require any manual keying of Tag configuration fields, reducing errors and ensuring each follow on deployment can be completed with minimal effort.

The appsettings.json file:

ServiceNode: the remote OAS server address

PortNumber: OAS Server port

MachineName: the unique name for the device hosting the UDI Driver

Project Source Code

This UDI implementation for the Raspberry Pi is fully functional, but can be used as the basis of your own projects. Source code is available in C#, and requires the following:

  • MS Visual Studio 2017+
  • .NET Core 2.0+ Libraries

Download Project Source Code

For more information on the OAS Universal Driver Interface and how to develop your own, see the following articles:

One Click OPC UA

Tags can be automatically setup by using the One Click OPC UA feature that browses OPC UA Servers automatically and creates tags based on the Nodes defined in the OPC UA Server. You can then delete tags from the configuration that you do not want.

Note: You will need to be running Open Automation Software Version 12.0.0.9 or greater to support the One Click OPC UA feature. You can download the latest version from our Open Automation Software Download page.

Step 1

Getting Started-Tags 1Start Configure OAS application from the program group Open Automation Software.

Step 2

Select Configure-Drivers.

Getting Started OPC UA

Step 3

Select localhost or the remote service you wish to modify with the Select button to the right of the Network Node list.

Getting Started OPC UA

Note: Optionally select the Live Data Cloud node if you are hosting OPC UA data over the Internet with a standard Internet connection.

Step 4

Enter a meaningful Driver Interface Name that you will refer to this physical connection when defining Tags with an OPCUA Data Source.

Define the properties for the connection to the OPC UA server.

OPC UA Configuration

Set the Driver to OPC UA.

Note: If you enable security the certificate path is C:\ProgramData\OpenAutomationSoftware\pki.

You can use the Browse button if you have installed the OPC UA Local Discovery Service from the OPC Foundation to find all available server names.

You can manually enter in your server if you have not installed the OPC UA LDS from the OPC Foundation.

Step 5

Select the Add button in the lower part of the form to add the Driver Interface as an available selection when defining Tags in the next step.

Getting Started OPC UA

Note: If you need to define several Driver Interfaces you can use the CSV Export and CSV Import on the toolbar in the upper right together with Microsoft Excel.

Step 6

Select Configure-Tags.

Getting Started-Tags 2

Step 7

Select the OAS Service you want to configure by selecting the Select button. Use localhost is the default local service.

Getting Started-Tags 3

Getting Started-Tags 4

Step 8

To begin the One Click OPC UA process you can either select an existing Group you have created in the Tag configuration and then right click on the Group and select Add Tag.

One Click OPC 1

Then select the button with the label “Add tags with One Click AB, One Click OPC, or One Click OPC UA.
Add Tag

Or you can select the root level of service and use the Add Tag or One Click button in the upper right.

One Click OPC 3

Note: You can also add organizational Groups as many levels deep as you prefer and add tags to groups. To do this first add a Group to the root level, then right click on the Group in the right window to add additional Groups or Tags.

Getting Started-Tags 8

Step 9

Select the desired OPC UA Driver Interface assigned to the OPC UA Server you want to import from then click on the Import OPC UA Items button.
One Click OPC UA

Use the One Click OPC UA Wizard to browse for a branch as a starting position within an OPC UA Server or do not select a branch if you want to import all Nodes from the OPC UA Server.

One Click OPC UA Browse

Select to enable the options to Get Data Type from OPC UA Server and optionally the Descriptions.

Additionally if you want to specify to Trend all of the points select Trend Points.

Step 10

Click Add Tags and it will automatically add all of the Nodes from the OPC UA Server Branch you have selected and all sub Branches beneath it.

Step 7

Optionally delete Tags and Groups you do not want to be included in the configuration that have been imported.
Select the Save button on the toolbar at the top.

Getting Started-Tags 19

Step 11

Under Configure – Options set the Default Tag Configuration File so when the computer restarts the tag file will automatically be loaded.

Getting Started OPC

Open Automation Software Tags can be defined to connect to Classic OPC Data Access 2.xx and 3.0 Servers with the built in OPC Interface.

The following steps can be used to setup communications with Classic Data Access OPC Servers.

Step 1

Getting Started-Tags 1Start Configure OAS application from the program group Open Automation Software.

 

Step 2

Select Configure-Tags.

Getting Started OPC Tags

Select localhost or the remote service you wish to modify with the Select button to the right of the Network Node list.

Select Network Node

Note: Optionally select the Live Data Cloud node if you are hosting OPC data over the Internet with a standard Internet connection.

Step 3

Select Add Tag to add a Tag.

Note: You can also add organizational Groups as many levels deep as you prefer and add tags to groups.  To do this first add a Group to the root level, then right click on the Group in the right window to add additional Groups or Tags.

Getting Started-Tags 8

Step 4

Change the Data Source Tag property to OPC.
Getting Started OPC Data Source

Step 5

Use the Browse button to the right of the OPC Item to browse OPC Servers for the desired OPC Item.

Getting Started OPC Item

Select Local, the desired OPC Server, branch within the OPC Server, and OPC Item and click OK.
Getting Started OPC Browse

Step 6

Specify the desired OPC Update Rate for the Tag.

Getting Started OPC Update Rate

Step 7

Select Apply Changes in the lower right to activate the communications for the OPC Item.
Apply Changes

The value from OPC Server for the OPC Item selected will appear in the current Value field.
Note: If the data quality is bad view the article Troubleshooting OPC Communications.

Step 8

To define multiple tags use one of the following optional methods.

  • Use One Click OPC to automatically create tags from all OPC Items from a selected OPC Server or branch within an OPC Server. Then selectively delete the groups and tags that are not required.
  • Use CSV Export and CSV Import on the toolbar in the upper right together with Microsoft Excel to add or modify tags.
  • Programmatically define Tags using the free to use OASConfig component with the TagCSVImport method.
  • Programmatically define Tags with the OAS REST API.

Step 9

Select the Save button on the toolbar at the top.

Getting Started-Tags 19

Step 10

Create a directory on the local C: drive with the name OPCSystemsDemo.

Save the file DemoTags.tags in the directory C:\OPCSystemsDemo.

Getting Started-Tags 20

Step 11

Under Configure – Options set the Default Tag Configuration File so when the computer restarts the tag file will automatically be loaded.

Data Historian Performance Benchmarks

DB Engines Compared

In an effort to help you decide which database engine to choose in your implementation, and how you can boost performance with an existing OAS configuration, we’ve performed extensive testing. On each of the database engines listed, we configured our Data Historian to log Tag Data in 3 different ways.

Narrow
In this configuration, a single value is written per table along with a timestamp for the logged value. This means each OAS Tag logged will result in a single database table.

Wide 10
Each table contains 10 OAS Tags arranged in a single row for each given timestamp. In this test we logged 10 OAS Tag values in a single table.

Wide 990
Using the same configuration as Wide 10, but logging 990 OAS Tags per timestamp.

Conclusions

From our testing, we’ve determined that the fastest overall DB engine is Microsoft SQL Server, even though it performed only slightly slower in the Narrow table test than the next fastest engine Oracle. But because of its dramatically superior performance in all other tests (>2M values per second!), we recommend using MS SQL Server for data logging where possible. Oracle and mySQL are the next fastest engines, and have similar performance numbers to each other, but are also extremely quick when using a Wide logging format.

Efficiency is boosted with logging multiple values per table in the Wide formats, and the fastest speeds can be achieved when increasing the number of values per record. Yet, because we log to an open format, you can still perform post-processing or data archiving that transforms this wide format into a normalized configuration for your own internal usage, while still getting the benefits of high-speed logging.

Configuring OAS for SSL

Using SSL with any OAS Web product as well as the REST API is fully supported.

You must first install an SSL Certificate on your server for the domain name(s) that you intend to use, for example “https://hmi.myserver.com:58726”. Once the certificate is installed properly on the server, check Use SSL and select the installed certificate from the dropdown menu.

IoT Web HMI Dashboard start services dialog

Node Name:
When not using SSL, this should remain as localhost. But when using SSL, this Node Name field should be set to the exact domain name (e.g. myapp.mydomain.com) configured in your certificate.

Port:
This defaults to 58725, but you can set this to anything you prefer, as long as the computer and network firewalls will allow clients to reach this machine on that port. We also suggest using a different port number when switching to SSL to avoid confusion when testing different methods and configurations.

SSL Certificate (host:issuer):
This dropdown will be populated with all certificates installed in the computer. Choose the proper certificate and click REGISTER. You will be asked if you want to proceed since it will require the OAS services to be restarted.

NOTE: If you are using the REST API and changing any port or SSL configurations, be sure to restart the OAS Framework 4.5 Service as well. If this service does not appear on your OAS Service Control utility, no further action is required.

Obtaining an SSL Certificate

Purchasing and installing an SSL certificate is outside of the scope of the OAS product. For more information on Windows and Certificates, see the following article.

During development, you may not have the final domain name that you will be using in production, but you would still like to test SSL communications. Many developers employ self-signed certificates. For more information, see this article.

 

 

FAQs – REST API

Can the REST API push data to another destination?
REST APIs by their very nature are HTTP services. This means that they are based on a request/response model. They are not event-driven and not capable of pushing data to a destination. You can poll against the REST API for updated values, but the data is only as current as the polling rate. So if the polling rate is longer than the refresh rate on the server value, you may miss updates. If you would like to move data based on events, you must write your own solutions using one of our other developer tools, such as the .NET Data Connector or the Universal Driver Interface.
Is the REST API secure?
YES! There are two levels of security when using the REST API. The first is the authentication required for all operations. You first perform an authentication call using a credential configured within the OAS Server. Then, you can encrypt all communications over the wire by using an SSL certificate and restrict the REST API to using only SSL communications.
When would I use the REST API?
The OAS Platform allows for connectivity and integration with many systems and devices. It also exposes tools for direct data integration and automation using .NET for Windows developers, and libraries for integration with web technologies. If you are developing custom software that runs on other platforms that do not host the .NET Framework, and if you prefer to develop more robust applications with or without user interfaces, the REST API is a perfect solution. It exposes functions for reading and writing real time and historical data, as well as operations for customizing the OAS tag configurations themselves.
How do I test the REST API?
The OAS REST API was developed as a standard REST API, and we have exposed our demo server for you to experiment with it using your own tools. We have also published the full REST API documentation online and have integrated it with the popular Postman tool. This free tool allows you to test operations without writing code, and then generate sample code to get you started. In fact, in our online documentation, just click "Run in Postman" and it will download the full API with examples to your Postman instance. Within Postman, you can then point to your own OAS server to test the REST API with your own data. Read more about Getting Started with REST API.
Can the REST API connect to other REST APIs?
REST APIs expose data or operations in a system via HTTP calls. The OAS REST API is no different in this regard, so it is intended to be used by 3rd party clients and developer tools. If you would like to connect to another 3rd party REST API and integrate the data into OAS Tags, you can use either the .NET Data Connector, or the Universal Driver Interface to develop a custom solution.
Can you run the REST API over SSL?
Yes, the REST API as well as Web HMI can be run over SSL. You must first install an SSL Certificate on your server for the domain name(s) that you intend to use, for example “https://hmi.myserver.com:58725”. Once the certificate is installed properly on the server, check Use SSL and select the installed certificate from the dropdown menu. Purchasing and installing an SSL certificate is outside of the scope of the OAS product. For more information on Windows and Certificates, see the following article.