Managing the CODESYS Virtual Safe Control SL via the Command Line

To manage and use the CODESYS Virtual Safe Control SL on a Linux device, you can directly interact with the VirtualControlAPI via the command line.

The VirtualControlAPI is a Python-based command-line tool for managing the CODESYS Virtual Safe Control SL on Linux systems and is also used by the CODESYS Control SL Deploy Tool.

Requirements

Device with a Linux-based operating system
Python 3 (>= 3.9)
Script: VirtualControlAPI.py

. You have two ways to get the VirtualControlAPI.py script:

Option 1 (recommended):
If you have not already done so, install the CODESYS Virtual Control for Linux SL package to your CODESYS installation on Windows. After that, you will find the VirtualControlAPI.py script in the directory <CODESYS installation directory> \CODESYS Virtual Control for Linux SL\Delivery\virtuallinux\VirtualControlAPI.py.
Option 2:
Download the CODESYS Virtual Control for Linux SL package from the store and extract the .package package (for example, CODESYS Virtual Control for Linux SL 4.18.0.0.package) with any ZIP program. In the extracted directory, you will find the VirtualControlAPI.py script under Delivery\virtuallinux\VirtualControlAPI.py.

Usage

The Python script VirtualControlAPI.py may need to be run as the root user. The script performs tasks such as making changes to container registries and modifying namespaces of network adapters.

sudo python3 VirtualControlAPI.py <command>

You can use the following command to display help for all possible options, parameters, and descriptions:

sudo python3 VirtualControlAPI.py --help

Typical workflow

Importing a container image to the local registry
To load an image to the registry, use the command --import-image and pass the name of the .tar.gz file where the image is located. This transfers the image to the local registry.
Example 5. Example:
```
sudo python3 VirtualControlAPI.py --import-image Docker_codesyscontrol_virtuallinux_4.19.0.0_amd64.tar.gz
```
To see which images already exist in the local registry, use the command:
```
sudo python3 VirtualControlAPI.py --list-images
```
Only images which meet the criteria of the VirtualControlAPI will be displayed.
Creating an instance
To create a runtime instance, the following command is used:
```
sudo python3 VirtualControlAPI.py --add-instance <instance name>
```
If you want to create an EdgeGateway instance or a Safe Runtime instance, specify this at the end of the command.
```
udo python3 VirtualControlAPI.py --add-instance <instance name> --safety
sudo python3 VirtualControlAPI.py --add-instance <instance name> --gateway
```
This is necessary because the different instance types are equipped with different default configurations and default parameters.
Configuring the instance
To configure the created instance, it is advisable to first review the available configuration parameters. To do this, the following command displays the configuration file in formatted form:
```
sudo python3 VirtualControlAPI.py --get-configuration <instance name>
```
The parameters listed under CONFIG_KEY are generally all configurable and can be edited with the following command:
```
sudo python3 VirtualControlAPI.py --configure <instance name> [set/add/remove] <CONFIG_KEY> <value>
```
- set will overwrite the current value.
- add will add values.
- remove will remove the current value.
Typically, for a first start, only setting the CONFIG_KEY image is required. To do this, run the following command and replace the image with the matching image. To show all images, you can use the command --list-images.
Example 6. Example
```
sudo python3 VirtualControlAPI.py --configure <instance name> set Image codesyscontrol_virtuallinux:4.19.0.0
```
Important
In order for an instance to be configured, it must be in a stopped state.
Starting and stopping the instance
The instance will be started with the option --run and stopped with the option --stop.
```
sudo python3 VirtualControlAPI.py --run <instance name>
sudo python3 VirtualControlAPI.py --stop <instance name>
```

For more information about the options and exit codes, run the command sudo python3 VirtualControlAPI.py --help.

Example "Safe House" scenario via scripting

The following subscripts describe, for example, how the "Safe House" scenario can be achieved via the VirtualControlAPI.

Important

The "Safe House" article sheds light on other technical aspects which are relevant for operating a safe controller. Consult this help page, as well as the safety documentation of the device manufacturer, for all safety or certification information.

Preparations

To get the VirtualControlAPI.py script, as well as the latest versions of the images of the CODESYS Virtual Control for Linux SL, follow the instructions from the step Requirements from the previous chapter. Repeat your procedure for CODESYS Virtual Safe Control SL to download the images for CODESYS Virtual Safe Control SL and CODESYS Virtual Safe Time Provider SL. The container images can be found in the following directories, depending on the method:

Option 1:
The container images are stored as tar.gz files in the following directory:
<CODESYS installation directory>\CODESYS Virtual Control for Linux SL\Delivery\<product>\
<CODESYS installation directory>\CODESYS Virtual Safe Control SL\Delivery\<product>\
Option 2:
The container images are stored as tar.gz files in the following directory of the CODESYS package:
Delivery\<product>\

Option 3 – Scripting:

Option 2 can also be achieved by means of scripts. See the following sample script for downloading and unpacking the CODESYS package as well as for pushing the images to the infrastructure of your company.

Tip

Note the licensing conditions for using a CODESYS software.

