Automatically translate this page?
17 July, 2018

When The Clouds Close Down: Feeding GPS Data to Microsoft Azure IoT

How to get messages from GPS trackers in MS Azure IoT via flespi telematics hub.

Today we will combine the power of Microsoft Azure IoT and flespi telematics hub — a powerful cloud IoT intelligence platform and a universal cloud platform for GPS and IoT connectivity.

You can always read the promotional and commercial details about both platforms on their official websites, so I will save you time and move straight to the nitty-gritty. Below is nothing but clear, bullet-point instructions which follow this scenario:

azure iot flespi integration

Create a channel in flespi

Add a channel that will pump the device messages into the flespi platform. Pick the protocol it will work over. You may also create a flespi device (optional) for each physical GPS tracker to group their messages together and have convenient access to them.

flespi channel toolbox

Hint: check the videos on how to create a channel and how to create a device in flespi.

Create Azure IoT Hub and IoT device

At this step we switch to Azure to create the IoT Hub and then create the IoT device

azure iot hub and device

Connect the flespi channel with Azure IoT device 

Click the plus button at the bottom right corner on the Streams page of the flespi panel to create a new outgoing stream. Pick the azure_iot protocol and fill in the required fields:

create azure stream in flespi

Hint: check the video on how to create a stream in flespi.

In azure_iot stream configuration specify hostname, device_id, and device_policy_key; you can copy those from the Azure portal:

hostname:

azure stream hostname

device_id:

azure stream device id

device_policy_key:

azure stream device policy key

Once enabled the stream will send telemetry messages into messages/events endpoint of the specified Azure IoT device. And don’t forget to subscribe the stream to the channel messages

Create an Azure function

Follow the instructions on how to create an Azure function here.

create azure function

Create Azure Cosmos DB

Follow the instructions on how to create an Azure Cosmos DB here.

create azure cosmos database

Combine MS Azure IoT Hub, Azure function, and Cosmos DB

New to Azure functions? Check for details here

A basic Azure function requires a configuration file and a code file. Here is what I came up with:

function.json:

{
 "bindings": [
   {
     "type": "eventHubTrigger",
     "name": "IoTHubMessages",
     "direction": "in",
     "path": "flespi-iot-hub",
     "connection": "flespi-iot-hub_events_IOTHUB",
     "cardinality": "many",
     "consumerGroup": "$Default"
   },
   {
     "type": "documentDB",
     "name": "device1",
     "databaseName": "outDatabase",
     "collectionName": "device1_collection",
     "createIfNotExists": true,
     "connection": "flespi-cosmos-db_DOCUMENTDB",
     "direction": "out"
   },
   {
     "type": "documentDB",
     "name": "device2",
     "databaseName": "outDatabase",
     "collectionName": "device2_collection",
     "createIfNotExists": true,
     "connection": "flespi-cosmos-db_DOCUMENTDB",
     "direction": "out"
   }
 ],
 "disabled": false
}

The above file configures my Azure function to execute every time a message arrives at my Azure IoT Hub instance and output the execution result into ‘device1’ and ‘device2’ collections of my Azure Cosmos DB.

index.js:

module.exports = function (context, IoTHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array: ${IoTHubMessages}`);
            
    var devices = new Object(); // create collection of devices

    IoTHubMessages.forEach(message => {
        var deviceId = message.ident;
        if (deviceId.indexOf(':') !== -1) {
            deviceId = deviceId.split(":")[0]; // skip password, if any
        }
        if (devices[deviceId]) {
            // device is already registered
            var device_messages = devices[deviceId];
            device_messages.push(message);
        } else {
            // register new device
            var device_messages = [];
            devices[deviceId] = device_messages;
            device_messages.push(message);
        }
    });

    for (var device in devices) {
        // output device messages into corresponding collection
        var device_messages = devices[device];
        context.log(`device: ${device}  - messages: ` + JSON.stringify(device_messages));
        context.bindings[device] = device_messages;
    }
    
 context.done();
};

This is my source code file (written in Javascript). It groups messages by devices, finds the corresponding output bindings, and sends them out to respective collections. The appropriate collection will be created in Cosmos DB as we specified “createIfNotExists”: true in the configuration file, and devices messages will be stored as documents in Cosmos DB collections. 

Finally, let's bring it all together and see how messages from devices connected to the flespi channel populate Azure Cosmos DB collections.

Logs are the ultimate weaponry of a developer. You can track the entire journey of telematics messages from GPS trackers to MS Azure IoT.

messages in flespi channel:

flespi channel logs

messages streamed to MS Azure IoT Hub:

flespi stream logs

messages are processed by Azure Function:

azure function logs

messages happily reside in Azure Cosmos DB collections:

messages in azure cosmos db

As a conclusion

Azure IoT is a very clever and powerful cloud platform. But it can’t parse data from various GPS trackers that communicate over a variety of protocols. Hey, that is exactly what the flespi telematics hub was invented for! Combining these two together brings synergetic power to your projects and business opportunities.

Hometask

Using the approach described in this article it’s possible to rename parameters so that they have shorter names (e.g. “lat” instead of “position.latitude”) or limit the set of parameters that are translated to MS Azure IoT Hub. Go ahead and try!



Get the latest updates and monthly newsletters from flespi in your inbox

11 October, 2018 | flespi integrations | Anton Kulichenko

Visualizing telematics data in Tableau. Dashboards, maps, charts.

Custom web data connector to get messages from flespi devices in Tableau and visualize telemetry data on fancy dashboards.

6 September, 2018 | flespi features | Anton Kulichenko

Migration between GPS tracking systems with zero data loss… and more

Proxy protocol allows forking the raw telematics data from trackers to up to three platforms, store messages, and easily debug connection issues.