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, e.g. a car will not be able to execute a command for unlocking the top case. In addition, it might also be the case that some of the vehicles in your fleet report data, for example, about their door status while others do not. All of this can depend on the vehicle’s form-factor, the vehicle model, the built-in telematics unit, a specific vehicle configuration, the firmware version, and so on.

That is why all vehicles in the INVERS OneAPI have capabilities. The capabilities indicate which commands you can send and which data you can expect in a vehicle state. They are divided into command capabilities and vehicle state capabilities. Both types of capabilities will be assigned to your vehicle when it is added to your fleet. You can retrieve the capabilities of each vehicle via the Vehicle Management API.

Why capabilities?⚓︎

Especially in a mixed fleet with various different vehicle types, brands and models, capabilities are very useful. They allow you to keep your own software free from hardcoded workflows or handlings for specific vehicle models (and different kinds of telematics units), and instead enable you to base your workflows on the more generic concept of capabilities. This requires fewer changes and adaptations, if any, should you add additional vehicle models 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:

For a car, the central lock needs to be unlocked
A kick scooter, on the other hand, does not have a central lock
One e-moped might come with a top case, while another e-moped, even from the same manufacturer, might not have one

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 moped in your fleet might have the command capability UNLOCK_TOP_CASE, a car won’t have that (as it usually does not have a top case). This means that sending the unlock-topcase command will succeed for the moped, but a car cannot perform this action.

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`
`UNLOCK_TOP_CASE`	`unlock-top-case`
`LOCK_TOP_CASE`	`lock-top-case`
`ENABLE_DRIVING`	`enable-driving`
`DISABLE_DRIVING`	`disable-driving`
`DRAW_ATTENTION`	`draw-attention`
`UNLOCK_BATTERY_COMPARTMENT`	`unlock-battery-compartment`
`REQUEST_VEHICLE_STATE`	`request-vehicle-state`

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.