User Guide
The following section explains how to bring together Vector SIL Kit enabled applications and how to successfully run a simulation.
Figure 1 : Example of a simple simulation setup with two participants that communicate on a bus network named “CAN1”.
Preparations
If you do not have a SIL Kit package at hand, please do the following:
Visit our Releases page on GitHub (https://github.com/vectorgrp/sil-kit/releases).
Find your desired SIL Kit version. We recommend the most recent version, as it may have new features and bug fixes.
Download the zip file for your platform. If there are no prebuilt binaries for your platform, then you must build from source. For more information, please see Build Instructions.
Unzip the archive.
SIL Kit might be installed on your system. In that case a registry service may already be running on your system. Otherwise, if you want to run the simulation locally, start the registry service (located at SilKit/bin/sil-kit-registry).
Quick Start
Note
This guide assumes you want to run the simulation locally. If you have a more complex scenario, take a look at The Participant Configuration File first.
In general a SIL Kit simulation consists out of a central sil-kit-registry process and one or multiple simulation participants/SIL Kit enabled applications. The registry’s purpose is to provide SIL Kit participants with information of which participants are present and how to connect to them. Besides this central book keeping, a SIL Kit registry does not participate in the SIL Kit simulation itself. To join the simulation SIL Kit participants/SIL Kit enabled applications must only be able to connect to this SIL Kit registry.
The following steps are required to set up a simulation and run it:
Make sure a SIL Kit registry is running. If no sil-kit-registry process is running, you can start one by simply starting the executable.
Start the SIL Kit enabled application(s) with the desired arguments. Participants without a lifecycle and autonomous participants will start directly. For example, the applications to start in Figure 1 are both SilKitDemoCan` with their respective participant name CanWriter and CanReader as arguments. See demo applications for informatio of how to build and start the sample applications. If you have access to the registry’s log, you should see log entries stating that the participant(s) connected.
Depending of the needs of your SIL Kit simulation, it may be necessary to start the System Controller Utility (see Configuring the Lifecycle Service for more information). Once all required simulation participants have joined the simulation, the coordinated participants within the simulation will start.
Coordinated participants can be stopped externally by the system controller utility; autonomous participants must stop themselves (see Terminology).
Note
If you encounter any problems during the initial setup (e.g., you started the registry and the participants but nothing happens), refer to Troubleshooting.
Participants
A participant in SIL Kit is a node in a simulation; Depending on the application, it may send or receive messages from other participants in the simulation. Each participant must have a unique name to be able to join the simulation. After a participant connects to a SIL Kit Registry, peer-to-peer connections are established with all other participants.
Participants have their own set of SIL Kit services to communicate with other participants. For example, CAN controllers send and receive CAN frames, which comprise an ID, flags, and the actual payload. Refer to Supported Services for each service’s capabilities.
Participants can be configured to coordinate their simulation start and stop behavior with other participants through use of the Lifecycle Service. To synchronize their virtual time with others, a participant can use the Time Synchronization Service.
Users can (re-)configure parts of the SIL Kit participants if the application allows the user to pass in a SIL Kit participant configuration file. For example, the user may want to configure logging to the standard output or to a file. See (Re-)Configuration for more information.
Utility Processes
The Registry is a utility which enables discovery between SIL Kit participants. Thus, it is mandatory and must be started prior to the creation of any participants. Once the registry is created, it listens for participants on a specified URI. Once a participant is created, if configured properly, it sends a message to the registry URI asking for the list of active participants. The registry, once receiving the message, sends the requested information back to the new participant. The new participant, once receiving the message from the registry, attempts to establish a peer-to-peer connection with all participants listed in the message.
The System Controller is an application which orchestrates participants in a SIL Kit simulation by specifying a list of required participant names at start up. A simulation’s coordinated participants are dependent on the state of all required participants. The coordinated participants won’t start if any required participant is still missing. In contrast, autonomous participants do not consider the state of other participants.
The Monitor utility tracks and displays participant state within a simulation. It’s an optional utility which can be started and stopped at any time.
Network Topology / Examples
SIL Kit supports TCP/IP and Unix Domain Socket network types. When joining a simulation, new participants will first open a publically visible listening socket. Then, it connects to the SIL Kit Registry and tells it its connection information (especially the port number of the just opened listening socket). If the registry was not configured before it was started, it will open a listening port at localhost:8500.
Once the connection to the registry is established, the registry replies with the connection information of all already connected participants. The new participant will try to connect to each of the other participants directly. By default, it will first connect via Unix Domain Sockets and if this does not work, it will try to connect via TCP. In case both connection attempts fail, the registry will act as a proxy between the participants.
In the most simple case, the registry as well as all participants are running on your local machine (shown in Figure 2).
Figure 2 : Setup in which registry and all participants run on a local host with their default configuration.
By default, connections to the simulation are established via TCP on the ‘localhost’ on port 8500. Figure 3 displays a simulation where the registry runs on a different machine and the participants are reconfigured to connect to it.
Figure 3 : A simulation setup in which the registry is running on a remote machine.
A special case are setups that involve containers, as it is common in docker or cloud setups. As mentioned before, SIL Kit participants open a socket on a (random) port that other participants can connect with. If you have a setup that involves containers you may need more control regarding the used ports. For that reason, participants may explicitly configure the listening port (or ports if you have the choice) that the participant opens its socket on. Figure 4 shows a container setup in which the registry and a participant run inside a docker runtime but on separate containers and one more participant connects from outside of the runtime.
Figure 4 : Docker setup with a SIL Kit Registry and a participant running in separate containers and another participant connecting from outside the runtime. The runtime is running on the local host.
(Re-)Configuration
Sometimes, it may be necessary to change the SIL Kit Registry’s configuration or the configuration of individual SIL Kit enabled application(s) that are only available as executables in binary form. The configuration can be changed through the use of a YAML configuration file. It is passed to a SIL Kit enabled application or Registry and overrides its initial configuration.
Note
If you do not want to change the default behavior or your SIL Kit application, it should be unnecessary to provide a configuration file.
Some of the most common options configured by users include the participant name, logging, bus network specifics, registry location, and health monitoring. For example, a user may need to modify an already existing participant to use a different name and change the network name that one of its bus services connects to (see Figure 5). To address this, the user can provide a configuration file, which contains the needed changes (see Figure 6).
Figure 5 : Faulty simulation setup with two participants that have the same name and a mismatch in their bus network names.
Figure 6 : Setup from Figure 5 in which the left participant was reconfigured via a configuration file.
See The Participant Configuration File for more information.