How to send data from an MXChip IoT DevKit to Thingworx through Azure

The purpose of this document is to see how you can setup an MXChip IoT DevKit and also how send the readings of this microprocessor to ThingWorx through an Azure cloud server. You will also learn how to view the values that are being sent.

Requirements:

- An MXChip IoT DevKit;

- Access to an azure cloud server with an active azure subscription;- The Device Explorer tool for IoT Hub devices (more info about the tool on this link)- Access to a TWX instance;

Connect the MXChip to your computer:

1. Connect the Micro-USB end to the DevKit;2. Connect the USB end to your computer;3. The green LED for power confirms the connection

Configure Wi-Fi:

IoT projects rely on internet connectivity. Use AP Mode on the DevKit to configure and connect to Wi-Fi

1. Hold down button B, push and release the reset button, and then release button B. Your DevKit enters AP mode for configuring the Wi-Fi connection. The screen displays the service set identifier (SSID) of the DevKit and the configuration portal IP address:

2. Use a Web browser on a different Wi-Fi enabled device (computer or mobile phone) to connect to the DevKit SSID displayed in the previous step. If it asks for a password, leave it empty.

3. Open 192.168.0.1 in the browser. Select the Wi-Fi network that you want the DevKit to connect to, type the password for the Wi-Fi conection, and then click Connect.

4. The DevKit reboots in a few seconds. You then see the Wi-Fi name and assigned IP address on the screen of the DevKit:

Start using the DevKit:

The default app running on the DevKit checks the latest version of the firmware and displays some sensor diagnosis data for you.

If you need a firmware upgrade, the screen will show the current and latest firmware versions. To upgrade, follow the Upgrade firmware guide

Next, you can test various sensors by pressing the B button. Continue pressing and releasing the button B to cycle through each sensor

Setup the development environment(Windows):

1. Download the .zip file that contains all the tools and packages for DevKit development. You can download the file from this https://aka.ms/devkit/prod/installpackage/latest

The .zip file installs the following tools and packages. (If you already have some of them installed, the script can detect and skip them.)

a. Node.js and Yarn: Runtime for the setup script and automated tasks.

b. Azure CLI 2.0 MSI - Cross-platform command-line experience for managing Azure resources. The MSI contains dependent Python and pip.

c. Visual Studio Code (VS Code): Lightweight code editor for DevKit development.

d. Visual Studio Code extension for Arduino : Extension that enables Arduino development in Visual Studio Code.

e. Arduino IDE : The extension for Arduino relies upon this tool.

f. DevKit Board Package: Tool chains, libraries, and projects for the DevKit.

g. ST-Link Utility: Essential tools and drivers.

2. Extract the downloaded file. Find install.cmd, right-click on it, and select Run as administrator:

3. Click Next to confirm install utilities like ST-Link drivers

Setup the development environment(macOS):

Homebrew is the easiest way to manage your CLI install. It provides convenient ways to install, update, and uninstall. If you don’t have homebrew available on your system, install homebrew before continuing.

1. Download the .zip file that contains all the tools and packages for DevKit development. You can download the file from this: https://aka.ms/devkit/prod/installpackage/mac/latest

2. Extract the downloaded file

3. Launch Terminal app, locate the folder into which you extracted the .zip file, and run the command: ./install.sh

Send data to Azure and ThingWorx via an Azure IoT HubThis demo/exercise will walk you through setting up TWX and Azure to work side-by-side

1. Get Access to a ThingWorx Instance

You'll need access to a ThingWorx instance. All new PTC-hosted ThingWorx instances are built on Azure VMs. Our engineering teams usually install ThingWorx on an Azure VM and use that.

If you don't have access to a ThingWorx instance, you get access to a free trial server at our ThingWorx Developer Portal. If you have access, you can log into the PTC Support Portal and download the latest version of ThingWorx.

2. Configure and Run a ThingWorx Azure IoT Connector

Go to the ThingWorx Support Portal and download the latest version of the ThingWorx Azure IoT Connector. It will be listed under, "ThingWorx Connection Server," on the software downloads page.

Configure a connection to your Azure IoT Hub and your ThingWorx instance by following the instructions in the ThingWorx Azure IoT Hub Connector Installation and Operations Guide, which comes with the connector download.

3. Send Data With the RemoteMonitoring Example

The remote monitoring example in this project is based on the RemoteMonitoring project that comes with the DevKit. You could run either. We've started our own fork for the following reasons:

We want to modify the project to send up more sensor values. Future enhancements could include more remote methods on the MXChip. We've annotated the code with lots of comments to save new developers ramp-up time. We don't want to, "mess up," our DevKit installations.

Open the RemoteMonitoring project and change the value of the Model parameter from „const char *twinProperties” which is on line 62:const char *twinProperties="{\"Protocol\": \"MQTT\", \"SupportedMethods\": \"Reboot,FirmwareUpdate,LedColor\", \"Telemetry\": { \"%s\": {\"Interval\": \"%s\",\"MessageTemplate\": \"{\\\"temperature\\\":${temperature},\\\"temperature_unit\\\":\\\"${temperature_unit}\\\", \\\"humidity\\\":${humidity},\\\"humidity_unit\\\":\\\"${humidity_unit}\\\",\\\"pressure\\\":${pressure},\\\"pressure_unit\\\":\\\"${pressure_unit}\\\"}\",\"MessageSchema\": {\"Name\": \"%s\",\"Format\": \"JSON\",\"Fields\": {\"temperature\": \"Double\", \"temperature_unit\": \"Text\",\"humidity\": \"Double\",\"humidity_unit\": \"Text\",\"pressure\": \"Double\",\"pressure_unit\": \"Text\" } } } },\"Type\": \"%s\",\"Firmware\": \"%s\",\"Model\":\"MXChipDemoSMH\",\"FirmwareUpdateStatus\": \"%s\",\"Location\": \"%s\",\"Latitude\": %f,\"Longitude\": %f}";

