We advise customers to use the full official Kepware documentation here:

iot-gateway-manual.pdf

Architecture

The IoT Gateway feature includes two main components:

• The server plug-in (IoT_Gateway.dll) is responsible for:
  • Configuration of the MQTT, REST client and, REST server agents
  • Data collection from the server runtime
  • Configuration of the Gateway settings
  • License enforcement
• The IoT Gateway system service (server_iotgateway.exe), which:
  • Manages the connections to each third party endpoint
  • Buffers data collected from the plug-in
  • Provides the authentication and encryption layer to each agent

This diagram shows the layout of the IoT Gateway and components. The plug-in and gateway are installed on the same machine with KEPServerEX. KEPServerEX uses drivers to connect to data sources. That data is collected in the plug-in and sent to the gateway. The gateway publishes that data to the configured endpoint(s). In this diagram, data flows from the device/data sources at the bottom up to the endpoints at the top.

Factbird is attached as the MQTT Broker in this overview.

The data is split into two major groups, "event" & "input" by the following definition:

• Input is regularly sampled time-series data, usually counters or process values. Examples of data types that belong in the input group of data could be:
  • Bottleneck counters of a production line
  • Scrap sensors
  • Temperature measurements
  • Vibration measurements
• Events are data that happen at a certain time, and usually as a response to some event happening. In the Factbird Cloud, events are not shown on a graph, but are instead used to tie an action to an event. Examples of event data could be:
  • Batch started/stopped
  • Button pressed
  • Stop registered by the line
  • Stop split

Setup

Assuming that the Kepware server has been set up with connections to the PLCs and an IoT Gateway, this covers the steps after that.

Setting up Kepware to publish MQTT messages to Factbird involves several steps:

• Adding the AWS Root certificate to Windows server

  
  💡 Some newer versions of Windows server do already have AWS Root CA installed!

   

  AWS certificates may be downloaded from here https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs. The VeriSign (legacy) CA link (necessary if communicating with an endpoint excluding -ats) may be dead, in which case the certificate can be downloaded from the following link:

  VeriSign Class 3 Public Primary Certification Authority - G5.pem

  The IoT Gateway supports the use of self-signed certificates with the MQTT and REST clients. For the MQTT Agent, this certificate can be used with one-way and two-way authentication. When two-way authentication is used, the user must also import a client certificate. These agents use the Microsoft Windows, computer-level trusted certificate store to keep track of these certificates. By using this store, most recognized certificate authorities are already approved. To import a certificate, use the instructions below.
  
  

   

  Note: It is necessary to log in to the computer with an account that is part of the Local Administrators user group to add certificates to the appropriate Windows certificate store.
  
  
  

  • Adding AWS Root Certificate in Windows Certificate manager by opening start menu and find Manage computer certificates

    

    Import the certificate under Trusted Root Certification Authority.

    

    Import under Current Machine.

    

    Select the Amazon Root CA 1 certificate file provided by Factbird. Is also available directly from Amazon

    

    Place the certificate under Trusted Root Certification Authority.

    

    

• Adding the MQTT client certificate to Kepware
  
  
  

  💡 From manual-iot-gateway.pdf, page 12, Importing an MQTT Client Certificate:

  A client certificate used by all MQTT Agent objects can be imported and viewed through the Administration | Settings... menu. A MQTT client certificate needs to be imported when connecting to MQTT brokers (e.g AWS IoT) that require two-way authentication; also known as Client Certificates or Client Authentication. When using TLS with two-way authentication the client provides a certificate that allows the server (MQTT broker) to identify and authenticate the client.

  

  Import New Certificate: Use this button to import a certificate in .PFX, .DER, .CER, .CRT, or .PEM format. PFX certificates contain the private key, but may be password protected. All of the other certificate types require the user to select an accompanying private key file, which may be password protected.

  View Certificate. This displays the details of the current certificate.

  Note: When importing a certificate, the new certificate does not take effect until the MQTT Client Agent(s) are stopped and restarted by disabling and re-enabling them or by reinitializing the server runtime.
  
  

• Configure Kepware IoT Gateway Agent with Client Name and Topic URL

  
  💡 Look at manual-iot-gateway.pdf, page 19, Configuring an Agent:

  When configuring an agent in Kepware we need to configure an agent for both the input and event data. See Architecture for data segmentation.

  
  💡 Best practice is to create an Agent for both input and event topics.

   

  • URL: Provided by Factbird
  • Client Id: UUID provided by Factbird
  • Topic: plc/[input | event]/[uuid] Example: plc/input/xxxyyyzzz
  • QoS: 1
  • TLS Version: 1.2
  • Password: none (We are using certificates to authenticate and not basic auth)
  • Client Certificate: Enabled
  • Rate(ms): 10.000

