Activate vehicles using High Mobility’s sample application
In contrast to the utilisation of additional hardware, in-vehicle telematics offer the advantage of enabling the activation of cars while on the move, without the need for any additional dongles or installations.
There are two distinct methods through which vehicles can be activated for data transmission. In this context it is important to note that fleet-owned vehicles undergo a distinct activation process when compared to privately-used vehicles. To gain a deeper understanding of these variations and commonalities, our GraphQL-based, freely available open source sample application is ideally suited.
In order to start visualising data and going through the activation life cycle, we are recommending going through each of the following steps. Every underlying aspect will be explained in more detail both in the video of our 13th Open Dev Talk and this blog post.
- Deploy application and configure your data container
- Initialise the sample application
- Connect to a fleet vehicle
- Collect consent for privately-owned vehicles
- Revoking access to cars
Sample app deployment
To simplify the process, our primary focus will be on test data that can be virtually created. However, it's important to note that this setup is compatible with both live data and simulated data generated within the free simulation studio.
The initial step involves setting up the necessary credentials that will be used in the sample application and installing the application itself. Begin by accessing the High Mobility webpage, and navigate to the Downloads section. Click on the "Explore" button for the GraphQL Dashboard, which will lead you to our GitHub Repository.
The sample application can be deployed on various modern cloud services, including AWS, Azure, and Google Cloud.For Heroku users, we offer a convenient one-click installation button that streamlines the deployment process when you are logged in. All that's required is a unique app name, owner information, and region selection.
By clicking the "Deploy app" button, the installation process will be initiated, which typically takes about 5 minutes to complete. In the meantime, you can prepare the configuration of data points using the High Mobility console. If you haven't already logged in or registered a new account, navigate to the Build mode for sandbox data or alternatively, select the Live data mode for production.
If you have yet to create a data container, we recommend reviewing Open Dev Talk 09, where we explain the best practices for working with use cases, data containers, and presets.
When creating a data container, your first decision should revolve around whether the use case is related to fleet or privately-owned vehicles. Afterward, select the desired data points or opt for a respective preset.
During the respective Open Dev Talk session, we created a Maintenance preset for Fleet Operators or third-party fleet software providers. We also established a second data container with the same preset for individual drivers. The primary technical difference between fleet and individual driver apps lies in the process of vehicle activation. For fleet apps, we provide a clearance API, which can be used by passing in the vehicle identification number. In contrast, privately-owned vehicles undergo a visual OAuth-based consent journey for activation.
Once the vehicle has been approved and activated, there are eight different ways to utilise the data. The sample dashboard application showcased in the Open Dev Talk is built on the GraphQL API.
Initialising the sample application
Once the application has been successfully deployed, it can be opened in a browser. To initiate the configuration process, click the "Get started" button. Begin by selecting the appropriate app type that matches the fleet or individual driver data container created earlier.In our Open Dev Talk video, we kick off with the fleet data container. The GraphQL configuration can be obtained from the High Mobility console, located in the GraphQL tab of the client certificate menu for the corresponding data container.
After pasting the configuration, a blue checkmark will indicate the correct format of the snippet. For fleet-related purposes, the sample application employs the fleet clearance flow, which necessitates the use of the underlying service account credentials.
Returning to the console and the data container, you can generate the service account API key within the service account keys menu. The JSON content of the file should then be pasted into the related field of the sample application's menu. Within the same app container, you can also locate the OAuth credentials, which can be copied to the dashboard's configuration view.
After clicking the "Get started" button, the initialization process will be completed, and vehicles can be activated accordingly.
A hosted app instance cannot function as both a driver and fleet application simultaneously. However, there is no need for redeployment when switching between scenarios. The configuration can be reset using the settings icon located in the top right corner.
Connecting to fleet vehicles
If vehicles have already been activated using the fleet clearance API, the corresponding vehicle identification numbers will already be displayed in the vehicle dropdown menu. In case they haven't, new vehicles can be added directly in the user interface by entering the vehicle identification number and brand. When connecting via the Sandbox environment, you can utilise the virtual vehicle simulators to emulate the same clearance process.
The Car simulators can be found in the console module known as the "Simulation studio." When creating or launching a simulator, its VIN can be retrieved in the console view, which can then be copied to the field in the vehicle form of the dashboard sample application.
Upon submitting the initial vehicle clearance request, the status will be marked as "pending." Once the vehicle is successfully activated, the status switches to "approved," and all available data values will be displayed. To simplify the process, the virtual vehicle simulators will automatically activate after 3 seconds.
The "Filter properties" menu allows you to customise the view, and all fetched data values can also be exported as a CSV file. Additionally, the GraphQL open-source dashboard provides the flexibility to adjust the automated refresh frequency and switch between grid, list, and map views.
By using the dropdown menu on the left-hand side, you can add additional vehicles and access detailed views of the cars.
Using the Consent Flow for individual drivers
The configuration process can be initiated by clicking the "Get started" button. This time, you need to select the "Driver app" to initialise the configuration for B2C purposes.
Once again, the GraphQL configuration can be retrieved from the High Mobility console, located in the GraphQL tab of the client certificate menu for the corresponding data container. It is crucial to ensure that the associated data container is also configured for the single driver use case.
To complete the setup, the OAuth client credentials should be copied from the console data container to the corresponding fields in the sample app configuration. Before clicking the "Get started" button, it's essential to copy the outlined redirect URI to the corresponding input field in the data container to ensure that the user is redirected back to the sample app once the consent flow has been successfully completed.
After this, the configuration can be confirmed, and the first vehicle can be added.
Instead of entering the VIN, the consent journey will be automatically initiated. The user will be redirected to the High Mobility driver service, where they can review the requested data categories, data points, and processing purposes. When using the sandbox, the driver service will list all assigned car simulators in a dropdown menu, which can then be used to authorize access to the vehicle accordingly.
As soon as the user is redirected back to the sample app, the view will refresh, and data values will be displayed according to the simulator's states. Any changes to data points in the simulator will also be reflected in the dashboard view.
Within the dropdown vehicle selection menu, each car is listed alongside an accompanying cross button. Clicking this button will initiate the revoke flow, and access to the vehicle will be revoked, rendering update requests no longer possible from that point onward.
This same behavior is also applicable to real vehicles. Revoking the car is essential in this context to prevent any further charges in the upcoming months.
High Mobility Open Dev Talks
At High Mobility, we are passionate about new technology. We offer free open source tools and developer friendly documentation for any projects to be integrated smoothly. More than 800 developers and product managers have already signed up for our moderated community platform and we are hosting connected car competitions for your innovative, connected car ideas.
Join our community on Slack