Raspberry Pi

µGFX applications can run natively (without emulation/simulation) on any Linux system. This means that µGFX can run without any problems on a Raspberry Pi. This is a step-by-step setup & configuration guide that will explain everything necessary to run µGFX on a Raspberry Pi.

Introduction

The most common question asked in this context is why to run µGFX on an embedded Linux device. Today's single board computers running Linux are powerful enough to run X and a complete desktop environment. Therefore, GUI applications can be written using desktop GUI frameworks such as Qt or GTK. Running µGFX instead on such as system has two main, but very important advantages:

• Dependencies: Installing X, a desktop environment all required desktop applications and the required libraries to run custom built desktop applications pull many dependencies. This makes the system become heavy and bloated. However, the most important issue is that all these dependencies need to be maintainer. For example, when performing as sytem update, more components have to be tested to ensure the continuous and uninterrupted functioning of the device. This becomes even more important for mission critical equipmenet such as medical devices where each component needs to be audited and certified individually. Running µGFX on such a device vastly reduces the complexity of the system and therefore allows to built more stable & cheaper devices featuring a GUI while still running on a powerful Linux based system.
• Resource requiremenets: ToDo
• Security: ToDo

Used utilities

The following utilities will be used in this tutorial:

• Raspberry Pi 3 Model B
• Raspberry Pi 7" Touchscreen Display
• NOOBS (Raspbian) operating system

However, this guide has been kept as generic as possible. Following the same steps should allow running µGFX on any embedded Linux system.

Prerequisites

It is important that the used Linux kernel has been compiled with framebuffer support. With the latest version of Raspbian (state of 2016-08-23) this is the case. Therefore, we don't need to modify anything. If your Linux distribution doesn't come with a Linux kernel with enabled framebuffer support, please consult the corresponding documentation on how to enable it.

If your Linux kernel comes with built-in framebuffer support, you should see the framebuffer device under /dev/fb0, /dev/fb/0 or similar.

For more information about the Linux framebuffer, please see Linux Framebuffer.

Disabling X

For simplicity, we are using the pre-configured Raspbian Linux distribution in this tutorial. That distribution comes with X and and entire desktop environment. It is configured in such a way that X always starts automatically. However, X blocks the access to the framebuffer. Therefore, we first have to manually disable X before we can continue. The easiest way of doing this is simply removing the X from auto-start. This is process is different for every Linux distribution. In case of Raspbian we can use the raspi-config tool to disable X:

raspi-config  --->  Boot Options --->  Console (Text console, requires user to login)

However, if you'd like to keep your system as small as possible (in which case you probably don't want to start off with Raspbian in first place), you can just completely remove X from your system. See here for instructions.

Setting up the environment

To keep this tutorial as simple as possible, we will compile the µGFX application directly on the target hardware (Raspberri Pi in this case). However, it is still possible to develop the actual µGFX application on a desktop computer for convenience, as the entire µGFX library is completely portable. Please refer to the corresponding guides to learn how to compile a µGFX application as a native application for Windows, Linux or OS X.

It is also possible to cross-compile the application for the target hardware on a desktop computer. However, that process will not be part of this guide.

Compiler

The easiest way to compile a µGFX application on the a Linux based embedded system is using GCC. The Raspbian distribution already comes with GCC pre-installed. Please refer to your distribution's documentation to learn how to install GCC.

µGFX library

A copy of the µGFX library can be obtained either as a ZIP file (stable release) or by cloning the official Git repository. Please refer to the Getting Started Guide for further instructions on how to downloading the µGFX library.

In this tutorial, we simply clone the git repository. Git is also part of the pre-installed packages of the Raspbian distribution:

cd ~/Documents
mkdir -p projects/resources
cd projects
git clone https://git.ugfx.io/ugfx/ugfx resources/ugfx

Note that you can setup your folder structure however you like.

Creating a project

After ensuring that the used Linux kernel comes with framebuffer support, installing GCC and downloading the µGFX library it's time to create a µGFX project.

cd ~/Documents/projects
mkdir hello_world

For the first test, the basic display test demo will be used that can be found under modules/gdisp/basics.

Troubleshooting

The most common issues are:

• The Linux kernel you are using has not been compiled with framebuffer support. (See Prerequisites).
• The framebuffer device is not accessible through one of the standard paths. (See Linux Framebuffer).
• The user executing the µGFX application doesn't have the permission required to access the framebuffer device. (See Linux Framebuffer).
• Another application (usually the X Server) already uses, and therefore blocks, the framebuffer. (See Prerequisites).