Getting started: OAS REST API and native iOS

Step 1

To read and write data between a native iOS app and OAS, you can use the OAS REST API. As a first step, register the HTTP listener with the OAS Service Control Manager under the section labeled “HTML HMI Registration”.

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be the registered domain name, IP address, or network node name that all clients will connect to from their browsers. If you are unsure of which node name to use, localhost will work in most cases.

NOTE: Before clicking “Register”, be sure to stop all services. If services are running, the Service Control app will prompt you to stop them.

Step 2

Start up all services, and be sure to include the Framework 4.5 Service as this houses the listener specific to the REST API.

Step 3

Test your API Service from your iOS device.

You will now ensure that your iPhone or iPad can communicate with OAS via the REST API. In this example, the OAS host is located at 192.168.0.101 on the local network, but you will have to replace this with the OAS host node on your network. The base URL you will use to connect to the REST API is http://{{node}}:{{port}}/OASREST/v2. Each operation performed against the REST API will use the specific operation name prepended with the base {{url}}. The first operation to complete is authentication. All sessions with the REST API must be authenticated. You can adjust the {{url}} in the following snippet and test authentication. In Xcode, create a new single-view iOS application, and choose Swift as the language. Add the following code to MainViewController.swift:

Authenticate Session (Swift):

If this code is executed without error, the response will include a clientid and token. These will be included in the header for all other operations.

Here are some Python examples of basic HTTP requests you might wish to make via the REST API after having completed authentication. For additional information, see our REST API documentation.

Create a Tag (Python 3):

Successful tag creation results in the following response from the OAS server:

Read a Tag (Python 3):

Reading a tag is accomplished with a GET request, using a simple query including the path to the Tag.

A possible response from the OAS server:

Update a Tag (Python 3):

Updating a tag is accomplished with a PUT request, using a payload including the path to the Tag, and the parameter(s) to be updated.

Update confirmation from the OAS server:

Step 4

Write tag data from Raspberry Pi to OAS.
Now that you’ve established connectivity with the REST API, you can complete a Python script to write data from your device. Here is an example script which detects when a button is pushed, and forwards that data into OAS as a discrete tag value. An LED on the breadboard (see figure) indicates the current value, and the OAS server is polled at a frequency of 1 Hz to reflect the current state.

For further help with the REST API, navigate to http://restapi.openautomationsoftware.com to open the REST API online documentation.

Writing data from Raspberry Pi using OAS REST API

Step 1

To write data into OAS from a Raspberry Pi, you will use the OAS REST API. As a first step, register the HTTP listener with the OAS Service Control Manager under the section labeled “HTML HMI Registration”.

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be the registered domain name, IP address, or network node name that all clients will connect to from their browsers. If you are unsure of which node name to use, localhost will work in most cases.

NOTE: Before clicking “Register”, be sure to stop all services. If services are running, the Service Control app will prompt you to stop them.

Step 2

Start up all services, and be sure to include the Framework 4.5 Service as this houses the listener specific to the REST API.

Step 3

Test your API Service from your Raspberry Pi.

You will now ensure that the Raspberry Pi can communicate with OAS via the REST API. In this example, the OAS host is located at 192.168.0.101 on the local network, but you will have to replace this with the OAS host node on your network. The base URL you will use to connect to the REST API is http://{{node}}:{{port}}/OASREST/v2. Each operation performed against the REST API will use the specific operation name prepended with the base {{url}}. The first operation to complete is authentication. All sessions with the REST API must be authenticated. You can adjust the {{url}} in the following snippet and test authentication.

Authenticate Session (Python 3):

If this code is executed without error, the response will include a clientid and token. These will be included in the header for all other operations.

Here are some Python examples of basic HTTP requests you might wish to make via the REST API after having completed authentication. For additional information, see our REST API documentation.

Create a Tag (Python 3):

Successful tag creation results in the following response from the OAS server:

Read a Tag (Python 3):

