The INVERS OneAPI is centered around vehicles.
Vehicles are the most important resource in the INVERS OneAPI: They each represent a real-life vehicle of any type, e.g. a car, moped, or kickscooter. Vehicles are addressed and identified by a
vehicle_id. This ID is generated by the INVERS OneAPI when you add the vehicle to your OneAPI fleet.
Typically, a vehicle is equipped with a telematics unit. This can either be an OEM telematics unit that is already installed ex-factory or an after-market telematics unit. To reflect that reality, every vehicle within the INVERS OneAPI relates to the telematics unit the vehicle is equipped with.
Every telematics unit has an ID assigned by the telematics manufacturer. In the INVERS OneAPI this is called
telematics_unit_id. It identifies the telematics unit among all telematics units of the same manufacturer, but is not necessarily unique across all telematics unit manufacturers supported by the INVERS OneAPI. Therefore, the
telematics_unit_id may not be unique in the entire INVERS ecosystem, but the
Your vehicles need to be equipped with a telematics unit that is supported by INVERS CloudConnect.
In order to interact with your vehicles, you need to add them to your fleet. Adding vehicles to your OneAPI fleet is easy and basically works the same way no matter what telematics unit is installed in your vehicles. You only need the brand of the telematics unit, its unique identifier/serial number, and credentials or a password to authenticate with the API of the telematics manufacturer or the vehicle itself.
If we cannot derive the vehicle model from the telematics unit’s identifier, you also need to provide the model so that we can correctly derive the vehicle’s capabilities. Optionally, you can also provide master data, such as license plate and custom fields. The process of adding vehicles to your fleet is described in detail on the Vehicle Lifecycle page and in our Integration Guide.
Interacting with vehicles⚓︎
Once a vehicle has been added to your OneAPI fleet, there are two channels for interacting with the vehicle. You can send commands to your vehicles and receive events from your vehicles.
Sending vehicle commands⚓︎
You can send commands to your vehicles via the Vehicle Commands API. Commands are sent via cellular network and are then executed by the vehicle. For example, you can unlock a vehicle’s central lock with the
To see a complete list of OneAPI-supported commands, visit Command Capabilities.
Receiving vehicle events⚓︎
You can receive events via the Events API using AMQP/RabbitMQ. Events have one of the following sources:
Events from a vehicle⚓︎
All vehicles with a telematics unit send events regularly. The frequency depends on the telematics unit and might also vary depending on whether or not the vehicle is currently driving.
A key event is the
VehicleStateRecorded event. It contains the current vehicle state and is generated every time new vehicle state information is transmitted by the vehicle. The vehicle state provides a hardware-agnostic description of the current state of the vehicle and the installed telematics unit, such as the GPS position or the central lock status. Depending on the vehicle model and telematics unit, each vehicle supports a subset of all possible vehicle state values. Which values are supported by a vehicle is described by the vehicle’s vehicle state capabilities.
For the complete list of all vehicle state values offered by the INVERS OneAPI, go to our API reference section.
Events from OneAPI⚓︎
The origin of these events is the INVERS OneAPI and not the vehicle or the installed telematics unit.
A key event is the
VehicleChanged event, which contains the current OneAPI representation of the vehicle including the vehicle’s master data. It is generated each time a vehicle property outside of the vehicle state (see above) is changed or updated. This could be the vehicle’s
operation_status, its master data, and so on. Usually, those changes happen via the Vehicle Management API or via FleetControl.
Furthermore, there are
VehicleRemoved events. Altogether, those events help you keep your fleet’s vehicles in sync between the INVERS OneAPI and your own application(s). Have a look at our Integration Guide to find out more.
- Store additional master data, such as license plate, vehicle identification number (VIN), custom name, remark, and tags.
- Use custom fields to store arbitrary metadata for your vehicles in addition to the predefined vehicle master data.
- Examine the vehicle’s connectivity status by looking at its life status.
- Group the vehicles in your fleet, e.g. by using the operation status or tags.
- Get a list of supported vehicle capabilities to see which commands and vehicle state properties a specific vehicle supports.
- List all the vehicles in your fleet together or search for specific vehicles based on the vehicle’s master data, custom fields, and more.
- Retrieve the latest vehicle states containing the most recent value for each of the supported vehicle state properties. Note: You should only use this if you need to know the current state of your vehicles only from time to time. If you need to receive a new vehicle state instantly after something happens or changes at your vehicles, please use the Events API instead!
Storing additional master data or custom fields for your vehicles is completely optional. However, by using those features of the Vehicle Management API you can make your life easier, as it streamlines your integration with the INVERS OneAPI and boosts your options in FleetControl. You then have more data to base your workflows on and to find the right vehicle using FleetControl’s fleet viewer functionality. Have a look at our Integration Guide to find out more.
When a vehicle is removed from the fleet, it immediately becomes unavailable for regular operation. The vehicle and its data remain in the vehicle archive for up to 90 days. Archived vehicles can no longer receive commands and data is no longer updated, e.g., last contact or latest vehicle state. The data of an archived vehicle can still be viewed by FleetControl or OneAPI.
Removed vehicles can also be added back to the fleet. If the vehicle has a CloudBoxx as a telematics unit, the telematics unit can also be added back into another vehicle to subsequently add it back to your fleet.