Page Comparison

This document is a guideline how to get support for Basler MIP-CSI camera for the i.MX 8M Mini based congatec module #051204 SMX8-Mini/Quad-4G eMMC16 DP. The guide describes how to download and install necessary tools and drivers to Congates Linux distribution based on Yocto project.
The first section contains information how to get supporting software packages. The second section describes how to incorporate camera support to Yocto build environment. The third section provides quick user guide for Basler camera supporting software and the last section describes how to build device trees for other i.MX 8M Mini modules.

1. Basler Camera Support Download Instructions

1.1 Linux Yocto

Congatec software package supporting i.MX 8M Mini modules is based on Yocto Project Linux distribution. Available Yocto distributions are listed in the table bellow. It is recommended to download specific version of manifest.

Please follow instructions in Yocto BSP guide to download and install necessary tools and Yocto source tree.

1.2 Congatec MIPI-CSI Supporting Package for Basler Camera

To enable Basler camera support it is necessary to download additional Yocto meta data layers. The first layer "meta-basler-cgt" provided by Congatec contains kernel driver, kernel patches and configuration updates. Suported Yocto BSP are listed in the table bellow together with related GIT branches and commit SHA hashes.
The branch is referenced as <congatec-branch> and the SHA hash is referenced as <commit-SHA>.

The directory containing downloaded Yocto project source is referenced as ~/<yocto-dir>

Meta data source tree that collect all recipes needed to build final image is located in subdirectory: ~/<yocto-dir>/sources. Balser camera supporting yocto meta data layers must be stored in this directory.

This is an example how to add meta-basler-cgt layer to Yocto:

For latest version of meta-basler-cgt:

	$ cd ~/<yocto-dir>/sources 
	$ git clone <https://git.congatec.com/arm-nxp/imx8-family/yocto/meta-basler-cgt>
	$ cd meta-basler-cgt
	$ git checkout --track origin/<congatec-branch>

And for partikular version, additoinally this command:

	$ git checkout <commit-SHA> 

1.3 Basler Camera Supporting Package

Basler camera utilities - can be downloaded from Basler web pages. The name of supporting software package is Camera Enablement Package for NXP®s i.MX8 applications processor series and approppriate links are in the table bellow.
Note: To download Basler utilities it is necessary to register on Basler website and accept license terms.

Store the Basler supporting in <yocto-dir>/sources directory and unpack it.
Note: supposing that package format is tar gzip

	$ cd <yocto-dir>/sources
	$ tar -xzf <package-name>.tar.gz 

2. Build Instructions

2.1 Configuration of the Build Directory and Environment

Downloaded Yocto source contains ....-setup-release.sh script (depending on Yocto version). This script prepares and configures build environment.
To make build process easier Congatec Basler Camera supporting package contains updated version setup script that is located in ~/<yocto-dir>/sources/meta-basler-cgt. The name of this script depends on Yocto version (listed in the table bellow).

Update link to ....-setup-release.sh :

	$ cd <yocto-dir>
	$ ln -s ./sources/meta-basler-cgt/<env-setup-script-name> <env-setup-script-name>

An example for Yocto 3.0:

	$ cd <yocto-dir>
	$ ln -s ./sources/meta-basler-cgt/imx-setup-release.sh imx-setup-release.sh

Now it is possible to setup environment:

	$ cd <yocto-dir>
	$ MACHINE='imx8mm-cgt-sx8m-basler' DISTRO=fsl-imx-xwayland source <env-setup-script-name> -b <build-dir>
	[ ! ] EULA accept needed for next step.

The script takes three inputs in this example - machine the build is being made for (variable MACHINE), distribution to use (variable DISTRO) and name of the build directory (the -b parameter).

2.1 Image Build

To build the image launch the Bitbake tool with name of image. Only supported image for Congates Basler demo is cgt-image-validation-imx-basler

	$ bitbake cgt-image-validation-imx-basler

The build process takes several hours depending on the build hardware.

2.2 Images

After the bitbake finishes, the following files can be found in the ~/<yocto-dir>/<build-dir>/tmp/deploy/images/imx8mm-cgt-sx8m-basler/ subdirectory of the build folder. The name of final SD card image differs in each Yocto version:

3. Quick User Guide

Congatec Yocto BSP Linux boots (in default configuration) graphical environment - Weston. Basler demo build contains additionally a launcher icon for Basler Pylon demo application. The icon for Pylon application is visible on the top left corner just beside launcher for Weston terminal. To launch the Pylon application click once to the camera icon.

...

After a while the screen of Pylon application is opened. Pylon applicaton start with greeting window that contains useful notes about application and updates. Close this window to continue.

...

Select your camera in the list on the top left listing window and click to red power button on top left side - follow arrows.

...

Setup of camera hardware takes several seconds. After camera is activated, camera control menu is unshaded. Click to the button with camera symbol. The output of the camera will be showed on right window.

...

4. Adjustments

To provide support for other Congatec i.MX 8M Mini modules it is necessary to change device kernel tree configuration.
Kernel sources can be found inside Yocto build tree at location:
~/<yocto-dir>/<build-dir>/tmp/work/imx8mm_cgt_basler-poky-linux/linux-congatec/<kernel-version>/git
To build device tree for the kernel it is necessary to install device tree compiler.

	sudo apt-get install device-tree-compiler

