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.

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
  • 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 to get set up with some tools to set up the Raspberry Pi and get the code loaded.

You can use balenaCloud to push the project code to the Raspberry Pi, and then for subsequent updates and management of the device. If you’ve not already used the balena CLI, you'll need to set that up too, which facilitates the process of pushing your code to the Pi.

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 for you as well.

Step 1 - Sign up to balenaCloud

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

Sign up 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 green '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 to the device.

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; now all you need is the Dockerfile which is the definition for that container, in the form of a plain text file. 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.

Installing the balena 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. However, there are also standalone binaries for Windows, macOS and Linux available.

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:

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. Go to: https://github.com/balena-io-projects/balena-dash 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.


As mentioned earlier, 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.

There is 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 Docker image and handles the process of setting it up and running it on your device.

From within the project directory, 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 yout-ube.com. 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 https://www.youtube.com/watch?v=dQw4w9WgXcQ, so we add https://www.yout-ube.com/watch?v=dQw4w9WgXcQ 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.

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