Reading a tag is accomplished with a GET request, using a simple query including the path to the Tag.

A possible response from the OAS server:

Update a Tag (Python 3):

Updating a tag is accomplished with a PUT request, using a payload including the path to the Tag, and the parameter(s) to be updated.

Update confirmation from the OAS server:

Step 4

Write tag data from Raspberry Pi to OAS.
Now that you’ve established connectivity with the REST API, you can complete a Python script to write data from your device. Here is an example script which detects when a button is pushed, and forwards that data into OAS as a discrete tag value. An LED on the breadboard indicates the current value, and the OAS server is polled at a frequency of 1 Hz to reflect the current state.

For further help with the REST API, navigate to http://restapi.openautomationsoftware.com to open the REST API online documentation.

Web HMI Dashboard Modules

Modules are each self-contained, and files relative to each can be found in the installation directory under the modules folder.
At a minimum, under each module folder you fill find a module.js file and a style.css file. The module.js file is the core module executable, and the style.css contains specific stylesheet rules used by the module.  Some modules may contain other assets, such as the Demo Module.

Removing Modules
To remove a module from the application, you simply need to remove the reference to the module script and stylesheet within the index.html file. These references are found in the <head> element of the index.html file.  Once you remove these references, the module will no longer appear in the list of  of modules for users to select.

See lines 31 – 51 in the code below to locate the module references.

If you are interested in modifications to the Web HMI Dashboard, or would like to speak with us about creating a module specific to your application, Contact Us today!


Demo Module

The Demo Module is an example of an interactive, visual representation of a physical system, with pumps, valves, and fluid level sensors. You can click or tap on each of the valves and pumps to simulate fluid flowing into or out of the two tanks. The corresponding tags in the OAS server can be found under the WPF/New Tanks Demo structure that is present in the demo tags included with each installation.


Numeric Tag Module

This module allows you to display a real time numeric value rendered as a gauge. As values change, the needle will animate, indicating the current value.can be configured

Configuration settings

Tag Name: the tag to be visualized – click the icon to browse or manually enter the tag
Label: the text label displayed below the current value
Min/Max: the range that determines the needle position (default: 0/100)
Gain/Offset: optional multiplier and value offset applied to the raw value
Decimals/Units: number of decimal places to display, and unit suffix added to the value
Read/Write: when checked, displays an input field, allowing users to set the tag’s value


Boolean Tag Module

This module displays the current live value of a Boolean Tag. When configured to allow for read/write access, the display icon becomes a switch. If the switch is clicked or tapped, the server value will be toggled between True and False.  The display can also be customized so that True and False text can be replaced with text of your choosing.


Configuration settings

Tag Name: the tag to be visualized – click the icon to browse or manually enter the tag
Label: 
the text label displayed with the current value
False/True: optional text to display when the value is false or true, respectively
Gain/Offset: optional multiplier and value offset applied to the raw value
Text Scale: optional scaling % applied to text
Read/Write: when checked, changes the indicator to a switch icon and allows the user o toggle the value


Tag Data Module

This modules allows for the display of multiple server Tags along with their data type and real time values. This is very useful for checking the raw data coming from the server within a single tabular format. This module also allows the end user to modify Tag values when the Read/Write option is enabled.

Configuration settings

Label: the text label displayed above the grid
Tags: the list of tags to display – click the icon to choose one or more tags
Read/Write: when checked, adds an edit button next to each tag, allowing the user to set the tag’s current value


Alarm Module

This module encapsulates the Web Alarm viewer and allows the end-user to configure it to display the columns desired. It also allows users to configure the viewer to filter alarms by type, group, status, and priority. Because it is based on the Web Alarm product, it retains all functionality. See the following for more information on Web Alarm.

Configuration settings

