Basic Controller

The basic controller plugin provides limited ACC, AEB, and LKA functionality. It is used for internal integration testing and as an example of how you can write a controller plugin.

Triggers

The following actions are provided by the plugin. Plugin trigger action names are dependent on the given name of a plugin in a simulation. This is by default the name of the plugin itself; this default name is used in this documentation.

<basic>/hmi

The basic controller model makes an action available to manipulate its HMI. The name of the action is prefixed by the given name of the plugin.

Parameter	Required	Type	Description
enable	no	bool	Switch to enable or disable controller’s ACC function.
cancel	no	bool	Push button to cancel ACC function.
resume	no	bool	Push button to resume ACC function.
plus	no	bool	| Push button to increase speed. Short press: increases to next 10 km/h. Long press: increases to next 5 km/h every 500 ms.
minus	no	bool	Push button to decrease speed. Short press: decrease to next 10 km/h. Long press: decrease to next 5 km/h every 500 ms.
distance	no	bool	Push button to cycle distance profiles.

Inline short-form is supported as a comma-separated list of fields to be pressed, optionally prefixed with ! to indicate release:

basic/hmi=!enable
basic/hmi=plus,minus
basic/hmi=!plus,!minus

The push-button interface is tricky to interface with correctly, since usually the effect triggers on release (like clicking a button with a mouse). Additionally, effect is often different if the button is held pressed for a certain period of time. The result is that pushing down on the button (by setting the field to true) must be accompanied by releasing the button (by setting the field to false).

If a field is not specified, it is ignored.

Warning

If a field is set and unset very quickly, it is therefore possible that both register for the same frame, in which case button presses would cancel each other out.

For this reason, it is recommended to keep the simulation at realtime speeds when dynamically inserting this kind of event.

Examples:

[
  { "event": "time=5.0", "action": { "name": "basic/hmi", "enable": true } },
  {
    "label": "Resume with current speed",
    "event": "time=10.0",
    "action": { "name": "basic/hmi", "resume": true }
  },
  { "event": "time=10.5", "action": "basic/hmi=!resume" },
  { "event": "time=15.0",
    "action": {
      "name": "push_release",
      "action": "basic/hmi",
      "duration": 0.25,
      "buttons": [ "plus" ]
    }
  }
]

Example Tests

You can see an example configuration in the tests/controller_basic.json file, which is included by almost all smoketests run.

{
  "version": "4",

  "controllers": [
    {
      "binding": "basic",
      "vehicle": "default"
    }
  ],

  "triggers": [
    {
      "event": "start",
      "action": {
        "name": "bundle",
        "actions": [
          "basic/hmi=!enable"
        ]
      }
    },
    { "event": "next=1",   "action": "basic/hmi=enable" },
    { "event": "time=5",   "action": "basic/hmi=resume" },
    { "event": "time=5.5", "action": "basic/hmi=!resume" },
    {
      "label": "Push and release basic/hmi=plus",
      "event": "time=6",
      "action": {
        "name": "insert",
        "triggers": [
          { "event": "next", "action": "basic/hmi=plus" },
          { "event": "next=1", "action": "basic/hmi=!plus" }
        ]
      }
    }
  ]
}

Defaults

The following help can be viewed with cloe-engine usage basic:

