Introduction

Fleet Management is a core use case for HERE Technologies. Pair our API’s with Microsoft Azure’s real time data processing capabilities and you get real time information about your fleet. In this workshop we will walk you through the simple process of deploying your own management website. You will set up a virtual fleet of vehicles driving around Chicago. Finally, we will also show you how to insert real-time vehicle parameters to track the health of the vehicles.

The application architecture uses Azure ARM templates, Azure Event Hub, Azure Serverless Functions, Azure PowerShell, Azure Cosmos DB and Azure Web App. You will be deploying your very own web application based on node.js to view the results in a web browser. The node.js based application is a “producer” script that simulates your own virtual fleet of vehicles. It also calls the HERE Geocoder serverless function to fetch the address corresponding to a latitude and longitude combination, that is stored in Cosmos DB. The Geocoder function receives the longitude and latitude, then finds the nearest physical street address.

See the diagram below for an overview of the complete architecture.

Modules

This workshop is divided into four modules. Each module describes a scenario of what we’re going to build and step-by-step directions to help you implement the architecture and verify your work.

Module	Description
1. ARM Template Deployment	The HERE Location Services Data Streams Template is a Solution Template on Azure
2. Data Setup Producer	Uploading the Producer setup data to the Azure PowerShell
3. Data Setup WebApp	Creating an Azure web-app and uploading the setup data
4. Validation	Launch the web application URL via the browser to see the dashboard on a real-time map

warning: These modules are intended to be executed linearly.

After you have completed the workshop, we recommend you delete all of the resources that were created by following the cleanup-guide.

Deploying your first ARM Template

Introduction

The HERE Maps & Location Services Data Streams Template deploys HERE’s Serverless Maps & Location Services, an EventHub and a CosmosDB for all your this application. In this first step you will sign up for the HERE Services (API’s), deploy your first ARM template and finally configure your web application.

What is an ARM Template?

Azure Resource Manager templates or ARM templates (learn more) is a way to quickly deploy services and dependencies depending on your use case. Simply put, it is a description of what your web application needs to run. HERE Technologies has created a number of ARM templates for you to use depending on the use case. To learn more, visit our blog post discussing these in depth.

In this module, you will deploy HERE Maps and Location Services Data Streams ARM Template. Azure ARM templates allows us to deploy various resources as a group, rather than handling these resources individually. As part of HERE Maps and Location Services Data Streams ARM Template, we will deploy Azure Event Hub, Azure Cosmos DB and HERE Azure Serverless functions as a group.

Solution Template Overview

HERE Maps & Location Services Data Streams Template deploys HERE’s enterprise class SLA backed Maps & Location Services, an EventHub and a CosmosDB for all your Azure Applications.

These services address a range of use cases like Fleet Utilization, Supply Chain Optimization, Urban Movement, etc., and open up new location intelligence opportunities in diverse industries like Automotive, Insurance, Internet and Media, Mobile Payments, Public Sector and Infrastructure, Telecom and Utilities, and Transportation and Logistics.

The function app in this ARM Template consists of the following HERE Location Service APIs:

• Geocoder: Forward and Reverse
• Batch Geocoder
• Geocoder Autocomplete
• Places
• Map Image
• Map Tile
• Routing - Mode (car, truck, public transit, bicycle) and algorithm (matrix, isoline routing)
• Positioning - Provides positioning estimates based on global Wi-Fi and Cell coverage, which includes the latitude and longitude of the position with accuracy.

Deployment Guide

1. Acquiring HERE API key
2. Deploying Solution Template on Azure Portal
3. Begin configuring your web application

1. Acquiring HERE API key

All users of HERE APIs must obtain authentication and authorization credentials and provide them as values for the parameters HERE API key in the HERE Credentials section in Azure’s template deployment page.

To obtain the credentials for the deployment of HERE Maps & Location Services Data Streams, please visit here to register for FREE with HERE.

Step-by-step instructions

1. Go to this link to register for FREE with HERE.

2. Provide your basic details and register your HERE account

3. After successful registration, It opens up the home page

   

4. Go to => Get your credentials: click on Create API key

5. It will generate your API key.

   

6. Note/save your API key to use in upcoming modules

2. Deploying Azure HERE ARM Template

The below steps help you deploy HERE Maps & Locations Services Data Streams Template in your Azure resource group.Use this link to deploy

Step-by-step instructions

1. Go to this link and type in the search bar HERE Maps & Locations Services Data Streams. In search result select HERE Maps & Locations Services Data Streams and the Click on Get it Now button to start the deployment process.

   

2. Click on Get it Now button to start the deployment process.

   

3. Read through the Microsoft agreement and click on Continue when you are ready.

   

