VersaLogic Tetra (VL-EPC-2700) User guide

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

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 ...

VersaLogic Tetra (VL-EPC-2700) User guide

VersaLogic Tetra (VL-EPC-2700) User guide

Related papers

Other documents