Label: the text label displayed above the alarms
Show Search/History: when checked, display the inline search and historical input fields
Alarm Types: list of Alarm Types to include in the display
Alarm Groups: a comma-delimited list of Alarm Groups to include in the display, defaulting to all if left blank
Network Nodes: a comma-delimited list of Network Nodes to include in the display, defaulting to localhost if left blank
Columns: list of Alarm fields to display in the grid
Include Alarms: list of Alarm statuses to include in the display
Priorities: the min and max priorities to include in the display


Trend Module

This module encapsulates the Web Trend viewer and allows the end-user to configure it to display a chart plotting both real time and historical trends. Because it is based on the Web Trend product, it retains all functionality, but requires no programming to configure. See the following for more information on Web Trend.

Configuration settings

Label: the text label displayed above the chart
Sample Rate: the frequency (in seconds) for each data point to be acquired
Timeframe: the number of seconds in the initial data set
Retain: The number of data points to retain in client memory – as more data is received, the chart will animate as it flushes non-retained values
History Data: when checked, allows users to select start and end dates for displaying historical data
Pens: click Add Tag to add a pen linked to a server tag. Each tag will include settings for Name, Label, Line style, and Y-axis range and position


Custom Module

This module allows you to specify any web URL so you may embed your custom code into the Web HMI Dashboard. You can either host the contents of a Custom module on any web server, or you may also add it to the modules folder in the application itself.

