The Wandboard comes in several different models and atleast the (original) Quad version is officially supported by Debian. This means you'll find instructions on how to get started with it in the official Debian Installer documentation. This page is intended to gather quick-start information and other practical info for the impatient reader.

Why installer, why not random image

It's very common and likely the first hit you see when googling Wandboard and Debian is a page describing where you can download an already existing SD-card image. It likely also tells you the existing users and passwords in the image. Why is it a bad idea to use these? Well primarily there's no easy way to verify these images aren't full of backdoors or other malicious contents. You may choose to trust them, but if you want to be more on the safe side then you should use official Debian software and that means either using the installer or manually constructing an sd-card image from scratch using debootstrap to build a rootfs and then carefully placing the bootloader, kernel etc at the right offsets. The recommendation for the easiest and safest route is to use the official Debian Installer, see below.



Downloading installer

The debian installer documentation chapter 5.1.5. Using pre-built SD-card images with the installer is one of the quickest ways to get started. Download these files from the download area :

Once you have there files you need to uncompress and combine them to generate a complete image:

zcat firmware.Wandboard_Quad.img.gz partition.img.gz > debian-installer-wandboard.img

Write installer to sd-card

Insert SD-card in Linux computer. Look up which device just appeared in /dev/sd*. (In this guide we'll write /dev/sdX which you should replace with your sd-card device.)

Overwrite the data on the sd-card with the installer:

sudo dd if=debian-installer-wandboard.img of=/dev/sdX bs=1M

Make sure data is completely written to card (three times for superstition):

sudo sync ;
sudo sync ;
sudo sync

Starting installation

Hook up the wandboard serial port via null-modem cable to your computer where you'll be running Putty (or equivalent) to get serial console access. Also hook up network cable for internet connection. And make sure to put the SD-card in the right slot. There are two card slots, one on the carrier board and one on the smaller main board. Use the one on the smaller main board. Finally hook up the 5V power cable and you should be seeing text appear in your serial console program.

We assume you're familiar with the debian installer which will guide you through the installation. Just follow the guide.

Graphical Environment

Most of the needed parts should be reverse engineered by now to have a fully libre graphics stack running on Wandboard.

There are still some issues with this in Debian though that makes it not work "out of the box". This section intends to document missing parts and possible workarounds.

xorg driver

The xorg video driver needed is called xf86-video-armada. General modesetting driver is not enough (why?).

TODO: This driver has not yet been packaged for debian!

The upstream repository is located at http://git.arm.linux.org.uk/cgit/xf86-video-armada.git/


The graphics stack parts for 3d on the Wandboard was first merged in mesa 17(-rc). You will also need the libdrm parts that first appeared in 2.4.74-2 (see 852685).

Newer mesa and libdrm versions are available in Debian Testing/Buster.

They install fine on a stretch system. This can be done without upgrading anything else by running the following commands (which will add testing repo, but give it lower priority than the stable repo to only install packages from testing when apt is explicitly told to do so):

# Make sure 'testing' (any others) have lower priority than 'stable'.
# This allows us to cherry-pick using 'apt install foobar/testing'
# without the entire installation being upraded on 'apt upgrade'.
# See 'man apt_preferences' section 'Tracking a "STABLE" distribution'.

echo 'Explanation: Uninstall or do not install any Debian-originated
Explanation: package versions other than those in the stable distro
Package: *
Pin: release a=stable
Pin-Priority: 900

Package: *
Pin: release o=Debian
Pin-Priority: -10' | sudo tee /etc/apt/preferences.d/lower-testing.pref

# add 'testing' repository.
echo 'deb http://deb.debian.org/debian testing main' | sudo tee /etc/apt/sources.list.d/testing.list

# fetch package lists.
sudo apt update

# upgrade all currently installed mesa packages to version from testing.
dpkg -l 'libdrm*' '*mesa*' | awk '/^ii/{print $2}' | xargs sudo apt install -t testing -y


Since mesa 17.2 it should be possible to run wayland. For more info see:


The continuous memory allocator used by the graphics drivers needs a memory chuck to use. This is not enabled by default in Debian and you will need to set up your system to pass the cma= kernel cmdline option, eg.:


Without the above you might see failures like:

[   64.088359] imx-drm display-subsystem: failed to allocate buffer with size 7962624

(Once 884375 is fixed it should be possible to extend uboot boot script via:  echo 'setenv bootargs ${bootargs} cma=256M' | sudo tee /etc/flash-kernel/ubootenv.d/cma  && sudo flash-kernel  )


GNOME is one of the few desktops that offer a (tech preview) Wayland session in Stretch and thus would sound like an interesting candidate to test. Unfortunately mozjs24 is broken on arm, which means gnome-shell will not work and thus also gdm will not work.

See 848190

On 2017-12-14 Debian Buster (currently 'testing') was tested and running GNOME on Wandboard almost worked right out of the box. (In Buster the GNOME session uses Wayland by default instead of Xorg.) The only change needed was reserving contiguous memory, see the 'cma' section above.