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.
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 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.
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>'
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.
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.
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.
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.
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.
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.
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
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.
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)
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.
npm ci
npm run build
npm start
http://localhost:4004