The Open Automation Software MQTT Broker is built into the OAS Engine which can be deployed on both Windows and Linux operating systems. MQTT Broker support was added to OAS version 15.00.0001 and does require a license of the MQTT driver to enable read and write functionality.
The OAS MQTT Broker supports reading, and writing to all local and remote OAS Tags, including Live Data Cloud.
You can view the MQTT Broker Video to familiarize yourself with the following steps to interface with local and remote OAS Tags.
0:00 – Introduction – OAS as MQTT Broker
0:15 – OAS as MQTT Client and MQTT Broker
0:20 – MQTT Client
0:40 – MQTT Protocol
0:44 – What’s MQTT Broker
0:58 – Where is built MQTT Broker
1:07 – What MQTT Broker support and requires
1:29 – How to Interface MQTT Client with OAS as an MQTT Broker
1:41 – How to verify if you have a valid license for MQTT
2:07 – Set up OAS as a MQTT Broker
3:23 – Set up to Subscribe to OAS MQTT Broker
5:54 – Sending a JSON message to the OAS MQTT Broker from MQTT Client
7:08 – More information
The following guide demonstrates how to interface an MQTT Client with OAS as a MQTT Broker.
Step 1
After installing Open Automation Software the verify you have a license of MQTT on OAS Engine that the MQTT Client will connect with.
Use the Configure OAS application and go to Configure-License and use Select to check the OAS Engine that MQTT appears in the Enabled Drivers list.
Step 2
To setup the OAS MQTT Broker go to Configure-Options and select the MQTT Broker tab.
Enter the ID you want to use for the OAS Broker in the OAS MQTT Broker field.
Choose either the default broker port (1883) or enter a new port into the OAS MQTT Broker Port field.
For SSL/TLS, choose either the default broker SSL port (8883) or enter a new port into the OAS MQTT Broker SSL Port field.
If you want to use SSL/TLS, Check the box for OAS MQTT Broker Enable SSL.
In the MQTT Private Key File field select Browse and select your private key file.
If you have a password assigned to the private key enter it into the MQTT Private Key Password field.
Enter the username in the MQTT Client Username field to require MQTT Clients to connect using a specific username.
Enter the password in the MQTT Client Password field to require MQTT Clients to connect using a specific password.
Optionally enter Topic Aliases to map topic names to OAS tag names. This is only required if the MQTT client cannot define the topics to interface with.
Step 3
If security is left to the Default to Enable All Features in all OAS Engines you can proceed to Step 4.
If Security has been setup on any of the OAS Engines to restrict Reading Tags or Writing Tags go to Configure-Options and select the Remote Services tab.
Set the Security User Name and Security Password to user to gain access to the remote OAS Engine for read and write access to the tags to be monitored and set by the MQTT Broker.
Step 4
The OAS MQTT Broker is now ready for use.
Naming Conventions
To access OAS tags set your topic to the OAS standard naming convention. A few examples below.
Read the value from the Ramp tag on the local OAS service. Topic = Ramp.Value
Read the Description from the Ramp tag on the local OAS Service. Topic = Ramp.Description
Read the value of Alarms Not Acked tag in the subgroup Alarms on the local OAS service. Topic = Alarms.Active Not Acked.Value
Read the value of the Ramp tag from a remote OAS service. Topic = \\Domain or IP address\Ramp.Value
The payload is in standard JSON format and includes the Value, Timestamp, and Quality.
Example Payload for Ramp.Value: {“Value”:84.0,”TimeStamp”:”2020-07-22T12:59:44-04:00″,”Quality”:true}
To return the tag value only not in JSON format subscribe to TagName.ValueOnly. Supported with OAS version 20.00.0133 or greater.
To Write to an OAS Tag use the same topic format as described above.
You can publish to any existing Tag.
You can create tags with the Data Type set to JSON in OAS to be able to publish extended meta data on OAS Tags. Using the JSON Handling in OAS you can parse the JSON message for extended functionality.
Wildcards
The following wildcards are supported with OAS version 18.00.0041 or greater.
# – Subscribe to all tags from the OAS Engine for the .Value variable of each tag.
+/<tag variable> – Subscribe to all tags from the OAS Engine for the tag variable specified. Example: +/DigitalAlarmActive
Deployment
You can deploy the OAS Engine to multiple servers on Windows or Linux using standard deployment or Docker containerized deployment, each OAS MQTT Broker supports communications to any OAS Engine.
The OAS Platform is capable of running in Docker containers on both Windows and Linux, with only a slight variation in configuration. In this article we will walk through the necessary steps for basic containerization, but using these principles you can build your own images and configure them for your particular needs.
00:00 – Introduction
00:15 – Container Installation
00:34 – Application Stack
00:48 – Steps for running docker
01:32 – Create a Docker Image
04:04 – Set of Instructions
05:10 – Commands
05:45 – Run your Container
10:26 – Configure the License Host
14:19 – Remaining Steps
18:06 – Configure Licensing
18:55 – More Information
Prerequisites
The OAS Platform was designed to be a high performance IoT Gateway, Data Logging engine, data visualization server, and more. To benefit from these features, whether the server is running as a stand alone or in a container, be sure to consider the following:
Docker experience – this document assumes some familiarity with containerization concepts, specifically with Docker, and is not intended to be a tutorial on Docker or containers in general. To learn more about Docker, see the following: Docker-What is a Container?
Networking – the server must be able to reach external resources, and if being accessed by any of the OAS SDKs for visualization or programmatic configuration, the server must be accessible from external sources. This is easily accomplished by exposing the necessary ports. Port 58727 is the default port used for TCP communications when using .NET SDKs and the OAS Configuration application. Port 58725 is the default port used for Web Visualization tools as well as the REST API. Running stand alone, you are free to change these ports as needed. However, when running in a container, these default ports should not be changed (more on this later).
Memory and CPU – when running multiple instances of the OAS Platform in containers, expect memory and CPU utilization to increase as a result. The amount of each needed entirely depends on your individual configurations, such as how many Tags are being used in each container, data logging, alarming, etc. Be sure to size your deployment platform only after testing with your intended configurations to determine the footprint. You can refer to the following for suggested CPU and RAM hardware requirements based on Tags and features to be implemented: OAS Recommended Hardware
Containerization Options
Docker containers can be configured to run completely independently or they can run utilizing shared resources on the Host server. OAS supports both scenarios, allowing you to utilize self-contained configuration files or shared configuration files on a Host using mapped volumes. This allows for generic containers to be spun up with identical configurations, or simply to allow the management of configurations external to a container.
Comparison of OAS containers running self-contained and with shared configuration files on the host.
Installing an OAS Image
All Docker versions of the OAS Platform are available on Docker Hub and can be pulled into your local machine with a single command. This makes installation and upgrading extremely convenient. You can browse all OAS images at hub.docker.com/u/oasiot. Once you have chosen the image you would like to use, matching the OS/architecture (e.g. Linux/x64 or Windows/AMD64) execute the pull command, which is provided on the page for each image. For example, the pull command for Linux/x64 is:
docker pull oasiot/oas-linux
This will download the latest version of the image. So, if OAS releases a new version, simply re-run the pull command and you can always be up-to-date. If you would like to pull a specific version, you can use the version tag in the pull command. For example, pulling version 15.00.042 would use:
docker pull oasiot/oas-linux:15.00.042
Using a version tag in your workflow will allow you to keep your installations uniform and predictable.
Running your new container
To run an instance of this image in a container, execute the following command. This will spin up an instance and display the console output in the terminal window. The container can be stopped by hitting CTRL-C. By default, the docker runtime will provide a randomized unique name for the container.
docker run -it oasiot/oas-linux
The container will now be running, and will be assigned an IP address only accessible from the host machine. If you want to map the container’s ports to ports on the host, allowing the container to be reached from external systems, you can use the -p or -P flags in the docker run command. For example this will map the host’s port 58727 to the container’s port 58727, so you can then reach the container from the host’s IP address on port 58727, allowing you use the OAS Configuration application remotely to connect into the container:
docker run -it -p 58727:58727 oasiot/oas-linux
To allow the Docker engine to assign random port mapping, you can use the following command. After doing this, just inspect the running container to see which ports have been assigned:
docker run -itP oasiot/oas-linux
Optional: Creating your own Image
Before any application can be run as a Docker container, it has to be bundled in an image. The process of creating an image involves the creation of a Dockerfile with configuration options, and calling docker build against the file. Whether the target platform for running the container is Linux or Windows, the process is the same, with some slight variations on the contents of the Dockerfile. For more information on Dockerfiles and their syntax, see the online documentation.
To containerize the OAS Platform we will take the following steps:
Ensure that Docker is installed properly on the target platform
Download and extract the OAS Platform distribution for Linux or Windows .NET Core depending on the chosen platform
Copy the contents to the target server in a directory, e.g. /oas-docker/oas-linux, /oas-docker/oas-win
Within the /oas-docker directory, create a text file called Dockerfile with the following contents. If you are familiar with crafting Dockerfiles, you can modify these settings to your preferences, as long as the default ports in the EXPOSE commands are not changed.
As you see, the Windows Dockerfile differs from the Linux version. The FROM entry references the nanoserver tag which is a bare bones Windows runtime host. The same ports are mapped in the EXPOSE lines. The COPY command copies the contents of the oas-win directory to the container’s oas directory. You’ll note the addition of the USER command, which specifies that the context the OAS Platform should run on is the System account with elevated privileges. This is required. Lastly, the ENTRYPOINT is modified to call the OASEngine.exe executable. Also, see the section below titled Windows Containers as you may run wither Linux or Windows applications in containers on the Windows platform.
Build the OAS container image with the following command. This creates and registers a reusable image that can be spun up as multiple side-by-side containers:
docker build --tag oas .
The OAS Platform allows you to customize which ports are used for configuration communications as well as for access with SDKs, the REST API, and WebHMI products. When using OAS within a container, it is important to use the defaults of 58727 for TCP communications and 58725 for HTTP calls. These can be mapped to fixed host ports within the Dockerfile, or mapped dynamically during the execution of “docker run”. The OAS LicenseHost relies on the default underlying ports to allow for license activation, but you may still map these to customized ports if you want to access the containers via localhost.
Options for running a container
Providing a custom name
If you run a Docker container with the previous command, the Docker runtime will assign a random name for that instance. You can provide a custom name for the container to more easily identify the container. This must be a unique name on the server since no two containers can have the same name. This example runs the container, giving it the name “oas_production”:
docker run -it --name oas_production oas
Mapping a host volume
In some cases, you may want several running OAS container instances to share the same configuration files so that when they spin up, they pick up the same settings. To do this, we’ll follow these steps:
Move the ConfigFiles directory to a location on the host machine
Build the docker image
Run the image using the -v host_dir:container_dir option to create a virtual directory in the container mapped to the host
docker run -v /OASConfigs:/oas/ConfigFiles --name oas1 oas
Mapping host directories can also be useful if you are logging data to a SQLite database, as they are file-system based and you would not want data lost when you spin down a container.
You can map multiple volumes for such a configuration, combined with the command above:
docker run -v /OASConfigs:/oas/ConfigFiles-v /SQLiteData:/oas/SQLiteData --name oas1 oas
Then, in your SQLite logging configuration, you would use /oas/SQLiteData as the path for the database.
Licensing
A stand-alone installation of the OAS Platform is licensed directly my using the OAS Configuration application. You select Configure > License, select the machine (typically localhost if working on the current machine) and are presented with a unique License Code for the machine. This is sent to OAS and you will then be provided an encoded License Key that will activate the features you have purchased.
Running the OAS Platform in containers, licensing is handled slightly differently. On the container host machine, you install and run the License Host application, which communicates with all running containers to activate product features, and recognizes new containers as they spin up. When purchasing a license from OAS, you will select product features to enable along with a number of tags, and if deploying OAS within containers, you also select the maximum number of containers you will be running on the host.
Standalone installations of the OAS Platform are licensed directly. Containers acquire their license from the LicenseHost installed on the host
Installing the License Host
Linux
On a Linux system, the installation and execution of the License Host is similar to installing the OAS Platform itself. From the product downloads page, locate the License Host for Linux and download the ZIP archive. Unzip this file and move the contents to your preferred location, then execute the following command on the Linux server to make the application executable:
sudo chmod +x LicenseHost
You can now run the LicenseHost application directly with the ./LicenseHost command, or configure it to be started with the system when it boots up. You can follow the directions for setting up an application as a daemon on Linux from Step 3 of our online documentation, replacing the name and path of the OASEngine with that of the LicenseHost, where applicable.
Windows
On Windows, the LicenseHost installer registers it as a Windows Service. Download and install the License Host and start the service either manually in the Windows Services control panel, or using the OAS License Host application from the Start menu, which acts as a service control for just the License Host. The service is named “OAS License Host” if you choose to start it manually
Managing Licenses with the License Host
After starting the License Host on the container host server, you can connect to it from the OAS Configuration Application to apply or modify a license for that server. Select Configure > Container License from the main dropdown menu and enter the IPAddress of the host server.
Note that the LicenseHost will communicate on port 58729 so the host machine must allow TCP communications on that port so adjust your firewall rules accordingly. If you choose to change this port, locate the appsettings.json file in the distribution of the LicenseHost application and change the port number within it. You can also use this file to secure the License Host by adding a username/password combination.
Configuring the license on the container host is identical to configuring a license on a stand alone installation of the OAS Platform. Your License Code is used to acquire a License Key from OAS Support, and the key contains information about the product features to enable along with the maximum number of containers it will support.
For more information on licensing an OAS server, see the following Knowledge Base article: OAS License Activation
Testing your installation
Once your containerized OAS installation is running, you can connect to the individual containers with the OAS Configuration application and inspect Tags or any other feature. You will need to connect using the container’s assigned IP address, found by inspecting the Host Docker service. If you have not mapped the custom ports to the defaults of 58725 and 58727, you can use these directly with the containers’ IPAddress. If you have mapped ports, you can use the host’s IP address (or localhost on the host itself) with the custom ports.
Considerations for Windows Containers
Assuming you are running Docker Desktop on Windows, you first need to make sure to switch to “Windows Containers”. By default, Docker Desktop assumes you will be using Linux containers with Hyper-V. To make the switch, you can go to the Docker Desktop tool and select “Switch to Windows containers…”
Alternatively, you can use the following Windows PowerShell script to switch:
The OAS Platform offers support for handling and manipulating JSON formatted data, which is crucial when integrating with many external systems such as cloud-based analytics platforms, and for working within common Industrial IoT scenarios. Specifically, data passed between systems using the MQTT protocol, data sent and received from REST APIs, and even records stored in many database engines all use JSON formatting for hierarchical data. For more information on JSON, see our article “What is JSON?” on how it is structured and compares to other similar data formats like XML.
JSON Data Type
Along with other standard Data Types such as Integer, String, Double Float, etc., OAS Tags can be assigned the JSON Data Type. This functions very much like a String Data Type except that internal JSON validation is performed whenever the value changes. This validation ensures that the value set on the Tag is properly formatted JSON. If the validation fails, the Tag will be marked as having Bad Quality. Your applications and other tags can be configured to respond to this state as needed, preventing invalid JSON from reaching other endpoints.
To set a Tag as a JSON Data Type, simply select JSON from the Data Type dropdown and click Apply Changes. Validation will immediately take effect. For all other operations such as Tag Calculations, you can reference a Tag of JSON Data Type just as you would with a String Tag. Values from JSON Tags can also be used in Text Calculations just as you would with String data.
Select JSON as a Data Type for Tag Configurations
JSON Data Source
In addition to setting the Data Type to JSON for automatic data validation, you can also set the Data Source as JSON for highly customizable generation of JSON data packets. This is especially useful for storing structured data or for crafting JSON data packets to be sent to external systems such as MQTT clients, or other 3rd party cloud applications. Using the JSON Data Source gives you the ability to define a base JSON structure, then use JSONPath syntax to locate nodes in the structure for replacement with OAS Tag data.
Learn more about the JSON Data Source, including some advanced usage and examples.
Setting the Data Source as JSON reveals additional properties
A Tag with a JSON Data Source can have a base Structure set directly as a valid JSON string, or it can be set using another Tag. This will allow you to dynamically modify the base structure, or use the same base structure for multiple tags. Below is an example of editing the JSON structure directly.
The JSON structure can be edited directly on the Tag
Assigning key/tag pairs are done in the by selecting Add in the table below the Structure property. This will open a Tag browser which allows you to pick a Tag from the local OAS instance or any reachable remote OAS instance. The key is a search parameter defining where to find the JSON node to fill with the Tag value. This key uses JSONPath syntax and can be either a direct path to the node or a dynamic query to find one or more nodes matching the criteria. For more information on JSONPath syntax, see this article.
This example illustrates injecting 3 Tag values using different JSONPath keys
JSON Data Visualization
You can access individual elements of JSON data for read and write access from any of the OAS client applications including WPF HMI, WinForm HMI, Web HMI, Excel, Calculations, Data Logging, Recipe, OPC UA client, OPC DA client, Data Route, and programmatic interface via .NET or REST API.
To access any individual element of an OAS tag with a Data Source of JSON use .JSON-<key name> as the tag variable. An example OAS_Tag.JSON-motors[0].current would provide read and write access of the current value of the first motor element of the array of motors.
The OAS Configuration Application also has the ability to recognize JSON data and will assist with visualization. For Tags of both String and JSON Data Type, clicking on the current value will display the value in text form. If the value can be parsed as valid JSON, it will be displayed using a hierarchical JSON visualizer allowing you to expand or collapse nodes and arrays, as well as see the data with syntax highlighting.
OPC UA Structures
OAS can read and write OPC UA values that are from flat or multi-level hierarchical structures. The element names and values will be parsed into JSON data as it is received from the OPC UA server. Values can also be written to the OPC UA server that represent structures.
JSON Calculations
The OAS Platform Calculation Engine provides powerful features for real time data transformations and logic. Additionally, the Calculation Engine supports a set of functions for generating, querying, and manipulating JSON data. For example, if you create a tag containing a JSON structure, you can use the JSON Calculations to locate data points within the structure, add other structures to the JSON, and even set values on a particular node. See our documentation on JSON Calculations for more information.
JSON and MQTT
The OAS Platform can act as an MQTT client as well as an MQTT broker. When used as an MQTT client with the MQTT Connector can publish and subscribe to any MQTT broker. This allows you to send OAS Tag data whenever values have changed. By default, OAS creates a simple JSON message that includes the current Tag value, and timestamp when it was updated in the OAS platform. If you prefer to craft your own custom message format, including more data and even data from multiple Tags, you can set the source Tag to the JSON data type or String data type containing valid JSON and the message published will be used instead of the default format. This includes using JSON Calculations to dynamically generate the Tag value as data changes. With this powerful feature you can guarantee the messages sent to remote systems comply with your requirements.
The OAS Platform built-in message payload for MQTT is simple and concise. The Tag’s current value, timestamp when the value changed, and the data quality of the tag are published as bare values in separate topics. For example, if your Tag name is MyTag, the topic of MyTag will contain the current value of the tag. In the configuration of a Tag with MQTT as the Data Source, you can also configure the topic name. Also, if you check “Include Timestamp” and/or “Include Quality”, an additional topic will be created for each.
While this is simple and easy to configure, there may be cases where you would like to send a custom payload containing the Tag’s value, timestamp, and quality in a single message published to a single topic. Or you may want to send values from multiple tags in a single payload. If you set the Tag Data Type to JSON or String containing a valid JSON structure, the payload will now contain the JSON structure. This means you can use a Calculation tag to construct your JSON, based on string literals or a segment derived from another larger JSON structure, or even combine multiple tags into a single JSON payload and you have the freedom to choose what gets sent to the MQTT Broker. For example, this JSON could be created from a JSON Calculation containing four tags in an array along with additional wrapper values:
OAS can publish any tag value to MQTT Brokers, AWS IoT Gateway, and Azure IoT Hub in bulk payload as one topic as JSON. View how to publish live data to AWS IoT Gateway, Azure IoT Hub, and MQTT Brokers. With these knowledge base articles you will see the structure created for bulk payload with multiple tags per topic and single topic payload for values from any OAS data source.
The tag IoT publish feature is built into each driver configuration to make setup extremely simple to define selected tags from the local OAS Engine or remote OAS Engine.
The following legacy video demonstrates some of the basic functions within the Calculation Engine. Please refer the the Calculations reference for a complete list of all current functions.
Below is a video tutorial detailing how to use the Watch Window:
NOTE: Adding a group of tags to the Watch Window will now add the tags within the group selected and all tags in all sub-groups. To add all tags from an OAS Engine select the Tags root object and select Add to Watch.
The Watch Window is a feature of the OAS Configure Application that allows you to view the value of multiple tags at one time. You can use it to view multiple tags from one Service installation or from multiple Service Installations at the same time.
It is free to use with the demo license or an active license for at least any one product feature.
The Watch Window is accessible from the Configure Tags screen. It can be opened by clicking the Watch Window button on the top menu bar.
To add a tag to the Watch Window, select any tag and right click on it. Then choose Add to Watch from the context menu.
The tag you selected will then appear in the Watch Window.
To resize the Watch Window, grab it by the bottom right corner and drag it to the size you would like.
You can also add a Tag Group to the Watch Window. To do this, select the Tag Group, right click on it and choose Add to Watch.
Note: that it won’t add the tags in nested groups, if you want to do that, you must add the sub groups individually as well.
To delete Tags from the Watch Window, simply select the tags you want to delete and click the delete button. You can hold the shift key to select multiple non-adjoining tags and the control key to select multiple adjoining tags.
You can save the current configuration in your Watch Window if you’d like. Choose Save from the top menu and then save the file to a location on your file system.
The configuration files are saved in CSV format so you can open them in Excel and edit them yourself manually. You can specify the Network Node and then the Tag Name right in Excel.
You can create and save multiple configurations for different purposes. It is a very useful feature.
The Watch List feature is free to use with OAS with either the demo license or an active license for at least any one product feature.
If you want to run two separate Watch Windows, you can do that by opening a second instance of the OAS configure application and then open the second Watch Window there. You can see now that I have two separate Watches running independently of each other.
The Open Automation Software OPC UA Server is built into the OAS Engine which can be deployed on both Windows and Linux operating systems. OPC UA Server support was added to OAS version 14.00.0042 and does require a license of the OPC Client Connector to enable read and write functionality.
The OPC UA Server supports browsing, reading, and writing to all local and remote OAS Tags, including Live Data Cloud, provided the OAS service hosting the Tags has a license of OPC Client.
View the following video to see how to connect OPC UA clients to the OAS OPC UA server.
The following guide demonstrates how to interface an OPC UA Client with OAS.
Step 1 – Check OPC Client License
After installing Open Automation Software verify you have a license of OPC Client on all OAS Engines that you want to interface with.
Start Configure OAS application from the program group Open Automation Software.
Use the Configure OAS application and go to Configure-License.
Check all OAS Engines that the OPC Client product appears in the Enabled Products list.
Step 2 – Define User Security
The OAS Engine by default restricts Tag Browsing so in order for an OPC UA Client to browse tags there are 2 options.
Option 1: Specify User authentication in the OPC UA Client with an OAS user that would have access to Get Tag Group Names and Get Tags Names.
Option 2: Go to Configure-Security and select the Default security group and allow Get Tag Group Names and Get Tag Names in the Tags tab of the Default security group.
Step 3 – Connect OPC UA Client
In the OPC UA Client software use the endpoint url opc.tcp://localhost:58728 to connect to the server. You can change the port number under Configure-Options-Network of the OAS Engine where the server is hosted with the property OAS OPC UA Server Port Number.
Connect to the server from an OPC UA Client. We recommend Unified Automation’s UA Expert if you do not have a client to test with. You can also use OAS as an OPC UA client to define tags with data source of OPC UA.
Note: If you are unable to connect to the OAS OPC UA Server due to a certificate security error that is shown in the OAS System Errors go to C:\ProgramData\OpenAutomationSoftware\pki-server\ on Windows or the pki-server sub-directory where the OAS Engine is located on Linux and copy the files in the rejected\certs directory to trusted\certs.
Step 4 – Browse OAS Tags
From the OPC Client browse either the Local service or a remote service under the Network branch.
To add network nodes or IP Addresses where other OAS Engines are running go to Configure-Options-Networking and add to the NETWORK NODES form. These will appear under the Network branch.
We have used 127.0.0.1 in this example to demonstrate the feature, but in actual use it is not needed as it would be the same as browsing Local.
You will be able to browse all Tag Groups and Tags from the local or remote OAS Engine to then see all property values available for a Tag.
Value is the most commonly used Variable. See Tag Variables for a complete list of all variables possible.
The NodeId returned with be the full tag path and the property selected. It this case Ramp.Value for the local Tag Ramp.
NOTE:Live Data Cloud hosting is only required if the hosting server has a dynamic IP Address without a fixed IP Address or fixed network node name. Basic Networking is the most common method of networking.
Continue to browse additional Tag values to add to your OPC Client specifying the Publishing Rate for your desired update rate to your Client.
All Data Sources for OAS with a valid license are supported for communications through the OAS OPC UA Server.
You can deploy the OAS Engine to multiple server PCs, each OPC UA Server support communications to any OAS Engine with an OPC Client license that is also version 14.00.0042 or greater.
The Web HMI, Web Trend, and Web Alarm products are completely open architecture that can be integrated into any web platform. WordPress is one of the most popular platforms to create websites.
NOTE: If you want to visualize your data in a desktop or mobile browser with zero programming, you may be interested in the OAS Open UIEngine . The UIEngine is a robust no-code web application and HMI builder for developing rich user interfaces in a browser-based development environment. See the UIEngine Documentation to learn more.
You can view the Web HMI in WordPress Video to familiarize yourself with the following steps to easily add a live user interface to your WordPress site.
What You Will Need to Start
In order to set up Web HMI in WordPress, you will need to have the ability to install a plugin on your WordPress site. Depending on your plan with WordPress or your user restrictions you may or may not be able to do this.
You will also need to have the OAS Service running and a license for WebHMI.
Adding the Script Files
The first thing you will need to do is add some script files to your site. If you don’t already have one, create a folder at the root of your site and call it js for JavaScript. If you already have a scripts folder, you can just use that one.
OAS installs with the script files you need. On my machine, they have been installed to: C:\Program Files\Open Automation Software\OAS\HTML_HMI. The files that you need are:
opc-lib-min.js
lib/jquery-1.8.3.min.js
The opc-lib-min.js file is the OAS Web HMI Script Library. The other file is the jQuery library. If your site already references a newer version of jQuery you may use that instead.
Copy those files into the js folder you just created.
Referencing the Script Files in the Page Headers
Next you will need to add references to the script files in the page headers of your site. If you already have the ability to do that, you can skip adding the plugin.
To add the plugin, go to the Dashboard of your WordPress site and from the left menu choose Plugins >> Add New. In the keyword search box, enter: Header and Footer Scripts.
When you see the Header and Footer Scripts plugin in the results, click Install Now. Once it has installed, click Activate.
Next, from the left menu of the Dashboard, choose Pages >> Add New. Give your new page a title. At the bottom of the new page, you should see a new section that says Insert Script to Head.
The first is the reference to the jquery library. Second, is the link to the opc-lib-min. If you put have yours in a different location, please be sure to change the src to reflect that.
The next line is the OAS_Config script block.
It has a security token in it that keeps session for the OAS WebHMI. It also has the URL for the OAS Service you want to point to. After the colon is the port number that you have the OAS Service set up on. Please note: that if your WordPress site is not on your local machine but your OAS Service is, you will need to have your service tied to a publicly accessible IP address or domain name, localhost will not work.
Click Save Draft to save your work.
Add HMI to the Page
Click the Plus Sign to Add a Block. You will need to choose Custom HTML.
You must have an ID for the div, it can be whatever you want. The OAS demo tags include a Sine Tag. If you don’t have a Sine Tag in your current configuration, enter the name of a tag that you do have followed by .Value. for the oas-tag-txt.
There are two articles in our knowledge base that you can
reference to help you write your own:
Click Save Draft to save your work and then Preview to see the results.
You should now be displaying the Sine Value (or the value of whatever tag you used) from your OAS Service in your WordPress site. If you open your OAS Configuration Application, you should be able to see the values updating together with a slight delay.
Utilizing the Web HMI Wizard
The OAS Web HMI Wizard is a tool to help developers create a Web HMI interface. Click Here to Open the Web HMI Wizard. There is a video that goes into detail about how to use it in here: Web HMI Wizard.
Open the Wizard and then expand the oas-tag-txt section on the left. Enter Sine.Value into the tag box. In the format string box below that, enter My Sine Value is {0}. In the format float box further down, enter .00. Now on the left you should see some code displayed in the HTML ELEMENT window and the Live Demo window below that should be displaying your Sine Value as a string truncated to two decimal places with the My Sine Value is in front of it.
Cut and paste the code from the HTML ELEMENT box into your WordPress site inside of a Custom HTML block to add it to your page.
Add the Header Scripts to Your Whole Site at Once
If you’d like to add the header scripts to all of the pages in your site instead of just one, you can. First, cut the code out of your first page. Then go to your WordPress Dashboard and from the left menu select Settings >> Header & Footer Scripts. Paste the code into the Header Box there and click Save Settings. You can also add the OAS_Config script block to an external file and then just add a script reference to that file to further contain things.
If you do not have a copy of Visual Studio you can download a free version of Visual Studio Community (formerly Visual Basic Express or C# Express) from visualstudio.microsoft.com/vs/community. You can choose whether to use Visual Basic or C#, but if you have no experience with either language, Visual Basic is easier for new developers. We do recommend Visual Studio 2017 or higher.
The following guide shows you the easy steps to define the MTConnect schema that can be used to read the possible data items and automatically create OAS Tags to be used with live update.
How to interface MTConnect live data into Open Automation Software.
Use the following steps to become familiar with the easy setup of MTConnect in OAS.
Step 1 – Check MTConnect License
Start Configure OAS application from the program group Open Automation Software.
Select Configure-License. Verify that MTConnect is one of the available Drivers in the lower left of the form. If you do not see MTConnect available contact support@oasiot.com to update your license.
NOTE: To configure remote OAS Engines enter the IP Address or node name in the Network Node field and click on Select.
Enter a meaningful Driver Interface Name that you will refer to this physical connection when defining Tags with a MTConnect Data Source.
Set the Driver to MTConnect.
Leave Enable and Add Tags Automatically enabled.
Specify the Live Data Url for the MTConnect stream.
Optionally define a secondary failover of data stream if the primary data stream fails with the property Enable Failover.
If both the primary and secondary device are offline the Return to Online settings determines the retry frequency.
View Driver Interface Failover for more information and and video demonstrating communications failover.
Select the Add Driver button in the left window to add the Driver Interface as an available selection when defining Tags in the next step.
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.
With the OAS Engine in Runtime and the Driver Interface property Add Tags Automatically is enabled all of the possible MTConnect data items will be added under a Tag Group with the same name as the Driver Interface specified.
Expand the tag group and sub groups to see all tags added.
If the Tag MTConnect Data Type is set to DataItem and the data stream has sent a value for the Id the current value will appear with Good Quality.
NOTE: You can optionally enable transaction logging for MTConnect communications to record all value changes to text files.
To record all data values for all Ids received from the data stream select Configure-Options and click the Network Node Select to then view the System Logging tab and enable the property Log MTConnect Communications and set the Transaction Log Path of where the files will be placed.
You can change the tag names of the OAS Tags if the automated creation does not suite your desired tag name.
Use the CSV Export and CSV Import on the toolbar in the upper right together with Microsoft Excel. to change multiple Tags.
You can private label Open Automation Software to deploy as your own IIoT software product quickly and easily. Edit the file OEMSettings.csv to include your company name, product name, support email, and web links. The settings will update the Configure OAS application, OAS Service application, and messages from the OAS Engine.
Prerequisite: OAS version 14.00.0017 or later must be used to support the OEM Settings.
OEMSettings.csv
The OEMSettings.csv file should be places in the same directory where the OAS Configuration.exe file, OAS_Service_Control.exe file, and OASEngine.exe service is deployed. The OEM Settings will update both the Windows version and Linux version of the OAS Engine, the file is identical for both versions.
The default location for Windows installation is C:\Program Files\Open Automation Software\OAS\ where you will find the example file. If editing directly in the installation folder launch your editor to Run As Administrator. As an alternative copy the file to another location for editing and copy back to the installation directory.
The default location for Linux installation is in the oas-linux root.
The OEMSettings.csv contains 2 columns, Item Name and Value. The item names must remain as the default names as these names are used as the identifier. The values will be changed to match your desired names and links.
Following are default values of the OEMSettings.csv file.
“Item Name”,”Value” “Company Name”,”Open Automation Software” “Product Name”,”Open Automation Software” “Short Product Name”,”OAS” “Help Web Page”,”/knowledge-base/getting-started-with-oas/” “Videos Web Page”,”/videos/” “License Key Generation Web Page”,”/manual-license-key-generator/” “Classic OPC Server Troubleshoot Web Page”,”/knowledge-base/overview-opc-troubleshooting/” “Access Remote Mapped Drive Web Page”,”/ufaqs/logging-ms-access-remote-mapped-drive-get-error-data-logging/” “Contact Company for Maintenance Renewal”,”Contact Open Automation Software at https://openautomationsoftware.com or reseller for renewal or install previous version.” “Support Email”,”support @ oasiot.com” “OPC UA Session Name”,”Open Automation Software” “OPC UA Application Name”,”Open Automation Software@localhost” “OPC UA Application Uri”,”urn:localhost:OpenAutomationSoftware:OpenAutomationSoftware” “OPC UA Product Name”,”urn:OpenAutomationSoftware” “OPC UA Certificate Subject Name”,”CN=Open Automation Software@localhost/O=Open Automation Software” “ProgramData Folder”,”OpenAutomationSoftware” “AppData Folder”,”Open Automation Software” “Tag Prefix”,”Open Automation Software” “Service Prefix”,”OAS” “Engine Service”,”OAS Engine” “Framwork 4.6.1 Service”,”OAS Framework 4.6.1 Service” “Reports Service”,”OAS Reports Service” “Classic OPC Service”,”OAS OPC Service” “Config App Image Path”,”Custom\Logo.ico”
OAS Configuration Application Icon
You can define the application icon using InstallShield or other install builder using the Shortcuts item. In InstallShield project go to Shortcuts and select the shortcut for the OAS Configuration application. There you can set the Icon property to your desired .ico file.
