Skip to content

Vehicles⚓︎

The INVERS OneAPI is centered around vehicles.

The basics⚓︎

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.

Telematics unit⚓︎

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 vehicle_id is.

Adding vehicles⚓︎

Supported Vehicles

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 messages 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 unlock-central-lock command.

To see a complete list of OneAPI-supported commands, visit Command Capabilities.

Receiving vehicle messages⚓︎

You can receive messages via the Messaging API using AMQP/RabbitMQ. Messages have one of the following sources:

Messages from a vehicle⚓︎

All vehicles with a telematics unit send messages regularly. The frequency depends on the telematics unit and might also vary depending on whether or not the vehicle is currently driving.

A key message is the VehicleStateReceived message. 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 full list of all vehicle state values offered by the INVERS OneAPI, go to Vehicle State Capabilities.

Messages from OneAPI⚓︎

The origin of these messages is the INVERS OneAPI and not the vehicle or the installed telematics unit.

A key message is the VehicleChanged message, 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 VehicleCreated and VehicleRemoved messages. Altogether, those messages 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.

Manage vehicles⚓︎

The Vehicle Management API allows you to store and retrieve data about your vehicles beyond the direct vehicle interaction offered by the Messaging API or the Vehicle Commands API.

  • 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 Messaging API instead!

Recommendation

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.

Back to top