Introduction
This article publishes a complete set of design files necessary to run the Linux desktop environment created targeting Terasic's DE25-Nano (equipped with Altera® Agilex™ 5 SoC FPGA). Please use it as a reference for verification using the evaluation board, proof of concept (PoC), or Linux environment setup.
For instructions on setting up the environment, please refer to the article below.
Reference material: Yocto Customization for SoC FPGA: How to Build Your Own Desktop Environment
1. Equipment and Development Environment
This section describes the tools, versions, and development machine requirements (OS) necessary to run the design demo.
1-1. Equipment
The equipment required to verify the sample design operation is as follows.
- ‘DE25-Nano Development and Education Board’ x 1
- USB Type-C cable: included with the board
- AC adapter: included with the board
- micro SD card (capacity 8GB or more, class 10 recommended): included with the board
- USB Type-C HUB (USB 2.0), USB keyboard/mouse x 1 each
- HDMI monitor (capable of displaying Full-HD 1920x1080 60p) x 1
- HDMI cable x 1
- [Optional] USB camera (general product compatible with Linux UVC) x 1
Note: Please prepare a USB HUB with enough ports according to the number of USB devices you will connect, such as keyboard, mouse, UVC camera, etc. Since the DE25-Nano USB ports are USB 2.0 specification, using a USB 3.x HUB will not improve performance.
1-2. Development Environment
Setup of the following tools is required. Please prepare the development machine (OS, etc.) according to the requirements supported by these tools (here, confirmed on Ubuntu 22.04 LTS environment).
- FPGA development tools (operation confirmed with Linux version of Version 25.3.1)
- Terminal software (TeraTerm, PuTTY, etc.)
Note: If you only write the pre-built image, a full installation of the FPGA development tools is not necessary. You can use Quartus® Prime Pro Edition Programmer and Tools.
Note: The FPGA development tools are available with a free license for Agilex™ 5 E-Series.
How to obtain the free license file for Quartus® Prime Pro Edition for Agilex™ 5 E development
2. Provided Files
The table below lists the files needed for the procedures introduced in this article.
| No. | File Name / Download Link | Overview |
Update Date / Version |
| [1] | sdimage_de25nano_xfce+mpv_QPDS25.3.1.zip | SD card image | 2026/3/12 |
| [2] |
de25nano_gsrdfb_QP25.3.1.jic de25nano_gsrdfb_QP25.3.1.sof |
FPGA configuration data （.jic / .sof） |
2026/3/12 |
| [3] | DE25-Nano_GSRDFB_QP25.3.1.qar | FPGA design project | 2026/3/12 |
| [4] | sources_2026.03_h.tgz | Bootloader/Linux source tree and build environment settings (Yocto configuration files) | 2026/3/12 |
3. Execution Procedure (Using Pre-built Image)
Using the pre-built image, you can easily verify the operation of the Linux desktop environment.
Please download the SD card image and FPGA configuration data from [1] and [2] in ‘2. Provided Files’ and proceed with the steps below.
3-1. Preparation / Board Setup
Set up the board as shown in the figure below. Since the DE25-Nano does not have a power switch, please do not plug the AC adapter into the outlet yet.
3-2. Preparing the micro SD Card
Unzip the .zip file from [1] in ‘2. Provided Files’ and write it to the micro SD card. After writing is complete, insert the card into the micro SD card slot on the back of the board.
Please refer to the following information for writing methods.
Reference material: How to create SD card image for SoC FPGA boot
- For Linux environment: 2-1. Support for Linux OS Environment > 2-1-2. Writing/Updating SD Card Images
- For Windows environment: 2-2. Working in Windows OS environment > 2-2-2. Writing the Base SD Card Image
3-3. Writing FPGA Configuration Data
Using either the .jic or .sof from [2] in ‘2. Provided Files’, write the FPGA configuration data. Set the board's MSEL switch to JTAG mode (OFF-OFF-OFF), then plug in the AC adapter and power on the board.
Please refer to the following information for the writing method.
Reference material: Let's Try Agilex™ 3 FPGA - FPGA Configuration
Note: When using .jic, after writing is complete, turn off power, change the MSEL switch to ASx4 mode (ON-ON-OFF), and power on again. When using .sof, the HPS (Hard Processor System) boot starts immediately after writing is complete.
| Mode | MSEL Switch (SW5) | Setting Image |
| JTAG | OFF-OFF-OFF | |
| ASx4 | ON-ON-OFF |
3-4. Boot Start – Desktop Launch
Once writing of the FPGA configuration data is complete (when using .jic, power on again in ASx4 mode), booting will start automatically. After a while, Linux booting completes and a login prompt appears.
Note: During U-Boot execution, the HDMI TX device (ADV7513) is initialized, and screen output to HDMI starts. Also, the serial terminal after Linux boot is set to display on the HDMI monitor, so operation can be verified without using terminal software such as Teraterm.
From the Linux login prompt, log in with username: root (no password), then enter the following command to start the desktop.
root@agilex5:~# startxfce4
Note: Linux login and desktop start commands can be executed from either the terminal on the HDMI monitor or the serial terminal.
Tip: Besides the launcher menu at the center bottom of the desktop, there is Applications menu at the top right, and user switching and power-related menus available at the top left.
3-5. Optional: Connecting UVC Camera and Video Verification
By connecting a USB camera supporting UVC (USB Video Class), video input verification is also possible. Two player apps available for camera video verification are installed as follows.
- gst-play-1.0: Player included with Gstreamer, for simple video verification (resolution and format rely on camera defaults)
- mpv: A powerful yet lightweight open-source media player, format selection possible
Below are commands useful for verifying the UVC camera.
Note: The commands assume the connected UVC camera is recognized as /dev/video0.
3-5-1. Check Supported Resolutions and Formats of the Camera
sh-5.2# v4l2-ctl --list-formats-ext -d /dev/video0
3-5-2. Simple Video Verification from Camera (gst-play-1.0)
sh-5.2# gst-play-1.0 v4l2:///dev/video0
3-5-3. Video Verification Specifying Input Format (mpv)
- Example command line to run in yuyv422 format (uncompressed):
sh-5.2# mpv av://v4l2:/dev/video0 --demuxer-lavf-o=video_size=320x240,input_format=yuyv422,framerate=30 --hwdec=no --profile=low-latency --untimed --no-cache --cache=no --demuxer-readahead-secs=0 --vd-lavc-threads=1 --no-audio sh-5.2# mpv av://v4l2:/dev/video0 --demuxer-lavf-o=video_size=640x480,input_format=yuyv422,framerate=5 --hwdec=no --profile=low-latency --untimed --no-cache --cache=no --demuxer-readahead-secs=0 --vd-lavc-threads=1 --no-audio
- Example command line to run in mjpeg format (compressed):
sh-5.2# mpv av://v4l2:/dev/video0 --demuxer-lavf-o=video_size=1280x720,input_format=mjpeg,framerate=5 --hwdec=no --profile=low-latency --untimed --no-cache --cache=no --demuxer-readahead-secs=0 --vd-lavc-threads=1 --no-audio
- Example command line to suppress low latency and ignorable error messages:
sh-5.2# mpv --really-quiet av://v4l2:/dev/video0 --demuxer-lavf-o=video_size=640x480,input_format=mjpeg,framerate=15 --hwdec=no --profile=low-latency --untimed --no-cache --cache=no --demuxer-readahead-secs=0 --vd-lavc-threads=1 --no-audio
Note: High resolution/high fps display may fail with YUYV422 (uncompressed).
USB 2.0 (High-Speed) isochronous transfer theoretically has an upper limit of about 24MB/s, and actual throughput is lower due to overhead and bandwidth sharing with other devices. Therefore, selecting resolution/frame rate above a certain level may cause UVC bandwidth negotiation (alt setting selection/bandwidth reservation) to fail, resulting in no video display (frames not arriving).
The command examples for 320x240@30fps and 640x480@5fps have been confirmed to display video.
Note: The above command examples are also prepared in /home/root/command.txt on the target environment. You can copy and paste them if typing is troublesome.
Conclusion
This time, we introduced a desktop environment that can be verified on the DE25-Nano.
Besides the content introduced here, web browsers and software keyboards are also installed. We hope you will try and confirm things like camera display delay and desktop responsiveness by actually using it.
Note: This design does not support audio output to HDMI, so please be aware.
Supplement: About Open Source Software Included in This Sample
The SD card image includes open source software. Detailed license information with SPDX notation is described in the following file.
OSS-Notice-SPDX.txt