After you modify the value it should look like this:const char *twinProperties="{\"Protocol\": \"MQTT\", \"SupportedMethods\": \"Reboot,FirmwareUpdate,LedColor\", \"Telemetry\": { \"%s\": {\"Interval\": \"%s\",\"MessageTemplate\": \"{\\\"temperature\\\":$

{temperature},\\\"temperature_unit\\\":\\\"${temperature_unit}\\\", \\\"humidity\\\":${humidity},\\\"humidity_unit\\\":\\\"${humidity_unit}\\\",\\\"pressure\\\":${pressure},\\\"pressure_unit\\\":\\\"${pressure_unit}\\\"}\",\"MessageSchema\": {\"Name\": \"%s\",\"Format\": \"JSON\",\"Fields\": {\"temperature\": \"Double\", \"temperature_unit\": \"Text\",\"humidity\": \"Double\",\"humidity_unit\": \"Text\",\"pressure\": \"Double\",\"pressure_unit\": \"Text\" } } } },\"Type\": \"%s\",\"Firmware\": \"%s\",\"Model\":\"AZ3166\",\"FirmwareUpdateStatus\": \"%s\",\"Location\": \"%s\",\"Latitude\": %f,\"Longitude\": %f}";

The RemoteMonitoring example has more tasks than the SensorStatus one. After you open the RemoteMonitoring project, you'll run the following tasks:

cloud-provisiono Asks you to select the Azure subscription you'd like to use.o Selects or provisions the Azure IoT Hub to which you'll send data.o Creates a IoT device with the name specified in the project on your Azure IoT Hub

config-device-connectiono Verifies that you'd like to connect to the device the project created.o Writes the connection information to the MXChip.

device-uploado Sends the sketch to the MXChip.o Starts communication with the IoT Hub.

4. Monitor the data - Open the Device Explorer tool;- In the Configuration Tab paste the connection string for the IoT Hub you have used in the

previous step(when you run the tasks for the RemoteMonitoring project) and press Update;

- In the Data tab select the Device ID that you created in the cloud-provision task from the previous step(it should be AZ3166)

- Press the Monitor button. If you are in a PTC network with your computer, you will not be able to monitor the values using the device explorer, when you press the Monitor button the device explorer will just freeze and you won’t be able to close it. It will look like this:

- You will be able to monitor the values if your computer will be outside the PTC network, you will see the values like this:

- Either if you work from a PTC network or not, the values are being sent from the MXChip to your IoT Hub and you can see that from the IoT Hub Overwiew page under „IoT Hub Usage” you will see that there are messages sent:

5. Create a Thing Model for Your Azure Devices

Verify Configuration of Your ThingWorx Azure IoT Hub Connector

If you have properly configured your ThingWorx Azure IoT Hub Connector, the ThingWorx entities needed for this part of the exercise will already be present. The first time your connector contacts your ThingWorx server, it will install the Azure Extension.

Verify this by selecting, "Import/Export ..Extensions .. Manage," on the ThingWorx Menu bar:

If the Azure Extension for ThingWorx is properly-installed, you'll see an entry for, Azure_ExtensionPackage:"

If you don't see the extension, please follow the steps in the ThingWorx Azure IoT Hub Connector Installation and Operations Guide to get the Azure IoT Hub Connector properly configured.

Use the ConnectionServicesHub to Import Your Azure IoT DevicesIn the ThingWorx Composer, search for the ConnectionServicesHub Thing:

Select the Services section from the menu on the left, and run the ImportAzureIoTDevices service by pressing the Test button next to it. The service takes parameters, but you can accept the defaults:

If you wish to exercise more fine-grained control, and you know the Device ID of the Azure device you'd like to import, you can use the ImportAureIoTThing service, instead.

Contextualize Your Azure DataYou've imported your Azure Devices, and now have ThingWorx Things that represent them in

your Thing Model. The next step is to add some remote properties to your Things to contextualize your Azure data, and to get data updates flowing to ThingWorx.

Use either the AzureIoT Toolkit extension in VSCode or the iothub-explorer Node.js utility to get some data from your IoT Hub. Here's an example of the data flowing from my MXChip IoT DevKit:

My Azure Device ID, and therefore my ThingWorx Thing name, is MXChipDemoSMH(by default, the Device ID name is AZ3166 so if you haven’t changed it you should create a Thing name AZ3166). Go to the Home tab in ThingWorx Composer, and look for your Thing. Open your Thing, and select the Properties tab. Select, "Edit," at the top of the page, unless you're already in edit mode.

{"temperature": 80.8,"temperature_unit": "F","humidity": 39.2,"humidity_unit": "%","pressure": 957.1,"pressure_unit": "psig"}{"$$CreationTimeUtc": "2018-05-15T07:51:45Z","$$MessageSchema": "chiller-sensors;v1","$$ContentType": "JSON"}

In the dropdown next to the, "Add My Property," button, select, "With Remote Binding":

Don't worry if you hit, "Add My Property," and forget about the remote binding, though. All you need to do is press the „My Property” button and select the "Remote" option:

Azure is sending a property named temperature, and it's numeric(we know this because this is what the RemoteMonitoring project was created to do), so I add a property named, "temperature," and make it type, "# NUMBER." I also tell ThingWorx I want to persist the current value in the database, so I mark it so. Finally, I specify the remote property name as, "temperature."

Along the temperature property, if you check the RemoteMonitoring project you will see that it is also sending Humidity and Pressure properties so you can add those as well.

Finally you can see that you have values that are changed automatically for your properties, this means that you have succesfully manage to send data from your MXChip to Azure and further to your ThingWorx server: