Output WebGL Content on a Screen

This tutorial shows how to install and modify a container that outputs web browser and webGL content


The Arduino Portenta X8's processor NXP® i.MX 8M Mini Processor can be used for 3D rendering, this will allow us to display 3D content on a screen or video output, the device is using OpenGL to process the 3D related calculations. In this tutorial we will render web content from the internet using WebGL and display it on a screen, using an USB Hub. We will go through the steps of how to setup, install and modify the video output.


  • Setup the Video Output
  • Get the required container
  • Run the container
  • Change the video output

Required Hardware and Software

  • Arduino Portenta X8
  • USB-C cable (either USB-C to USB-A or USB-C to USB-C)
  • USB-C hub with HDMI
  • External monitor
  • HDMI cable


Install The Container

There are two ways to get the container, either through

or downloading the container from portenta-containers repository

With Foundries.io:

If you use Foundries.io you can switch the current

of your device to
by switching the app from a terminal on your computer:

1//Change the app to an existing one
2fioctl devices config updates --apps "x-kiosk-imx8-webgl" <deviceName> -f <yourFactoryName>
4//Make a clean installation with no containers
5fioctl devices config updates --apps "," <deviceName> -f <yourFactoryName>
7//If you are getting issues to do so, make sure you are logged correctly with your token
8//You can logout:
9fioctl logout
11//Then login again and follow the instructions
12fioctl login

You will now see the home-screen for some seconds and then it will fade-out and open the Aquarium 3D from WebGL samples - Aquarium.

With downloaded repository: In case you downloaded the portenta-containers repository you will need to connect your board directly to your computer and run the

adb shell
, then push the container to your Portenta X8.

Connect to a Wi-Fi

Check the available Wi-Fi access points

1nmcli de wifi
5 AA:BB:CC:DD:EE:FF <yourAP-SSID> Infra X 130 Mbit/s -- * WPA2

You can save your Wi-Fi details with these commands:

1nmcli c add type wifi con-name <customName> ifname wlan0 ssid <SSID>
2nmcli con modify <customName> wifi-sec.key-mgmt wpa-psk
3nmcli con modify <customName> wifi-sec.psk <PASSWORD>
4nmcli con up <customName>
6//To disconnect from a custom connection
7nmcli con down <customName>
9//To delete a saved connection
10nmcli c delete <customName>

If the LED is on and green then we know that has been correctly connected. If you want to check it in your terminal, you can type:

1nmcli de
5usb0 ethernet connected usbrndis
6usb1 ethernet connected usbecm
7wlan0 wifi connected <customName>
8docker0 bridge connected (externally) docker0

Get Your Board's IP

1ifconfig wlan0
4wlan0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
5 inet <localIP> netmask broadcast <broadcastIP>

Test your IP connection by exiting the

adb shell
, you can use CTRL+Z or typing
, then try to connect through ssh with:

1ssh fio@<localIP>

To connect through ssh it will request the user's password, which is "fio". If you have troubles connecting with the ssh, please check the troubleshooting section at the end of this tutorial

Copy/push the Container

You can push the container from your computer, first open a terminal on the container's directory, then you can use this command to send the container to the Portenta X8:

1scp <folderName> fio@<portentaX8-IP>:<desiredPath>

Video Output Setup

Now we need a USB Hub that has a video output connector, like for an HDMI cable. Connect the Portenta X8 to the USB Hub as a Host, the video connector to a display, the power supply USB to your computer. We could also connect a USB mouse to the hub, this step is optional.

The setup should look like this:

X8 usb hub setup

By default if you connect the board to a display you will see the "home-screen" with the

Arduino PRO
background wallpaper, and a bottom bar with the real time.

You can interact with the interface by plugging USB devices to your hub, like a mouse or a keyboard.

X8 home-screen
X8 home-screen

Running The Container

If you got the container from Foundries.io it will run automatically after few seconds.

In case you copied from the repository, you will need to initialize it with docker by accessing your Portenta X8 through ssh, going to the directory where you copied it and run it from there:

1//Connect to your device
2ssh fio@<portentaX8-IP>
4//Change directory
5cd <containerPath>
7//Compose with docker
8docker-compose up --detach
10//Stop the docker-compose
11docker-compose stop

Edit The Output

You can change the URL of the web output, by going to the container's directory and editing the


1//Connect to your device
2ssh fio@<portentaX8-IP>
4//Change directory
5cd <containerPath>
7//Edit the file with VIM
8vim docker-compose.yml

Once you are inside the VIM editor, to edit the file you will need to press insert and replace the url as shown in the screenshot.

VIM editing docker-compose.yml
VIM editing docker-compose.yml

To save the changes press the ESC key and type

this will write and quit the VIM editor. After editing it you will need to compose the container again.


In this tutorial we went through how to connect the board and display something on a screen. Using a container from FoundriesFactories or by downloading it and uploading it to your Portenta X8. Lastly, we showed how to edit the video output by editing the container.

Next Steps

  • Make your own HTML content, push it to your device and output that content.
  • You could make an app that shows information about the weather in a web and having that on a display.


  • If you tried to connect with
    and you get a fingerprint issue you will need to remove the IP and fingerprint on your
    file, on windows the file is at
    and try again the ssh connection.


1//<portentaX8-ip> <type> <fingerprint>
2192.168.50.8 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAasdaddgre<kopPOTYAAABBBM8EZPWPKdRRGHpSMosJM08R1d10G0h5g5rE4cNjXdJtYpmJNOR+X2FhNRpEdvyDGHfSomJepbaqBoRcCi0Y7M=

Tutorial Toolbox

Contribute to Arduino

Join the community and suggest improvements to this article via GitHub. Make sure to read out contribution policy before making your pull request.

Missing something?

Check out our store and get what you need to follow this tutorial.

Suggest Changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. You can read more on how to contribute in the contribution policy.