Configuration

The Vector SIL Kit provides optional configuration to enhance flexibility and control through use of YAML files. This allows users to modify behavior without recompiling source code. Further, it allows configuration of services which are inactive by default, such as tracing and logging. Different configuration options are available for SIL Kit participants and the SIL Kit Registry.

The Participant Configuration File

Participants are primarily configured by developers in source code using the SIL Kit API. However, the following scenarios are conceivable in which some flexibility is useful even after compile-time:

  • A simulation participant is distributed in binary form to users. In order to integrate such participants into simulations, a user must be able to post-configure some aspects of the participant to make it fit, particularly its properties, behavior and how it interconnects within a simulation.

  • A simulation consists of multiple participants that share the same behavior. A user would have to ask developers to compile these participants from the same sources multiple times, with only the participant names differing.

  • Developers or users want to temporarily enable debugging features without the need or the ability to recompile the sources, for example logging, tracing, and health checking.

To cover these scenarios, SIL Kit participants can be modified by participant configuration files. This is done by creating a participant configuration object from a given file in YAML or JSON format and passing the object as an argument when a participant is created:

auto participantConfiguration = SilKit::Config::ParticipantConfigurationFromFile(participantConfigurationFilename);
auto participant = SilKit::CreateParticipant(participantConfiguration, participantName, registryUri);

Alternatively, the configuration object can be created directly from string:

const std::string participantConfigText = R"(
Description: My participant configuration
Logging:
    Sinks:
    - Type: Stdout
      Level: Info
)";
auto participantConfiguration = SilKit::Config::ParticipantConfigurationFromString(participantConfigText);
auto participant = SilKit::CreateParticipant(participantConfiguration, participantName, registryUri);

Participant configurations allow to override a subset of parameters which are configurable via the SIL Kit API. Configuration parameters that are specified within the participant configuration override corresponding programmatically defined values. For example, the ParticipantName field overrides the participant name that is provided through the API when a participant is created, namely CreateParticipant(..., const std::string& participantName, ...). This gives users the ability to run a simulation with multiple instances of a participant from a single implementation.

Note

It is recommended that configurations are specified in the source code where possible. That way, an empty configuration file can be provided for most simulation runs. However, a process that creates a SIL Kit participant should also accept a configuration file such that a user is able to reconfigure names or network connections without recompiling the application.

Note

Many IDEs automatically support participant configuration schema support when the participant configuration file ends with the suffix .silkit.json/yaml.

A participant configuration file is written in YAML syntax according to a specified schema. It starts with the SchemaVersion, the Description for the configuration and the ParticipantName. This is followed by further sections for Includes, Middleware, Logging, HealthCheck, Tracing, Extentions and sections for the different services of the SIL Kit. The outline of a participant configuration file is as follows:

"$schema": "./ParticipantConfiguration.schema.json"
SchemaVersion: 1
Description: Sample configuration with all root nodes
ParticipantName: Participant1
Includes:
  ...
Middleware:
  ...
Logging:
  ...
HealthCheck:
  ...
Tracing:
  ...
Extensions:
  ...
CanControllers:
  - ...
LinControllers:
  - ...
FlexrayControllers:
  - ...
EthernetControllers:
  - ...
DataPublishers:
  - ...
DataSubscribers:
  - ...
RpcClients:
  - ...
RpcServers:
  - ...
Experimental:
  - ...

Overview

Setting Name

Description

"$schema"

File path to the participant configuration schema. The ParticipantConfiguration.schema.json is part of the SIL Kit sources and can be found in the folder ./SilKit/source/config/.

SchemaVersion

The version of the used participant configuration schema. Current version is 1.

Description

User defined description for the configuration.

ParticipantName

The name of the simulation participant that joins the SIL Kit simulation. Overrides a programmatically defined participant name.

Includes

This can be used to include other participant configuration files.

Logging

The logger configuration for this participant.

HealthCheck

Configuration concerning soft and hard timeouts for simulation task execution.

Tracing

Configuration of experimental tracing and replay functionality.

Extensions

Configuration of optional extensions to the SIL Kit and where to find them.

Middleware

This optional section can be used to configure the middleware running the SIL Kit. If this section is omitted, defaults will be used.

CanControllers

Configure CAN controllers.

LinControllers

Configure LIN controllers.

EthernetControllers

Configure Ethernet controllers.

FlexrayControllers

Configure Flexray controllers.

DataPublishers

Configure data publishers.

DataSubscribers

Configure data subscribers.

RpcServers

Configure RPC servers.

RpcClients

Configure RPC clients.

Experimental

Experimental configuration options for the SIL Kit.

Configuration Options

The Registry Configuration File

An instance of the SIL Kit Registry (sil-kit-registry(.exe)) can be configured via a YAML file. The configuration file is optional and overrides the settings specified on the command line. It also allows extended configuration, beyond what the command line allows, particularly for logging.

The outline of a registry configuration file is as follows:

---
SchemaVersion: 1
Description: Sample registry configuration.

ListenUri: silkit://localhost:8500

Logging:
  Sinks:
    - Type: Stdout
      Level: Trace
    - Type: File
      Level: Trace
      LogName: SampleRegistryLogFile
DashboardUri: http://localhost:8082

Overview

Setting Name

Description

SchemaVersion

The version of the used registry configuration schema. Current version is 1.

Description

Free text field allowing a user to describe the configuration file in their own words. The contents of this field are not parsed or used internally.

ListenUri

The configured registry instance will listen on this address for incoming connections. This field overrides the -u, and --listen-uri command line parameters.

Logging

Configuration of where and how logs produced by the registry are processed. See Logging.

NOTE It is not possible to configure LogFromRemotes. Using this value will lead to an error during registry startup.

NOTE It is only possible to use the Sink types Stdout and File. Using Remote will lead to an error during registry startup.

DashboardUri

The configured registry instance will send data to this address to show it on the dashboard This field overrides the -d, and --dashboard-uri command line parameters.

NOTE The default URI to use for a local SIL Kit dashboard setup is http://localhost:8082.

Configuration Options

API and Data Type Reference

auto SilKit::Config::ParticipantConfigurationFromFile(const std::string &filename) -> std::shared_ptr<SilKit::Config::IParticipantConfiguration>

Parse configuration from a YAML or JSON file.

Create a configuration data object from settings described by a YAML or JSON file.

Parameters

filename – Path to the YAML or JSON file (UTF-8).

Throws

SilKit::ConfigurationError – The file could not be read, or the input string violates the YAML/JSON format, schema or an integrity rule.

Returns

The configuration data

auto SilKit::Config::ParticipantConfigurationFromString(const std::string &text) -> std::shared_ptr<SilKit::Config::IParticipantConfiguration>

Parse configuration from a YAML or JSON string.

Create a configuration data object from settings described by a YAML or JSON formatted string.

Parameters

text – A string that adheres to our JSON schema (UTF-8).

Throws

SilKit::ConfigurationError – The input string violates the JSON format, schema or an integrity rule.

Returns

The configuration data