Packaging an Electron application (Quick Start) as an IoT GUI

Ubuntu Frame is the foundation for embedded displays. It provides a reliable, secure and easy way to embed your applications into a kiosk-style, IoT device, or digital signage solution. With Ubuntu Frame, the graphic application you choose or design gets a fullscreen window, a dedicated set of windows behaviours, input from touch, keyboard and mouse without needing to deal with the specific hardware, on-screen keyboard, and more.

Together with Ubuntu Core, Ubuntu Frame provides all the infrastructure you need to securely deploy and maintain graphic applications on edge devices. And while Ubuntu Core maximises performance and security of your apps, Ubuntu Frame is compatible with any Linux operating system that supports snaps.

This developer guide will show you how to deploy your graphic application that supports the Wayland protocol to work with Ubuntu Frame and Ubuntu Core. This guide is for developers looking to build kiosks, digital signage solutions, infotainment systems, IoT devices or any other applications that require a graphic interface running on a screen.

We will cover:

  1. Setting up the tools and environment required to package and deploy your application on your desktop
  2. Testing if an application works with Ubuntu Frame on your desktop
  3. Troubleshooting some common issues
  4. Packaging the app as a snap and testing whether the snap works on your desktop
  5. Packaging the snap for an IoT device and testing it on the device

If you want to learn how to install pre-built applications such as wpe-webkit-mir-kiosk, mir-kiosk-kodi, or Scummvm, follow their official installation and configuration guides.

If you are new to Ubuntu Core, we recommend reading our getting started document. If you want to learn about building custom Ubuntu Core images, you could find information on the snapcraft docs.

Requirements

Developers use different tools and processes to build their graphic applications. For the purpose of this guide, we assume that you have an application that supports the Wayland protocol that you can test on your Linux-based desktop.

It is possible to work in a container or on a different computer (if snapd and X forwarding work well enough). But those options are outside the current scope.

For some of the later steps, you will need an Ubuntu One account. This will let you enable remote-build on your Launchpad account and publish on the Snap Store.

Setting up your test environment

Ubuntu Frame provides a tool for developers to simulate how their end application will look and respond in your development environment. So, you don’t need to work directly on your target device to perform the first design and usability iterations.

Open a terminal window and type:

sudo snap install ubuntu-frame

Snapcraft is a command-line utility for building snaps. This software allows users to build their own applications or software packages, and then publish them to the Snap Store.

In the same terminal window type:

sudo snap install snapcraft --classic

If you don’t have git installed, now is a good time to install it (on Ubuntu, use the command sudo apt install git).

Checking your application works with Ubuntu Frame

There can be problems with both getting your application to work well with Ubuntu Frame and getting your application to work in a snap. To avoid confusion, we recommend first testing your application with Ubuntu Frame before packaging it as a snap. In this section, you will test your application, explore some common issues you might run into, and learn how to fix them.

Enabling Ubuntu Frame simulator

The key thing to know about connecting an app to Ubuntu Frame is that the connection is controlled by the WAYLAND_DISPLAY environment variable. You need to set that to the same value for both processes and, because you may be using a Wayland-based desktop environment (which uses the default of wayland-0), set it to wayland-99.

In a terminal window (that you’ll use for this section and the next section) type:

export WAYLAND_DISPLAY=wayland-99
ubuntu-frame&

You should see an “Ubuntu Frame” window containing a graduated grey background. You should use the “Ubuntu Frame” simulator for testing your application

image

Testing using Ubuntu Frame simulator

We will use the Electron “Quick Start” here. With a bit more effort the demo can be replaced by your kiosk application, industrial GUI, smart fridge GUI, digital sign and more, but you may need to update your snapcraft.yaml packing recipe to reflect how that is built.

The first step is to download the application and execute it. If you are able to see it on the “Ubuntu Frame” window, then you know that your application works with Ubuntu Frame.

git clone https://github.com/electron/electron-quick-start.git
cd electron-quick-start
npm install
npm start -- --enable-features=UseOzonePlatform --ozone-platform=wayland

Now Frame’s window should contain the “Hello World!” app.

image

If your application doesn’t appear or look right at this stage, then this is the time to work out the fix, before packaging as a snap. You will see some examples of the problems you might encounter in the developer guide.

Close “Hello World!” (Ctrl-C)

Packaging your application as a Snap

Now that you know how to confirm that the application is working with Ubuntu Frame, the next step is to use snap packaging to prepare it for use on an IoT device. As before, this section will show you how to package your application together with some issues you might find and their troubleshoot.

Snap packaging for IoT graphics

For use with Ubuntu Core, your application needs to be packaged as a snap. This will also allow you to leverage Over The Air updates, automatic rollbacks, delta updates, update semantic channels, and more. If you don’t use Ubuntu Core, but instead another form of Linux, we recommend you use snaps to get many of these advantages.

