Skip to main content
Version: 5.0

Web Browser / Kiosk Mode with TorizonCore

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) or torizon/weston-vivante (iMX8) 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. As of torizon/chromium:2.6.0, GPU acceleration is enabled.

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 and iMX8 based modules. From Cog container with the container tag 2.6 onwards, Cog is supported also on devices that lack a GPU (e.g. iMX7 and iMX6ULL).

This article complies to 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 or torizon/weston-vivante) to provide the graphical environment for the browser window:

(Optional) pull the torizon/weston container image:

# docker pull torizon/weston:$CT_TAG_WESTON

Start the weston compositor:

# docker run -d --rm --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 13:* rmw' \
--device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
torizon/weston:$CT_TAG_WESTON --developer weston-launch --tty=/dev/tty7 --user=torizon

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 5.6.0 or earlier, see Running Chromium on Torizon 5.6.0 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 -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.

Running Cog​

info

If you are running Torizon 5.6.0 or earlier, see Running Cog on Torizon 5.6.0 and earlier.

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 TorizonCore. 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/bullseye/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

TorizonCore with Evaluation Containers​

The TorizonCore with Evaluation Containers image comes with the Chromium container, since we run the Portainer container manager on top of it. You can read or edit the file on the board on /var/sota/storage/docker-compose/docker-compose.yml for quick evaluation. To make persistent changes or deploy your own docker-compose.yml, we recommend using the TorizonCore Builder Tool.

Examples​

In the article Using Multiple Containers with TorizonCore, 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.

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 TorizonCore GUI Using VNC or RDP to learn more.

Torizon 5.6.0 and earlier​

In Torizon 5.6.0 and earlier, there is only one container for both Chromium and COG.

Running Chromium​

The kiosk 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 kiosk-mode browser container with Chromium:

# docker run -d --rm --name=kiosk \
-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/kiosk-mode-browser:$CT_TAG_KIOSK_MODE_BROWSER \
--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

Running Cog​

You can run the following command to start the kiosk-mode browser container with Cog:

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

For version 5.6.0 and earlier, Cog is not supported on iMX7 and iMX6ULL based modules.

Send Feedback!