Skip to main content
Version: Torizon OS 7.x.y

Web Browser / Kiosk Mode with Torizon OS

Introduction​

The Torizon Chromium and Cog browser containers run a browser in kiosk-mode, allowing the implementation of web-based UIs for kiosk applications.

These containers should be used together with the torizon/weston (iMX6/iMX7), torizon/weston-vivante (iMX8) or torizon/weston-am62 (AM62) containers to provide a kiosk-mode user interface with a browser that opens an URL passed as a parameter, does not show error messages/popups and does not allow the user to navigate to different websites.

What is Kiosk-mode​

It is a full-screen mode where only the web page is displayed. The user cannot see the window, the top bar, refresh button, or anything else.

Technical Details​

Torizon provides support for Chromium and Cog.

Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all users to experience the web. In the Chromium container, Chromium uses Ozone/Wayland as a rendering backend.

Cog is a single "window" launcher for the WebKit WPE port. It is small, provides no user interface, and is suitable to be used as a Web application launcher. Cog is able to leverage the GPU for hardware-accelerated applications, which works well on iMX6, iMX8 and AM62-based modules. Cog is also supported on devices that lack a GPU (e.g. iMX7 and iMX6ULL).

This article complies with the Typographic Conventions for Torizon Documentation.

BSP and Reference Images​

If you are looking for information on how to use web browser on Linux and/or how to use Yocto to build an embedded Linux image with web browser, refer to How to Use Web Browser (Linux).

Prerequisites​

Preparing the environment​

Start the Wayland server container (torizon/weston, torizon/weston-vivante or torizon/weston-am62) to provide the graphical environment for the browser window:

# docker container run -d --name=weston --net=host \
    --cap-add CAP_SYS_TTY_CONFIG \
    -v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
    --device-cgroup-rule="c 4:* rmw" --device-cgroup-rule="c 253:* rmw" \
    --device-cgroup-rule="c 13:* rmw" --device-cgroup-rule="c 226:* rmw" \
    --device-cgroup-rule="c 10:223 rmw" --device-cgroup-rule="c 199:0 rmw" \
    torizon/weston-imx8:4 \
    --developer
info

To learn more about the device_cgroup_rules section of the docker-compose file above, please refer to the Hardware Access through Control Group Rules (cgroup) section of the Torizon Best Practices Guide

To learn more about it, read the article Debian Containers for Torizon to provide the graphical environment for the browser window.

Moreover, depending on how your application is designed, also start a container that provides the local UI that the kiosk browser will render.

Running Chromium​

info

If you are running Torizon 6.3.0-devel-202306 or earlier, see Running Chromium on Torizon 6.3.0-devel-202306 and earlier.

The Chromium container needs visibility to some host resources (for accessing the accelerated graphical environment, buffer sharing, and inter-process communication), and the URL of the web UI as a command-line parameter. It also recognizes some optional command-line flags (explained ahead).

You can run the following command to start the Chromium container:

# docker run -d --rm --name=chromium \
    -v /tmp:/tmp -v /dev/dri:/dev/dri \
    -v /var/run/dbus:/var/run/dbus --device-cgroup-rule='c 226:* rmw' \
    --security-opt seccomp=unconfined --shm-size 256mb \
    torizon/chromium:$CT_TAG_CHROMIUM \
    --virtual-keyboard https://www.toradex.com

Optional command line flags​

It's possible to start Chromium in less-secure ways (secure from the point of view of a user being able to run other graphical apps etc.) using command line switches.

  • --window-mode : runs the browser inside a maximized window without the navigation bar
  • --browser-mode : runs the browser in a standard window with navigation bars and all user menus enabled
  • --virtual-keyboard : enables a virtual keyboard for text entry

Additionally, it is possible to pass flags or options directly to Chromium binary when invoking Chromium container, for example:

# docker run -d --rm --name=chromium \
    -v /tmp:/tmp -v /dev/dri:/dev/dri \
    -v /var/run/dbus:/var/run/dbus --device-cgroup-rule='c 226:* rmw' \
    --security-opt seccomp=unconfined --shm-size 256mb \
    torizon/chromium:$CT_TAG_CHROMIUM \
    --virtual-keyboard --user-data-dir=/tmp \
    https://www.toradex.com

GPU Hardware Acceleration flags​

By default Chromium runs with GPU hardware acceleration for all devices except iMX7 and iMX6ULL. Following flags affect this feature:

  • --disable-gpu-compositing : Disables GPU compositing only. May increase performance for some applications at the cost of increased CPU utilization. Reduces the performance of WebGL applications.
  • --disable-gpu : Disables GPU hardware acceleration completely.

Running Cog​

You can run the following command to start the Cog container:

# docker run -d --rm --name=cog \
    -v /tmp:/tmp -v /var/run/dbus:/var/run/dbus \
    -v /dev/dri:/dev/dri --device-cgroup-rule='c 226:* rmw' \
    torizon/cog:$CT_TAG_COG \
    https://www.toradex.com

