KEPServerEX and Microsoft Azure IoT Edge

www.kepware.com 1 © 2018-2020 PTC, Inc. All Rights Reserved

Connectivity Guide KEPServerEX and Microsoft Azure IoT Edge

April, 2020 Ref 1.04


Table of Contents

1. Overview ........................................................................................................................................................................................................................................................ 3 2. Configure IoT Edge as a Transparent Gateway............................................................................................................................................................... 3 3. Establish a Trust Relationship ....................................................................................................................................................................................................... 3 4. Ensure KEPServerEx Can Resolve the Azure IoT Edge Runtime IP Address............................................................................................. 4 5. Create IoT Device and Get SAS Token................................................................................................................................................................................... 4 6. Verify Successful “Device-to-Cloud” Communications ......................................................................................................................................... 13 7. Configure MQTT Client Agent to receive “Cloud-to-Device” messages from Azure IoT Hub .............................................. 14 Appendix A: Creating an Initial Deployment for the IoT Edge Device.................................................................................................................. 16 Appendix B: Importing a root certificate into the Windows Trust Store ............................................................................................................ 18


1. Overview This document explores how to configure the KEPServerEX® IoT Gateway Plug-in to communicate with Microsoft® Azure IoT Hub using MQTT over TLS through Azure IoT Edge acting as a transparent gateway. Once configured, modules in IoT Edge (such as Azure Stream Analytics, Azure ML, or custom code) can be used to “process” the data before sending it to the IoT Hub.

These instructions are similar to creating an IoT Hub direct connection, with the following additions: • Verify the server can resolve the Edge gateway name or IP address • Verify the Windows PC running KEPServerEX trusts the Edge gateway root certificate, and

allow KEPServerEX to open a TLS connection with the Edge Hub • Point to the EdgeHub module within Azure IoT Edge as the MQTT server endpoint instead of

using the IoT Hub directly.

Important: These instructions assume that an IoT Edge device has been installed with the IoT Edge Runtime and is registered with the IoT Hub.

For a step-by-step guide to creating initial deployments, see Appendix A.

