Vehicle Capabilities⚓︎

Vehicles can execute commands and provide information about their current state in vehicle states. However, not all vehicles support all of the available commands and/or vehicle state values. Some examples to make this more clear:

It might be the case that some of the vehicles in your fleet report changes to their door and window states while others do not (differences between different vehicle models).
Depending on the type of top case installed to a moped, some mopeds will offer the lock-top-case command while others do not. This is because some types of top cases automatically and only lock if the top case lid is closed by the driver (differences in certain vehicle extensions or form-factors).
A CloudBoxx-equipped car is always able to execute the request-vehicle-state command to actively retrieve an updated vehicle state from the vehicle. Currently, not all OEM APIs offer such functionality, so some cars connected using OEM telematics will not be able to actively request a new vehicle state (differences between different telematics units).

In general, the capabilities of a given vehicle are depending on the vehicle’s form-factor, the vehicle model, the built-in telematics unit, a specific vehicle or telematics unit configuration, the telematics unit’s firmware version, and more.

Because we do not want you to worry about all those things, we have introduced vehicle capabilities as an integral part of the INVERS OneAPI. They are divided into command capabilities (which commands can be sent to the vehicle) and vehicle state capabilities (which data can be expected in the vehicle’s vehicle states). Both types of capabilities will be assigned to your vehicle when it is added to your fleet and might be updated if you reconfigure any relevant property of the vehicle or built-in telematics unit. You can retrieve the capabilities of each vehicle via the Vehicle Management API.

Why capabilities?⚓︎

As indicated above, capabilities allow you to keep your own software free from hardcoded workflows or handlings for specific vehicles, based on vehicle model or telematics unit. Instead, they enable you to implement your workflows in a more generic way. Consequently, fewer (if any) changes and adaptations are required should you add additional vehicle models or different telematics units to your fleet.

Example: Sharing workflow based on capabilities

Your fleet typically contains different vehicle models, oftentimes from different manufacturers and sometimes even different types of vehicles (e.g. cars and mopeds). Based on that, you have to use different commands when your customers would like to start a rental.

Start rental flow (without capabilities)⚓︎

The following pseudo code shows how you would have to handle those differences manually without using command capabilities.

void start_rental()
{
  if (vehicle.type == "car")
  {
    send_command("unlock-central-lock", vehicle.id);
    send_command("enable-driving", vehicle.id);
  }
  else if (vehicle.type == "kickscooter")
  {
    send_command("enable-driving", vehicle.id);
  }
  else if (vehicle.type == "moped")
  {
    if (vehicle.brand == "niu" && vehicle.model == "n1"
      || vehicle.brand == "segway" && vehicle.model == "e-moped c80")
    {
      send_command("unlock-top-case", vehicle.id);
      send_command("enable-driving", vehicle.id);
    }
    else
    {
      send_command("enable-driving", vehicle.id);
    }
  }
}

This does not scale well if you need to support additional vehicle models. As this is not the only workflow you need to support, you will face a similar complexity in multiple areas within your software. Usually, the most complex workflow is the “end rental” workflow where you also want to check various different conditions before the customer can end the rental, all of which are also highly dependant on the vehicle model and its individual capabilities.

Start rental flow (with capabilities)⚓︎

With the help of the INVERS OneAPI you can base the same decisions simply on the vehicle’s capabilities. In pseudo code, this would look more like this:

void start_rental()
{
  if (vehicle.capabilities.commands.contains("UNLOCK_CENTRAL_LOCK"))
  {
      send_command("unlock-central-lock", vehicle.id)
  }
  if (vehicle.capabilities.commands.contains("UNLOCK_TOP_CASE"))
  {
      send_command("unlock-top-case", vehicle.id)
  }
  if (vehicle.capabilities.commands.contains("ENABLE_DRIVING"))
  {
      send_command("enable-driving", vehicle.id)
  }
}

When adding new vehicle models or variants of existing models to your fleet, you don’t have to change your code! While this example only used command capabilities, the same of course applies to the vehicle state using vehicle state capabilities.

Command capabilities⚓︎

The set of commands you can send to a vehicle is described by the list of its individual command capabilities. For example, while a car equipped with a CloudBoxx always has the command capability REQUEST_VEHICLE_STATE, a car with OEM telematics connected through an OEM API not necessarily offers this functionality. Consequently, sending the request-vehicle-state command will work for the first car, but not for the second one.

For each command, there is a corresponding command capability. The following command capabilities are currently supported by the INVERS OneAPI:

Has command capability	Allows to send command
`UNLOCK_CENTRAL_LOCK`	`unlock-central-lock`
`LOCK_CENTRAL_LOCK`	`lock-central-lock`
`ENABLE_DRIVING`	`enable-driving`
`DISABLE_DRIVING`	`disable-driving`
`REQUEST_VEHICLE_STATE`	`request-vehicle-state`
`...`	Go to complete list

Vehicle state capabilities⚓︎

The properties you can receive as part of a vehicle state are described by the list of your vehicle’s individual vehicle state capabilities. For example, while it might be possible to retrieve the status of the windows (whether or not they are open or closed) for one car in your fleet, that may not be possible for another.

For each property in the vehicle state there is a corresponding vehicle state capability. The table below shows you some of the most important vehicle state capabilities supported by the INVERS OneAPI. You can find the complete list of supported capabilities in our API reference section. We are constantly adding additional capabilities as telematics units and their protocols or APIs become more mature and add new features.

Name of vehicle state capability -> Name of corresponding vehicle state property	Description
`CENTRAL_LOCK` -> `central_lock`	State of the central lock (LOCKED/UNLOCKED)
`DRIVING_ENABLED` -> `driving_enabled`	Whether the driver can start the engine of the vehicle
`MILEAGE_IN_KILOMETERS` -> `mileage_in_kilometers`	Current odometer value of the vehicle, measured in kilometers
`POSITION` -> `position`	Position of the vehicle (latitude and longitude)
`STATE_OF_CHARGE_OR_FUEL_LEVEL_IN_PERCENT` -> `state_of_charge_or_fuel_level_in_percent`	Fuel level or state of charge of the vehicle, in percent
`CHARGING_STATUS` -> `charging_status`	Whether the vehicle is currently charging
`...`	Go to complete list

Info

For the complete list of all vehicle state capabilities offered by the INVERS OneAPI (including information about their data types and value ranges), go to our API reference section.