Contoso-Drive Support Application

This repo is an IoT Central companion experience which is part of a set of repos demonstrating a Fleet Management scenario. To get up and running with the full experience, visit the Learning Path here.

Companion experience overview

Watch a 5 minute overview of the experience

Contoso-Drive is an example codebase and demonstration of an IoT Central companion experience. It's a codebase built around Fleet Management scenarios and leverages the Azure IoT Central REST APIs to communicate with the corresponding IoT Central applications.

The Contoso-Drive companion experience is split into three concepts

• The Support Portal. This application is an example of role specific scenarios for the technician/support person of Contoso-Drive. Typically this is a desktop application and is owned, managed and deployed by the Contoso-Drive company.

• The Driver App. This application represents the device that sends the vehicle's telematics to IoT Central which is subsequently available in the Support Portal. Typically this is a phone acting as a gateway and is run on the driver's mobile phone or an internet accessible device. Visit this repo to see the Driver Application.

• The IoT Central application(s). The main experience to manage the Contoso-Drive devices and admin level tasks for Contoso-Drive. It is typically used by the technician/support person and other privileged persons to perform admin level device management, insights and actions. Visit this repo to see the Learning Path on how to set up the Contoso-Drive IoT Central applications.

This repo represents the Support Portal application scenario.

The Support Portal codebase

The codebase is a SPA application that runs 100% in the browser. There is no server side API component. The server is only used to deliver the SPA files to the browser. All device interactions have been fully coded into the application. Therefore simulating or even using a real device will make the application functionally work as expected.

Usage

Setup

There are a couple of steps that need to be completed before running the code.

• Configure the AAD application

  You will need to have an AAD application so that an authenticated user can be authorized to use IoT Central APIs and ARM. If you have set up the support portal already, you can share the same AAD application. If you need to set up a new or different AAD application, use the following repo to guide you: Setting up an AAD application to work with IoT Central. Once you have an AAD application, change the config.ts file and update the following:

  AADClientID: '<YOUR AAD APPLICATION CLIENT ID HERE>',
  AADDirectoryID: '<YOUR ADD APPLICATION DIRECTORY ID HERE>',
  

• Configure Azure Maps

  You will need to add an Azure Maps Account into your Azure Subscription (choose Standard S0 pricing tier). Once completed, get your Primary Key from the Authentication option in the Azure Maps Account page in the Azure Portal and change the config.ts file and update the following:

  AzureMapKey: '<YOUR AZURE MAPS PRIMARY KEY HERE>'
  

First run

When you run the application for the first time, you will need to sign in and select the subscription that the IoT Central Contoso-Drive applications have been added to. All apps in that subscription will be available, but only those with the correct IoT Central device template will be used to query data. If you have followed the Learning Path module, you will be familiar with this concept.

Authentication

Once you have provided valid credentials, you will not need to re-provide these until the authorization token expires. During that period, every use of the application will silently sign you in.

Regular use

Once the app has been set up and is running, there are several screens that you can visit that demonstrate how to use the APIs to provide scenario-specific experiences.

View Map screen

The View Map screen is a visualization that spans across applications within the subscription. Here, devices (vehicles) can be selected which opens a side panel. Filtering the apps will remove devices from the map so you can find relevant devices.

Vehicle details

You can view basic telemetry that the device has sent. Additionally, the device-specific actions become available. The only operations that can be carried out are Diagnostics Mode (a writeable device property) and Reboot Device (a command). If you are using the Driver Application to simulate your devices, you will see the results of these operations in that application and the status in the details panel.

Fleet screen

You can filter applications on this screen. You can use this page as an example for how to use the IoT Central APIs to combine device properties, cloud properties, and device data into a single view. Additionally, it demonstrates single/silent sign-in deep-linking over to IoT Central to see the version of the device's details screen.

Register Driver screen

This screen is designed to demonstrate a series of API calls to create and register users into the application. This is the API orchestration:

• Use ARM APIs to validate access to the Azure Subscription
• Call MS Graph APIs to create a new user in the AAD directory
• Call IoT Central APIs to create the same user in IoT Central
• Call IoT Central APIs to create a new device and update a cloud property (the user's email) or update an existing device's cloud property
• Provide registration information for the Driver Application

Before running the Driver Application, the user should be registered using this flow

Using the Register Driver experience

Follow the steps in order to register a new user. Though the user's email address is additionally added as a cloud property, it offers no functionality again and merely serves to demonstrate calling the API.

Once completed, the registration information can be used for the Driver Application. Use the orange arrows to follow how the data lines up between the two apps.

Manage Apps screen

The manage apps screen provides basic information about each IoT Central application and is taken from the Azure Subscription data. The only interaction here is to deep-link over to the respective IoT Central application (which will also silently sign you in)

Installing, building and running the codebase

The codebase is built on create-react-app and therefore implements the same react-scripts. If you are not familiar with it visit the site for more details.

Install

npm ci

Build

npm run build

Run

npm start

Use

http://localhost:4004