Built-in Actions¶

The following actions are built-in and are always available. The actions and arguments are case-sensitive.

Note

In some of the examples, fictitious events and actions are used. These are prefixed with plugin/.

pause¶

Pause a running simulation, which can only be resumed with the following trigger:

{ "event": "pause", "action": "resume" }

This will pause the simulation even if specified from the very start.

No arguments are accepted. Inline short-form is implicitly supported.

Examples:

[
  { "event": "time=60", "action": "pause" },
  { "event": "start", "action": "pause" }
]

Note

Without the embedded web server enabled, the pause action would render the simulation unable to escape it, as the resume action must somehow be inserted from outside. To counter-act this, the web server will be temporarily started for the duration of the pause state if it is nominally disabled.

resume¶

Resume a paused simulation. Note that this only makes sense for pause event.

No arguments are accepted. Inline short-form is implicitly supported.

Examples:

[
  { "event": "pause", "action": "resume" }
]

stop¶

Stop the simulation as neither success nor failure.

No arguments are accepted. Inline short-form is implicitly supported.

Examples:

[
  { "event": "time=60", "action": "stop" }
]

succeed¶

Stop the simulation as a success.

No arguments are accepted. Inline short-form is implicitly supported.

Examples:

[
  { "event": "time=60", "action": "succeed" }
]

fail¶

Stop the simulation as a failure. Note that this does not abort the simulation immediately, but does cause the simulation to end.

No arguments are accepted. Inline short-form is implicitly supported.

Examples:

[
  { "event": "time=60", "action": "stop" }
]

keep_alive¶

Pause the simulation after the stop and fail events instead of tearing down the simulation. This occurs after the aforementioned events but before the stop event. The simulation can be induced to complete its tear-down by sending a stop or fail trigger with the pause event.

No arguments are accepted. Inline short-form is implicitly supported.

Examples:

[
  { "event": "next", "action": "keep_alive" },
  { "event": "pause", "action": "stop" }
]

reset¶

Resets the simulation.

Warning

The only reason why this action is provided is for testing purposes. It is currently an unstable feature with undefined behavior; for example: all triggers that have run up until this point may have been deleted. Or if a controller does not support the action, the simulation may crash.

No arguments are accepted. Inline short-form is implicitly supported.

Examples:

[
  { "event": "time=60", "action": "reset" }
]

realtime_factor¶

Sets the target simulation speed.

Parameter	Required	Type	Description
`factor`	yes	number	< 0 indicates unlimited speed, = 0 indicates paused state, > 0 indicates realtime factor, = 1 is realtime speed.

Inline short-form is supported as the content of factor.

Examples:

[
  { "event": "start", "action": { "name": "realtime_factor", "factor": -1 } },
  { "event": "start", "action": "realtime_factor=0.2" }
]

Note

This action is unstable and may be renamed in future releases. Additionally, the behavior around pause and resume states may diverge or be changed.

reset_statistics¶

Reset the simulation statistics. This can be useful if an initial period of simulation should be ignored.

No arguments are accepted. Inline short-form is implicitly supported.

Note

This action is experimental and may be removed in future releases.

log¶

Log messages with a given severity.

Parameter	Required	Type	Description
`level`	no	string	logging level to use, one of: - `trace` - `debug` - `info` (default) - `warn`, `warning` - `err`, `error` - `fatal`, `critical` - `off`, `disabled`
`msg`	yes	string	message to log

Inline short-form is supported as an option level followed by a colon, then an optional space followed by the message.

Examples:

[
  { "event": "stop", "action": { "name": "log", "msg": "Simulation ended." } },
  { "event": "fail", "action": "log=critical:Failure will not be tolerated!" }
]

command¶

Run arbitrary system commands as interpreted by the /bin/sh shell.

Parameter	Required	Type	Description
`command`	yes	string	command to execute in shell
`mode`	no	string	one of `sync`, `async`, `detach`
`log_output`	no	string	one of `never`, `on_error`, `always`
`ignore_failure`	no	bool	whether to ignore execution failure

And the alternative is:

Parameter	Required	Type	Description
`path`	yes	string	command to execute directly
`args`	no	array	arguments to pass to path
`mode`	no	string	one of `sync`, `async`, `detach`
`log_output`	no	string	one of `never`, `on_error`, `always`
`ignore_failure`	no	bool	whether to ignore execution failure

Inline short-form is supported as the content of command.

Commands run with this action can become quite complex and even take advantage of environment variables (such as $PPID for the process ID of the Cloe runtime) and other shell functions such as piping commands together or running commands in the background (with &). See the test directory in the Cloe repository for several examples.

Warning

This can represent a security risk and is therefore only enabled when /engine/security/enable_command_action is set to true. Otherwise the action only logs what would have been executed.

Example 1:

[
  { "event": "stop", "action": { "name": "command", "command": "notify-send 'Simulation ended.'" } },
  { "event": "stop", "action": "command=notify-send 'Simulation ended.'" }
]

Example 2:

[
 {"event": "time=45", "action": "pause"},
 {
   "label": "Insert resume trigger via curl to test the pause-resume behavior.",
   "event": "pause",
   "action": {
     "name": "command",
     "command": "echo '{\"event\": \"pause\", \"action\": \"resume\"}' | curl -d @- http://localhost:23456/api/triggers/input"
   }
 }
]

Example 3:

{
  "version": "4",
  "include": [
    "config_nop_smoketest.json"
  ],
  "engine": {
     "keep_alive": true,
     "security": {
       "enable_command_action": true
     }
  },
  "triggers": [
     {
       "event": "stop",
       "action": {
       "name": "command",
       "command": "sleep 1 && kill -s INT $$PPID &"
       }
     }
   ]
 }

bundle¶

Wrap one or more actions into a single action. This can be used to run more than one action together with a single event.

Parameter	Required	Type	Description
`actions`	yes	array	action objects or strings (inline short-form)

Inline short-form is not supported.

Examples:

[
  {
    "event": "plugin/collision",
    "action": {
      "name": "bundle",
      "actions": [
        "command=notify-send 'Simulation failed!'",
        "fail"
      ]
    }
  }
]

insert¶

Insert one or more triggers into the simulation. This can be used to only activate a trigger when some event has occurred.

Parameter	Required	Type	Description
`triggers`	yes	array	trigger objects

Inline short-form is not supported.

Example:

[
  {
    "event": "plugin/aeb_activation",
    "action": {
      "name": "insert",
      "triggers": [
        { "event": "next", "action": { "name": "plugin/steering_torque", "left": 50.0 } }
        { "event": "future=0.05", "action": {
          "name": "insert",
          "triggers": [
            { "event": "plugin/aeb_activation", "action": "fail" }
          ]
        }}
      ]
    }
  }
]

push_release¶

Push buttons down (by setting to true) for a specified duration, followed by releasing (by setting to false. This eliminates the tedium of creating multiple actions.

Parameter	Required	Type	Description
`action`	yes	string	action name
`duration`	yes	number	number of seconds to hold
`buttons`	yes	array	button names to set

Inline short-form is not supported.

Examples:

[
  { "event": "time=10.0", "action": { "name": "basic/hmi", "plus": true } },
  { "event": "time=10.5", "action": { "name": "basic/hmi", "plus": false } },

  { "event": "time=15.0",
    "action": {
      "name": "push_release",
      "action": "basic/hmi",
      "duration": 0.25,
      "buttons": [ "plus" ]
    }
  }
]