DownloadUnpackPush.cmd

@echo off
setlocal EnableDelayedExpansion

REM ===== Configuration =====
set ZIP_URL_vControl=https://store.codesys.com/ftp_download/3S/VirtualLinuxSL/000138/4.18.0.0/CODESYS%%20Virtual%%20Control%%20for%%20Linux%%20SL%%204.18.0.0.package
set ZIP_URL_vSafe=https://store.codesys.com/ftp_download/3S/VirtualSafeSL/000139/4.18.0.0/CODESYS%%20Virtual%%20Safe%%20Control%%20SL%%204.18.0.0.package

set ZIP_FILE_vControl=%TEMP%\CODESYS Virtual Control for Linux SL 4.18.0.0.package
set ZIP_FILE_vSafe=%TEMP%\CODESYS Virtual Safe Control SL 4.18.0.0.package

set DEST_DIR=C:\ExtractedFiles
set "vControlDir=%DEST_DIR%\vControl"
set "vSafeDir=%DEST_DIR%\vSafe"

set "REGISTRY=example.registry.com"

REM ===== Create destination folder =====
if not exist "%vControlDir%" mkdir "%vControlDir%"
if not exist "%vSafeDir%" mkdir "%vSafeDir%"

REM ===== Download ZIP =====
curl -L --ssl-no-revoke --no-keepalive --retry 5 --retry-delay 2 -o "%ZIP_FILE_vControl%" "%ZIP_URL_vControl%"
curl -L --ssl-no-revoke --no-keepalive --retry 5 --retry-delay 2 -o "%ZIP_FILE_vSafe%" "%ZIP_URL_vSafe%"

REM ===== Extract ZIP =====
"C:\Program Files\7-Zip\7z.exe" x "%ZIP_FILE_vControl%" -o"%vControlDir%" -y
"C:\Program Files\7-Zip\7z.exe" x "%ZIP_FILE_vSafe%" -o"%vSafeDir%" -y

REM ===== load images to docker and push to registry =====

for /f "tokens=3 delims=: " %%I in ('docker load -i "%vControlDir%\Delivery\virtuallinux\Docker_codesyscontrol_virtuallinux_4.18.0.0_amd64.tar.gz"')
    do (
    docker tag %%I %REGISTRY%/%%I
    docker push %REGISTRY%/%%I
)
for /f "tokens=3 delims=: " %%I in ('docker load -i "%vControlDir%\Delivery\edgeamd64\Docker_codesysedge_edgeamd64_4.18.0.0_amd64.tar.gz"')
     do (
    docker tag %%I %REGISTRY%/%%I
    docker push %REGISTRY%/%%I
)

for /f "tokens=3 delims=: " %%I in ('docker load -i "%vSafeDir%\Delivery\linuxsafei386\Docker_codesyssafecontrol_linuxsafei386_4.18.0.0_i386.tar.gz"')
     do (
    docker tag %%I %REGISTRY%/%%I
    docker push %REGISTRY%/%%I
)
for /f "tokens=3 delims=: " %%I in ('docker load -i "%vSafeDir%\Delivery\linuxsafetimeprovider\Docker_codesyssafetimeprovider_linuxsafetimeprovider_4.18.0.0_amd64.tar.gz"')
     do (
    docker tag %%I %REGISTRY%/%%I
    docker push %REGISTRY%/%%I
)

echo Done.
endlocal
pause

Additional preparation:

In the same way, download the packages for CODESYS License Server for Linux SL and CODESYS CodeMeter for Linux SL.

Because CODESYS Virtual Control for Linux SL can be licensed only via network licensing, these two packages are required for licensing. This step is not necessary for a test setup, but it is recommended and is included in the following scripts.

Transferring the script, Debian packages, and container images to the controller

For a single application, you can transfer the individual files from the CODESYS packages directly to the target devices. For example, with pscp:

pscp -pw password <PathToDockerImage.tar.gz> user@<IP>:~/

If the container images, VirtualControlAPI.py, and any necessary Debian packages have been loaded to an internal server or an internal container registry, then you can also get them directly from there.

#!/bin/bash docker pull example.registry.com/codesyscontrol_virtuallinux:4.18.0.0
docker pull example.registry.com/codesyssafecontrol_linuxsafei386:4.18.0.0
docker pull example.registry.com/codesysedge_edgeamd64:4.18.0.0

curl my-server-url/VirtualControlAPI.py -o VirtualControlAPI.py

Script for the automatic setup of the "The Safe House" scenario

Note

The following scripts serve only as examples. You may need to make adjustments to the version, network adapters, IP addresses, etc.

In the following examples, it is assumed that the individual files have been directly transferred to the controller after being extracted from the CODESYS package. Adapt the scripts according to your use case.

Linux-Host-PC 2

Navigate to the directory containing VirtualControlAPI.py as well as the .tar.gz-compressed container images. Adapt the following script to your specific platform and run it.

SetupExample_LinuxHostPC2.sh

#!/bin/bash

