Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Azure/iot-central-contoso-drive-support

An example IoT Central Companion Experience that demonstrates how to build a custom web app for a support technician operating a fleet management solution
https://github.com/Azure/iot-central-contoso-drive-support

iot iot-central webapp

Last synced: 3 months ago
JSON representation

An example IoT Central Companion Experience that demonstrates how to build a custom web app for a support technician operating a fleet management solution

Awesome Lists containing this project

README 

        
# 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](https://github.com/iot-for-all/companion-experiences-learning).



## Companion experience overview

Watch a 5 minute overview of the experience



[![IoT Central Companion Experience - Contoso Drive](/images/yt_thumb.png)](https://youtu.be/_6woSCJfk4I)



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](https://docs.microsoft.com/en-us/rest/api/iotcentral/) 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](https://github.com/iot-for-all/contoso-drive-simulator) 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](https://github.com/iot-for-all/companion-experiences-learning) 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](https://github.com/iot-for-all/iot-central-aad-setup). Once you have an AAD application, change the [config.ts](/src/config.ts) file and update the following:



  ``` 

  AADClientID: '',

  AADDirectoryID: '',

  ```



* __Configure Azure Maps__



  You will need to add an [Azure Maps Account](https://portal.azure.com/#create/Microsoft.Maps) 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](/src/config.ts) file and update the following:



  ```

  AzureMapKey: ''

  ```



## 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](https://createreactapp.github.io/) 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

````