Balluff - mvBlueFOX3 Technical Documentation
|
When developing machine vision applications using Docker containers, it might be required to access USB3 Vision™ devices inside the container. With the Impact Acquire driver stack this can be achieved fairly easily and this chapter will demonstrate how to build a basic Docker container where USB3 Vision™ devices can be used.
Since Docker uses the kernel of the Linux host machine, it is important to Increasing Kernel memory of the USB file system first to make sure that there will be enough temporary buffer for image data transmission at USB3 speed.
USB devices physically connected to the host system are not automatically accessible in the WSL2 Linux distro. They need to be first attached from the Windows host to the default Linux distro via USB/IP. Please follow Connect USB devices WSL2 for implementation guidance.
udev is needed to identify attached USB devices and to access USB3 Vision™ devices as non-root users with the help of the udev-rules shipped by the Impact Acquire driver package. However, systemd, which starts udev automatically, is by default not supported in WSL2 distros. Besides, udev doesn't support containers. Since WSL2 distros themselves are technically containers, they are not supported by udev. In order for udev to work in WSL2 distros, the following lines need to be commented out in /etc/init.d/udev
before manually starting udev, as shown below:
#if [ ! -w /sys ]; then # log_warning_msg "udev does not support containers, not started" # exit 0 #fi
Then start udev in the WSL2 default Linux distro:
$ sudo /etc/init.d/udev start
The default usbfs buffer in the Linux kernel is 16MB which is usually too small for reliable USB3 Vision™ data transfer. A value of 256MB is recommended. Please refer to Increasing Kernel memory to learn about how to calculate a suitable value for your application.
The easiest way to increase the value automatically when starting the WSL2 distro is to add this kernel parameter in the WSL2 global config file .wslconfig
which is usually located under C:\Users\<UserName>
on the Windows host system:
# Settings apply across all Linux distros running on WSL 2 [wsl2] kernelCommandLine = usbcore.usbfs_memory_mb=256
.wslconfig
doesn't exit under C:\Users\<UserName>
, create one on your own. .wslconfig
file, the WSL2 distro needs to be restarted by calling "wsl --shutdown"
in Windows PowerShell for changes to take effect.The following demo Dockerfile builds a basic Docker image based on a slim version of Debian, where the Impact Acquire GenTL driver package and its sample programs are installed. This Dockerfile can be used in many ways:
Before building the Dockerfile, please download the Impact Acquire GenTL driver installation files from MATRIX VISION GmbH website (https://www.balluff.com/en-de/downloads/software) (e-mail address is required):
Create a directory called mvIMPACT_Acquire (as used in this demo Dockerfile) and move both installation files into this directory. In this example, both files are downloaded into the Downloads directory and the mvIMPACT_Acquire directory is created inside the Downloads directory:
$ cd ~/Downloads $ mkdir mvIMPACT_Acquire $ mv install_mvGenTL_Acquire.sh mvGenTL_Acquire-x86_64_ABI2-*.tgz mvIMPACT_Acquire/
Make the installation script install_mvGenTL_Acquire.sh executable:
$ cd mvIMPACT_Acquire $ chmod a+x install_mvGenTL_Acquire.sh
Navigate back into the directory where mvIMPACT_Acquire resides (e.g. Downloads) and create your Dockerfile:
$ cd ~/Downloads $ touch Dockerfile
Create the content of your Dockerfile. Our demo Dockerfile (for Linux x86_64) looks as follows:
# start with slim version of actual Debian FROM debian:9-slim ENV LC_ALL C ENV DEBIAN_FRONTEND noninteractive # entrypoint of Docker CMD ["/bin/bash"] # set environment variables ENV TERM linux ENV MVIMPACT_ACQUIRE_DIR /opt/mvIMPACT_Acquire ENV MVIMPACT_ACQUIRE_DATA_DIR /opt/mvIMPACT_Acquire/data ENV GENICAM_GENTL64_PATH /opt/mvIMPACT_Acquire/lib/x86_64 ENV GENICAM_ROOT /opt/mvIMPACT_Acquire/runtime ENV container docker # update packets and install minimal requirements # after installation it will clean apt packet cache RUN apt-get update && apt-get -y install build-essential && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* # move the directory mvIMPACT_Acquire with *.tgz and *.sh files to the container COPY mvIMPACT_Acquire /var/lib/mvIMPACT_Acquire # execute the setup script in an unattended mode RUN cd /var/lib/mvIMPACT_Acquire && \ ./install_mvGenTL_Acquire.sh -u && \ rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
Finally, build a Docker image using this Dockerfile:
$ sudo docker build -t [image_name] .
If built successfully, the newly built [image_name] will be listed when calling:
$ sudo docker images
Since the Docker container is isolated from the host system, it needs to be started with certain volume mounts and cgroup permissions for it to access USB3 Vision™ devices. In order to avoid running the container in privileged mode, which is not secure, it can be started like this:
$ sudo docker run -ti -v /dev:/dev -v /run/udev:/run/udev:ro --device-cgroup-rule 'a 189:* rwm' [image_name] /bin/bash
Where:
After starting the container, the correct operation of USB3 Vision™ devices can be validated by running one of the sample programs provided by the Impact Acquire (e.g. SingleCapture):
$ cd /opt/mvIMPACT_Acquire/apps/SingleCapture/x86_64 $ ./SingleCapture
If the attached USB3 Vision™ device appears in the device list of the program's output, access to it in the container by using the Impact Acquire has been established. Now the USB3 Vision™ device can be used inside the Docker container for your machine vision applications.
The following demo Dockerfile builds a basic Docker image based on a slim version of Debian, where the Impact Acquire GenTL driver package and its sample programs are installed. This Dockerfile can be used in many ways:
Before building the Dockerfile, please download the Impact Acquire GenTL driver installation files from MATRIX VISION GmbH website (https://www.balluff.com/en-de/downloads/software) (e-mail address is required):
Create a directory called mvIMPACT_Acquire (as used in this demo Dockerfile) and move both installation files into this directory. In this example, both files are downloaded into the Downloads directory and the mvIMPACT_Acquire directory is created inside the Downloads directory:
$ cd ~/Downloads $ mkdir mvIMPACT_Acquire $ mv install_mvGenTL_Acquire.sh mvGenTL_Acquire-x86_64_ABI2-*.tgz mvIMPACT_Acquire/
Make the installation script install_mvGenTL_Acquire.sh executable:
$ cd mvIMPACT_Acquire $ chmod a+x install_mvGenTL_Acquire.sh
Navigate back into the directory where mvIMPACT_Acquire resides (e.g. Downloads) and create your Dockerfile:
$ cd ~/Downloads $ touch Dockerfile
Create the content of your Dockerfile. Our demo Dockerfile (for Linux x86_64) looks as follows:
# start with slim version of actual Debian FROM debian:9-slim ENV LC_ALL C ENV DEBIAN_FRONTEND noninteractive # entrypoint of Docker CMD ["/bin/bash"] # set environment variables ENV TERM linux ENV MVIMPACT_ACQUIRE_DIR /opt/mvIMPACT_Acquire ENV MVIMPACT_ACQUIRE_DATA_DIR /opt/mvIMPACT_Acquire/data ENV GENICAM_GENTL64_PATH /opt/mvIMPACT_Acquire/lib/x86_64 ENV GENICAM_ROOT /opt/mvIMPACT_Acquire/runtime ENV container docker # update packets and install minimal requirements # after installation it will clean apt packet cache RUN apt-get update && apt-get -y install build-essential \ iproute2 && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* # move the directory mvIMPACT_Acquire with *.tgz and *.sh files to the container COPY mvIMPACT_Acquire /var/lib/mvIMPACT_Acquire # execute the setup script in an unattended mode RUN cd /var/lib/mvIMPACT_Acquire && \ ./install_mvGenTL_Acquire.sh -u && \ rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
Finally, build a Docker image using this Dockerfile:
$ sudo docker build -t [image_name] .
If built successfully, the newly built [image_name] will be listed when calling:
$ sudo docker images
Start the Docker container with --net=host flag, so that it will use the host network instead of the default bridge network:
$ sudo docker run -ti --net=host [image_name] /bin/bash
Since the Docker host mode networking doesn't work on Windows due to the isolated network namespace of Docker daemon, the container needs to be started using the default bridge network with specific ports published for receiving GigE Vision™ streaming packets. For instance, port 49152 can be used for event messages and port 49153 for streaming packets:
$ sudo docker run -ti -p 49152:49152/udp -p 49153:49153/udp [image_name] /bin/bash
Inside the container, the GigE Vision™ device needs to be discovered first. Since the Docker bridge network resides in a different subnet, unicast needs to be applied in order to discover the GigE Vision™ device. Follow Unicast Device Discovery via mvIPConfigure or use Impact Acquire SDK (see InterfaceModule.mvUnicastDeviceDiscoveryCommandCount()
etc.) to set up the unicast procedure.
Once the GigE Vision™ device has been discovered by unicast and initialized by Device.open()
, several GVSP transport layer parameters still need to be configured before being able to receive streaming packets due to the WSL2 NAT network. Here are the parameters that need to be changed manually:
GevMCPHostPort
GevSCPHostPort
GevSCDA
GevSCPSPacketSize
manually to 1500After starting the container, the correct operation of GigE Vision™ devices can be validated by running one of the sample programs provided by the Impact Acquire (e.g. SingleCapture):
$ cd /opt/mvIMPACT_Acquire/apps/SingleCapture/x86_64 $ ./SingleCapture
If the attached GigE Vision™ device appears in the device list of the program's output, access to it in the container by using the Impact Acquire has been established. Now the GigE Vision™ device can be used inside the Docker container for your machine vision applications.