App Parameters

An application can define parameters with metadata (such as the parameter type, description or default value) in auterion-app.yml. The application can read the values or get notified on changes, while a user (or OEM) can configure the parameters according to the metadata.

Defining Parameters

Parameters can be defined by adding a list of parameters under parameters: in the auterion-app.yml configuration file.

For example:

parameters:
  - name: my_test_parameter
    description:
      short: My parameter description (single line)
      long: |
        More detailed description.
        Can be multiple lines.
        And is optional.
    type: bool
    default: false

This is the full list of available fields:

parameters:
  - name: string, required. Can include any of these characters: a-zA-Z0-9-_.
    description:
      short: string, required. Short, single-line description of what the parameter
             does
      long: |
        string, optional. More detailed description, can be multiple lines.
    type: string, required. Defines the parameter type.
          One of: "bool", "int64", "float64", "string", "byte[]", "bool[]", "int64[]",
                  "float64[]", "string[]"
    default: required. Default value, matching the type specified in the 'type' field
    
    enum_values: object, optional. Enum values, only applicable if the type is int64.
                 Defines key-value mappings from a value to a string (for display),
                 e.g. 0: zero, 1: one 
    volatile: boolean, optional. If true, it can dynamically be changed by an
              application, and should not be transferred to other vehicles. It is
              still stored persistently.
              Can be used for example for calibration parameters.
    decimal: integer, optional. Number of decimal places to display in a UI
             (only for float64 types)
    increment: number, optional. Increment step size for a UI (only for float64 types)
    unit: string, optional. Unit, e.g. 'm/s'
    readonly: boolean, optional. If true, a user cannot modify the value (but an
              application or an OEM layer still can)
    visibility: string, optional. The visibility of the parameter for user-facing
                configuration interfaces.
                One of: "visible", "advanced", "hidden"
    reset_on_update: boolean, optional. If true, a user-set value is reset on an
                     update
    min: number, optional. Minimum value (only for int64 or float64). This is only
         enforced in the UI, i.e. the value can still be outside of this limit.
    max: number, optional. Maximum value (only for int64 or float64). This is only
         enforced in the UI, i.e. the value can still be outside of this limit.

Accessing Parameters

Parameters can be accessed from an application in two ways: using the Auterion SDK or though a REST GET request. The SDK should generally be preferred, as it is simpler to use and for notifications on parameter changes.

Auterion SDK

Parameters can be accessed like this (the notification callback is optional):

#include <auterion_sdk/auterion.hpp>
#include <auterion_sdk/exception/exception.hpp>
#include <fstream>

int main(int argc, char* argv[]) {
    auterion::SDK sdk(argc, argv, "parameters_example");

    try {
        auto parameter = sdk.getParameter<bool>("my_test_parameter", [](bool value) {
            std::cout << "my_test_parameter updated: " << value << std::endl;
        });

        std::cout << "my_test_parameter: " << parameter << std::endl;

    } catch (auterion::ParameterException& e) {
        std::cout << "Parameter exception: " << e.what() << std::endl;
        return -1;
    }
    sdk.run();

    return 0;
}

Make sure the type matches with the type defined in the yaml configuration file.

An exception is only thrown for example if the parameter does not exist, the type mismatches or the parameter server is not running.

There is an example under auterion-sdk/parameters in the example applications.

REST API

Parameters can also be read via REST GET requests. You can check that the API is accessible using this command from an application:

curl http://172.17.0.1/api/params/version/latest -w "\n"

The output should be:

v1

Parameters can then be accessed with this request:

curl http://172.17.0.1/api/params/v1/get/parameter_raw?name=<name>

where <name> has this form: <app-author>.<app-name>.<parameter-name> with the values from the auterion-app.yml configuration. For example com.auterion.parameters-example.my_test_parameter.

The request directly returns the value, without any newlines.

Changing Parameters

Parameters can be changed on the Skynode via command line using param-cli. There are a number of subcommands. For example all parameters can be displayed with:

param-client get

Or to set a parameter:

param-client set <name> <value>

It is planned to provide configuration UI's, including in AMC and on the Skynode's web interface.

Environment-variable-based Parameters (deprecated)

You can specify user-overridable environment variables for your app. These environment variables can then be edited by visiting the vehicle web-page on 10.41.1.1, when connected via USB.

To add user-customizable environment variables to your app, create a file called settings.default.env in the root directory of your app project. In this file, specify the environment variables along with their default values like this

VARIABLE_1=Value
OTHER_VARIABLE="Other value"