In this article:

This guide provides a starting point for integrating Myriota and Microsoft Azure IoT Central (IoTC). Rather than connecting Myriota devices directly to IoTC, we deploy Azure resources to create a device bridge. This enables the Myriota Cloud to send messages via HTTP POST request, configured as a Destination in Device Manager, to an Azure Function that immediately forwards the data to IoTC. This guide provides links to Microsoft documentation, instructions for configuring the Azure resources and details about transforming the Myriota data messages into the IoTC message structure.

Requirements

• An Azure subscription; if you are just getting started with Azure you can use their free trial. The trial provides credits that enable the use of a consumption plan for the Azure Function App - Function Apps consume Azure credit when they are executed. Search Microsoft documentation for Azure pricing calculators for more information.
• A Myriota Device with a User App installed; we have used the Myriota SDK tracker example in this guide with a Dev Kit, but this example can be extended to support any Myriota message format and device.
• Your Myriota Device Manager account.
• You will need some Java Script coding skills to modify the message structure to suit your application.

Set Up IoT Central as a Device Bridge

Follow the instructions in the "Use the IoT Central device bridge to connect other IoT clouds to IoT Central" guide from Microsoft.

The guide walks through deploying an open-source project from Microsoft, hosted on Github, which deploys the Azure resources required. The example code does not need to be modified or forked in Github, customisations can be made within the Azure portal after following the deployment steps. (The project can be customised to include deployment of additional Azure resources, for example, Event Hubs or Azure Data Explorer - more information about IoTC data integrations can be found here.)  

As a prerequisite to the above guide, you will need to create an IoTC Application; open the Azure IoT Central portal. Select Build, then click the Create app button to create a custom app. Give your application a name, select Custom Application for the Application template, select your Azure pricing plan and subscription information.

When you create the IoTC application, Azure also creates a Resource Group called IOTC; when you deploy the example to Azure use this IOTC resource group.

After completing the npm install and function restart steps, the guide provides instructions to get the Function URL; we will use this URL to configure the Myriota Device Manager Destination.

Configure IoTC Destination in Device Manager

Open Device Manager, create a new HTTP Destination using the Azure Function URL.

Assign your Destination to a Device. Device Manager will POST any messages transmitted by your device to the Azure function.

Transform Messages to IoTC Format

Messages sent to the device bridge must have a specific format to be received by IoTC. This can be achieved by modifying the Java Script in the Azure Function App to transform the Myriota messages into a suitable format. 

The JSON struct below was copied from the IoTC guide at the time of writing; please confirm the IoTC message structure has not changed before proceeding. The examples below use this structure to illustrate the requirements.

In the Azure Function you have created, click on Code + Test to view the index.js file.

You can navigate to the function by starting on the Azure portal home page and clicking the "My Function Apps" tile; your function name will start with iotc. From the Function App, click Functions in the left hand menu, select the IoTCIntegration function from the list.

The module.exports = async function code can be modified to perform the data transformation. In the example below we have extracted the Module ID in the async function and have implemented an additional unpacker function to decode the Myriota message payload into the measurements struct required by IoTC. You can implement a new unpacker function to suit your data requirements. 

For detailed information about the Myriota Device Manager HTTP POST request structure, see the HTTP code example. We are extracting data from the data payload (the Data field).

The Data field in the POST request is a JSON serialised structure containing an array of raw messages received from one or more modules; the Packets array. 

Elements within the Packets array have the following structure:

• Timestamp: Unix epoch time (s) at which the POST request was fulfilled by the Myriota Cloud
• TerminalId: Module ID of the device from which the data was received 
• Value: Myriota message payload data, serialised as a 20-byte hexadecimal string

Although the POST request structure has been implemented as an array so that multiple device messages can be sent per POST request, Device Manager currently only sends one message per POST. There is no need to implement loop logic to parse the Packets array as there will only ever be data in the first array element.

Note that there are multiple timestamps included in each POST request; the timestamp of when the data was issued by the Myriota Cloud, the timestamp of when the packet was transmitted to the Myriota Network (contained in the Packets array), and timestamps can be included within the message payload (for example, a GNSS fix time, as shown below).

The message payload data is a serialised hexadecimal string and needs to be decoded into its component data types. The data types and message format depend on the Myriota Module User Application. To decode the string, use the appropriate node.js read function for each data type contained in the Myriota message. The node.js read function is passed the index of the first bit for each component of the message data. 

In the example below we are unpacking messages from the tracker example. The message payload includes the following fields:

Field	Data Type	Description
Sequence number	16-bit Unsigned Integer	Message sequence number
Latitude	32-bit Signed Integer	Latitude scaled by 1e-7
Longitude	32-bit Signed Integer	Longitude scaled by 1e-7
Timestamp	32-bit Unsigned Integer	Unix epoch timestamp in seconds of last GNSS fix

• IoTC uses millisecond representation of Unix epoch time; the timestamp must be multiplied by 1000 to convert seconds to milliseconds.
• The latitude and longitude are scaled by 1e-7 for precision and compression; these values must be multiplied by 1e7 to convert to decimal degrees format. 
• You also can assign values to IoTC data fields; in the example below we have assigned a value of "Myriota Tracker" to a field called DeviceType.

For readability a screenshot of the code modifications in index.js is shown below; there is an IoTC-tracker-snippet.txt file attached at the end of this article with a code snippet that can be copied and pasted into the index.js file in the Azure editor (you must replace the module.exports = async function and create the unpack_tracker function).

We recommend using the message injection function within Device Manager or the Satellite Simulator to send messages via the Myriota Cloud to IoTC to test your data transformation. 

Tip: You can view log messages in the Azure Function by clicking on Log at the bottom of the Function Code + Test screen. This is helpful to view when you are sending data as it will show any error messages, for example, if the data has not been transformed correctly into the IoTC message structure.

Create a Device Template in IoTC

Once the Myriota Cloud begins transmitting data to the IoTC Destination, the devices will appear in IoTC. To use data within IoTC the devices must be assigned to an IoTC Device Template which maps the fields in the measurements struct to IoTC data fields.

Templates can be created manually or they can be automatically created from the device data. To autogenerate a template, click on the module ID in Devices. Select Manage Template > Auto-create template. Follow the prompts on screen to map the measurements data to IoTC fields. 

Once the template has been created you can modify the display names of fields, rename the template and modify the views associated with the template. More information about device templates can be found here.

To convert the Unix epoch time of the GNSS Fix Timestamp to human readable format, click on the down arrow next to the GNSSFixTimestamp field and select DateTime from the Schema options. 

As an example of IoTC data visualisation capabilities, we can add a map that shows the device location coordinates to the About view in the Tracker Example IoTC device template.

1. On the Device Template screen, click Views > About.
2. Scroll down to the Map (telemetry) option and drag it onto the view.
3. Click the pencil icon to configure the tile.
4. Click the +Capability option and select the Tracking value. 
5. Click Save to save the view, click Back to return to the template and click Publish. 

Extending Your Integration

If you have Myriota devices with different user applications and message formats, you can create additional Functions within the Function App and create unique Device Manager Destinations for each device type. 

The IoT Central documentation portal contains useful guides such as integrating IoTC with other Azure services and mapping data on ingress using device templates (which may be an alternative to using multiple functions for multiple device types).

 

Code Snippet Download