The module has a single parameter of a URL. When you use an absolute URL (containing the full URL such as “http://someurl.com/page”), the module will load from the source.  If you use a relative URL (e.g. “somepage.html”) it will be loaded from the Web HMI Dashboard www folder. For example, if you create an HTML page titled index.html and you put it in a folder titled “newModule” under the modules folder, set the URL parameter to “modules/newModule/index.html”.


If you are interested in modifications to the Web HMI Dashboard, or would like to speak with us about creating a module specific to your application, Contact Us today!

Web HMI Dashboard Deployment

Default installation – No web server required

Once you have configured the Web HMI Registration host and port within the steps defined in Getting Started, you can now access the Web HMI Dashboard from your browser.
Open a browser to the Web HMI Dashboard at the following address:

http(s)://<server>:<port>/app/home

For example, if you are on the same machine as the OAS Service installation, you are not using SSL, and you are using the default port, the URL will be:

http://localhost:58725/app/home

By default, the Web HMI Dashboard will run in Demo Mode which will do the following:

  • All logins no matter the credentials, will be allowed to log into the application and be provided individual dashboard settings
  • New logins will be pre-populated with demo dashboards

To alter any application configurations, locate the Web HMI Dashboard directory located in the installation directory for Open Automation Software. This is typically in C:\Program Files (x86)\Open Automation Software\OPC Systems.NET.  The Dashboard directory is labeled “www“.

Within this directory, look in the “js” directory and locate the file app_config.js. This is a JSON file containing application settings.

oas_url : optional hard-coded URL of the OAS server location. Omit this setting and the application will assume the server:port used to connect to the app
show_login_url : <true | false> determines if the OAS url can be supplied by the user in the login screen to point the application to a specific OAS service
session_timeout : <integer> number of minutes of inactivity before the user session is ended and the login screen is displayed
demo_mode : <true | false> enables or disables demo mode
demo_dashboards : a JSON representation of the demo dashboards pre-populated for new users in demo_mode

Standalone web server deployment

If you choose to host the Web HMI Dashboard on your own web server, simply copy the contents of the www directory (described above) to the web server like any other static files. Be sure to include all files and folders within the www directory.

NOTE: when hosting the Dashboard on a separate server, you must alter the app_config.js setting for oas_url. This must be the server:port of the OAS server hosting the live data. This setting must be in the form:

http(s)://<server>:<port>

 

Getting Started – Web HMI Dashboard

Step 1

To use the Web HMI Dashboard you must first register the Web HMI libraries. This is done with the OAS Service Control Manager with the Web HMI Registration (highlighted below).

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be the registered domain name, IP address, or network node name that all clients will connect to from their browsers. It can also be left as localhost.

The Port number is set to 58725 by default, but can be changed to any available port on the server.  You may also select Use SSL if you choose to require an SSL connection for all Web HMI communications, including the Web HMI Dashboard.  If you choose to use SSL, you must select which SSL Certificate to use with the service. SSL requires that a server certificate be present and installed on the server where the OAS Services are installed.

Once you have configured the Web HMI Registration fields using your desired settings, click Register to set the server registration. If your services are running, you will be asked if you would like the services to be stopped, as it is required for the registration to be completed.

Step 2

Open a browser to the Web HMI Dashboard at the following address:

http(s)://<server>:<port>/app/home

For example, if you are on the same machine as the OAS Service installation, you are not using SSL, and you are using the default port, the URL will be:

http://localhost:58725/app/home

Step 3

Once presented with the Web HMI Dashboard login screen, enter in an OAS server credential, or leave blank to use the default server credential and click “Sign In“.

Upon successfully logging in, you will be presented with your personalized Web HMI Dashboard. If the application is in Demo Mode, you will be provided with some demo dashboards and you will see live data flowing into each module.  All modifications to your dashboard will be saved within your login and remembered for your next session.

Additional Configuration Settings

By default, the Web HMI Dashboard will run in Demo Mode which will do the following:

  • All logins no matter the credentials, will be allowed to log into the application and be provided individual dashboard settings
  • New logins will be pre-populated with demo dashboards

To alter any application configurations, locate the Web HMI Dashboard directory located in the installation directory for Open Automation Software. This is typically in C:\Program Files (x86)\Open Automation Software\OPC Systems.NET.  The Dashboard directory is labeled “www“.

Within this directory, look in the “js” directory and locate the file app_config.js. This is a JSON file containing application settings.

oas_url : optional hard-coded URL of the OAS server location. Omit this setting and the application will assume the server:port used to connect to the app
show_login_url : <true | false> determines if the OAS url can be supplied by the user in the login screen to point the application to a specific OAS service
session_timeout : <integer> number of minutes of inactivity before the user session is ended and the login screen is displayed
demo_mode : <true | false> enables or disables demo mode
demo_dashboards : a JSON representation of the demo dashboards pre-populated for new users in demo_mode

 

Web HMI Dashboard

 

Overview

The Web HMI Dashboard is an application which allows you to visualize real time and historical data from within desktop and mobile browsers. Since it is built upon the Web HMI product, it requires the installation and licensing of Web HMI.  However, it can be accessed without the installation of an additional web server, or you are free to install it on a web server of your choosing.

More:

See also:

Getting Started – REST API

Step 1

To use the OAS REST API you must first register the HTTP listener. This is done with the OAS Service Control Manager under the section labeled “Web HMI and REST API Registration”.

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be the registered domain name, IP address, or network node name that all clients will connect to from their browsers. If you are unsure of which node name to use, localhost will work in most cases.

 

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be set to the Network Node Name, IP Address, or registered domain name that all client applications will browse to. This will be the serverURL that all clients will specify. Unless you are using a server with multiple network interfaces, keep the Node Name set to localhost.

Using SSL with 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: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.

NOTE: Before clicking “Register”, be sure to stop all services. If services are running, the Service Control app will prompt you to stop them.

Step 2

Start up all services, and be sure to include the Framework 4.5 Service as this houses the listener specific to the REST API.

Step 3

Test your API service.
Navigate to http://restapi.openautomationsoftware.com to open the REST API online documentation.

This documentation illustrates all of the operations available to any REST API client and can be tested using the Postman application client.  In the upper right corner of the documentation, you will see a button to Run in Postman, which will install the API documentation into the Postman client for direct execution against any OAS server.  Additionally, the documentation can be configured to display code samples in multiple languages including cURL, jQuery, and NodeJS. Feel free to browse the documentation at any time and to refer back to it while developing your applications.

Clicking Run in Postman will pop up a dialog box to import the REST API into an existing installation of Postman, or you can choose to install the app for the first time. Postman is available for Windows and Mac desktops as well as in a Chrome extension.

Once installed and the API has been downloaded into the app, you will see the following interface, with all operations on the left, organized identically to the online documentation:

The first operation to execute is the Authenticate call, which will generate a REST API session and returns a clientid and token to be used in all subsequent calls to the OAS server.

In the list of operations, expand and select Authenticate and you will see the following on the right side of the app:

This shows that the Authenticate operation is executed as an HTTP POST against the /authenticate URL appended to the base {{url}}. This base URL is defined in your Environment here. Select Manage Environments to add new fields:

Click ADD to create a new Environment which will hold environment variables:

Add a name for your environment, then add a key of url with a value of http://localhost:58725/OASREST/v2 and click ADD to create the new environment. Then return to the Authenticate operation.

Now under the Environments dropdown, select your new Environment. You should see the {{url}} turn orange, indicating that the environment variable is being used.

You can now click SEND to execute the post against your server. If successful, you should see a response body similar to the one below, containing the clientid and token fields.

You can then use these fields in the header of all other operations using the Postman app to test your server.

Getting Started – Web HMI

The following content will get you started with Web HMI, building your own web user interfaces with real time data. If you are interested in visualizing your data in a desktop or mobile browser with zero programming, you may be interested in Getting Started with the Web HMI Dashboard.

Step 1

To use the Web HMI interface you must first register the Web HMI libraries. This is done with the OAS Service Control utility with the Web HMI Registration.

Define the exclusive Node Name and Port Number  that is to be supported. The Node Name should be set to the Network Node Name, IP Address, or registered domain name that all client applications will browse to. This will be the serverURL that all HTML clients will specify. Unless you are using a server with multiple network interfaces, keep the Node Name set to localhost.

Using SSL with Web HMI 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: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.

NOTE: Networking to other OAS Services is easily supported by defining the IP Address, Network Node Name, or registered domain name in the HTML code for the client. Use the Web HMI Wizard to define the remote networking nodes to multiple remote services relative to where the web project is hosted.

Step 2

Create a project directory. (Example C:\myWebHMI)

Step 3

Copy the 4 supplied files from C:\Program Files (x86)Open Automation Software\OPC Systems.NET\HTML_HMI, js and css subdirectories to your project directory keeping the directory structure just the same.

Web HMI Getting Started 2
jQueryDirectories
1. jslibjquery-1.8.3.min.js
2. jslibjson2.js
3. jsopc-lib-min.js
4. cssopc-style.css

Step 4

Open/create a new text document and add the following minimum code:

NOTE: Specify the serverURL that includes the Node Name and Port Number that has been registered by the OAS Service Control Manager.

Step 5

If you are new to HTML code use the HTML Wizard code generator at http://opcweb.com/wizard/ to generate the code for you.

HTML Wizard
HTML Wizard

In the body add the following code to display the Ramp tag value:

Step 6

Below the Ramp code add the following code to display the Pump tag Value:

Step 7

Finally below the Pump code add the following to create a button that will allow you to “Toggle” the Pump Value.

NOTE: To be able to set a value (write to it) it must first be setup to read in the web application.

Step 8

Save your file as myWebHMI.html

Web HMI Getting Started 3

Step 9

From the Control Panel > Administrative Tools, open Internet Information Services (IIS) Manager

Step 10

If you do not find the IIS Manager under administrative tools please add IIS to you operating system using add remove programs.

Step 11

Right click on the default web site and add a virtual directory linking to your project directory.

Step 12

Use myWebHMI as the alias name. Then browse to your project directory for the physical path.

Step 13

Hit OK.

Step 14

To see the results open a browser and enter: http://localhost/myWebHMI/myWebHMI.html

Step 15

Your final code should look like this:

NOTE: To be able to set a value (write to it) it must first be setup to read in the web application.

Open Automation Software provides a tool for automatically creating the HTML code to read and write to Open Automation Software Tags using the HTML HMI Wizard.