To change how the output will be configured, the following environment variables can be set:

  • --env COG_PLATFORM_WL_VIEW_FULLSCREEN
  • --env COG_PLATFORM_WL_VIEW_MAXIMIZE
  • --env COG_PLATFORM_WL_VIEW_WIDTH
  • --env COG_PLATFORM_WL_VIEW_HEIGHT

Video Playback with Cog​

By default video playback does not work with the above container image. You'll need to customize or build a new container image in order to have video playback. For this you'll need to perform the following steps:

  • Install Gstreamer packages. You can reference all the available Gstreamer packages from How to use Gstreamer on Torizon OS. Not all Gstreamer packages may be needed, but this can depend on the video formats/codecs that are required.
  • Set the following environment variable within the container: GST_GL_API=gles2.

After these customizations, you can then launch this new container with the same arguments as shown above. But now the container should be able to playback videos, like on Youtube for example.

Docker Compose​

Docker compose can be used to start multiple containers at the same time, providing shared data volumes, mount points, resource usage limitations, etc. If you want to use Chromium or Cog container in this way it's a good idea to make it dependent on the Wayland compositor container and the container providing the data that should be displayed by the UI.

You can find example Docker compose files in our sample repository: https://github.com/toradex/torizon-samples/tree/bookworm/debian-container/demonstration

Optional Command Line Flags on Docker Compose​

The previously described command line flags must be added to the command parameter on the docker-compose file. See an example in the code snippet below:

docker-compose.yml
services:
  kiosk:
    command: --virtual-keyboard --window-mode http://portainer:9000

Examples​

This section collects examples that help use or extend the browser containers.

Multiple Containers - Weston, Chromium, and Grafana​

In the article Using Multiple Containers with Torizon OS, we use the Chromium container to display Grafana on a local UI. It allows us to explain, with a practical example, how to use multiple containers on Torizon.

Installing Fonts - CJK Unified Ideographs​

Fonts for Japanese, Chinese, Korean, and other languages may have to be installed. This example focuses on CJK Unified Ideographs.

Build a container that uses a web browser as base, and install the fonts you are interested. Debian packages have a fonts subsection, so you can install these using apt-get:

ARG BASE_VERSION=3

# Board architecture (arm or arm64)
ARG IMAGE_ARCH=

# Platform prefix (empty for upstream, -vivante for iMX8, -am62 for TI AM62)
ARG GPU=

# DEPLOY ------------------------------------------------------------------------
FROM --platform=linux/${IMAGE_ARCH} torizon/chromium:${BASE_VERSION}

RUN apt-get -y update && apt-get install -y --no-install-recommends \
    fonts-noto-cjk \
    && apt-get -y upgrade \
    && apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*

Remote Connection via VNC/RDP​

Remote access via VNC

As the image above illustrates, you can remote access the Weston container via VNC or RDP, please refer to the Remote Access the Torizon OS GUI Using VNC or RDP to learn more.

Torizon 6.3.0-devel-202306 and earlier​

info

Torizon OS does not support AM62 on version 6.3.0 and earlier.

In Torizon 6.3.0-devel-202306 and earlier, chromium-x11 is used for GPU less SoMs such as iMX7 and iMX6ULL. Cog is run the same way as current versions.

Running Chromium​

The Chromium container needs visibility to some host resources (for accessing the accelerated graphical environment, buffer sharing, and inter-process communication), and the URL of the web UI as a command-line parameter. It also recognizes optional command-line flags (explained ahead).

You can run the following command to start the Chromium container:

# docker run -eMACHINE -d --rm --name=chromium \
    -v /tmp:/tmp -v /dev/dri:/dev/dri \
    -v /var/run/dbus:/var/run/dbus --device-cgroup-rule='c 226:* rmw' \
    --security-opt seccomp=unconfined --shm-size 256mb \
    torizon/chromium:$CT_TAG_CHROMIUM \
    --virtual-keyboard https://www.toradex.com

Optional command line flags​

It's possible to start Chromium in less-secure ways (secure from the point of view of a user being able to run other graphical apps etc.) using command line switches.

  • --window-mode : runs the browser inside a maximized window without the navigation bar
  • --browser-mode : runs the browser in a standard window with navigation bars and all user menus enabled
  • --virtual-keyboard : enables a virtual keyboard for text entry

GPU Hardware Acceleration flags​

By default Chromium runs with GPU hardware acceleration for all devices except iMX7 and iMX6ULL. Following flags affect this feature:

  • --disable-gpu-compositing : Disables GPU compositing only. May increase performance for some applications at the cost of increased CPU utilization. Reduces the performance of WebGL applications.
  • --disable-gpu : Disables GPU hardware acceleration completely.


Send Feedback!