2. Configure IoT Edge as a Transparent Gateway Follow the instructions from Microsoft (https://docs.microsoft.com/en-us/azure/iot-edge/how-to-create-transparent-gateway) for both Windows and Linux operating systems.

Important:

• The self-signed certificates generated via the scripts in the instructions above are meant for test scenarios and are not recommended for production.

• Record the IoT Edge gateway name or IP address (e.g. iotedgegw). This is the name in the hostname parameter in the MQTT Agent configuration

Information Example

< IoT Edge Gateway host name or IP address> edgegateway.mydomain.com or 10.10.100.200

3. Establish a Trust Relationship The Azure IoT Edge Runtime utilizes TLS (Transport Layer Security) to authenticate and encrypt communications between MQTT clients (like KEPServerEX) and the Edge Hub’s MQTT endpoint. A trust relationship must be established between KEPServerEX and Azure IoT Edge for communications to succeed.

Important: For communications to succeed between KEPServerEX and Azure IoT Edge, TLS authentication must be successful. TLS authentication requires a trust relationship between KEPServerEX and Azure IoT Edge.

Azure IoT Edge Runtime shares its device instance certificate with KEPServerEX automatically as part of TLS negotiation at the beginning of the KEPServerEX MQTT connection sequence to the Edge Hub. TLS negotiation will fail unless the Windows PC running KEPServerEX has imported the root certificate of the Azure IoT Edge Runtime into its Trust Store (according to Microsoft documentation).

Note: If the certificate utilized during IoT Edge Runtime setup was either a root certificate purchased from a third-party or trusted corporate certificate authority already trusted by the Windows PC running KEPServerEX, skip this step.

To import a root Certificate Authority certificate into the Windows Trust Store, see Appendix B.

https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.microsoft.com%2Fen-us%2Fazure%2Fiot-edge%2Fhow-to-create-transparent-gateway-windows&data=02%7C01%7CSteve.Busby%40microsoft.com%7C98a0006deee64ad6b2f308d5ec326a03%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636674623639011456&sdata=JBXXMnggFPy1Jv6lz5dQ%2FEP5s3dsD6%2Bz0LkwWi5kBA0%3D&reserved=0















4. Ensure KEPServerEx Can Resolve the Azure IoT Edge Runtime IP Address

When accessing the IoT Edge Runtime by hostname, and running ping <hostname> fails, it is likely there is not a DNS entry for the IoT Edge device’s hostname (e.g. iotedgegw) or the IoT Edge host is not configured to resolve NetBIOS hostname resolution. If a dynamically allocated IP (DHCP) is used for the IoT Edge host’s network adapter, it is recommended to configure the host to either support NetBIOS or configure a DNS entry for the network to be able to resolve the hostname. If a static IP is used for the IoT Edge host’s network adapter, add an entry to the \windows\system32\drivers\etc\hosts file on the Windows PC running KEPServerEX to resolve the name.

5. Create IoT Device and Get SAS Token The Azure IoT Hub acts as a central message hub for bidirectional communication between the IoT applications and devices. How “devices” are modeled depends on the specific application, but it’s important to understand that each IoT Device configured in the IoT Hub will be associated with the data stream/connection for an MQTT Client agent in KEPServerEX IoT Gateway Plug-in.

Notes: • These instructions use Visual Studio Code with an Azure IoT Hub extension to manage the

hub, devices and to monitor or send data to the IoT Devices. Management of IoT Devices can also be done through Azure CLI commands, through the Azure Portal and other coded methods using the Azure IoT Hub SDKs.

• Connection status for a device in the IoT Hub is based upon the overall connection state of the MQTT connection. An MQTT Client agent in the IoT Gateway Plug-in will only connect if the server has data to publish. If an application is designed to monitor the connection status of a device in the IoT Hub, it is recommended that you enable subscriptions in the MQTT Client agent (as defined in Section 7).

1. Open a KEPServerEX instance with the IoT Gateway Plug-in. In this example, one channel and

device are configured with the Simulator driver, and there is one tag that ramps up on scan.

2. Download and install Visual Studio Code at: https://code.visualstudio.com/download

https://code.visualstudio.com/download


3. Install Azure IoT Hub Extension for Visual Studio Code at: https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-toolkit

4. Once the Azure IoT Hub Extension is installed, click Select IoT Hub, and select Sign in when prompted by the pop-up noted below.

Note: The remainder of this guide assumes that an IoT Hub already exists within the Azure Portal account.

https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-toolkit


5. The default web browser will launch and open a Microsoft Sign In page. Log into the Microsoft Sign In page using Azure Portal credentials.

6. Once signed in, return to Visual Studio Code and expand the Azure IoT Hub extension in the Explorer tree view. Click the ellipses (noted below).


7. From the context menu, click Create Device.

8. Enter a Device ID for the new IoT device.


9. To verify the IoT device has been successfully created, find it listed below the Azure IoT Hub extension in the Explorer tree view.

10. The Connection String will part of the Device Info displayed in the Output window in Visual Studio Code. Review the Connection String that was created for the device and record the following pieces of information from this string:

Information Example

<IoT Hub name> myCloudHub1.azure-devices.net

<deviceID> myDevice1


11. Right-click the IoT Device and select Generate SAS token for device.

12. Enter a Time To Live (TTL) or expiration for the SAS token.

13. The SAS token will be created and displayed in the Output window in Visual Studio Code and automatically copied to your clipboard. Save the SAS token by pasting it into a text document.

Information Example <SAS token> SharedAccessSignature

sr=myCloudHub1.azuredevices.net%2Fdevices%2FmyDevice1&sig=HS%2FfyEVuCFxem5JYZJ%2BzKKIQZyp1 SqfcSVQDzSlgtCg%3D&se=1562872697


14. In KEPServerEX, click Add Agent… under the IoT Gateway Plug-in, and select MQTT Client as the agent type.


15. In the MQTT Client Agent, access the Client property group to edit the URL and Topic per the following formats:

• URL format: ssl://< IoT Edge Gateway host name or IP address>:8883

Note: This should point to IoT Edge as the endpoint, not directly to the cloud-based IoT Hub.

• Topic format: devices/<deviceID>/messages/events/<property bag>

<property bag> (optional) sends each message with additional properties in a url-encoded format. For example:

For more information about the property bag, visit. https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support.

Important: The topic format must include the forward slashes, including the ending forward slash the <property bag> objects are not included. For example:

ssl://myCloudHub1.azure-devices.net:8883

devices/myDevice1/messages/events/location=abcd&id=12345

location=abcd&id=12345

devices/myDevice1/messages/events/

https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support



16. Enter security credentials in the following formats:

Property Format

Client ID <deviceID>

Username <IoT Hub name>/<deviceID>/?api-version=xxxx-xx-xx Password <SAStoken>

Important: Refer to the following documentation for the latest API version: https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support

17. Access the MQTT Client Agent and select Add IoT items... to add an IoT item reference (i.e. a

KEPServerEX tag reference) to the Agent.

13. To verify that the MQTT Client agent has connected to the Azure IoT Hub, find an event log entry similar to the following:



6. Verify Successful “Device-to-Cloud” Communications 1. Verify a successful connection to the local IoT edge device instead of IoT Hub.

a On the edge device, run the docker logs -f edgeHub command.

b Once KEPServerEX IoT Gateway starts, the Edge Hub logs should indicate a successful connection:

2. Use Visual Studio Code to monitor the device’s built-in event endpoint and verify that data starts flowing from the Azure Edge Runtime to the cloud-based Azure IoT Hub within a few seconds.

a In Visual Studio Code, right-click the edge device entry and select Start Monitoring Built-In Event Endpoint.

b KEPServerEX data payloads should display in the Output window of Visual Studio Code.


7. Configure MQTT Client Agent to receive “Cloud-to-Device” messages from Azure IoT Hub

Applications can send write or command messages to KEPServerEX using “Cloud-to-Device” messages. When a device is created in the IoT Hub, an endpoint is created to allow this transaction to the device or MQTT Client Agent in KEPServerEX. Functionally, to send a command to a PLC, a properly formatted JSON payload will need to be sent as documented in the Kepware IoT Gateway Manual.

Note: Connection status for a device in the IoT Hub is based upon the overall connection state of the MQTT connection. Setting up the Subscriptions will ensure that the MQTT Agent will always reconnect, even when there is no data from the server to publish.

1. In the MQTT Client Agent, access Subscriptions property group. Change the “Listen for Write Requests” to Yes and update Topic per the following format:

• Topic format: devices/<deviceID>/messages/devicebound/#

For example:

For more information about the cloud to device messages:, visit https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support .

devices/myDevice1/messages/devicebound/#

https://www.kepware.com/en-us/products/kepserverex/advanced-plug-ins/iot-gateway/documents/iot-gateway-manual.pdf



2. Execute “Cloud-to-Device” messages from the Visual Studio Code IoT Hub extension to test the configuration. Right click on a device to receive the command and select Send C2D Message to Device.

3. Enter the JSON payload to send. Write a value to a specific tag or collection of tags per the IoT

Gateway manual.

4. The Visual Studio Code output should indicate that the C2D message was sent successfully.


Appendix A: Creating an Initial Deployment for the IoT Edge Device To create an initial configuration for an IoT Edge Device, follow the instructions below:

1. Access and log into the Azure portal.

2. Open the IoT Hub to access Settings and Properties.

3. Under subsection Automatic Device Management, select IoT Edge.

4. Select the desired Edge device name.

5. Select Set modules. Click Next to navigate through the prompts for Add Modules and Specify Routes. The default values do not need to be adjusted.

6. Review the deployment settings and select Submit.


Restart the IoT Edge runtime container and confirm the EdgeHub module is connected to Azure and successfully using Visual Studio Code.


Appendix B: Importing a root certificate into the Windows Trust Store

1. Launch Microsoft Management Console (MMC).

a. From the Start menu, open Run.

b. Enter mmc and click OK.

2. Add the Certificates Snap-In.

a. Navigate to File | Add/Remove Snap-In.

b. Select Certificates and click Add.

c. Select Computer Account and click Next.

d. Click Finish and OK to complete.

3. Expand Certificates.

4. Right-click Trusted Root Certification Authorities and select All Tasks | Import….

5. Browse for the root Certificate Authority certificate and import it via the Certificate Import Wizard.

6. Verify the certificate imported successfully via a confirmation from the MMC.

7. Restart the KEPServerEX Runtime Service.

KEPServerEX and Microsoft Azure IoT Edge

Documents

Transcript of KEPServerEX and Microsoft Azure IoT Edge