VCE Launcher#

On the previous pages, you learned how to run and configure each VCE component individually. As you have probably noticed, it can be tedious to keep track of the different (Python) environments and commands to start each component in the configuration that you need for a particular experiment. To make this easier, the VCE comes with the script scripts/vce-launcher.py.

Note

scripts/vce-launcher.py does not require any Python modules that aren’t already availabe in a standard Python installation. However, tomllib only comes integrated with Python 3.11 or newer.

The script assumes that the VCE is already installed. In addition to Python, Tmux and optionally Apptainer (depending if you used the VCE container for installation) should be installed.

To try this out with an example, go to the root folder of your VCE installation and run the following command:

scripts/vce-launcher.py \
    --container \
    --prepare-only \
    networks/paderborn-north/with-minimap-and-bike-interface.launcher.toml

Here, --container means that each component will be launched using the Apptainer image vce-container.sif that scripts/vce-install-container.sh downloads automatically.

--prepare-only means that the launcher will only cd into the respective component subfolder and type out the respective command for each component, but you will still be required to hit the enter key for each. Leave this out to launch every component automatically as soon as they are ready.

Once you run the launcher, a Tmux session should open with one window for each component.

Warning

Tmux does not really support nested sessions, so be careful to not run the VCE launcher from inside an active Tmux session.

The launcher will also fail if another Tmux session from a previous launch is still open. Use tmux ls to check for active sessions and tmux a -t VCE to re-enter the active VCE session, then close it if necessary.

If you’re not familiar with Tmux yet, closing the session may be a bit unintuitive. In Tmux, most commands for controlling its behavior (like opening/closing windows or tabs) are prefixed by a special key combination. By default, this is Ctrl+B. If you want to close the current session, hit Ctrl+B, then the : key, then type kill-session, and finally hit enter.

Launch Configurations#

VCE Launcher configurations are stored in TOML files. Let’s look at an example to understand how you can write your own:

Listing 1 ../../../scenarios/paderborn-north/with-minimap-and-bike-interface.launcher.toml#
 1[evi]
 2config_file = "../../evi/networks/paderborn-north/paderborn-north.evi.ini"
 3args = """\
 4       --verbosity WARNING \
 5       --sumo-binary sumo-gui \
 6       --veins-host localhost \
 7       --veins-port 12347\
 8       """
 9wait_for_ports = [12347]  # Wait for veins-evi
10
11[veins-evi]
12scenario = "../../veins-evi/examples/minimap"
13args = "-u Cmdenv -c LanradioDisabled"
14
15[env3d]
16# executable_path = "../../3denv/build/3denv.x86_64"  # already the default
17scenario = "../../evi/networks/paderborn-north/paderborn-north.net.xml"
18allow_container = false  # Makes it easier to use host's graphics drivers and executable should be portable anyway
19evi_address = "localhost"
20evi_port = 12346
21evi_connect_on_launch = true
22scenario_seed = 42
23skip_menu = true
24vehicle_type = "BICYCLE_INTERFACE"
25wait_for_ports = [12346]  # Wait for evi
26
27[bike-interface]
28args = """\
29       --unity-ip localhost \
30       --wheel-diameter 0.7 \
31       --num-spokes 18 \
32       --steering-sensor android \
33       --android-deadzone 0 \
34       --speed-sensor irspeed_esp32 \
35       --initial-orientation 0 \
36       --speed-factor 2\
37       """

Each VCE component supported by VCE Launcher that you want to include in your simulation should have its own section in your launcher.toml. You can get a list of all supported components and parameters by running scripts/vce-launcher.py --help.