While building your next Internet-of-things (IoT) project, sometimes you get to a point where you need to run applications that are made to run on a screen, we call them graphical user interface (GUI) applications.
After multiple requests from our users, we decided to write a short tutorial explaining how you can run a desktop manager or a GUI application with balenaCloud
on any kind of display.
To get started, you will need an account for balenaCloud
. If you are new to the balena ecosystem, take a look at the introduction
first, as the initial setup of your account and provisioning a device is outside the scope of this guide.
This tutorial will set you up with an example project that runs a desktop manager so that you’re able to run GUI applications and display them on an LCD screen. The project is also designed to work on multiple devices such as a Raspberry Pi or an Intel NUC.
Downloading the application
To get started, go to the GitHub repository
and clone or download the project into your computer.
Clone or download then on the
Download ZIP button to get the files you will need. If you are already familiar with Git you can use
git clone in the same way you would usually do.
Pushing the code to the device
Let's first push the project code to the device without any changes to make sure everything works. Once you have the files on your computer, using the terminal, go to the directory you cloned or unzipped the files into and push the code to the device already connected to balenaCloud.
For this, we will use the balena cli
tool, where you can push the code by running
balena push <ApplicationName>
in the same folder as the project. You can read more about the CLI here
If everything worked OK, you'll see the magic unicorn 🦄:
Good job, things are looking promising!
In this project, we are demonstrating the use of a new feature of balenaCloud that allows you to target different device types and architectures with separate dockerfiles. If you check the project root folder, you will notice that there are two dockerfiles,
If you are running this project on a Raspberry Pi 3, the docker container will be created based on the
, which will install RASPBIAN
and use the PIXEL Desktop Manager. For all other devices, it will install and use XFCE Desktop Manager.
Multiple docker files
The multiple docker file feature works by scanning the folder for dockerfiles and matching the correct one with your application device type. For example, if you want to run a similar code base on two different device types, you could have one application configured for the Raspberry Pi 3 and another for the BeagleBone Black. By having two dockerfiles,
Dockerfile.beaglebone-black, when building the docker image, the system will choose the right configuration for each device. 🧙
In order to target a specific device type or architecture, the extension for the
must match BALENA_MACHINE_NAME
for device-type and BALENA_ARCH
for architecture. A list of the available values for each of these variables is available at https://www.balena.io/docs/reference/base-images/devicetypes/
The files are processed in the following order of preference:
After pushing the project to balenaCloud, it will download onto your device and if everything works as planned, you’ll be able to see the desktop manager on the screen, just like the Raspberry Pi example in the image below:
If you’re using an X86 device such as the Intel NUC, the project will deploy XFCE and look something like the below:
This project supports the use of a keyboard and mouse directly connected to the deployed devices in order to provide input to the GUI.
You now have a plain version of either the Raspbian Desktop or XFCE running on your device, it’s time to learn how to add new applications to it and also configure them to start automatically on boot!
The base project comes with just the bare minimum required to run the desktop manager. In order to add applications to your setup, you need to change the dockerfile so that they can be installed during the image build.
The easiest way to install applications to your project is by using
, where based on the docs
, you can use the command
as a shortcut, which additionally handles the clean up of any temporary installation files afterward. In this example, you can add an extra
at the end of
and add all the applications you need on the line underneath.
For example, if you want to run a terminal emulator such as
install_packages part of the dockerfile will be:
RUN install_packages xserver-xorg \
If you have any questions on this (or any other) step, please start a thread on our forums
where our team will be happy to help.
Running an application on boot
Depending on your project, you may want to start an application as soon as the desktop manager starts. Due to the differing window managers, the process to do this is slightly different depending on what device you’re using.
The first thing to do is edit
Dockerfile.template and uncomment the line
COPY autostart /etc/xdg/lxsession/LXDE-pi/autostart.
Next, edit the file
autostart. On the last line change
xterm to your desired application.
Below you can see the results of the example above where we start the
xterm application automatically when the device boots.
Other devices (e.g. X86 Intel NUC)
In other devices, to run an application on startup, you can edit the file
start_x86.sh and change the
startx to add the application you want to autostart, for example,
Rotating the screen
In case you need to rotate the screen, all you need to do is to open balenaCloud dashboard and add or edit environment variables.
When working with a Raspberry Pi, the configuration will vary if you are using a display connected via HDMI or via the LCD DSI Display Connector.
To configure the Raspberry Pi to use the HDMI connector, click on Device Configuration and at the bottom where it says CUSTOM CONFIGURATION VARIABLES, add new custom variables:
Now to rotate the display, you can use the variable called
BALENA_HOST_CONFIG_display_rotate with a value from 0 to 3 with (0, 90, 180 and 270 degrees).
LCD DSI Display Connector:
In case your display is attached to the DSI connector, you can add the custom variable
BALENA_HOST_CONFIG_lcd_rotate with a value from 0 to 3 which corresponds to 0, 90, 180 and 270 degrees.
Similar to the configuration above, go to
Device Variables and add a new variable called
ROTATE_DISPLAY with the values of
left which corresponds to 0, 90 180 and 270 degrees.
In this post, you saw how you can easily start a project that requires a desktop manager with balenaCloud
. Now it’s up to you to create an amazing project with it!
Thanks for reading! If you followed this tutorial we’d love to hear how it went, similarly, if you got stuck or have any questions, let us know in our forums at https://forums.balena.io
, on Twitter @balena_io
, on Instagram @balena_io
or on Facebook
. See you next time! ;)