Skip to content

Vehicle Capabilities⚓︎

Vehicles can execute commands and provide data in vehicle states. However, no vehicles support all commands, e.g. a car will not be able to execute a command for unlocking the top case and e-scooters will not report data about the door status, as they do not have doors. 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 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
  • An e-moped might come with a top case, while another e-moped even from the same manufacturer and within the same model range 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 with top case"
      || 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 since it has no 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 its individual vehicle state capabilities. For example, while it might be possible to retrieve the status of the doors (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. You can find the list of currently supported vehicle state capabilities below. Additional capabilities are being added constantly.

Has vehicle state capability Supports vehicle state property Description
ALTITUDE_IN_METERS altitude_in_meters Altitude of the vehicle.
CELLULAR_SIGNAL_QUALITY cellular_signal_quality Indicates how strong the signal of the cellular connection is.
CENTER_STAND_POSITION center_stand_position Position of the center stand.
CENTRAL_LOCK central_lock State of the central lock.
DOOR_STATUS door_status Status of the doors.
DRIVING_ENABLED driving_enabled Whether you can start the engine of the vehicle.
FUEL_LEVEL_IN_PERCENT fuel_level_in_percent Fuel level of the vehicle in percent (for electric vehicles, this is the state of charge).
IGNITION ignition A vehicle only has the vehicle state capability “ignition” if the vehicle requires the driver to manually disable the ignition.
MILEAGE_IN_KILOMETERS mileage_in_kilometers How far the vehicle has driven in total. Measured in kilometers.
POSITION position Position of the vehicle (latitude and longitude).
REMAINING_RANGE_IN_KILOMETERS remaining_range_in_kilometers An estimate of how far the vehicle can drive with the remaining fuel or battery charge. Measured in kilometers.
TOP_CASE_LID top_case_lid State of the top case lid (open or closed).
TOP_CASE_LOCK top_case_lock State of the top case lock (locked or unlocked).
Back to top