11. Output WebGL Content on a Screen

Overview

The Arduino Portenta X8's processor NXP® i.MX 8M Mini Processor is capable of 3D rendering by using OpenGL to process the 3D-related calculations, allowing us to display 3D content on a screen or video output.

In this tutorial, we will render web content from the internet using WebGL and display it on a screen using a USB Hub. We will go through the steps to set up, install, and modify the video output.

Goals

• Learn how to setup the Video Output
• Learn how to get the required container
• Learn how to run the container
• Learn how to change the video output

Required Hardware and Software

• 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

Instructions

Install The Container

There are two ways to get the container: through

foundriesFactories

With Foundries.io:

If you use Foundries.io, you can switch the current

target

x-kiosk-imx8-webgl

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

You will see the home screen for a few seconds, and then it will fade. Open the Aquarium 3D from WebGL samples - Aquarium.

With downloaded repository:

If you downloaded the portenta-containers repository, you would need to connect your board directly to your computer and run the

adb shell,

Connect to a Wi-Fi®

Check the available Wi-Fi® access points using the

nmcli de wifi

BSSID

SSID

Copy
1nmcli de wifi
2
3//Output
4IN-USE  BSSID              SSID             MODE   CHAN  RATE        SIGNAL  BARS  SECURITY
5        AA:BB:CC:DD:EE:FF  <yourAP-SSID>    Infra  X     130 Mbit/s  --      *     WPA2

The Wi-Fi® details can be saved using the following commands in sequence:

Copy
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>
5
6//To disconnect from a custom connection
7nmcli con down <customName>
8
9//To delete a saved connection
10nmcli c delete <customName>

If the LED is illuminating Green, we know it has been correctly connected. If you want to check it in your terminal, you can use the following commands:

Copy
1nmcli de
2
3//Output
4DEVICE   TYPE      STATE                   CONNECTION
5usb0     ethernet  connected               usbrndis
6usb1     ethernet  connected               usbecm
7wlan0    wifi      connected               <customName>
8docker0  bridge    connected (externally)  docker0

The output table will display information regarding active connections and the Wi-Fi® connection we are interested in.

Get Your Board's IP

The IP information of the board can be obtained using

ifconfig wlan0

inet

netmask

broadcastIP

Copy
1ifconfig wlan0
2
3//Output
4wlan0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
5        inet <localIP>  netmask 255.255.255.0  broadcast <broadcastIP>

Test your IP connection by exiting the

adb shell

exit

Copy
1ssh fio@<localIP>

To connect through SSH, the user's admin password you setup at first access will be requested. If you have trouble connecting with the SSH, please check the troubleshooting section at the end of this tutorial.

Copy/Push the Docker-Compose.yml

You can push the docker-compose.yml, a file that describes the app in ASCII format, from your computer using a terminal on the file's directory. The following command is used to send the composer to the Portenta X8:

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

Video Output Setup

Now, we need a USB Hub with an available video output connector, such as an HDMI cable. Connect the Portenta X8 to the USB Hub as a Host, the video connector to a display, and the power supply USB to your computer. It is optional, but we could connect a USB mouse to the hub. The setup should look like as follows:

As a reference, a list of validated USB-C® to HDMI hubs that you can use are: TPX00145 and TPX00146.

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

Arduino PRO

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

Suppose you need to change the resolution of your display/monitor to improve the video output quality. In that case, you need to add a specific resolution to the configuration file of the graphical server (Weston on Portenta X8). To do so, you need to generate the right Modeline, i.e., a row that specifies a custom mode for the graphical interface to drive the display correctly.

In the next steps, we provide an example of a 1600 x 758 display running at 60Hz. If you need to modify the modeline and generate a new one, you can use

cvt

To get started in modifying the resolution of your display, connect to your Portenta X8 through ADB (check this link to learn how to do it).

At this point, you are ready to modify the

/etc/xdg/weston/weston.ini

Vim

Copy
1sudo vim /etc/xdg/weston/weston.ini

You can now add the following lines to the

weston.ini

Copy
1[output]
2name=DP-1
3mode=98.00  1600 1680 1840 2080  758 761 771 787 -hsync +vsync

Save the file and exit. To see the changes in place, you have to reboot your Portenta X8 using the command

sudo systemctl reboot

Running The Image

If you obtained the app descriptor, structured through docker-compose.yml, from Foundries.io, it will run automatically after a few seconds.

On the other hand, if you copied from the repository, you will need to initialize with docker by accessing your Portenta X8 through SSH, going to the directory where you have copied it, and running it from that directory using the following commands:

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

Edit The Output

It is possible to change the web output URL by editing the

docker-compose.yml

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

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

Press the ESC key to save the changes and type

:wq

Conclusion

In this tutorial, we went through how to connect the board and display something on a screen. Using a container from FoundriesFactories or 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 the desired content.
• You could make an app that shows information about the weather on the web and have that on a display.

Troubleshooting

• If you tried to connect with

  ssh

  and you get a fingerprint issue, you will need to remove the IP and fingerprint on your

  .ssh

  file. On Windows, the file is located at

  C:\Users\<yourUsername>\.ssh\known_hosts

  and try again with the ssh connection. An example is as follows:

Copy
1$portenta-x8: ssh-keygen -R <name or IP address of the host>