Make a web frame with Raspberry Pi in 30 minutes

Try balenaDash, a simple project to quickly get you up and running with a web frame to display family photos, dashboards, videos, and more.



balenaDash is a Raspberry Pi powered digital photo/web frame with a difference! It can display a fully GPU accelerated web page or app of your choosing and allow you to update that content from anywhere.

Here're some ideas to get you started:

balenaDash is a project you can build really quickly, and if you’re a bit of a hacker/maker like us, hopefully with hardware you already have lying around. If not, read on, as there's a good deal on a hardware bundle from a friendly supplier for you to check out too.

You can set up a Raspberry Pi, connect it to a dashboard allowing you to remotely manage it, and then install and build applications to run on it.

Hardware required

This project has been designed so that you don’t need any unusual hardware, and so hopefully you have everything you need to get started already.

You’re going to need:

  • Raspberry Pi 3B/3B+ (Note: this project will not work with the Pi Zero or older devices with < 1GB RAM; unfortunately that means the new 3A+ wont work either)
  • 16GB Micro-SD Card (we recommend Sandisk Extreme Pro SD cards)
  • Display (any Raspberry Pi display will work for this project, and you can use HDMI monitors too)
  • Micro-USB cable
  • Power supply
  • Case (optional)
  • Ability to flash your SD card (try balenaEtcher!)

This project makes a great gift once you’ve built it so if you haven’t got the hardware or just need more, our friends at PiSupply have created a couple of bundles that contain everything you need. You can get the full kit that includes everything you need or a barebones kit without the display.

Software required

All the code you need for this project is on GitHub, but you're going to need some basic tools to get the project loaded on to your Raspberry Pi.

You can use balenaCloud to push the project code to the Raspberry Pi, and then for subsequent updates and remote management of your balenaDash device.

Setup of the Raspberry Pi

This project has been built to be very simple in order to get you up and running quickly. It forms a basis for you to progress to developing your own projects.

There's a step-by-step guide to follow below but if you prefer, here's a screencast as well.

Step 1 - Sign up for a free balenaCloud account

The first thing to do is sign up for a free account. If you’ve already got a GitHub or Google account you can use that to login and bypass the signup process.

Sign up for free here

Step 2 - Create an application

This will take you to the dashboard for your newly created application, where you can move on to the next step and add your device.

Step 3 - Add a device and download the OS

Once your application has been created, you can setup and add a device within that application by clicking the 'add device' button. When you add a device you specify your device type, which in this case is a Raspberry Pi 3, and if you are connecting to a wireless network you can set your WiFI SSID and passphrase here too.

This process creates a customized image configured for your application and device type, and includes your network settings if you specified them.

Note: When you're first getting started, a development image will be most useful, as it permits a number of testing and troubleshooting features. More details on the differences between development and production images can be found here.

Step 4 - Flash your SD card and boot the device

Once the OS image has been downloaded, it’s time to flash your SD card. You can use balenaEtcher for this.

Once the flashing process has completed, insert your SD card into the Raspberry Pi and connect the power supply.

When the device boots for the first time, it connects to the dashboard, after which you’ll be able to see it listed as online and move onto the next step.

Troubleshooting: It should only take a few minutes for the new device to appear in your dashboard, If your device still hasn't shown up on your dashboard after a few minutes, something has gone wrong. There's an extensive troubleshooting guide in the documentation, with lots of information on why this could be, but if you still can't get your device online, come on over to the forums where we’ll be able to help out.

Assembling the display and case

Once you’ve got your Raspberry Pi booted and appearing in the balenaCloud dashboard, it’s time to assemble it into the case with the display. It’s difficult to access the SD card once it's assembled in the case so it’s good to make sure you’re up and running and don’t need to disassemble it again before putting everything together.

You can find a guide showing you how to assemble, connect and orient the display and case here too.

If you’re seeing the output on your display as above, this means that everything is working and ready to go.

Deploying code

Now that your Raspberry Pi has been provisioned, has booted, and connected to balenaCloud, you're ready to push the application code and get things working; we do this using the balena CLI tools.

Installing the balena CLI tools on your computer

The balena CLI tools are installed on your computer/laptop and allow you to communicate with and send code to balenaCloud, which is then sent to your Raspberry Pi. Note: you don't need to use the terminal within the balenaCloud dashboard for anything in this tutorial.

The balena CLI tools are supported on Windows, macOS and Linux, download links and installation instructions can be found here.

If you're on Windows, we've created this YouTube video to show you how to get up and running with the CLI tools.

If you already have (or can setup) npm on your machine, this is most likely the easiest way to get the CLI tools up and running quickly. The documentation for the CLI tools is the best place to start, and covers the installation and setup of both the npm package and the standalone binaries.

When you have the CLI installed and working, the first step is to login to balenaCloud by issuing the balena login command from the terminal or command prompt on your computer:

Once you’ve reached this point, and have a working CLI which has been logged in to your account, you're ready to start pushing code to your Raspberry Pi.