# load images into registry
docker load -i Docker_codesyssafetimeprovider_linuxsafetimeprovider_4.18.0.0_amd64.tar.gz

# create timeprovider instance and configure
python3 VirtualControlAPI.py -a timeprovider --timeprovider
python3 VirtualControlAPI.py -c timeprovider set Image codesyssafetimeprovider_linuxsafetimeprovider:4.18.0.0
python3 VirtualControlAPI.py -c timeprovider set GenericCommands -e TARGET_IP=10.0.0.4 -e TARGET_PORT=60000

python3 VirtualControlAPI.py -r timeprovider

Linux-Host-PC

Navigate to the directory containing VirtualControlAPI.py as well as the .tar.gz-compressed container images. Adapt the following script to your specific platform and run it.

SetupExample_LinuxHostPC.sh

#!/bin/bash

# load images into registry
docker load -i Docker_codesyscontrol_virtuallinux_4.18.0.0_amd64.tar.gz
docker load -i Docker_codesysedge_edgeamd64_4.18.0.0_amd64.tar.gz
docker load -i Docker_codesyssafecontrol_linuxsafei386_4.18.0.0_i386.tar.gz
dpkg -i codemeter-lite_8.30.6885.501_amd64.deb
dpkg -i codesyslicenseserver_licenseserver_4.18.0.0_all.deb

# create runtime instance and configure
python3 VirtualControlAPI.py -a vPLC
python3 VirtualControlAPI.py -c vPLC set Image codesyscontrol_virtuallinux:4.18.0.0
python3 VirtualControlAPI.py -c vPLC set Ipc shareable
python3 VirtualControlAPI.py -c vPLC set LicenseServer 10.0.0.4

# create edge gateway instance and configure
python3 VirtualControlAPI.py -a vGateway --gateway
python3 VirtualControlAPI.py -c vGateway set Image codesysedge_edgeamd64:4.18.0.0

# create safe runtime instance and configure
python3 VirtualControlAPI.py -a vSafePLC --safety
python3 VirtualControlAPI.py -c vSafePLC set Image codesyssafecontrol_linuxsafei386:4.18.0.0
python3 VirtualControlAPI.py -c vSafePLC set Ipc container:vPLC
python3 VirtualControlAPI.py -c vSafePLC set Dependencies vPLC

python3 VirtualControlAPI.py --run-all

After the scripts have been run on the respective computers, the instances are configured according to the scenario and are in the Running state. All the required devices are now ready. The next steps for creating a project and integrating PROFIsafe are described in the CODESYS Safety Extension documentation.

Script for updating the runtime instances

Only a few commands are required to upgrade the version of individual instances. Stopping, changing the container image and restarting the instances will not affect any other settings. However, you will benefit from all the new features and improvements of the new version.

Deploy the images to the device as you did in the previous steps.

UpgradeVersions.sh

#!/bin/bash

# load images into registry
docker load -i Docker_codesyscontrol_virtuallinux_4.19.0.0_amd64.tar.gz
docker load -i Docker_codesysedge_edgeamd64_4.19.0.0_amd64.tar.gz
docker load -i Docker_codesyssafecontrol_linuxsafei386_4.19.0.0_i386.tar.gz

# stop all instances. If only selective instances should be upgraded, use python3 VirtualControlAPI.py -s <instance name> to only stop specific instances
python3 VirtualControlAPI.py --stop-all

# configure new images for instances
python3 VirtualControlAPI.py -c vPLC set Image codesyscontrol_virtuallinux:4.19.0.0
python3 VirtualControlAPI.py -c vGateway set Image codesysedge_edgeamd64:4.19.0.0
python3 VirtualControlAPI.py -c vSafePLC set Image codesyssafecontrol_linuxsafei386:4.19.0.0

# start all instances
python3 VirtualControlAPI.py --run-all

Troubleshooting

Error	Symptom	Cause	Solution
Permission denied / Access error	Error message: `PermissionError: [Errno 13] Permission denied`	The script requires higher permissions, for example to access the container registry, system paths, and to make changes to the namespaces of network adapters.	Execute the command again with `sudo`. sudo python3 VirtualControlAPI.py <command>
Image is not displayed in the registry	`--list-images` does not show the expected image.	The image is not compatible. Only images which meet specific CODESYS criteria are displayed.	Check if it is an official CODESYS Virtual Control SL image.
		The import was canceled.	Run the import again. sudo python3 VirtualControlAPI.py --import-image
		Incorrect file name / corrupted file	Validate that the `tar.gz` is complete and can be read.
Instance hangs on startup	Timeout or endless start attempt	Misconfiguration of the network	Check the image
		Missing or incorrect image tag	Validate the configuration
		Container runtime (for example, Podman or Docker) not started	Restart the container environment

In this section:

Managing the CODESYS Virtual Safe Control SL via the Command Line

Requirements

Usage

Typical workflow

Important

Example "Safe House" scenario via scripting

Important

Preparations

Tip

Transferring the script, Debian packages, and container images to the controller

Script for the automatic setup of the "The Safe House" scenario

Note

Script for updating the runtime instances

Troubleshooting

Search results