Balluff - BVS CA-GX0 / BVS CA-GX2 Technical Documentation
Using GigE Vision™ Devices In A Docker Container

When developing machine vision applications using Docker containers, it might be required to access GigE Vision™ devices inside the container. With the Impact Acquire framework this can be achieved fairly easily and this chapter will demonstrate how to build a basic Docker container where GigE Vision™ devices can be used. It is recommended to use a native Linux machine as host system for this type of application.

Host Preparation

Linux

The Linux host network interface card has to be first configured for an optimized GigE Vision™ transmission: Checklist for Linux

Windows

Note
It is not recommended to use GigE Vision™ devices in Docker containers on Windows, because the data transfer rate is highly limited due to the network implementation of WSL2 and the set-up to access the device is complicated enough. If the device has to be operated this way, please check the set-up instructions for Windows below.

The Windows host NIC has to be first configured for an optimized GigE Vision™ transmission: Checklist for Windows

Host system requirements

  • Windows 11 64-bit: Home or Pro version 21H2 or higher, or Enterprise or Education version 21H2 or higher
  • Windows 10 64-bit: Home or Pro 21H1 (build 19043) or higher, or Enterprise or Education 20H2 (build 19042) or higher
  • WSL2 backend (For installation please follow: Docker Window Install)

macOS

The macOS host network interface card should be first configured for an optimized GigE Vision™ transmission: Checklist for macOS

Building A Docker Image

The following demo Dockerfile builds a basic Docker image based on the latest stable release version of Debian, where the Impact Acquire GenTL framework including its sample programs are installed. This Dockerfile can be used in many ways:

  • Use it directly to test your device in a Docker container.
  • Use it as a base image for your device applications.
  • Use it as an inspiration for building your own Dockerfile.

Before building the Dockerfile, please download the Balluff Impact Acquire framework installer (https://www.balluff.com/en-de/downloads/software):

  • The installation script: ImpactAcquire-x86_64-linux-*.sh (* should be replaced by the version number)
Note
In case of ARM architectures, all occurrences of "x86_64" in this documentation have to be replaced by the correct platform e.g. "arm64" or "armhf".

Create a directory called ImpactAcquire (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 ImpactAcquire directory is created inside the Downloads directory:

  • $ cd ~/Downloads
  • $ mkdir ImpactAcquire
  • $ mv ImpactAcquire-x86_64-linux-*.sh ImpactAcquire/

Make the installation script ImpactAcquire-x86_64-linux-*.sh executable:

  • $ cd ImpactAcquire
  • $ chmod a+x ImpactAcquire-x86_64-linux-*.sh

Navigate back into the directory where ImpactAcquire 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 the latest stable release version of Debian
FROM debian:latest

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/ImpactAcquire
ENV MVIMPACT_ACQUIRE_DATA_DIR /opt/ImpactAcquire/data
ENV GENICAM_GENTL64_PATH /opt/ImpactAcquire/lib/x86_64
ENV GENICAM_ROOT /opt/ImpactAcquire/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 ImpactAcquire with *.sh file to the container
COPY ImpactAcquire /var/lib/ImpactAcquire

# execute the setup script in an unattended mode
RUN cd /var/lib/ImpactAcquire && \
    ./ImpactAcquire-x86_64-linux-3.3.0.sh -u -gev && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
Note
In case of ARMhf architectures, the environment variable GENICAM_GENTL64_PATH defined in this demo Dockerfile should be relaced by GENICAM_GENTL32_PATH instead.

Finally, build a Docker image using this Dockerfile: 

$ sudo docker build -t [image_name] .
Note
Please make sure to call docker build from within the directory where the Dockerfile resides. Note that Internet access is required for the docker build.

If built successfully, the newly built [image_name] will be listed when calling: 

$ sudo docker images

Starting The Docker Container

Linux

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

Windows

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 IPConfigure 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:

  • Assign one published port (e.g. 49152 for example) to GevMCPHostPort
  • Assign the other published port (e.g. 49153 for example) to GevSCPHostPort
  • Assign the windows host IP address to GevSCDA
  • Increase the packet size GevSCPSPacketSize manually to 1500

Validation

After 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/ImpactAcquire/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.