Vehicle Configuration⚓︎
Vehicle Configuration allows you to configure additional features and settings of your vehicle’s telematics unit. Most of those features are exclusively available with an INVERS CloudBoxx installed into your vehicle. If third-party telematics units also support one or more of the features mentioned below, we are enabling you to configure those using the same API endpoints, lowering the effort on your end to work with telematics-specific configuration endpoints.
Types of configuration⚓︎
On this page, we cover two types of vehicle configurations:
- Feature configurations: The INVERS platform offers multiple additional features, which can be enabled for your fleet. Once enabled, you can activate them for your vehicles and, depending on the feature, adjust the configuration of the feature for individual, some, or all of your vehicles
- CloudBoxx settings: If your vehicles are equipped with an INVERS CloudBoxx you can adjust some of the settings of the CloudBoxx according to your needs. CloudBoxx settings are not vehicle model-related (see vehicle models for more info on that topic), but rather generic settings of the CloudBoxx
Feature configuration⚓︎
The Telematics Unit Configuration API (see box to the right) contains endpoints for activating, deactivating, and configuring each of the following features. You can also retrieve the current feature configuration of your vehicles.
Tracking⚓︎
The Tracking feature can be used to trigger the generation of additional vehicle states while driving, mainly to receive the current vehicle position. Trackings can be generated based on distance traveled, time elapsed, or heading changes.
Damage Detection⚓︎
The Damage Detection feature generates events for various types of damages ranging from small bumps or scratches to crashes.
Smoke Detection⚓︎
The Smoke Detection feature generates an event when someone is smoking in one of your vehicles. Using pattern recognition and factoring in the current state of the vehicle, our Smoke Detection service calculates the likelihood of a smoke event.
Driving Events⚓︎
The Driving Events feature generates an event each time a high acceleration is detected while driving, e.g. heavy braking, harsh cornering, or even crashes. You are able to adjust various thresholds in order to tailor this feature to your needs.
Parking Events⚓︎
The Parking Events feature generates events when abnormal acceleration or shocks are detected while the vehicle is parked, e.g. if someone is bumping into the vehicle or due to vandalism and break-in attempts.
Auto Immobilizer Control⚓︎
The Auto Immobilizer Control feature can increase security by automatically locking the immobilizer of your vehicle (see disable-driving command) if certain conditions are met, indicating that the driver has left the vehicle without properly locking or securing it.
CloudBoxx Settings⚓︎
CloudBoxx Settings allow you to configure individual settings of the CloudBoxx installed in your vehicle. These settings are not part of a specific feature listed above, and also not related to or affected by the vehicle model. Please refer to the Telematics Unit Configuration API linked at the top of this page to find out more, including descriptions and examples of the settings you can change.
Using the API⚓︎
For each feature (and for CloudBoxx settings), you can find three endpoints in our API:
GETendpoint to get the current configuration of the vehicle for that given featurePUTendpoint to activate the feature or to change configuration parameters of the featureDELETEendpoint to deactivate the feature
Useful hints and tips
If you would like to activate a certain feature using its default configuration, you can use the corresponding PUT endpoint and simply send an empty request body. We will then activate the feature using the default parameters. Consequently, if you would like to activate a feature while only changing one of the available feature parameters, you only need to provide the parameter you would like to change. We will fill in default values for the remaining parameters.
For example: The tracking feature has three configuration parameters. If you activate the feature using the PUT /vehicles/{id}/telematics-unit/feature-configuration/tracking endpoint and only provide values for time_interval_in_seconds and distance_interval_in_meters, we will automatically apply the default value for the omitted parameter heading_change_threshold_in_degrees (60 at the time of writing).
Be careful: If you would like to change one specific parameter of a feature and if you are not using the default configuration for all of the remaining parameters, you will need to supply the desired values for all other parameters diverging from the default value as well. Due to the semantics of a PUT request (vs. a PATCH), the entire configuration is replaced and not just the configuration parameters that you supply in your request.
Bulk configuration⚓︎
In addition to retrieving or updating the feature configuration or CloudBoxx settings of a single vehicle, we offer endpoints to update vehicle configuration in bulk. You can create bulk configuration change requests for up to 10,000 vehicles with a single API request, and then monitor the results of the bulk operation, as bulk configuration changes are processed asynchronously. The status of the resulting bulk configuration can be requested using the id of the bulk configuration job.
The configuration of features and settings will be applied to each vehicle. If a telematics unit can not be reached, the configuration request will be retried using an exponential backoff for up to 12 hours. The bulk operation is then concluded and you will be able to see a detailed result indicating which vehicles successfully received the updated configuration and which ones not, including the reason for that.
Example: Configure trackings and driving events, and disable parking events for multiple vehicles
curl -X POST \
https://api.invers.com/configure-vehicle-telematics-unit-bulk \
-H 'Authorization: Bearer ❰access_token❱' \
-H 'Content-Type: application/json' \
-d '{
"items": [
{
"id": "JQ7RP"
},
{
"id": "K7272"
},
{
"id": "MT3T3"
}
],
"feature_configuration": {
"tracking": {
"time_interval_in_seconds": 120,
"distance_interval_in_meters": 500,
"heading_change_threshold_in_degrees": 60
},
"driving_events": {
"crash_detection": {
"minimum_acceleration_in_mg": 800,
"minimum_duration_in_milliseconds": 60,
"data_gathering_duration_in_seconds": 5
},
"heavy_braking_detection": {
"minimum_longitudinal_acceleration_in_mg": 400
},
"harsh_cornering_detection": {
"minimum_lateral_acceleration_in_mg": 400
}
},
"parking_events": {
"enabled": false
}
}
}'
If the request has been successful, HTTP status code 201 will be returned. Here is an example of what the response payload might look like:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 | |