4. You will be re-directed to template deployment home screen. Click on Create button to continue.

   

5. You will now be prompted to provide details specific to deployment. In the Basics use any existing resource group you might have or click on create new button to create a new resource group. Select your Subscription details and location and click Review + create to continue.

   

6. You now need to provide HERE credentials (HERE API key) which are pre-requisite to access HERE resources. If you already have HERE credentials available with you, provide the same and click OK. If you don’t have HERE credentials, please visit here(https://here-tech.skawa.fun) to register for FREE with HERE. You also need to select a Storage option, you can either select any existing Storage or continue with a newly created one.

   

7. You will see the summary of details, which were provided during the previous steps. Review the values and click Review + create once you are satisfied with all values.

   

8. Review the master agreement and click the check box at the bottom of agreement. You are now ready for template deployment. Click on Create to start template deployment.

   

9. Deployment should have started, and you will be able to see in the notification tabs deployment in progress. Once deployment is complete, you should receive the notification of the same and be able to see new resources in the resources section of your account.

   

3. Get Configuration Details

In this step you will find the connection string details of Event Hub & Cosmos DB to configure in the upcoming modules.

Step-by-step instructions

1. Open the Azure portal home page.

2. Select the Resource groups from the left hand navigational menu.

3. Select the Resource group which you used to deploy the ARM Template in the previous step.

   

4. You will be able to see the list of resources which were created as part of deployment of ARM template.

   

5. Select the Azure Cosmos DB from the list.

   

6. In the selected Azure Cosmos DB account page select Keys from left hand menu under Settings.

   

7. Copy the URI & Primary Key and note that in a text editor. These values will be used in configuration in upcoming modules.

8. Now go back to the Resource groups on the left hand navigational menu to get Event Hub Connection String details.

9. Select the Resource group which you used to deploy the ARM Template in the previous step .

   

10. Select Event Hubs from the list.

11. On the Event Hubs Namespace page, select Shared Access Policies from the left hand menu.

    

12. Select a shared access policy in the list of policies. The default one is named: RootManageSharedAccessPolicy. You can add a policy with appropriate permissions (read, write), and use that policy as well.

    

13. Select the copy button next to the Connection string-primary key field. Copy this key and note that in a text editor.This value will be used in configuration in upcoming modules.

    

Data Setup Producer

Introduction

Fleet providers use various IoT devices to capture data from their fleets. Typically this data includes real time positioning data in the form of latitude and longitude. These devices are also capable to monitor various vehicle health parameters and send them to a central system as a near real time feed.

In this module, you’ll a script to generate data simulating these IoT devices. The data will be generated and sent in a near real time feed to the Azure Event Hub.

You will use the provided command-line producer script to simulate latitude, longitude, engine temperature, RPM, load and coolant temperature.

You will then configure the Azure Event Hub and Azure Cosmos DB to receive the data.

Finally, you will send the data stream to the EventHub via which HERE Reverse Geocode function that will be invoked to fetch the nearest address against each latitude and longitude combination generated by the producer script. The response along with the stream parameters will be persisted in the Azure Cosmos DB.

Overview

The Event Hub receives the data from our producer script and facilitates the data being inserted into the CosmosdB. In this module we will deploy the producer script and make the connections between the Event Hub and the producer script.

Prerequisite

In our previous module we configured the Event hub and Cosmos DB. We assume that you have completed the previous module successfully, in this module we are going to FTP the producer script to generate the data every Five seconds.

Implementation

1. Data Setup for Producer

In this step you will download the script files from the link below and then we will walk you through the configuration to connect producer script with Azure Event Hub and Azure Cosmos DB.

Step-by-step instructions

1. Download the zip file Producer.zip and save it on your local machine.

2. Open Azure Portal home page and login with your credentials.

3. Click on Cloud Shell to open the Azure PowerShell command-line.

   

4. It may take few second for PowerShell command-line to be configured for your account.

   

5. By default, the path of PowerShell will be in the Azure directory. We need to set location to our home directory to execute our Producer script. Execute the below command to set location to your home path.

            >Set-Location $home

6. Above command would have changed the current path and it should be set as your home path.

7. In menu tab click on Upload/Download files icon, then click on upload to upload the zip file.

   

8. Browse to the directory where you saved the Zip file locally which you have downloaded in step-1. Choose the file and click Upload.

   

9. Once the upload is completed successfully, you need to extract the file. For extracting the files, use the below command.

            >Expand-Archive “Producer.zip”

   

10. It may take few seconds to extract, after successful extraction you can verify the file by using the below command.

           >ls

11. It lists the files and directories available in the current directory. You should be able to see new files now as the output of above command.

2. CosmosDB & Event Hub Configuration

In this step you will configure the Azure Event Hub and Azure Cosmos DB connection details in the Producer script. The producer will produce the data and send it to the Azure Event Hub which in turn invokes HERE Reverse GeoCode function and stores the response in the Azure Cosmos DB. The producer script will produce the current location, Engine Temperature, Engine RPM, Engine Load & Coolant Temperature details of the Truck.

Step-by-step instructions

1. Navigate to the Producer directory by executing the below command.

    >cd Producer

2. In menu tab click on Open editor icon, it will open the VS code text editor online.

   

3. In the left panel of text editor, select the Producer folder and under this folder find & open config.json

   

4. In config.json find the key here_credentials and replace the API key with HERE API key value which you have copied in the module 1.

5. In config.json Find the key eventhub and replace the connection_string with Event Hub Connection string-primary key value which you have copied in the module 1.

6. In config.json Find the key cosmosdb and replace the uri & masterKey with Cosmos DB URI & Cosmos DB PRIMARY KEY value which you have copied in the module 1.

7. After making the changes, click on more tab to save the file. Click on more tab on the right corner, click save to save the file. Then click on close editor to close the window.

   

8. Now back in to PowerShell execute the below command in the command window to install the dependencies.

    >npm install

   

9. Your Data setup for the Producer script has been completed successfully.

Producer Validation

In this step you can execute the producer script and validate whether the producer is emitting data or not.

1. On the Azure PowerShell window, execute the below command to validate the producer script. You will see the data generated by the producer script. By default, it produces data for 5 trucks.

    >node producer.js

   

2. You can simulate up to 10 Trucks from producer script. You can mention the number of trucks to be simulated at run time by mentioning it as an argument on the command line. You can mention any value between 1 to 10.

    >node producer.js 8

   

3. Press ctrl+c on the keyboard to stop the producer.

You have completed this module successfully.

Data Setup Web App

Introduction

In this module, you’ll deploy a dashboard to plot trucks on a map and watch their status in real-time. You will create a line-graph dashboard to analyze the various parameters of the trucks in real-time; temperature, RPM, load and coolant temperature.

Overview

In this module you will deploy an Azure Web App that creates a dashboard to monitor your virtual fleet of trucks in real time. In our previous module we deployed a producer script, which sends data to the Azure Cosmos DB. Using this web application we will fetch and interpret the data from the Cosmos DB and then we will plot a map with realtime updates.

Prerequisite

In our previous modules we have created and configured the Azure Event Hub and Cosmos DB to process our realtime information. We assume that you have completed the previous modules successfully. In this module you are going to create a Web App and deploy (FTP) the dashboard script to fetch the records from the Cosmos DB.

Implementation

1. Data Setup for Web App

Download the script files from the link below. Next we will walk you through configuring the script to connect the dashboards to Cosmos DB. This web application code will plot the dashboard for the trucks in near real time and it will also plot the line graph dashboard for the engine details.

Step-by-step instructions

1. Download the zip file FleetDashboard.zip files.

2. Save it in to your local machine.

2. Create Azure Web App

Now, we will upload the dashboard script files to Azure. Then we will walk you through configuring the scripts to connect to the Cosmos DB.

Step-by-step instructions

1. Go to Azure Portal home page.

2. Click Create a Resource on the top left. Enter web app in the search box to get the required resource type and hit Enter.

   

3. Select Web App from the search results and click Create button.

   

4. You need to provide some basic information for this App:

   1. Project details tab, select your subscription and the use the same resource group which you used in the previous modules.

   2. In the Instance details, the first box is the name of your app. Use unique and qualified name like fleetdashboard.

   3. Select Run-Time Stack as Node 8.0 and select Runtime as windows

   4. Leave the other parameters as default.

5. Click on Review & Create, it will validate the details.

   

6. Click on Create, it may take more than a minute for deployment to complete.

7. After successful deployment, Click on Go to resource.

   

8. In App service search bar type “Advanced Tools”.

   

9. Click on Advanced Tool under Development Tools section.

   

10. Click on Go -> it will open in a new tab.

11. In menu select Zip Push Deploy under Tools

    

12. Browse to the directory where you have saved the downloaded zip file (fleetdashboard.zip) in step-1.

13. Select the file and “drag and drop” into the “Kudu console” under /wwwroot path.

    

14. Files will be extracted automatically, wait till extraction is 100% complete.

    

15. Once extraction is completed, you will be able to see all the files and on the console you will see a log message “Deployment Successful”.

    

Configure Azure Web App

In this step you will configure your Azure Web App with Azure cosmos DB to run the webapp.

Step-by-step instructions

1. Now we are going to make configuration changes. We need to configure Azure Cosmos DB so that the dashboard is able to fetch the data.

2. Select the file config.js click the Edit icon (pen icon)

   

3. In config.js file find the variable config.endpoint & config.primaryKey and replace the value with Cosmos DB URI & Cosmos DB PRIMARY KEY value which you copied in the module 1.

4. Click on the Save button to save the file.

   

5. Click on the Script to open the folder in the list.

   

6. Now go to the file truck_dashboard.js click the Edit icon (pen icon).

   

7. In truck_dashboard.js file find the variable apiKey and replace the value with HERE apiKey value which you copied in the module 1.

8. Click on Save button to save the file & Close the tab

9. Go back to your Web App

10. In App service search bar type “Configuration” on the left hand navigation menu.

11. Click on Configuration under Settings section.

    

12. Click on New application setting.

    

13. In “Add/Edit application setting” add in Name as “WEBSITE_NODE_DEFAULT_VERSION” and Value as “8.9.0”, then click “update”. Click on “save” button to save the changes.

         Name: WEBSITE_NODE_DEFAULT_VERSION
         Value: 8.9.0

    

14. Click on overview tab, find URL to access your web app.

    

15. Save the URL to access the dashboard, we will use the same in the next module.

     Eg: https://fleetdashboard.azurewebsites.net

Implementation Validation

In this module, you are going to access the Azure Web App to view the dashboard which we have created in the previous module. You will be able to access two seperate Dashboards, one to track the Fleet movement and another one to view the engine health parameters.

Prerequisite

In our previous modules we have created a Web App. We assume that you have completed all the previous modules successfully. In this module you are going to execute the producer script to generate the data. You will then view the fleet movement of the vehicles on the dashboard by running the Azure web app.

Implementation

Steps to Execute the Producer Script

Step-by-step instructions

1. Open Azure Portal home page.

2. Click on Cloud shell to open the Azure PowerShell command-line.

   

3. It may take few seconds for PowerShell command-line to be configured for your account.

   

4. By default, the path of the PowerShell will be in the Azure directory. We need to set location to our home directory to execute our Producer script. Execute the below command to set location to your home path.

            >Set-Location $home

5. Above command would have changed the current path and it should be set as your home path.

6. Navigate to the Producer directory by executing the below command.

            >cd Producer

7. You can simulate up to 10 Trucks to generate the data with this script. You specify the number of trucks by defining it as an argument in the command line. You can specify any value between 1-10.

            >node producer.js 8

   

8. Keep this window open so that the Producer script can keep generating the data for the Dashboards.

Steps to Execute Web App

Step-by-step instructions

1. Open the browser tab and enter the Web App URL which you copied/saved in the previous module. It will be similar to the below format.

    Eg: https://fleetdashboard.azurewebsites.net

2. You should now be able to see the Map dashboard. Based on your truck count defined for the Producer script, the Truck icons will be displayed on the Map.

3. You should be able to see simulated movement of the vehicles on the dashboard.

   

4. To access the Line Graph dashboard, change your web browser’s path by adding “/graph” to the URL.

          Eg: https://fleetdashboard.azurewebsites.net/graph

   

5. It will open a web page where you can select any vehicle from the dropdown.

   

6. Click on the text box to select the vehicle.

   

7. Select a truck and click on the Submit button, it will plot the Line graph of the engine’s temperature, RPM, load and coolant temperature.

   

   

Congratulations you have successfully completed the workshop!

After you have completed this workshop, be sure you delete all of the resources that were created by following the cleanup guide.

Workshop Cleanup

This module provides instructions for cleaning up of the resources created during the workshop.

1. Resource Group Cleanup Instructions

:white_check_mark: Step-by-step directions

1. Open the Azure portal home page.

2. Select Resource groups on the left navigational menu.

3. Select the Resource group which you used to deploy the ARM Template and you used in the previous modules.

   

4. You will be able to see the list of resources part of this resource group.

5. Click on “Delete resource group” to delete all the resources.

   

6. You will receive a prompt to confirm deletion of resources. Enter the Resource group name in the text box then click the delete button.

   

7. It may take a few minutes to complete the delete operation.

   

8. Once the delete operation is completed you will receive the notification that Deleted resource group DemoResource

   

2. Producer Script Cleanup

Delete the AWS Producer files in Powershell.

:white_check_mark: Step-by-step directions

1. Go to Azure Portal home page.

2. Click on Cloud shell to open the Azure PowerShell command-line.

3. Enter the below command to clean-up the Producer folder.

       >rm -r Producer

4. Enter the below command to clean-up the Producer ZIP file

       >rm Producer.zip