Name: basic
Type: controller
Path: ~/.conan/data/cloe-plugin-basic/0.23.0/cloe/develop/package/2de4bf77c73ae74c023ce41bfefbe300c8a251a4/lib/cloe/controller_basic.so
Usage: {
  "acc": "object :: ACC configuration",
  "aeb": "object :: AEB configuration",
  "driver_request": "string :: component providing driver request",
  "lka": "object :: LKA configuration"
}
Defaults: {
  "acc": {
    "derivative_factor_dist_control": 5.0,
    "derivative_factor_speed_control": 5.0,
    "ego_sensor": "cloe::default_ego_sensor",
    "integral_factor_dist_control": 0.0,
    "integral_factor_speed_control": 0.0,
    "latlong_actuator": "cloe::default_latlong_actuator",
    "limit_acceleration": 3.0,
    "limit_deceleration": 5.0,
    "proportional_factor_dist_control": 0.8,
    "proportional_factor_speed_control": 0.8,
    "world_sensor": "cloe::default_world_sensor"
  },
  "aeb": {
    "always_full_stop": false,
    "ego_sensor": "cloe::default_ego_sensor",
    "enabled": true,
    "latlong_actuator": "cloe::default_latlong_actuator",
    "limit_deceleration": 8.0,
    "world_sensor": "cloe::default_world_sensor"
  },
  "driver_request": "",
  "lka": {
    "adjustment_rad": 0.02,
    "enabled": false,
    "latlong_actuator": "cloe::default_latlong_actuator",
    "lerp_factor": 0.1,
    "tolerance": 0.1,
    "world_sensor": "cloe::default_world_sensor"
  }
}

JSON Schema

The following can be viewed with cloe-engine usage --json basic:

{
  "$id": "~/.conan/data/cloe-plugin-basic/0.23.0/cloe/develop/package/2de4bf77c73ae74c023ce41bfefbe300c8a251a4/lib/cloe/controller_basic.so",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "description": "very basic vehicle controller",
  "properties": {
    "acc": {
      "additionalProperties": false,
      "description": "ACC configuration",
      "properties": {
        "derivative_factor_dist_control": {
          "description": "factor to tune the D term of the PID distance controller",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "derivative_factor_speed_control": {
          "description": "factor to tune the D term of the PID speed controller",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "ego_sensor": {
          "description": "ego sensor component to read from",
          "type": "string"
        },
        "integral_factor_dist_control": {
          "description": "factor to tune the I term of the PID distance controller",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "integral_factor_speed_control": {
          "description": "factor to tune the I term of the PID speed controller",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "latlong_actuator": {
          "description": "actuator to write to",
          "type": "string"
        },
        "limit_acceleration": {
          "description": "acceleration limit in [m/s^2]",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "limit_deceleration": {
          "description": "how much deceleration is allowed, in [m/s^2]",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "proportional_factor_dist_control": {
          "description": "factor to tune the P term of the PID distance controller",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "proportional_factor_speed_control": {
          "description": "factor to tune the P term of the PID speed controller",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "world_sensor": {
          "description": "world_sensor component to read from",
          "type": "string"
        }
      },
      "type": "object"
    },
    "aeb": {
      "additionalProperties": false,
      "description": "AEB configuration",
      "properties": {
        "always_full_stop": {
          "description": "whether to brake to a full-stop on activation",
          "type": "boolean"
        },
        "ego_sensor": {
          "description": "ego sensor component to read from",
          "type": "string"
        },
        "enabled": {
          "description": "whether automatic emergency braking is enabled",
          "type": "boolean"
        },
        "latlong_actuator": {
          "description": "actuator to write to",
          "type": "string"
        },
        "limit_deceleration": {
          "description": "how much deceleration is allowed, in [m/s^2]",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "world_sensor": {
          "description": "world_sensor component to read from",
          "type": "string"
        }
      },
      "type": "object"
    },
    "driver_request": {
      "description": "component providing driver request",
      "type": "string"
    },
    "lka": {
      "additionalProperties": false,
      "description": "LKA configuration",
      "properties": {
        "adjustment_rad": {
          "description": "wheel angle adjustment in [rad]",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "enabled": {
          "description": "whether lane keeping assist is enabled",
          "type": "boolean"
        },
        "latlong_actuator": {
          "description": "actuator to write to",
          "type": "string"
        },
        "lerp_factor": {
          "description": "linear interpolation factor with domain (0-1]",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "tolerance": {
          "description": "absolute tolerance in [m]",
          "maximum": 1.7976931348623157e+308,
          "minimum": -1.7976931348623157e+308,
          "type": "number"
        },
        "world_sensor": {
          "description": "world_sensor component to read from",
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "title": "basic",
  "type": "object"
}