OpenDLV Desktop

OpenDLV Desktop is an easy-to-use environment that includes all tools and software that is needed to learn and work with OpenDLV. It runs on your computer inside Docker as containerized software and gets full access to your computers resources. First you need to prepare your computer by installing Docker.

We will talk more about Docker later in the tutorials, so for now its enough to know that it is used to run containerized software such as the OpenDLV Desktop.

Installing Docker

The installation process for Docker differs between different types of systems, and here the steps for Windows, Mac OS, and Linux are shown. The instructions assume that you are familiar with your installed system, so the instructions are not very detailed. If the instructions are to brief, please also refer to the documentation from the developers of Docker as found here.

Windows

Windows supports Docker via the Windows Subsystem for Linux (WSL) extension, available in Windows 10 and Windows 11. To allow for higher execution speeds and support for graphics cards you should make sure to have WSL version 2 enabled.

To enable WSL (if you did not use it before), open a Windows terminal with administrator privileges and run:

wsl --install

You will need to restart your computer to complete the installation. In the end of the installation you will be prompted for a username and password for you newly installed Ubuntu Linux installation. When the installation is done, you can close the Ubuntu terminal, as it continue to run in the background.

Then, install Docker Desktop by downloading the installer from here. Run the installer, make sure to select the recommended configuration, and then log out from your Windows to complete the installation.

You are now ready to follow the steps to run OpenDLV Desktop below. Simply create the folders and the YML-file (it might be a good idea to show the full file extension to verify that the filename is correct). Then, open a terminal and start OpenDLV Desktop as stated below. You may also open the Docker Desktop app to view the running containers.

If you encounter problems with the installation, read more here.

Mac OS

If you have Mac OS with apple silicon (M1, M2) It is recommended that you install Rosetta2 before installing Docker Desktop, since there are a few optional command line tools that require Rosetta 2 when using Darwin/AMD64.

softwareupdate --install-rosetta

The following steps are the same for all the Mac Os users

Download Docker Desktop for Mac with Intel chipor Docker Desktop for Mac with Apple silicon and open the application. Read the terms of conditions, press accept and continue to start Docker Desktop..

You are now ready to follow the steps to run OpenDLV Desktop below. Then, open a terminal and start OpenDLV Desktop as stated below. You may also open the Docker Desktop app to view the running containers.

If you prefer to install from the command line, please follow the steps here If you encounter problems with the installation, read more here

Linux

There are many different kinds of Linux systems, so called distributions. Here, a few common distributions are covered.

Ubuntu

First, start by opening the terminal and then install a small tool called curl used to download resources from the internet:

sudo apt-get install curl

Next, download and install the Docker key, to verify later downloads to be genuine (the key is piped into the program apt-key which is run as the super user):

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add

Next, add the Ubuntu software catalog from Docker:

sudo add-apt-repository \
  "deb [arch=amd64,arm64,armhf] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

Here, the backslash (\) is used to break the line into two lines. It is not required but might increase readability, so you could just write it all in one line if you want.

The architectures amd64, arm64, and armhf refers to different types of processors (CPUs), and $(lsb_release -cs) is an environmental variable that exists in Ubuntu. You can type it into another terminal to see the value, which in this case is your current version of Ubuntu.

Next, go ahead and install Docker:

sudo apt-get update
sudo apt-get install docker-ce
sudo usermod -aG docker $USER

The last command adds your Linux user into the group docker, allowing it to use Docker. To make that take effect, you need to logout of Ubuntu and login again.

Now you can test Docker by using a hello-world image that exists in the official Docker image registry. When using this image to test Docker it also demonstrates one of the purposes of using Docker: an easy way of distributing images online and being able to download and run them on different computers.

docker run hello-world

If you get the message Hello from Docker! your installation was successful.

Arch Linux

If you use Arch Linux (rather than for example Ubuntu), then follow the steps in this section. Arch Linux includes Docker in their software catalog. Simply run the following to install, as root (using su or sudo):

pacman -S docker
usermod -aG docker $USER
systemctl enable docker
systemctl start docker

Then, log out from your Arch Linux session and log in again to allow your user into the docker group. Finally, test your Docker installation by running:

docker run hello-world

If you get the message Hello from Docker! your installation was successful.

Running OpenDLV Desktop

When you system supports Docker you are ready to start OpenDLV Desktop. It is most easily started using docker compose, which we will demonstrate more later in the tutorials.

First, create a folder from where you will start your instance of OpenDLV Desktop. Simply create an empty folder named opendlv-tutorials anywhere on your computer. Inside, create another empty folder named opendlv-desktop-data and an empty file named docker-compose.yml. If you are using Windows, make sure that the file extension is correct, by checking the view file extension check box. In the file, add the following:

version: '3'
services:
  opendlv-desktop:
    image: registry.opendlv.org/community/opendlv-desktop:14.1
    privileged: true
    ports:
      - 5901:5901
      - 5901:5901/udp
      - 6080:6080
    volumes:
      - /run/user/1000/pulse/native:/run/user/1000/pulse/native
      - ./opendlv-desktop-data:/home/opendlv/data
    environment:
      - PASSWORD=

Make sure to enter a strong password, especially if you are using a computer in a non-home network. Anyone with the password and your computers network address can connect (even over the Internet), and also get access to your Docker engine. With a strong password, with at least eight characters, you are safe.

To start the Docker container, point a terminal to the folder where the file docker-compose.yml is located and then run the command docker compose up. OpenDLV Desktop will now start inside a new Docker container. To access it, points a browser to here. The folder opendlv-desktop-data can be used to save data OpenDLV Desktop back to the host system.

Using OpenDLV Desktop

OpenDLV Desktop is based on the Ubuntu Linux distribution, but it is slimmed down and does not look exactly the same. Still, if you are used to Ubuntu or other Linux distributions you will quickly get familiar with OpenDLV Desktop.

To get started, after accessing the webpage and typing in your password, simply right click to open a menu. The system includes some typical pre-installed software and apps, especially with IoT and robotics in mind. It includes tools both for C++ and Python, and has Docker exposed from the underlying host system. In short, everything needed in order to start learning and developing for the OpenDLV ecosystem.

One of the most typical apps used when working with the system is the terminal window. To open a terminal, simply right click and then choose Terminal. From here you have all the commands that you are used to from an Ubuntu system, and you can easily install more apps if needed.