Yocto Linux
User Guide
REV. January 2023
Tetra
(VL-EPC-2700)
Arm* i.MX6 Single Board Computer
with Gigabit Ethernet, Video, USB,
Serial I/O, Digital I/O, CAN Bus, SPI,
I2C , Mini PCIe and SATA or mSATA
ii Tetra (VL-EPC-2700) User’s Guide
WWW.VERSALOGIC.COM
12100 SW Tualatin Road
Tualatin, OR 97062-7341
(503) 747-2261
Fax (971) 224-4708
Copyright © 2019-2020 VersaLogic Corp. All rights reserved.
Notice:
Although every effort has been made to ensure this document is error-free, VersaLogic makes no representations or
warranties with respect to this product and specifically disclaims any implied warranties of merchantability or fitness
for any particular purpose.
VersaLogic reserves the right to revise this product and associated documentation at any time without obligation to
notify anyone of such changes.
* Other names and brands may be claimed as the property of others.
Tetra (VL-EPC-2700) User’s Guide iii
Product Release Notes
Rev 1.00 Production release for the Rev 1.0 board
Rev 1.01 Updated CBR-0504 information
Rev 1.05 Added GPIO pinout table on page 47
Rev 1.10 Updated commands on page 20
Rev 1.15 Updated commands on page 19
Added “Building Kernel 5.4.3 with Yocto’s Zeus release” section (page 42)
Rev 1.20 Updated section head on page 19. Updated repo init command on page 19
Rev 1.30 Updated primary build example steps to Yocto Kirkstone version
Support Page
The Tetra Product Page contains additional information and resources for this product including:
Operating system information and software drivers
Data sheets and manufacturers’ links for chips used in this product
U-Boot information and upgrades
VersaTech KnowledgeBase
The VersaTech KnowledgeBase contains useful technical information about VersaLogic products, along
with product advisories.
Customer Support
If you are unable to solve a problem after reading this manual, visiting the product support page,
contact VersaLogic Technical Support at (503) 747-2261. VersaLogic technical support are also available
via e-mail at [email protected].
Repair Service
If your product requires service, you must obtain a Returned Material Authorization (RMA) number by calling
503-747-2261. Be ready to provide the following information:
Your name, the name of your company, your phone number, and e-mail address
The name of a technician or engineer that can be contacted if any questions arise
The quantity of items being returned
iv Tetra (VL-EPC-2700) User’s Guide
The model and serial number (barcode) of each item
A detailed description of the problem
Steps you have taken to resolve or recreate the problem
The return shipping address
Warranty Repair: All parts and labor charges are covered, including return shipping charges
for UPS Ground delivery to United States addresses.
Non-warranty Repair: All approved non-warranty repairs are subject to diagnosis and labor charges,
parts charges and return shipping fees. Specify the shipping method you prefer and provide a purchase
order number for invoicing the repair.
Note: Mark the RMA number clearly on the outside of the box before returning.
Tetra (VL-EPC-2700) User’s Guide v
Contents
Introduction.................................................................................................................................................. 7
Quick Start .................................................................................................................................... 8
EPC-2700 Tetra Hardware Introduction .................................................................................. 8
Setting up Tetra for the First Time ........................................................................................... 8
Booting up Tetra for the First Time ......................................................................................... 9
Tetra Features and Commands ............................................................................................................ 12
USB Support ............................................................................................................................... 12
Video Support ............................................................................................................................ 12
Storage Support ......................................................................................................................... 12
Multimedia Support ................................................................................................................... 13
Multimedia Playback ............................................................................................................. 13
Audio Recording ..................................................................................................................... 14
Video Capture ........................................................................................................................ 15
Setting up the Development Host ........................................................................................................ 17
Host Packages ............................................................................................................................ 17
Setting up the Repo Utility ......................................................................................................... 18
Building the Tetra Image ........................................................................................................................ 21
Setting up Build Configurations ................................................................................................. 21
Patching Build Configuration ..................................................................................................... 22
Creating the Target Image ......................................................................................................... 23
Deploying the Image to Tetra ................................................................................................................ 25
Deploying to a MicroSD card ..................................................................................................... 25
Deploying to a SATA Disk ........................................................................................................... 25
Preparing the SATA Disk ........................................................................................................ 25
Configuring U-Boot Environment Variables ........................................................................... 29
Booting from the Network ......................................................................................................... 30
Configuring the Host PC ......................................................................................................... 30
Configuring U-Boot Environment Variables ........................................................................... 31
vi Tetra (VL-EPC-2700) User’s Guide
Deploying to eMMC ................................................................................................................... 33
Creating a Sample Application ............................................................................................................. 34
Standalone Application .............................................................................................................. 34
Adding an Application to the Image .......................................................................................... 35
Customizing the Image ........................................................................................................................... 38
Adding or Removing Packages ................................................................................................... 38
Modifying Linux Kernel Configuration ....................................................................................... 38
Updating U-boot ........................................................................................................................ 41
Building Kernel 5.4.3 with Yocto’s Zeus release ........................................................................ 43
Advanced Features and Commands ................................................................................................... 45
Sensors ....................................................................................................................................... 45
Video Output Selection .............................................................................................................. 46
LVDS Panel Backlight .................................................................................................................. 47
CAN Network.............................................................................................................................. 47
I2C Commands ............................................................................................................................ 48
GPIO ........................................................................................................................................... 49
References ................................................................................................................................. 50
Figures
Figure 1. Major Components and Connectors ................................................................................................. 8
Figure 2. Boot Messages ............................................................................................................................... 10
Figure 3. System Login ................................................................................................................................. 11
Figure 4. X11 Desktop .................................................................................................................................. 11
Figure 5. Opening the Terminal .................................................................................................................... 13
Figure 6. Alsamixer Playback ....................................................................................................................... 14
Figure 7. Alsamixer Recording ..................................................................................................................... 14
Figure 8. Video Capture ................................................................................................................................ 15
Figure 9. SDB Drive and Partitions ............................................................................................................... 26
Figure 10. The Netboot Screen ...................................................................................................................... 32
Figure 11. The Firefox Icon .......................................................................................................................... 38
Figure 12. Kernel Configuration ................................................................................................................... 39
Figure 13. Selecting Device Drivers ............................................................................................................. 40
Figure 14. Selecting MemoryStick Support .................................................................................................. 41
Tables
Table 1. Yocto Project Images ................................................................................................................. 23
Table 2. Partition Sizes .............................................................................................................................. 26
Table 3. GPIO Pinouts ............................................................................................................................... 49
Introduction
Tetra (VL-EPC-2700) User’s Guide 7
Introduction
The VersaLogic EPC-2700 Tetra is an Arm based SBC. This board includes an NXP Arm Cortex-
A9 Quad processor and many standard components which will be described in more details later.
The recommended OS is Yocto* Linux which is an open-source collaboration focused on
embedded Linux OS development.
This guide covers several topics:
Provides an overview of the Tetra and will guide the user in setting up the initial boot.
Instructions in setting up a Yocto Linux development environment to build the OS image
and develop a simple application.
Deploying the OS and application to the Tetra for execution.
This guide is not intended to provide significant amount of background information on the NXP
Arm Cortex-A9* Quad processor or Yocto Linux. The commands used are intended as examples;
it is possible that there are also other Linux commands which will achieve the same results. The
user is encouraged to follow the links in the reference section to learn more.
This guide assumes the user has basic knowledge of the Linux operating system and is able to
obtain the necessary hardware and software that are required to complete the tasks outlined in
this guide.
Note: The NXP Arm Cortex-A9 Quad processor was originally made by Freescale. Freescale
was purchased by NXP, but much of the documentation still retains the name Freescale.
Introduction
8 Tetra (VL-EPC-2700) User’s Guide
Quick Start
EPC-2700 Tetra Hardware Introduction
Detailed hardware description is available in the Tetra hardware reference manual, but here is
some essential information to assist in quickly setting up the board.
The following diagram shows the major components of a Tetra:
Figure 1. Major Components and Connectors
The Tetra will be shipped with power supply and a cable kit, which includes most of the required
cables for the various ports shown above. A micro SD card with a demo image of the Yocto Linux
OS is also shipped with the cable kit.
Setting up Tetra for the First Time
At a minimum, the following ports and devices should be connected before booting up Tetra for
the first time:
1. J1 – USBx2: connect USB mouse and keyboard to the USB ports. There are two options
to do this:
Option one is to connect a USB hub to the bottom port and then connect both mouse
and keyboard to the hub.
Introduction
Tetra (VL-EPC-2700) User’s Guide 9
2. Option two is to set the top USB port to host mode (install the V2 jumper on pins 1-2) and
then use both on board ports for mouse and keyboard.
3. J4 – MicroSD: install the MicroSD card in this socket. The hinge lid slides down toward
J13 to unlock, and then the hinge lid rotates open toward J13. Please take care not to
damage parts with the lid or tools in this process, and never attempt to hot plug a
MicroSD card on this board. The space is tight so please be careful not to bend the pins
or cause other damage to surrounding components.
4. J5 – Ethernet: connect a network cable (RJ45) to the Ethernet port.
5. J6 – HDMI: connect a HDMI monitor to this port. If a HDMI monitor is not available, then
a HDMI to VGA adapter is needed to connect to a VGA monitor. An adapter may require
an external power source as the HDMI connector 5V output is limited to 55 mA.
6. J16 – COM1: connect the CBR-0504 adapter for a RS-232 serial port, and then connect
a serial cable (null modem) to a PC COM port. Make sure that the terminal for the COM
port is using the baud rate of 115200, 8-bit data, 1 bit stop, no parity or flow control. Use
a terminal emulator such as PuTTY for console access to the Tetra.
Booting up Tetra for the First Time
At this point, the Tetra is ready to boot for the first time. Connect the power cable to the board
and watch the serial console and you should see the boot messages displayed. Note that instead
of BIOS, Tetra uses a different boot loader called U-Boot. Unless auto boot is stopped by
pressing a key on the keyboard, U-Boot will load Yocto Linux from the MicroSD card.
Introduction
10 Tetra (VL-EPC-2700) User’s Guide
Figure 2. Boot Messages
Introduction
Tetra (VL-EPC-2700) User’s Guide 11
Once the system boots, a login prompt will be displayed. Login as root; no password is required.
Figure 3. System Login
If a monitor is connected to the HDMI port, then a basic X11 Desktop as shown below will be
displayed on the monitor.
Figure 4. X11 Desktop
12 Tetra (VL-EPC-2700) User’s Guide
Tetra Features and Commands
This section describes some of the built-in features on the Tetra board, along with Yocto Linux commands
used for the demo OS provided by VersaLogic.
USB Support
There are two USB ports on the Tetra that support standard USB 2.0 devices. The bottom USB port is set
to host mode, but the top USB OTG port is set to device mode by default per the storage of the V2
jumper. To change the top USB port to host mode, install the V2 jumper per Tetra on pins 1-2.
Video Support
Tetra provides a HDMI output and a LVDS output. Most standard monitors can use the HDMI port. The
LVDS port supports LVDS panels or standard VGA monitors via a LVDS to VGA adapter. Currently only
the Sharp LQ150X1LG91* panel is configured in the Linux device tree in the demo OS shipped with the
board. VersaLogic can configure additional panels for the demo OS if needed. However, it is expected
that the users will configure their own panel as part of their OS development. See section 10.2 for
instructions on how to select HDMI or LVDS output.
Storage Support
Tetra supports onboard storage devices such as MicroSD and eMMC, as well as external storage device
such as a SATA hard disk. Note that the EPC-2700-EDK-02A replaces the SATA connector and Mini
PCIe interface with an mSATA interface to the J3-Minicard socket, so the SATA device connection would
be available via mSATA.
The fdisk command can be used to list all the storage devices that are currently attached, as shown in the
example below.
root@imx6qtetra:~# fdisk –l
…
[This is the MicroSD card installed in the onboard slot. ]
Disk /dev/mmcblk1: 3.8 GiB, 4008706048 bytes, 7829504 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x37aeca36
Device Boot Start End Sectors Size Id Type
/dev/mmcblk1p1 8192 24575 16384 8M c W95 FAT32 (LBA)
/dev/mmcblk1p2 24576 2834431 2809856 1.3G 83 Linux
[This is an external SATA disk connected via the SATA port.]
Disk /dev/sda: 149.1 GiB, 160041885696 bytes, 312581808 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
Tetra Features and Commands
Tetra (VL-EPC-2700) User’s Guide 13
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x64e8a864
Device Boot Start End Sectors Size Id Type
/dev/sda1 20480 1024000 1003521 490M 83 Linux
/dev/sda2 1228800 312581807 311353008 148.5G 83 Linux
Multimedia Support
Multimedia Playback
GStreamer* is the default multimedia framework on the Linux OS. gplay-1.0 is a command line tool built
on top of GStreamer that can be used to test basic playback. MP3, MP4, WAV and AVI file formats have
been verified on the Tetra.
To play back a multimedia file, first make sure a speaker or headphones are properly connected to the
J10 Audio port. Open a terminal from the X11 Desktop as seen below.
Figure 5. Opening the Terminal
Type the following command in the terminal window:
sh-4.3# gplay-1.0 <file name>
For MP3 and WAV files, command output should indicate that sound track is playing. For MP4 and AVI
files, a new window will also open displaying the video. If there is no sound during playback, check the
volume level by entering the alsamixer command in the terminal window and adjust the headphone
volume in the GUI using up or down arrow keys.
sh-4.3# alsamixer
Tetra Features and Commands
14 Tetra (VL-EPC-2700) User’s Guide
Figure 6. Alsamixer Playback
Audio Recording
To record audio on the Tetra connect a microphone or headset to J10 – Audio port. Adjust the recording
level in alsamixer to high to ensure that sound can be captured. The level can be adjusted downward
later to achieve the best result.
Figure 7. Alsamixer Recording
Tetra Features and Commands
Tetra (VL-EPC-2700) User’s Guide 15
Type the following command in the terminal window and speak into the microphone:
sh-4.3# arecord -r 48000 -f S16_LE -c 2 -d 10 testrecord.wav
Recording automatically stops after 10 seconds. Play back the recording using the gplay-1.0
command:
sh-4.3# gplay-1.0 testrecord.wav
Video Capture
Currently the only supported camera on the Tetra is the Raspberry Pi Camera v1.3. While the power is
off, connect the camera to the J9 – Camera port on the Tetra. Power on the system and execute the
following commands in a terminal window:
sh-4.3# echo 3 > /sys/bus/i2c/devices/2-0036/ov5647_mode
sh-4.3# gst-launch-1.0 v4l2src device="/dev/video0" ! video/x-
bayer,width=640,height=480 ! bayer2rgb ! videoconvert ! fbdevsink
A new window should pop up in the foreground displaying raw video that the camera is currently
capturing.
Figure 8. Video Capture
Tetra Features and Commands
16 Tetra (VL-EPC-2700) User’s Guide
Contact VersaLogic for additional information on modes available and the camera usage in general, or if
support is needed for a different camera.
17 Tetra (VL-EPC-2700) User’s Guide
Setting up the Development Host
With an understanding of the basics on Tetra, now it is time to dig deeper. This chapter begins the
discussion on how to build and customize the Yocto Linux OS running on Tetra.
A host PC or build server is required to setup the Yocto Linux development environment, which will be
used to create the Operating System that will run on the VersaLogic Tetra board.
There are a few minimum requirements for this system:
1. Hardware – a server machine will provide the best performance, but at least a mid-range desktop
PC is needed. Specifically, at least the following configuration:
2 GHz dual core processor
2 GB RAM (system memory)
120 GB of free disk space is required in order to install the OS and required packages, and to
build the target image. However, more disk space is highly recommended as multiple builds
during typical development cycle can consume the disk space quickly.
A monitor capable of 1024x768 screen resolution
Either a CD/DVD drive or a USB port for the installer media
A static IP address is recommended but not required
Internet access to download additional required software
2. Operating System – the recommended OS for the host PC is Ubuntu 20.04 (See the Reference
Section for download and reference links), which is the version currently supported for Tetra that
has been recommended by NXP and verified by VersaLogic. If the user decides to try a different
version or Linux distribution, then it is up to the user to get the Yocto Linux Project expected
behavior on the host PC, as well as making sure the packages and utilities described below are
compatible and can be installed correctly.
Host Packages
A Yocto Linux Project build requires that some prerequisite software packages be installed. Please use
the commands below to install these packages. Also note that in Ubuntu, the command sudo is typically
used to execute other commands with root privileges.
Install essential Yocto Project host packages:
sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential
chrpath socat cpio python python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping
python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 xterm rsync curl zstd lz4 libssl-dev
Setting up the Development Host
18 Tetra (VL-EPC-2700) User’s Guide
Setting up the Repo Utility
Git is a version control system for tracking changes in source code files and coordinating work on those
files among multiple developers. Repo is a tool built on top of Git that makes it easier to manage projects
that contain multiple repositories, which do not need to be on the same server. Repo complements very
well the layered nature of the Yocto Project, making it easier for users to add their own layers to the BSP.
To install the “repo” utility, follow these steps:
1. Create a bin folder in the home directory.
2. Add the following line to the .bashrc file to ensure that the ~/bin folder is in your PATH variable.
3. Apply the new path to the current login session.
Setting up the Development Host
Tetra (VL-EPC-2700) User’s Guide 19
Yocto Project Setup
Yocto Project, files used to build an image are stored in layers. Layers contain different types of
customizations and come from different sources. Some of the files in a layer are called recipes. Yocto
Project recipes contain the mechanism to retrieve source code, and to build and package a component.
The following list shows some of the layers used to build the Tetra image:
VersaLogic release layer
meta-versalogic
Yocto Project and NXP community layers
meta-freescale: provides support for the base and for i.MX ARM® reference boards.
meta-freescale-3rdparty: provides support for 3rd party and partner boards.
meta-freescale-distro: additional items to aid in development and exercise board capabilities.
meta-imx: NXP current and up to date support layer
meta-openembedded: Collection of layers for the OE-core universe. See
layers.openembedded.org/.
poky: basic Yocto Project items in Poky. See the Poky README for details.
meta-browser: provides several browsers.
meta-qt6: provides Qt6.
In order to download all the necessary files, first make sure that git is setup properly with the commands
below, which only need to be run once on the host PC.
The NXP Yocto Project BSP Release directory contains a "sources" directory which holds the recipes
used to build the image, as well as one or more build directories, and a set of scripts used to set up the
environment.
The recipes used to build the Tetra image come from VersaLogic, the Yocto Project community and NXP.
The Yocto Project layers are downloaded to the sources directory. This sets up the recipes that are
used to build the project. Follow the instructions below to download the Freescale Yocto Project
Community BSP recipe layers.
As an example, a directory called fsl-release-bsp is created for our project. Any name can be used
instead of this.
repo init -u https://github.com/nxp-imx/imx-manifest -b imx-linux-kirkstone -m imx-
5.15.32-2.0.0.xml
Setting up the Development Host
20 Tetra (VL-EPC-2700) User’s Guide
When this process completes, the source code is checked out into the directory fsl-release-
bsp/sources. You can perform repo synchronization periodically with the command repo sync to
update to the latest code. If errors occur during repo initialization, try deleting the .repo directory and
running the repo initialization command again.
Download the VersaLogic release layer and recipes for the Tetra board:
$ cd sources
$ git clone git://github.com/versalogic/meta-versalogic.git -b kirkstone
The VersaLogic layer provides U-boot 2022.04 and Linux ARM Kernel 5.15.32 forked from NXP’s
repository, and configured for the Zebra. NPX maintains their primary repository at the time of this writing
at:
https://github.com/nxp-imx/
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
Page is loading ...
/