• Setting up a Tag in the IoT Gateway Agent

  
  💡 Look at manual-iot-gateway.pdf, page 37, section Adding Tags to an Agent:

  An important thing to note, if you want to be able to detect stops (or, specifically, tell the difference between a stop and an offline device), then you need to change the tag to send up data at every scan and choose a sensible scan rate, such as 5000ms.

  

  Usually, it's enough to do this for all PLC tags that count good items, and simply let the rest send only on changes.
  
  

• Change the IoT Gateway Agent with a High Publish Rate

  First, open up the properties of the IoT Gateway Agent:

  Next up, configure the publish rate to something sensible, like 1000 events every 1000ms, to ensure we get all the messages that Kepware wants to send.

  

💡 Often, we see PLCs only updating their timestamp on write and not read. This leads to them sending the same timestamp if they are stopped. To handle this, you can add the configuration value sampleTimestampEvent: 'WRITE' to the root of the config object of the peripheral.

Disclaimer: This is not a reliable solution (as we shift the times).

Consider the following case: { equipmentType: 'plc', uuid: 'uuid', timestamp: '2020-12-18T11:32:24.079Z', values: [ { t: '2020-12-18T11:32:19.625Z', v: 823496, id: 'id' }, { t: '2020-12-18T11:32:20.720Z', v: 823498, id: 'id' } ] }, { equipmentType: 'plc', uuid: 'uuid', timestamp: '2020-12-18T11:32:24.110Z', values: [ { t: '2020-12-18T11:32:21.813Z', v: 823502, id: 'id' } ] },

The two measurements are sent milliseconds apart, and it seems 823502 was received slightly later the 823498 was measured and sent. Shifting from Kepware server time (WRITE config) results in 823498 being shifted after 823502. This will lead to a reset detection (drop in value), and there's no reliable way of not detecting it, because the behavior reflects an error. As per 27/01-2021 we are ignoring any additional observations within that bundle.

Client id

In the IoT gateway properties, configure the Client ID to be the UUID of the peripheral. If using more than 1 client per UUID, you may be able to use [UUID]-[Client identifier].

Multiple topics/UUIDs

Sometimes we want to send data to multiple different topics from the same Kepware server. For example, ‘plc/input/xyz123’ and ‘plc/event/xyz123’. However, Kepware server does not currently support using separate certificates for different topics.

To work around this, you can use one of the following methods:

• If sending to the same UUID on both topics, you can simply set different clientIds of the format [UUID]-[Client identifier] for the two IotGateways in Kepware (If the cloud supports it).
• Otherwise, you attach the same certificate to multiple Things in AWS IoT. This will allow Kepware to use a single certificate for multiple UUIDs

Tag names

Factbird technically supports tag names to include letters, numbers, and symbols with a few exceptions. However, we recommend following:

• Use clear and consistent naming, like ISA95 standard
• Avoid special characters like @#&()?+`^*,-
• Avoid local characters like øæåàâ
• It is safe to use ._

Common Problems & Troubleshooting

Troubleshooting PLC Connection via Kepware:

• If a PLC tag appears offline:

  • Check that the machine (production line) is turned on

  • Check that Kepware has a connection to the PLC (expand for more)

    • Open up your KepServerEx instance and connect to your runtime if it's not already connected

    • Open the Quick Client tool

      

    • Locate the PLC tag from the menu on the left side

      

    • Click on the tag, and verify that the Quality column says Good

    If the Quality is Bad, this indicates that there is a problem with the connection from your PLC to your KepWare server.

  • Make sure that the Kepware IoT Gateway is sending with the right clientId and topic

• If the PLC has no connection in Kepware:
  • Make sure that the PLC is configured correctly
  • Check that no firewall is preventing connections to the PLC
  • Check that the PLC has whitelisted the server to read from it (only needed in some cases)
• If PLC has connection in Kepware but is offline in Factbird
  • Restart Kepware runtime
  • Make sure that the PLC tag is set up in IoT Gateway to send up data to Factbird
  • Ensure that the tag in IoT Gateway matches the peripheral id in Factbird

Troubleshooting Kepware:

• Firewall blocking connections to the PLC/OPC servers or outgoing to the MQTT endpoint

  • Make sure that firewalls on your sandbox/testing server match your production setup

• Make sure that IoT Gateway is enabled

• Check if there is anything suspicious in the Kepware server logs

https://www.ptc.com/store/-/media/kepware-store/en/manuals/iot-gateway-manual.pdf

https://www.ptc.com/store/-/media/kepware-store/en/manuals/iot-gateway-manual.pdf