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, a moped, or a truck. Vehicles are addressed and identified by a unique vehicle_id. This identifier is generated by the INVERS OneAPI for each vehicle that is added to your fleet. The vehicle_id is a 5-digit alphanumerical identifier.

Telematics unit⚓︎

Each 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, like the INVERS CloudBoxx. To reflect that reality, every vehicle within the INVERS OneAPI contains a telematics_unit property, including additional details and settings of the telematics unit the vehicle is equipped with.

Every telematics unit has a unique identifier assigned by the telematics unit manufacturer, 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 (see above) is. This is why we the INVERS OneAPI is using the vehicle_id in order to uniquely address a vehicle.

Adding vehicles⚓︎

Supported Vehicles

Your vehicles need to be equipped with a telematics unit that is supported by the INVERS OneAPI. This can either be a CloudBoxx, or a telematics unit offered as part of our OEM Integrations feature.

In order to interact with your vehicles, you first need to add them to your fleet. Adding vehicles to your fleet is easy and basically works the same way no matter what telematics unit is installed in your vehicles. In most cases, you only need to know the following:

  1. the brand of the telematics unit (e.g., CloudBoxx or Mercedes Benz OEM)
  2. the unique identifier of the telematics unit (e.g., the QNR of the CloudBoxx or VIN of your vehicle with integrated OEM telematics unit)
  3. the correct model name and year of the vehicle

CloudBoxx Vehicles

Use our SmartControl app to add all CloudBoxx-equipped vehicles to your fleet. Scan the QR code shown on the CloudBoxx and chose the correct vehicle model. We’ll take care of the correct configuration.

It is important to know and chose the correct vehicle model as we derive the vehicle’s capabilities and vehicle data translation rules from our extensive vehicle model database in order to provide you with correct vehicle state information.

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 our Vehicle Lifecycle page and in our Integration Guide.

Interacting with vehicles⚓︎

Once a vehicle has been added to your OneAPI fleet, there are two main 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 using 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.

Visit Command Capabilities to see a complete list of OneAPI-supported commands.

Receiving vehicle events⚓︎

Use our Events API to receive real-time events using AMQP/RabbitMQ. Events have one of the following sources:

Events from a vehicle⚓︎

Specific Events

Depending on your use case or implementation, you might want to take a look at the OneAPI events described in the following chapter.

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, including the vehicle’s position, mileage, state of charge, and other relevant values. Depending on the vehicle model and telematics unit, a vehicle can support all or just a subset of all possible vehicle state values. A vehicle’s vehicle state capabilities describe which values are supported by a given vehicle.

Go to our API reference to see the complete list of vehicle state values offered by the INVERS OneAPI.

Events from OneAPI⚓︎

The origin of these events is not the vehicle or the installed telematics unit directly. Instead, they are generated by the INVERS OneAPI based on data from the vehicle or operations on the API.

In some cases, those events are based or triggered by VehicleStateRecorded events, though. For example, there is a CentralLockChanged event which will be created each time the central lock status of the vehicle changes from LOCKED to UNLOCKED or vice versa. This information is derived from a series of VehicleStateRecorded events by comparing them against each other. Depending on your use case or implementation, you might prefer to work with the raw data contained in our VehicleStateRecorded events or with pre-aggregated data from our ***Changed events.

An example for the second type of event being created by INVERS OneAPI is the VehicleChanged event. This event is completely unrelated to vehicle state data, or other information coming from the vehicle or built-in telematics unit. The event contains the current OneAPI representation of the vehicle including the vehicle’s master data (license plate, VIN, and so on). It is generated each time a vehicle property outside of the vehicle state (see above) is changed. Together with the VehicleCreated and VehicleArchived events, you can keep your vehicle data 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 Events 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 or our extensive Connectivity Monitor within FleetControl.
  • 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!

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, our fleet management tool. You then have more data to base your workflows on and to find the right vehicle using FleetControl’s fleet viewer and search functionality. Have a look at our Integration Guide to find out more.

Removing vehicles⚓︎

Should you need to remove a vehicle from your fleet, simply go to FleetControl and archive the vehicle. Go to the Vehicle Lifecycle page to find out more. If a vehicle is removed from your fleet, it immediately becomes unavailable for regular operation. The vehicle and its data remain in archived for up to 90 days, but archived vehicles can no longer receive commands and data is no longer updated, e.g., last contact or latest vehicle state.