There’s a lot of information about packaging snaps online, and the purpose here is not to teach about the snapcraft packaging tool or the Snap Store. We will, instead, focus on the things that are special to IoT graphics.

Much of what you find online about packaging GUI applications as a snap refers to packaging for desktop. Some of that doesn’t apply to IoT as Ubuntu Core and Ubuntu Server do not include everything a desktop installation does and the snaps need to run as daemons (background services) instead of being launched in a user session. In particular, you should ignore various Snapcraft extensions that help writing snap recipes that integrate with the desktop environment (e.g. using the correct theme).

Writing snap recipes without these extensions is not difficult as we’ll illustrate for each of the example programs used in the previous section.

In the same terminal window you opened at the start of the last section, switch back to the root directory of the snap project:

cd -
git clone https://github.com/MirServer/iot-example-graphical-snap.git
cd iot-example-graphical-snap

The customised snapcraft recipe for each example described in this guide (i.e. GTK, Qt and SDL2) is on a corresponding branch in this repository:

$ git branch -a
* master
remotes/origin/GTK3-mastermind
remotes/origin/HEAD -> origin/master
remotes/origin/Qt5-bomber
remotes/origin/SDL2-neverputt
remotes/origin/master

Once you have the customised snapcraft recipe you can snap your example applications.

Switch to the GTK example branch. Then use snapcraft to build the snap:

git checkout Electron-quick-start
snapcraft

Snapcraft is the packaging tool used to create snaps. We are not going to explore all its options here but, to avoid confusion, note that when you first run snapcraft, you will be asked “Support for ‘multipass’ needs to be set up. Would you like to do it now? [y/N]:”, answer “yes”.

After a few minutes, the snap will be built with a message like:

Snapped iot-example-graphical-snap_0+git.03795a5_amd64.snap

You can then install and run the snap:

sudo snap install --dangerous *.snap
snap run iot-example-graphical-snap

The first time you run your snap with Ubuntu Frame installed, you are likely to see a warning:

WARNING: wayland interface not connected! Please run: /snap/iot-example-graphical-snap/current/bin/setup.sh
[231190:0624/162014.069287:ERROR:wayland_connection.cc(209)] Failed to connect to Wayland display
[231190:0624/162014.069317:ERROR:ozone_platform_wayland.cc(226)] Failed to initialize Wayland platform
[231190:0624/162014.069322:ERROR:env.cc(226)] The platform failed to initialize.  Exiting.
The futex facility returned an unexpected error code.

The first WARNING is the key to the problem and comes from one of the scripts in the generic recipe. While developing your snap (that is, until your snap is uploaded to the store and any necessary “store assertions” granted), connecting many “interfaces” your snap uses needs to be done manually. As the message suggests, there’s a helper script for this. Run it and try again:

/snap/iot-example-graphical-snap/current/bin/setup.sh
snap run iot-example-graphical-snap

Now Frame’s window should contain the “Demo” app.

image

Close that (Ctrl-C) and also close “Ubuntu Frame”.

Installing on a device

In this section, you will see how to build for and install on a device. So far, you explored the process for testing your snapped application will work on Ubuntu Frame only using your desktop. Testing on the desktop first accelerates the development process, but you still need to consider the final your edge device.

For the sake of this guide, we are using a VM set up using the approach described in Ubuntu Core: Preparing a virtual machine with graphics support.

scp -P 10022 *.snap <username>@localhost:~
ssh -p 10022 <username>@localhost
snap install ubuntu-frame
snap install --dangerous *.snap

image

Building your snap for other architectures

The simplest way to build your snap for other architectures is:

snapcraft remote-build

This uses the Launchpad build farm to build each of the architectures supported by the snap. This requires you to have a Launchpad account and to be okay uploading your snap source to a public location.

Once the build is complete, you can copy the .snap file to your IoT device and install. Apart from the address used for scp and ssh this is the same as with the VM used in the last section.

Conclusion

From testing to deployment, this guide shows you how to use Ubuntu Frame to deploy your graphic applications. It covers topics as setting up the tools and environment on your desktop, testing if an application works with Ubuntu Frame, and packaging the application as a snap for an IoT device. It also included some issues you can encounter working with your applications and how to troubleshoot them.

We have also shown all the steps needed to get your snap running on a device. The rest of your development process is the same as for any other snap: uploading the snap to the store and installing on devices from there. There are just a few parting things to note:

Now that the Snap interfaces are configured, the application will automatically start when the system (re)starts.

Once you’ve uploaded the snap to the store, you can request store assertions to auto-connect any required interfaces. Alternatively, if you are building a Snap Appliance, then you can connect the interfaces in the “Gadget Snap”.

Learn more

For more information about Ubuntu Frame please visit our website.

You may also consider reading the following materials:

Need help in getting to market? Contact us

Last updated 8 months ago. Help improve this document in the forum.