Configuration

Both tools and measurements can contain user-defined parameters, which are described in the GdkTool_Describe method.

The framework uses the description, containing meta-data such as name and type, to populate the tool configuration sections in job files. Any parameter defined is automatically exposed by the GUI and the SDK, and are accessible by tool implementations.

Parameters can be added in the following fashion:

GdksFx(kStatus) GdksTestTool_VDescribe(GdkToolInfo toolInfo)
{
    // ...

    // Tool parameters

    params = GdkToolInfo_Params(toolInfo);
    kCheck(GdkParamsInfo_AddInt(params, "BaseCount", kNULL, 1, kNULL));
    kCheck(GdkParamsInfo_AddFloat(params, "BaseRadius", kNULL, 10.0, kNULL));

    // Measurement parameters

    kCheck(GdkToolInfo_AddMeasurement(toolInfo, "X", &measurementInfo));
    params = GdkMeasurementInfo_Params(measurementInfo);
    kCheck(GdkParamsInfo_AddInt(params, "ObjectIndex", kNULL, 0, kNULL));

    // ...

    return kOK;
}

A default value can be specified when defining a new parameter. Whenever a new tool is created, its configuration will be populated with the defined parameters for that tool and its measurements with the default values specified. An user can modify these parameters using the GUI or the SDK.

When the tool is instantiated and started (when the user runs the sensor), the parameter values can be obtained through the GdkTool object like in the following example.

GdksFx(kStatus) GdksTestTool_VStart(GdksTestTool tool)
{
    GdksTestToolClass* obj = GdksTestTool_Cast_(tool);
    GdkToolCfg config = GdkTool_Config(tool);
    GdkParams params = GdkToolCfg_Parameters(config);
    GdkParam param;

    param = GdkParams_Find(params, "BaseCount");
    GdkLogf("BaseCount: %d", GdkParam_AsInt(param));

    param = GdkParams_Find(params, "BaseRadius");
    GdkLogf("BaseRadius: %f", GdkParam_AsFloat(param));

    return kOK;
}

Compatibility

Parameters can be added without affecting backward compatibility if they are marked as optional. By default all parameters are required – if a declared parameter is missing from the configuration (e.g. when loaded from storage), parsing fails. However if the parameter is marked as optional with GdkParamInfo_SetIsOptional, then parsing succeeds even if the parameter is missing from the configuration. In this case the parameter is initialized with the default value, and GdkParam_IsSet returns kFALSE. This provides a simple mechanism for version control.

Versioning

Over the course of the life time of a tool, there may be the need to make changes to its interface e.g. changing or removing parameters. The user-defined aspects of a tool interface, namely its parameters, measurements, and measurement parameters, are captured by GdkToolVersionInfo objects.

By default a tool has just one version (GdkToolInfo_FirstVersion), but more versions may be added using GdkToolInfo_AddVersion. Whenever the interface of a tool has changed, a new version can be registered so that the new interface can be correctly parsed by the framework. When the configuration of a tool instance is saved, the version used at the time is also saved. This saved version is used by the framework to parse the configuration. If a version not defined by the firmware implementation, then that tool instance will not be inactive.

During run-time the user can query the version of the configuration of a tool instance by using GdkToolCfg_Version.

Advanced Parameter Handling

While the default parameters should be sufficient for most scenarios, sometimes the tool should be initialized to values that cannot be hardcoded in such a way. In these cases, the methods GdkTool_NewToolConfig and GdkTool_NewMeasurementConfig can be overriden to provide more complex initialization logic. These methods are called when new tools and measurements are instantiated by the client, and allows the tool implementation to initialize values using sensor parameters (e.g. active area).

Sometimes it is always necessary to modify the attributes of some parameters based on the value of other parameters. For example regions may need to be hidden when an "Enable Regions" checkbox is unchecked, or the minimum and maximum constraints of a parameter depends on the value of another parameter. For these cases, the Gdk_UpdateConfig method can be overriden to provide dynamic attribute updates. This method is called by the framework whenever the configuration has been updated, to give the tool implementation the opportunity to update the attributes. Note that whenever this method is called, the implementation should update all attributes that should be modified; the framework will not necessarily keep previously set attributes between calls.