Getting Started for Customers of PTC ThingWorx Cloud Services
If you are setting up the ThingWorx Azure Industrial IoT (IIoT) OPC UA integration on your own, go to the topic,
Step 1. Required Resources.
If you are a PTC ThingWorx Cloud Services customer, you can skip most of the installation, configuration, and deployment information in this section of the help center. However, you are responsible for connecting your edge devices to the Azure IoT Hub. To connect an IoT Edge device to the IoT Hub, a "device twin" must be created on the IoT Hub. Since PTC Cloud Services cannot provide you access to the Azure Portal, the "device twin" must be created using the Microsoft Azure CLI or Microsoft Visual Studio Code.
If you have not already, you should get to know ThingWorx Composer and ThingWorx Mashup Builder through the ThingWorx Platform 9 Help Center:
•
Getting Started with ThingWorx — Through use case examples, this topic starts you on your journey with ThingWorx and how you can use it in your organization.
◦
Programming for the IoT — With ThingWorx you can build solutions using ThingWorx Composer and ThingWorx Mashup Builder. This section of the ThingWorx Platform 9 Help Center will help you understand the ThingWorx concepts and modeling of devices, referred to as "Things". This section links you to ThingWorx
Analytics, which provides tools to embed advanced analytics into your smart, connected solutions.
◦
Modeling: Why do I have Thing Shapes and Thing Templates? — This topic explains the use of Thing Templates and Thing Shapes and provides a simple example of how they are used to represent different types of equipment at a site.
•
ThingWorx Model Definition in Composer: Modeling — For all the details about modeling, projects, things, Thing Templates, Thing Shapes, Thing Groups, Data Shapes, and more, refer to the topics in this section.
•
Mashup Builder — This section provides a wealth of information about building Web page visualizations that can deliver information from your ThingWorx OPC UA Industrial Connections. If you want to develop a UI for monitoring your OPC UA endpoints and devices, read this section as you experiment with this powerful tool.
Here are some general references for setting up IoT Edge devices and Edge modules in Azure IoT:
• Quickstarts to create a device on an IoT Hub using Azure Cloud Shell —
Quickstart: Deploy your first IoT Edge module to a virtual Windows device. There is also a Quickstart for a Linux device,
Quickstart: Deploy your first IoT Edge module to a virtual Linux device.
To create IoT Edge Devices and the IoT Edge Runtime, follow the steps in the next section.
Onboarding New IoT Edge Devices and the IoT Edge Runtime Device for Customers of PTC Cloud Services
As part of their deliverables, PTC Cloud Services provides you with an iothubowner connection string. It is up to you to create new IoT Edge Devices and set up the IoT Edge Runtime. The connection string contains all of the information you need to complete onboarding and comes in the following format:
HostName=<IOT_HUB_NAME>.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<ACCESS_KEY>
 |
You must enter both the name of your IoT Hub, (<IOT_HUB_NAME> as shown in the connection string and the entire connection string, from HostName= through <ACCESS_KEY> when running the Azure CLI commands in the steps below.
|
To perform the IoT Edge Device onboarding operations, follow these steps:
1. If you have not already done so, install, or update to, the latest version of the Azure CLI and the
Microsoft Azure IoT extension for Azure CLI. To install the CLI on a Windows system, refer to
Install Azure CLI on Windows.
2. To create a new Azure IoT Edge device on the IoT Hub, enter the following version of the az iot hub device-identity create command in the Azure CLI:
az iot hub device-identity create --device-id "<DESIRED_DEVICE_NAME>" --hub-name "<IOT_HUB_NAME>" --edge-enabled --login "<IOTHUBOWNER_CONN_STRING>”
Where
◦ <DESIRED_DEVICE_NAME> is the name to use for your IoT Edge device.
◦ <IOT_HUB_NAME> is the name of your Azure IoT Hub.
◦ <IOTHUBOWNER_CONN_STRING> is the iothubowner connection string provided by PTC Cloud Services. This connection string is needed to log in to Azure IoT to create the device.
|
|
This command will create and register the IoT Edge Device using symmetric keys. It is also possible to register using X.509 certificates, as explained in the Microsoft document,
Create an IoT Edge device, Option 2: Register with X.509 certificates.
|
3. Enter the following command in the Azure CLI and copy the JSON output to a file to be edited in the next step:
az iot hub device-twin show --device-id "<DESIRED_DEVICE_NAME>" --hub-name "<IOT_HUB_NAME>" --login "<IOTHUBOWNER_CONN_STRING>"
4. Open the file containing the JSON output, add the following name value pair, and save the changes:
"tags": {
"__type__": "iiotedge",
"os": "Linux"
}
5. Enter the following command in the Azure CLI, passing in the name of the file containing the updated JSON:
az iot hub device-twin replace --device-id "<DESIRED_DEVICE_NAME>" --hub-name "<IOT_HUB_NAME>" --login "<IOTHUBOWNER_CONN_STRING>" --json <UPDATED_JSON>
6. To retrieve the connection string for the newly created device, enter the following version of the az iot hub device-identity show command in the Azure CLI:
az iot hub device-identity connection-string show --device-id "<DESIRED_DEVICE_NAME>" --hub-name "<IOT_HUB_NAME>" --key-type primary --login "<IOTHUBOWNER_CONN_STRING>"
Where
◦ <DESIRED_DEVICE_NAME> is the name to use for your IoT Edge device.
◦ <IOT_HUB_NAME> is the name of your Azure IoT Hub.
◦ <IOTHUBOWNER_CONN_STRING> is the iothubowner connection string provided by PTC Cloud Services. This connection string is needed to log in to Azure IoT to retrieve the connection string for the new device.
7. Using the device connection string you retrieved, set up the IoT Edge Runtime to connect the IoT Edge Device to the IoT Hub, following the Microsoft instructions,
Install or uninstall Azure IoT Edge for Linux.
 |
The IoT Edge Runtime is typically deployed on Linux. However, it can also be provisioned on a Windows device by using Linux virtual machines. To install on a Windows VM, refer to the Microsoft instructions,
Install and provision Azure IoT Edge for Linux on a Windows Device (Preview).
|
This completes the setup of your IoT Edge Device and IoT Edge Runtime.
What's Next?
You need to log in to ThingWorx Composer and follow these instructions: