RPi - Igalia/meta-webkit GitHub Wiki

Introduction

This wiki page documents how to build an image with WPE for the Raspberry Pi (model 4, 3 or 2)

Please be sure to first read the WPE introduction page that gives an overview of the launchers and wpebackends available.

Building an image with WPE for the RPi

To build WPE for the RPi there are 3 alternatives:

  1. Use upstream Mesa VC4 driver with the wpebackend-fdo through the wayland protocol (Weston).
    • Benefits: you get a fully open source stack and you also get to test the graphic architecture the project is currently pushing for (next-gen graphics pipeline)
  2. Use upstream Mesa VC4 driver with the wpebackend-fdo directly over the Direct Rendering Manager (DRM) Linux subsystem.
    • Benefits: still a fully open source stack using the DRM as interfacing with GPUs of modern video cards.
    • Limited to kiosk-mode scenarios without window manager.
  3. DEPRECATED:exclamation:: Use proprietary Broadcom OpenGL drivers (userland drivers) and wpebackend-rdk/rpi-dispmanx
    • Benefits: currently (as of time of writing this) it has better performance than the VC4 alternative and allows to run WPE full-screen.
    • Limited to 32 bits images AND Raspberry Pi models 2 and 3.

Common steps: setup the Yocto build environment

Get the sources for your yocto build environment

The first thing is to get the poky, meta-openembedded, meta-gstreamer1.0 and meta-rapsberrypi layers. In this example I'm using honister as version because is the last stable available as of time of writing this.

mkdir ${HOME}/yocto-rpi-wpe
cd ${HOME}/yocto-rpi-wpe
git clone https://git.yoctoproject.org/git/poky -b honister
git clone git://git.openembedded.org/meta-openembedded -b honister
git clone https://git.yoctoproject.org/git/meta-raspberrypi -b honister
git clone https://github.com/Igalia/meta-webkit -b main

Initialize the yocto build environment

Now we should initialization the build environment and do the initial configuration of the build

cd ${HOME}/yocto-rpi-wpe
source poky/oe-init-build-env build

Configure the list of layers.

Now edit the file conf/bblayers.conf and add to it (inside the BBLAYERS variable) the paths (full path) to the directories containing the required layers:

$ cat conf/bblayers.conf 
LCONF_VERSION = "7"

BBPATH = "${TOPDIR}"
BSPDIR := "${@os.path.abspath(os.path.dirname(d.getVar('FILE', True)) + '/../..')}"

BBFILES ?= ""
BBLAYERS = " \
  ${BSPDIR}/poky/meta \
  ${BSPDIR}/poky/meta-poky \
  ${BSPDIR}/meta-openembedded/meta-oe \
  ${BSPDIR}/meta-openembedded/meta-python \
  ${BSPDIR}/meta-raspberrypi \
  ${BSPDIR}/meta-webkit \
"

Image with Mesa VC4 driver, weston and wpebackend-fdo :heavy_check_mark:

Configure the build.

Edit the file conf/local.conf and add this lines at the bottom:

MACHINE = "raspberrypi3" 
MACHINE_FEATURES:append = " vc4graphics"
GPU_MEM_256 = "128"
GPU_MEM_512 = "196"
GPU_MEM_1024 = "396"
DISTRO_FEATURES:append = " opengl egl wayland"
EXTRA_IMAGE_FEATURES = "debug-tweaks"
IMAGE_FEATURES:append = " ssh-server-dropbear hwcodecs"
PREFERRED_PROVIDER_virtual/wpebackend = "wpebackend-fdo"
IMAGE_INSTALL:append = " wpewebkit cog"
  • Note: the line for debug-tweaks is optional, but it makes testing easier (e.g.: enables ssh access for root without password)
  • Note: you can set raspberrypi2, raspberrypi4 or raspberrypi4-64 instead of raspberrypi3 in the MACHINE line.

Build the image

bitbake core-image-weston

Test the image

After it finish building you should be able to find the image inside the subdirectory tmp-glibc/deploy/images/raspberrypi3. Now simply write that raw with dd to a sdcard. If you preffer a GUI program, you can use etcher to write the image instead of dd

dd if=tmp/deploy/images/raspberrypi3/core-image-weston-raspberrypi3.wic.bz2 of=/dev/mmcblk0 bs=4k status=progress

The image should boot and start a weston session. Be sure to connect the ethernet cable on the RPi to your LAN. As wireless doesn't work by default. Once it starts the weston session you should be able to open a weston terminal and run cog from there.

cog -P fdo http://wpewebkit.org

Note: To test easier, you can ssh into the board IP from your PC as root and launch cog from the ssh session. In case you are testing with a weston/wayland based image, for this to work you have to remember to export the WAYLAND_DISPLAY and XDG_RUNTIME_DIR environment variables. First open a weston terminal on the board, write down the values of this variables and then export the same values to this variables from the ssh terminal.

Image with Mesa VC4 driver, DRM and wpebackend-fdo :heavy_check_mark:

:exclamation: There is an open issue related to the DRM backend in combination with the Raspberry Pi 4. You could check this comment meta-webkit#275 to find an workaround meanwhile it is not solved in Cog.

Configure the build.

Edit the file conf/local.conf and add this lines at the bottom:

MACHINE = "raspberrypi3"  # Or: raspberrypi2, raspberrypi4 or raspberrypi4-64
MACHINE_FEATURES:append = " vc4graphics"
GPU_MEM_256 = "128"
GPU_MEM_512 = "196"
GPU_MEM_1024 = "396"
DISTRO_FEATURES_append = " opengl egl wayland"
EXTRA_IMAGE_FEATURES = "debug-tweaks"
IMAGE_FEATURES:append = " ssh-server-dropbear hwcodecs"
PREFERRED_PROVIDER_virtual/wpebackend = "wpebackend-fdo"
IMAGE_INSTALL:append = " wpewebkit cog"

Build the image

bitbake core-image-base

After it finish building you should be able to find the image inside the subdirectory tmp-glibc/deploy/images/raspberrypi3. Now simply write that raw with dd to a sdcard. If you preffer a GUI program, you can use etcher to write the image instead of dd

dd if=tmp/deploy/images/raspberrypi3/core-image-base-raspberrypi3.wic.bz2 of=/dev/mmcblk0 bs=4k status=progress

Test the image

The image should boot and start a weston session. Be sure to connect the ethernet cable on the RPi to your LAN. As wireless doesn't work by default. Once it starts the weston session you should be able to open a weston terminal and run cog from there.

cog -P drm http://wpewebkit.org

Image with proprietary Broadcom OpenGL drivers (userland drivers) and wpebackend-rdk (rpi-dispmanx) :warning:

DEPRECATED

Configure the build.

Edit the file conf/local.conf and add this lines at the bottom:

MACHINE = "raspberrypi3"  # Or: raspberrypi2. Other machines (ex: based on raspberrypi4 are not supported by this backend) 
GPU_MEM_256 = "128"
GPU_MEM_512 = "196"
GPU_MEM_1024 = "396"
EXTRA_IMAGE_FEATURES = "debug-tweaks"
IMAGE_FEATURES:append = " ssh-server-dropbear hwcodecs"
PREFERRED_PROVIDER_virtual/wpebackend = "wpebackend-rdk"
PACKAGECONFIG:pn-wpebackend-rdk = "rpi"
IMAGE_INSTALL:append = " wpewebkit cog"
DISABLE_VC4GRAPHICS = "1"

Build the image

Finally you are ready to build an image with weston and WPE for the rpi3, to achieve that simply run

bitbake core-image-base

Test the image

After it finish building you should be able to find the image inside the subdirectory tmp-glibc/deploy/images/raspberrypi3. Now simply write that raw with dd to a sdcard. If you prefer a GUI program, you can use etcher to write the image instead of dd

dd if=tmp/deploy/images/raspberrypi3/core-image-base-raspberrypi3.wic.bz2 of=/dev/mmcblk0 bs=4k status=progress

The image should boot. Be sure to connect the ethernet cable on the RPi to your LAN. As wireless doesn't work by default. Once the login prompt is shown in the screen you can login and launch cog from there.

cog http://wpewebkit.org

You need to export this two environment variables before running the launcher to have mouse and/or touchscreen support

export WPE_BCMRPI_TOUCH=1
export WPE_BCMRPI_CURSOR=1
cog http://wpewebkit.org

Enabling accelerated video decoding

With proprietary Broadcom OpenGL drivers (userland drivers) and wpebackend-rdk/rpi-dispmanx

:exclamation: Limited to: 32 bits images AND Raspberry Pi 2 and 3.

The RPi GPU is capable of decoding H.264 via hardware. To leverage this with WPE we need the following:

  1. Select to build an image with the proprietary Broadcom OpenGL drivers (userland drivers) (option 1 above).
  2. Ensure the version of GStreamer being used is 1.10 or newer. You may need to update your Yocto version if you have an older version.
  3. Ensure the gl plugin of gstreamer-plugins-bad is being built. It should build by default if you add this to conf/local.conf
DISTRO_FEATURES:append = " opengl"
  1. Ensure the packageconfig gst_gl is enabled on WPE (this is the default)
  2. Install the gstreamer-omx plugins into the image. You can do this by adding to conf/local.conf
IMAGE_INSTALL:append = " gstreamer1.0-omx"
LICENSE_FLAGS_WHITELIST:append = " commercial"

With Mesa VC4 driver and wpebackend-fdo

Note: The instructions above regarding accelerated video decoding have been only tested with the proprietary stack (userland). In theory it should be also possible to enable accelerated hardware decoding in the near future using the open source stack by leveraging the gstreamer v4l2 plugin. The steps for that should be pretty much the same, but installing the v4l2 gstreamer plugin instead of the gstreamer1.0-omx one. Watch https://github.com/anholt/linux/issues/13 for tracking video decode support in the opensource RPi vc4 stack.

See also this issue that links some patches for WebKit that may be needed