Adding Remote Desktop to MaaXBoard 8ULP

Introduction

In a previous article Rapid UI Prototyping with MaaXBoard 8ULP & PySimpleGuiWeb I discussed how you can use the PySimpleGuiWeb framework to quickly create a UI for headless hardware.

In this project we’ll explore another tool for interfacing with headless setups called FreeRDP, or Free Remote Desktop Protocol. FreeRDP allows users to remotely access and interact with an operating system, in this case Linux on MaaXBoard 8ULP. It does this by facilitating secure communication between the client (desktop computer) and server (MaaXBoard 8ULP). The result is access to the desktop/graphical user interface to manipulate files or run applications.

We’ll start by setting up a Linux Yocto build for MaaXBoard 8ULP and show how to add freeRDP to the image. After building the image, we'll flash the board and set up the freeRDP server on MaaXBoard 8ULP. In the final step we'll show how to connect your host PC machine to the MaaXBoard 8ULP and gain access to the targets desktop environment.

Prerequisites & Resources

It's assumed the user has prior knowledge with Yocto and building images for MaaXBoards. If not, there are existing articles that cover this in detail such as Building Your Own Yocto for MaaXBoard. Below are other helpful links for getting started with the MaaXBoard 8ULP as well as Linux / Yocto user manuals.

MaaXBoard 8ULP Reference Material:

· MaaXBoard 8ULP Product Page

· MaaXBoard 8ULP HUB Page

· MaaXBoard 8ULP Github

· MaaXBoard 8ULP Linux/Yocto User Manual

· MaaXBoard 8ULP User Guide

Avnet Meta-Weston-RDP Repository:

- meta-weston-rdp

FreeRDP Documentation:

· FreeRDP Homepage

Developing with VSCode:

· Remote Development using SSH

Yocto:

· Yocto Project

· Yocto Documentation

Installing XfreeRDP on Host PC

XfreeRDP is compatible with Windows, Linux, or Mac. I will cover installing xfreeRDP on Linux first, and then Windows. If you run into any issues reference the freeRDP documentation listed in the references section.

Linux/Ubuntu Install

On a Linux workstation, open a terminal and run the following command:

sudo apt install freerdp2-x11

Enter your password and freeRDP should begin installing. Once finished, run “xfreerdp” in a terminal to verify it’s installation. You should see the following output.

Windows 10 Install

If you’re using Windows, you will have to download an executable from the following site. A zip file will be downloaded with the executable included. Note that you may need admin privileges on your machine to run the executable.

Setup Linux Yocto Image Build for MaaXBoard 8ULP

In the article MaaXBoard 8ULP Linux Yocto Development Guide there are instructions for setting up a base image. Since it’s assumed the user already has a working build environment I will skip section 1.1 and begin at section 1.2 of the development guide. I will be using VScode to interface with my build system over SSH. If you’re unfamiliar with this setup, please see the Prerequistes and References section on how to get started with VScode and SSH.

On the build machine, select a path where you’d like to create the MaaXBoard 8ULP image.

$ mkdir ~/imx-yocto-bsp
$ cd ~/imx-yocto-bsp

$ repo init -u https://github.com/nxp-imx/imx-manifest -b imx-linux-langdale -m imx-6.1.1-1.0.0.xml

$ repo sync

I am using SSH from VScode to connect to my build system as shown below.

Next, download the meta-maaxboard source code into the ~/imx-yocto-bsp/sources/folder.

$ cd ~/imx-yocto-bsp/sources
$ git clone https://github.com/Avnet/meta-maaxboard.git -b langdale meta-maaxboard

Once this step is completed, your file directory should look similar as the one below. If you’re missing any layers or the repo tool isn’t properly setup, please refer to Linux Yocto Development Guide mentioned at the beginning of this section.

Adding Meta-Weston-RPD Repository

To add freeRDP functionality to the image, clone this repository meta-weston-rdp into the sources folder. The repository includes all necessary files to setup and initialize freeRDP on the target board when powered on. The repo also contains instructions for adding freeRDP to your image.

Your sources directory should now look similar to the following setup.

Once the repository has been cloned, navigate to:

~/imx-yocto-bsp/sources/meta-maaxboard/images/

Find avnet-image-oob.bb. Add freeRDP to the CORE_IMAGE_EXTRA_INSTSALL list as shown below. There will be several packages included this append list.

CORE_IMAGE_EXTRA_INSTALL:append = " \
    ... \
    freerdp \
“

A screenshot below is provided as an example.

After the freeRDP variable has been added to the out-of-box image and the repo has been cloned into sources, you must add the new meta-weston-rdp layer using bitbake. First create your machine/distribution. An example of my setup is shown below.

jacob@avnet-HP-Z4-G4-Workstation: ~/imx-yocto-bsp$ MACHINE=maaxboard-8ulp source sources/meta-maaxboard/tools/maaxboard-setup.sh -b maaxboard-8ulp/build

Now add the meta-weston-rdp layer using the following command. These details are also provided in the meta-weston-rdp github repo.

$ bitbake-layers add-layer ../../sources/meta-weston-rdp

Finally, build the out-of-box image:

$ bitbake avnet-image-oob

Note that building a yocto linux image can take several hours depending on the machine. If you run into any build errors, step back through the instructions in this document or in the meta-weston-rdp github.

