-------------------------------------------------------------------------------
Matrox Imaging Library (MIL) 10
MIL 10 1911 for Linux and MIL 10 Processing Pack 3
Release Notes (MilLinux)
November, 2019
(c) Copyright Matrox Electronic Systems Ltd., 1992-2019.
-------------------------------------------------------------------------------
This document outlines limitations and notes when using
MIL under Linux.
Contents:
1. What's new in MIL 10 1911 for Linux and MIL 10 Processing Pack 3
2. Conventions in this readme file
3. Installation
4. Supported distributions
5. Packages required
6. Recompiling examples
7. Licensing
8. Intellicam utility and the MIL Processing GUIs
9. Display
10. Boards and drivers
10.1 Matrox Solios
10.2 Matrox Radients
10.2.1 Serial port
10.3 Matrox GigE Vision
10.3.1 Bandwidth optimisation
10.3.2 Firewall
10.3.3 Multiple Interfaces
10.3.3.1 Ubuntu
10.3.3.2 RHEL
10.3.4 Configuration Notes
11. Security and permissions.
12. SecureBoot
13. Configuration
14. Firewall
15. Using MIL in a deamon/service
15.1 Services started using initd
15.2 Services started using systemd
-------------------------------------------------------------------------------
1 - What's new in MIL 10 1911 for Linux and MIL 10 Processing Pack 3
* Updated list of supported Linux distributions (see section 4)
* Now using GenICam 3.1 with GenCP and CLProtocol
2. Conventions in this readme file
* Command lines starting with # must be executed with root permissions,
either as the root user or using the sudo command. Command lines starting
with $ can be executed without root permissions.
3. Installation
* Before installing MIL, make sure the required packages are installed;
see "Section 4. Packages required" in this readme file.
* If you use sudo and wish to use the graphical installer, you may
need to execute the following command prior to starting the installation:
$ xhost si:localuser:root
This will be necessary on a default installation of RHEL but not on a
default installation of Ubuntu.
* To install the full version of MIL, execute the following command:
# sh ./mil-10.35_XXXX-installer.run
Whereas, to install MIL-Lite, execute the following command:
# sh ./mil-lite-10.35_XXXX-installer.run
Replace XXXX with the MIL build number.
* During installation, a new group named mil is added to the /etc/group file,
and you will be prompted to add at least one valid user to this group. Any
user in this group can change the MIL configuration using the MILConfig
utility (modify examples, recompile MIL drivers, and manage the Distributed
MIL services).
Note that you don't need to add the root user to the mil group.
* During installation, MIL drivers will be compiled to match the version of
the running kernel. After installation, any user in the mil group can
recompile the drivers by accessing the "Driver Status" page of the
MILConfig utility, and then clicking on the "Compile Drivers" button.
Note : Ubuntu will silently keep the kernel up to date. When an update happens,
the MIL drivers will need to be recompiled in order to be loaded by the new kernel.
If the drivers do not load, check Drivers Status under Boards in MILConfig.
* To uninstall MIL completely, execute the following command:
# mil-uninstall
4. Supported distributions
Red Hat Enterprise 8.(1) 64-bit
CentOS 8.0 64-bit
Ubuntu LTS 18.04 64-bit
SUSE Enterprise 15 SP1 64-bit
5. Packages required
Typically, MIL requires the following packages to run under each
supported Linux distribution. You will not be able to install MIL
if these packages are not installed:
Ubuntu 18.04 LTS
Runtime: setserial, libgconf-2-4, libcanberra-gtk-module and gvfs-backends
Development: build-essential
Installation command to use to install the packages:
CLI: apt-get
For example: apt-get install setserial
GUI: synaptic
(Menu System->Administration->Synaptic Package Manager)
RHEL 8.x
Development: Choose "Software Development" during the installation
Installation command to use to install the package:
CLI : rpm
For example: rpm -Uvh package_name.rpm
SLE 15
Runtime: insserv-compat-0.1-2.15
Development: Choose "C/C++ Compiler and Tools " during the installation
Installation command to use to install the package:
GUI : yast
(Applications->System Tools->YaST->Software Management)
If you want to recompile the Gtk and Qt examples, the following packages
must be installed:
* gtk3-devel
* qt4-devel or qt5-devel
You might need to install additional packages, depending on the following:
* The installed edition of Linux (Desktop Edition/Alternate Edition/
Server Edition).
* The installed distribution of Linux is an unsupported distribution.
6. Recompiling examples
* If you want to recompile the examples in the installation directory, open a
console window and type:
$ cd $MILDIR/examples
$ make clean; make
* The first example that you should try running is:
$ cd MappStart
$ ./mappstart
7. Licensing
* The Matrox Concord cannot be used as a fingerprint for licensing.
8. Intellicam utility and the MIL Processing GUIs
* The Intellicam utility and the MIL Processing GUIs are not supported under
Linux.
9 Display
* Buffers with the attributes M_DIB, M_DIRECTX, and/or M_VIDEO_MEMORY
are not supported.
* M_NO_TEARING is not supported in windowed mode.
* When using an exclusive display, if you obtain the message "vcf exceeds
monitor capabilities" and you are using an old version of the Xorg server,
make sure the "Virtual" option in the Display subsection of your xorg.conf
file is set appropriately. This option sets the maximum size of the virtual
desktop, and should be set to a size that is at least as large as the
exclusive display size, established by the selected VCF. In the following
example, the virtual desktop size
is 2048x2048:
SubSection "Display"
Depth 24
Modes "1600x1200" "1280x1024" "1024x768" "800x600" "640x480"
# ADD A VIRTUAL LINE TO PROVIDE FOR THE LARGEST SCREEN YOU WILL HOTPLUG
Virtual 2048 2048
....
Note that the maximum size of the virtual desktop depends on the amount of
display memory.
10. Boards and drivers
* The XEN kernels are not supported.
* The PAE kernels are not tested.
10.1 Matrox Solios
* The Matrox Solios Processing FPGA is not supported.
10.2 Matrox Radients
10.2.1 Serial ports
* Matrox Radient has 1, 2, or 4 serial interfaces (each controlled by a
UART); the number of serial interfaces depends on the version of the
board.
* By default, the standard Linux serial port driver does not properly
identify the Matrox Radient serial interfaces. They will therefore
not be available as /dev/ttyS* as ordinary serial port. The Radient
or Radient eV-CL driver will create /dev/RadientS* or /dev/RadienteVCLS*
device which can be used like any ttyS*
10.3 Matrox GigE Vision
10.3.1 Bandwidth optimisation
If you are using a high bandwith camera, you should raise the MTU (Ethernet
packet size) value above the 1500 default. The optimal value is dependant
on your machines and network configuration. You can change this in
NetworkManager on RedHat or Ubuntu. You can also use either of these two
commands:
# ifconfig eth0 mtu 9000
# ip link set eth0 mtu 9000
Of course, you should change eth0 for whichever interface your camera is
connected to and 9000 for the value you want for the MTU.
When running in a debugger, the camera heart beat will be disabled
(if supported) or increased to 5 minutes.
10.3.2 Firewall
If your firewall is enabled, you will need to allow UDP packets coming from
port 3956 (gvcp) to pass or MIL will not be able to detect cameras on your
network. To do so, you can issue this command:
# iptables -I INPUT 1 -p udp --sport gvcp -j ACCEPT
This command will need to be done at every reboot. You will need to consult
your distro's documentation to make it permanent.
10.3.3 Multiple Interfaces
If you have more than one interfaces on the same subnet, as is the case when
using multiple cameras with auto-ip(a 169.254.X.X address), you will need to
configure a bridge between those interfaces.
10.3.3.1 Ubuntu
Under Ubuntu, to make the change permanent you need to change
/etc/network/interfaces with these lines:
iface eth3 inet manual
iface eth4 inet manual
auto br0
iface br0 inet static
bridge_ports eth3 eth4
address 169.254.5.67
broadcast 169.254.255.255
netmask 255.255.0.0
bridge_fd 0
Of course, you can have more than two interfaces in a bridge and you should
change eth3 and eth4 for whichever interfaces your cameras are connected
to. Your bridge doesn't have to be named br0. To make those change active
you will need to restart your networking or reboot.
10.3.3.2 RHEL
Under RHEL, You will need to add the file
/etc/sysconfig/network-scripts/ifcfg-br0 with the following content:
DEVICE=br0
TYPE=Bridge
IPADDR=169.254.5.67
NETMASK=255.255.0.0
ONBOOT=yes
BOOTPROTO=static
NM_CONTROLLED=no
DELAY=0
In addition, for every interfaces (ex: eth3, eth4 ...) you want part of this
bridge, you will need to modify its configuration file (ex:
/etc/sysconfig/network-scripts/ifcfg-Auto-eth3 or
/etc/sysconfig/network-scripts/ifcfg-eth3 ). You will need to modify or
add the following lines to set these variables to those values.
BOOTPROTO=none
NM_CONTROLLED=no
BRIDGE=br0
To make those changes active you will need to restart your networking
or reboot.
10.3.4 Configuration Notes
We noted that under SUSE the link-local (Zeroconf) configuration option doesn't
seems to always optain an IP address. You might want to use a static IP
configuration instead.
11. Security and permissions
* To prevent permission access errors, two users should not be running MIL
at the same time on the same computer.
* Note that the MIL installer changes the sudo configuration file
(/etc/sudoers) so that MIL can shutdown a user’s computer after
updating the firmware of their installed Matrox Imaging boards.
Changing the configuration file is required because when you run a
MIL example/application, MIL automatically detects whether the
firmware of each installed Matrox Imaging board is up-to-date.
If it is not, MIL will update the firmware of the board and then
request to shutdown the computer. If the current user does not have
sufficient privileges, they will not be able to proceed with the required
shutdown and the current example/application will wait indefinitely.
After uninstalling MIL, the sudo configuration file is restored.
* If you get SELinux errors, execute the following command:
# mil-selinux
This will fix the SELinux context of the MIL *.lib files.
12. SecureBoot
Kernel modules must be signed if Secure Boot is enabled in the UEFI BIOS in order for them to be loaded.
You can check the status of MIL?s kernel modules (i.e., drivers) through MILConfig?s Drivers compilation page.
The steps below are to self-sign the MIL kernel modules:
* Generate a custom x509 key:
> openssl req -new -x509 -newkey rsa:2048 -keyout MOK.priv -outform DER -out MOK.der -nodes -subj "/CN=Owner/"
Keep it for reference in order to later sign the kernel modules.
* Enroll the new key
> sudo mokutil --import MOK.der
This will request the public key to be added to the MOK ( Machine Owner Key)
- Sign the kernel modules
> for f in /opt/matrox_imaging/drivers/modules/custom/$(uname -r)/*.ko; do sudo /lib/modules/$(uname -r)/build/scripts/sign-file sha256 ~/MOK.priv ~/MOK.der $f;done
* reboot
After reboot, a dialog will appear to accept enrolling the new MOK key ( MokManager). (Use the password used to import the MOK key)
Notes:
- In the early versions of Ubuntu 16.04 with kernel 4.4.0-21-generic, signed kernel modules could not be loaded. Update the kernel to fix the issue.
- The kernel modules must be re-signed each time the Linux kernel is updated. Again, check MILConfig?s Drivers compilation for the status.
For more information on how to sign kernel modules, see the man pages for mokutil or the web site for your Linux distribution.
13. Configuration
* To establish the Linux ttyS port corresponding to a Matrox Solios or Morphis
board's serial interface (UART), do the following:
1. Identify the address of the required board's serial interface. To do so,
type 'lspci -v -d 102b:*' on a command line. This command lists all the
Matrox PCI devices installed in your computer (Matrox vendor number is
102b):
05:04.0 Signal processing controller: Matrox Graphics, Inc. Device 47c1
(rev 03)
Subsystem: Matrox Graphics, Inc. Device 4d80
Flags: bus master, medium devsel, latency 64, IRQ 16
Memory at d4000000 (64-bit, prefetchable) [size=1M]
Memory at e0000000 (64-bit, prefetchable) [size=256M]
Capabilities: <access denied>
Kernel driver in use: Solios
05:04.1 Serial controller: Matrox Graphics, Inc. Device 47c2 (rev 02) (prog-if 02)
Subsystem: Matrox Graphics, Inc. Device 47c8
Flags: medium devsel, IRQ 17
I/O ports at ccf0 [size=8]
Capabilities: <access denied>
Kernel driver in use: serial
05:04.2 Serial controller: Matrox Graphics, Inc. Device 47c2 (rev 02)
(prog-if 02)
Subsystem: Matrox Graphics, Inc. Device 47c9
Flags: medium devsel, IRQ 17
I/O ports at ccf8 [size=8]
Capabilities: <access denied>
Kernel driver in use: serial
Except for Matrox Radient, the serial interfaces of Matrox boards are
seen as separate PCI devices from the acquisition section of the board.
Although only the acquisition section ("Signal processing controller")
of the board is listed with the board name, you can establish the board
of a serial interface ("Serial controller") by matching the first four
digits of its "Serial controller" listing with those of a "Signal
processing controller" listing. In the above example, both serial
interfaces are on a Matrox Solios board.
From the listing of the required serial interface, establish the
interface's address. The address of the serial interface is listed on
the line that starts with "I/O ports". In the listing above, the address
of the second serial interface is ccf8.
2. Execute the following command:
# cat /proc/tty/driver/serial
This will list the usable ttyS ports on your computer. For example:
0: uart:16550A port:000003F8 irq:4 tx:1772 rx:0 RTS|DTR|DSR
1: uart:16550A port:0000CCF0 irq:17 tx:24 rx:0 CTS|DSR|CD
2: uart:16550A port:0000CCF8 irq:17 tx:24 rx:0 CTS|DSR|CD
3: uart:unknown port:000002E8 irq:3
The first number indicates the ttyS port that the line describes (for
example, the first line describes ttyS0). The number after "port:"
indicates the address of the serial interface mapped to the ttyS port.
In the listing above, ttyS1 and ttyS2 correspond to the first (0xCCF0)
and second (0xCCF8) serial interfaces on the Matrox Solios board,
respectively.
If there are enough ttyS ports, the address of the required board's
serial interface should be listed. Take note of the ttyS port to which
this address is mapped and use this port to access the serial
interface.
3. If all ttyS ports are mapped to devices other than the required board's
serial interface, you can either:
- Increase the limit on the number of serial interfaces that your Linux
kernel can access, and recompile the kernel.
- Free a ttyS port and then remap it to your Matrox board's
serial interface.
To increase the limit on the number of serial interfaces that your Linux
kernel can access and then use the required board's serial interface:
a) Confirm that your Linux kernel was compiled with too few usable
ttyS ports (usually 4). Look for CONFIG_SERIAL_8250_RUNTIME_UARTS
in the config file of your running kernel, usually found under
/boot/config-`uname -r` or /boot/.config.
b) If this limit is lower than the number of required serial ports,
you must recompile your kernel with a higher limit. Refer to
your Linux documentation for instructions on how to do so.
c) List the usable ttyS ports on your computer as you did above. The
address of the required board's serial interface should now be
listed, if there are enough ttyS ports. Take note of the ttyS port to
which this address is mapped and use this port to access the serial
interface.
To free a ttyS port and then use it to access the required board's
serial interface:
a) Disable the serial interface currently mapped to the required ttyS
port. To do so, add 'reserve=0xXXXX,YY' to the vmlinux line of the
grub bootloader configuration file. Replace 0xXXXX with the address
of the serial interface to disable (for example, 0xCCF8) and replace
YY with the size (in bytes) of the I/O address space of the UART
controlling the serial interface (for example, for a normal 16550
UART, it is 8). For example:
kernel (hd1,0)/vmlinuz root=/dev/hdb8 vga=0x317 selinux=0 splash=silent resume=/dev/hdb5 desktop elevator=as showopts reserve=0xCCF8,8
b) Reboot your computer. The serial interface at the specified address
will be disabled and the ttyS port will be remapped to the next
serial interface, which hopefully is the Matrox serial interface
that you want to use.
c) List the usable ttyS ports on your computer as you did above. The
address of the required board's serial interface should now be
listed, if it was mapped to ttyS port that was freed. Use this ttyS
port to access the serial interface.
14. Firewall
* Some MIL network services require changes to the firewall settings to
function correctly. Unlike Windows, the Linux MIL installer doesn't
change the firewall rules, therefore the user must to do it manually
using the iptables utility or a system configuration tool.
Here is a list of MIL services and default TCP/IP ports (to be opened):
Distributed MIL Master/Slave 57010
Distributed MIL Slave (Multiple clusters) 57000 to 57009
MIL Monitoring 57020
MIL Cluster Manager 57030
15. Using MIL in a deamon/service
MIL applications need some environment variables. These are normally provided by the mil.sh
script installed by the MIL setup program.
Services/deamons run in an environ with a minimal set of environment variables and it may not
be possible to use MIL in that case by default.
15.1 Services started using initd
The init script of the service must source the /etc/profile.d/mil.sh file.
15.2 Services started using systemd
The following entry must be added to the [Service] section of the systemd config file of the service
EnvironmentFile=/etc/environment