Device tree structure depends on Yocto version. Next sections describes how to adjust and compile device tree for supported Yocto.
Compiled device tree file basler-demo.dtb need to be coppied to SD card "boot" partition.
U-boot needs to be reconfigured for new DTB. To do that interrupt boot sequence inside ubuoot. Then update kernel DTB setting. The guide how to work with U-boot bootloader is at: i.MX 8M Mini Bootloader

	$ env set fdt_file basler-demo.dtb
	$ saveenv
	$ boot

4.1 DTB for Yocto 2.5 (Sumo)

The location of kernel source code is: ~/<yocto-dir>/<build-dir>/tmp/work/imx8mm_cgt_basler-poky-linux/linux-congatec/4.14.98-r0/git

Congatec provides several predefined device trees for diferrent display configuration:

To change dtb it is good practice to start with existing file - imx8mm-cgtsx8m-basler-camera-csi0-2ch.dts which contains a configuration for Basler camera. Copy this file to the same directory with diferrent name - referrenced as <DT-file-name>.dts.

	cd ~/<yocto-dir>/<build-dir>/tmp/work/imx8mm_cgt_basler-poky-linux/linux-congatec/4.14.98-r0/git
	cp arch/arm64/boot/dts/congatec/imx8mm-cgtsx8m-basler-camera-csi0-2ch.dts arch/arm64/boot/dts/congatec/<DT-file-name>.dts

Edit arch/arm64/boot/dts/congatec/<DT-file-name>.dts:
Remove or update display configuration node:

&i2c4 {
      dpbridge: sn65dsi86@2d {
            dp,use-edid-data;
      };
};

DTS file with removed display configuration part uses U-boot to configure display type and resolution. Display type is selected according to i.MX 8M Mini board version, resolution is set to default and could be updated manualy. Refer to the guide:
conga-SMX8-Mini Video Output.

Then compile device tree source and save the resulting DTB file to SD card boot partition. Finaly update fdt_file variable in U-boot shell.

	cpp -nostdinc -I include -undef -x assembler-with-cpp arch/arm64/boot/dts/congatec/<DT-file-name> > temporary.dts
	dtc -O dtb -o basler-demo.dtb -I dts temporary.dts 

4.2 DTB for Yocto 3.0 (Zeus)

Kernel sources can be found inside Yocto build tree at location:
~/<yocto-dir>/<build-dir>/tmp/work/imx8mm_cgt_basler-poky-linux/linux-congatec/linux-congatec-sx8m_5.4_r0/git
<br>
Congatec provides several predefined device trees for diferrent display configuration:

To change dtb it is good practice to start with existing file - imx8mm-cgtsx8m-basler-camera-csi0-2ch.dts which contains a configuration for Basler camera. Copy this file to the same directory with diferrent name - referrenced as <DT-file-name>.dts.

	cd ~/<yocto-dir>/<build-dir>/tmp/work/imx8mm_cgt_basler-poky-linux/linux-congatec/5.4-r0/git
	cp arch/arm64/boot/dts/congatec/<DT-file-name>.dts arch/arm64/boot/dts/congatec/<DT-file-name>.dts

Edit arch/arm64/boot/dts/congatec/<DT-file-name>.dts:
To use one of pre-defined display configuration change include directive at the top of <DT-file-name.>dts file to one of predefined dts files. If Generad DTB is included, resolution is set by U-boot using autodetection or manual setting. You can also add a section with custom resolution definition to this file and include General DTB. Refer to the guide:
conga-SMX8-Mini Video Output.

/*
 *  Devicetree for a Basler camera on a iMX8M Mini
 *
 *  Created by Hauke Wulff on 23.07.19.
 *  Copyright (c) 2019 Basler AG. All rights reserved.
 *
 */

#include "imx8mm-cgtsx8m-dp.dts"
......

Example of custom definition:

/dts-v1/;

#include "imx8mm-cgtsx8m.dts"

/ {
	dpdisplay {
		status = "okay";
		/delete-property/ use-uboot-settings;

		panel-timing {
			clock-frequency = <110011001>;
			hactive = <1280>;
			vactive = <1024>;
			hsync-len = <184>;
			hfront-porch = <48>;
			hback-porch = <200>;
			vsync-len = <3>;
			vfront-porch = <1>;
			vback-porch = <26>;
		};
	};
};

&i2c4 {
	dp-bridge@2d {
		status = "okay";
		hpd-enable;
	};
};

....... 

Then compile device tree source and save the resulting DTB file to SD card boot partition. Finaly update fdt_file variable in U-boot shell.

	sudo apt-get install device-tree-compiler

	cd ~/<yocto-dir>/<build-dir>/tmp/work/imx8mm_cgt_basler-poky-linux/linux-congatec/5.4-r0/git
	cpp -nostdinc -I include -undef -x assembler-with-cpp arch/arm64/boot/dts/congatec/<DT-file-name>.dts > temporary.dts
	dtc -O dtb -o basler-demo.dtb -I dts temporary.dts