Downloading the balenaDash project from Github

The next step is to download the code for this project from GitHub to your workstation. Go to: and download the project as shown in the image below:

The blue button pictured will download a .zip file of the project but if you're already familiar with Git you can use git clone in the normal way.

Important note for Windows users: if you're using Windows the use of git clone and balena push can cause issues due to line ending changes; we recommend using a combination of either the zip download of the project and balena push or if you'd like to use git clone then also use the git deployment method git push instead of balena push.


The WPE project takes advantage of the hardware GPU acceleration on the Raspberry Pi, and so in order for balenaDash to run, you'll need to allocate a bit more memory to the GPU than is set by default. As you’ve now got the device up and running on balenaCloud, there is the benefit of being able to set configuration values like this remotely, but it’s similarly possible to specify them in /boot/config.txt by editing the file on the SD card directly.

We have a guide to setting configuration variables on balenaCloud in case you can’t find it in the menu.

Note: RESIN_HOST_CONFIG_gpu_mem is one of the default options within balenaCloud and so you can change the existing value rather than adding a new configuration variable.

Name Value

Pushing the project code to your Raspberry Pi

As you have the CLI setup and the latest code downloaded, you can now execute a single command to push that code to balenaCloud which in turn builds the project and handles the process of setting it up and running it on your device.

From within the project directory, that is the balena-dash or balena-dash-master folder, execute balena push <appName>, where appName is the application name you set back at the beginning of the guide. For example: balena push balenaDash.

If everything worked OK, you'll see the unicorn:

Go back to the dashboard and you’ll be able to see the status of your device. It should be downloading the application that’s just been built:

When you push the code for the first time it can take a few minutes to download (dependant on your internet connection speed) but after that only the changes in the container are downloaded so things happen much quicker.

Congratulations! At this point your display is ready to use; by default, it will display YouTube TV. To change this to your desired output, read on...

Displaying your own content

Right now the display is a blank canvas ready to show your content.

You can choose any URL to be displayed on the screen. The easiest way to change the URL is by adding a variable into the device variables inside balenaCloud.

Click on "Add variable" and set the NAME as WPE_URL and VALUE as the URL you'd like balenaDash to display.

Give it a try

To give you some ideas, here are a few examples of things you can use your balenaDash display for. In addition to the big list at the start of this article, try the following…

A YouTube loop

Besides using YouTube as in the initial example, you can easily set a video to automatically open in full-screen and run on repeat.

To do this, you can use the service provided by This is as simple as finding the video you'd like to play, and adding a - character after the t in the URL. For example…

Being Rick Astley fans, we'd like to loop the video with the URL, so we add to the WPE_URL parameter.

To change to a different video, alter the video ID in the URL. Some good ones to get you started: njJJSmWdIgA, OZBWfyYtYQY and QH2-TGUlwu4.

Setting up a dashboard

Take a look at our guide on setting up a dashboard application to use with balenaDash.

Setting up a Google Photos slideshow

Try building a slideshow with Google Slides to use with your display.

Controlling the content with the webUI & your own apps with the HTTP API

balenaDash has a webUI running on port 8080 allowing you to change the content with a web browser. This is covered in detail here.

Set up the display backlight to turn on and off with a timer

A feature of balenaDash is the ability to turn on and off the backlight of the Raspberry Pi according to a schedule.

Using a mouse

If you'd like to plug in a mouse to use with balenaDash, add the following environment variable to the application or device: WPE_BCMRPI_CURSOR with a value of 1.

About the project

The balenaDash project makes use of the WebKit WPE project, which is a port of the WebKit web browser engine designed for embedded and low-power-consumption computing devices. This project takes advantage of the hardware GPU acceleration available on the Raspberry Pi, and so allows us to display a wide variety of web applications with fullscreen animation and full motion video smoothly.

Using this software means that you can display web-based projects without the requirement to install a full GUI and typical desktop browser, with the benefits of improved performance, reduced resource requirements, and ease of automation.

As the configuration and build of WebKit WPE can be quite involved and have a lot of steps, we have taken care of that by setting everything up for you within a Docker container; A container can be thought of as an isolated environment within the operating system running on the Raspberry Pi, that can be preconfigured to install various software packages, data, code and configuration files.

If you'd like to learn more, an introduction to containers can be found here.

What's next?

At this point you're setup with your shiny new balenaDash display and are most likely overflowing with ideas what to use it for.

You've setup your Raspberry Pi using balenaCloud which makes adding a second screen trivial. Flash another SD card with the same image and your second device will appear in the same application and automatically be provisioned with the same software without any further setup work!

You can add 9 more Raspberry Pi devices to your account for free, and manage them all centrally from one dashboard.

We hope this post has inspired you to set up your own balenaDash display. If you have any questions or feedback, or have built your own version of this project, we'd love to see you share your work over in our forums! Happy hacking!

comments powered by Disqus
Terms of Service | Privacy Statement | Master agreement | Copyright 2019 Balena | All Rights Reserved