Downloading freeRDP Image to MaaXBoard 8ULP

Once the build is completed, locate the image in your build directory. On my machine this is:

/imx-yocto-bsp/maaxboard-8ulp/build/tmp/deploy/images/

Locate two files “imx-boot-maaxboard-8ulp-sd.bin-flash_singleboot_m33” and “avnet-image-oob-maaxboard-8ulp-<date_time>.rootfs.wic”. Your.wic file will have a date/time appended in the name of the file. If you encountered any errors during the build, please double check your build distribution/machine and system dependencies. If you continue to encounter errors please refer to the references section.

Prepare your MaaXBoard 8ULP for USB download by placing all switches on SW1 DIP to off with the exception of switch 4 on the backside of the board.

Next, connect cables from your Linux build machine or PC to the MaaXBoard 8ULP. You can connect the Ethernet cable directly to your host PC or a router. If connecting to a network, please ensure the host PC is on the same network as the MaaXBoard 8ULP, otherwise you will not be able to access the target’s desktop environment over freeRDP.

After the cables have been connected and the target boots up, use the UUU tool (university update utility) to download your image to the board.

$ ./uuu_1.5.21.exe -b emmc_all u-boot-maaxboard-8ulp.imx avnet-image-oob-maaxboard-8ulp-20231106174245.rootfs.wic

After the image is successfully downloaded, set the target to boot from eMMC using SW1 DIP. Place all switches off with the exception of switch 5. Reset power to the board to boot with the new image.

Open a PuTTY or SSH into the MaaXBoard 8ULP to interface with the file system. A PuTTY example is provided below however please note your comport number will most likely be different.

Ensure that you have successful communication to the target. Login is "root".

Configuring FreeRDP on MaaXBoard 8ULP

With the new image loaded and board powered on, a few changes are required on the MaaXBoard 8ULP prior to starting freeRDP. To make the necessary file changes, I will be using VScode and SSH to the MaaXBoard 8ULP. You can also use PuTTY as setup in the last example.

First we will locate the Weston.ini file on the target board and edit it’s screen sharing parameters. The Weston.ini file is located in the following directory on the target board:

/etc/xdg/weston/weston.ini

Once found, add in the following line under the [core] section:

[core]
...
modules=screen-share.so

Replace the [screen-share] section with the following:

[screen-share]
command=/usr/bin/weston --backend=rdp-backend.so --rdp-tls-cert=/etc/freerdp/keys/server.crt --rdp-tls-key=/etc/freerdp/keys/server.key --shell=fullscreen-shell.so --no-clients-resize
start-on-startup=true

Your Weston.ini file should look identical to the following screenshot:

Next we will use winpr-makecert to create server and key certificates for connectivity. Using the terminal please enter the following. This will create a freeRDP/Keys folder inside /etc, add the generated certificates, and rename them appropriately.

$ mkdir /etc/freerdp
$ mkdir /etc/freerdp/keys
$ winpr-makecert -path /etc/freerdp/keys
$ mv /etc/freerdp/keys/maaxboard8ulp.crt /etc/freerdp/keys/server.crt
$ mv /etc/freerdp/keys/maaxboard8ulp.key /etc/freerdp/keys/server.key

Once this step is completed, you should see two new files in /etc/freerdp/keys.

Once these changes have been made, it’s required that the target be rebooted for all file changes to take affect. After the target has been rebooted, use ifconfig to retrieve the IP address of the MaaXBoard 8ULP which will be needed to connect from the host PC to the target board.

Launch FreeRDP Client from Host (Linux) PC

Using PuTTY or VSCode as shown in previous sections, collect the IP address from the MaaXBoard 8ULP targtet. In the following example the IP address on my board is 192.168.1.165, however yours may be different.

Linux/Ubuntu

Open a terminal on your Linux PC and ensure you have a display or monitor connecte. With the terminal open, enter the following command using the MaaXBoard 8ULP IP address as found in the previous section.

xfreerdp /u:<username> /p:<password> /v:<ip_address>

After running the following command you should be prompted to trust certificates from the board.

Enter “Y” in the terminal to continue. This will connect the freeRDP client (host PC) to the freeRDP server running on board. You should now see a remote desktop connection established and running on the MaaXBoard 8ULP.

Windows 10

Navigate to where the binary download onto your host machine and find the executable.

Open a command terminal and run the same command with the correct username and IP address.

wfreerdp.exe /u:<username> /v:<ip_addr>

Launching FreeRDP Manually on MaaXBoard 8ULP

If you received an error connecting from the Host PC to the MaaXBoard 8ULP target, it could have been that freeRDP wasn’t initialized on the board or there was an error generating the security certificates.

First please verify that the server.key and server.crt have contents in the files. If they contain data, it’s possible that freeRDP did not automatically start when the board was powered on.

If this is the case, please open a terminal to the MaaXBoard 8ULP, and run the following command either through PuTTY or VScode.

weston --backend=rdp-backend.so --rdp-tls-cert=/etc/freerdp/keys/server.crt --rdp-tls-key=/etc/freerdp/keys/server.key

You should see the following output from the MaaXBoard 8ULP.

If the output you received from the board matches above, try reconnecting from your Host PC to the target board using the same commands as shown in the previous section.

Summary

In this article we covered how to add freeRDP to both a MaaXBoard 8ULP and host PC system to gain remote desktop access to an embedded target board.