External Dependencies
WINDOWS: For the IoT Gateway to run, the server requires a 32-bit version 8 Java or OpenJDK-based JRE or full JDK installation. At this time, only 32-bit version 8 runtimes are supported. The most current supported version of 32-bit version 8 runtimes is always recommended.
LINUX: For the IoT Gateway to run, the server requires a working 64-bit Java or OpenJDK-based JRE or full JDK installation.
It is recommended that updates for Java be applied as they become available.
Tip: Java does not need to be enabled in a browser for the gateway to run.
Notes:1. Because the IoT Gateway is a product that has the potential to push data across the Internet to third-party endpoints, configuring the host computer or corporate firewall appropriately to allow just the specific ports that those endpoints are configured to use is recommended.
2. To prevent the loss of data and to keep the server running properly, installing Java updates while in production is not recommended. The runtime service and gateway service should be taken offline before a Java update is run. With Java 8 a new version is placed side by side with the existing version, allowing multiple versions of Java to exist on the computer at the same time. In this scenario, the default gateway behavior is to continue to use the old version of Java 8 until a reboot, an IoT Gateway restart or a change to the Java configuration in the Server Settings. If a JRE or JDK is specified to use for the IoT Gateway in the Server Settings, it will continue to use that version even after an update. The version of Java running is available through the Event log. Please see the online Support Site for specific recommendations for updating Java.
General Operation
This section explains how the two components, server runtime, and java gateway, work together to form the basis of the IoT Gateway. This also serves as an introduction to the terminology used in this document.
Initialization
An agent configuration is created using the IoT Gateway from within the Server Configuration user interface. Details of this are covered later in the document. When an agent is configured and a runtime connection with the Server Configuration exists, the server_iotgateway service starts as directed by the Plug-in. At this time, the configuration is transferred from the Plug-in to the gateway where it is initialized. There may be multiple configurations for the same type of endpoint in the Plug-In. Each of these configurations creates its own instance on the gateway.
An agent configuration is created using the Configuration API. Details of this are covered later in the document. There may be multiple agents configured in the same project or configuration. Each of these agents creates its own instance on the gateway.
Startup
At system startup with a configured agent, the Server Runtime loads its project file (e.g. default.opf). Upon detecting that an agent is defined, the plug-in starts the server_iotgateway service. The plug-in establishes a connection to the gateway service and transmits the active agent configuration(s).
At system startup the Java service may be set to startup by default. If there is no MQTT agent configured it is recommended to disable the Java service by following these steps:
Data Updates
Data updates are managed by the plug-in for the REST, and MQTT clientsserver runtime. The agent creates a server item reference from each configured tag and polls for data at the configured scan rate like any other client. Scan rates are configured on a per tag basis. The updates received are forwarded to the Java gateway service, where they are buffered and eventually pushed to the third-party endpoint at the configured publish rate.
Each data update persisted to the agent consists of four elements: ID, value, quality, and timestamp.
In the default “narrow format,” new data is pushed to the Java gateway when there is a change in value. More than one value change may be published per tag if more than one value update was received before the next publish time. All buffered data is sent with narrow format. The Every Scan feature sends an update to the gateway to be published to an endpoint for every good-quality scan of the tag whether or not there was a data change. A bad-quality scan will be sent only once. When the “every scan” option is set on a tag, the deadband setting for that tag is ignored. The “Wide format” option sends only the last data update for every tag enabled on that agent on each publish whether there was a data update or not. No buffered data is sent with the “Wide format” option.
Data Buffer
Each individual agent has a buffer of 100,000 events in case the third-party endpoint is unreachable. An event is a single value change of a single tag that is configured on that agent. The buffer stores the oldest 100,000 events; when full, it drops new data coming in. This buffer is entirely in memory and is not written to disk. There is no buffer enabled when using the “wide format” publish on the MQTT and REST client agents.
Shutdown
When the Server Runtime receives a request to shutdown, the IoT Gateway is responsible for stopping data collection. After sending the final tag updates, the IoT Gateway uses the messaging interface to tell the server gateway service to close any active TCP/IP connections to third-party endpoints.