Raspberry Pi Native Debug

Have more questions? Submit a request
Native debug on RPi3 requires you to install Epiphany Browser (a.k.a. Gnome Web) on your PC. It's necessary as the RPi is3 using WebKitGTK as its rendering engine. It implements its own developer console which is different from Chromium's, and they're not compatible.

The reason for this is that Chromium isn't capable of using RPi3's GPU for hardware acceleration at the moment. Hardware acceleration is necessary on RPi3 in order to reach optimal performance. The implementation we're using is doing just that, resulting in much better performance.

Even though Epiphany isn't as well-known as Chromium, the developer console it offers is robust and matches the functionality of Chrome dev tools.

RPi4

 

Raspberry Pi4 allows debugging the device by standard Native Debug which needs to be turned on in Box. After turning it on you just need to open your browser, type about://inspect and the device should appear in remote target. Click on it and start debugging :)

RPi3 or NEC compute mode

Prerequisities

Install Epiphany browser (a.k.a. Gnome-web)

Prerequisities

# Download compressed image
wget https://2.signageos.io/bin/epiphany/docker-epiphany_3.28.6_webkitgtk-2.26.4.tar.gz
# Import docker image to your local docker instance
docker load -i docker-epiphany_3.28.6_webkitgtk-2.26.4.tar.gz
# Allow docker to access your local X11 server. Do this after every restart of host PC. (linux only)
xhost +local:docker
# For WSL 2, install Docker desktop and follow Xming "Windows with WSL2" setup
# Start epiphany sandboxed session. Once you close it, everything will be lost
docker run --privileged --net=host -it --rm \
	-v /tmp/.X11-unix:/tmp/.X11-unix:ro \
	-e DISPLAY=:0 \
	registry.gitlab.com/signageos/docker-epiphany:3.28.6_webkitgtk-2.26.4

The docker image's Webkit version 2.26.4 in example is compatible with our signageOS Raspberry Pi image release v1.0.1.

# Download compressed image
wget https://2.signageos.io/bin/epiphany/docker-epiphany_3.28.6_webkitgtk-2.26.4.tar.gz
# Import docker image to your local docker instance
docker load -i docker-epiphany_3.28.6_webkitgtk-2.26.4.tar.gz
# Allow docker to access your local X11 server. Do this after every restart of mac.
xhost <your_ip_address> 
# Start epiphany sandboxed session. Once you close it, everything will be lost
docker run --privileged --net=host -it --rm \
	-v /tmp/.X11-unix:/tmp/.X11-unix:ro \
	-e DISPLAY=<your_ip_address>:0 \
	registry.gitlab.com/signageos/docker-epiphany:3.28.6_webkitgtk-2.26.4
### For starting after docker is stopped.
docker start epiphany-2.26

The docker image's Webkit version 2.26.4 in example is compatible with our signageOS Raspberry Pi image release v1.0.1.

Install Ubuntu
On Windows 10 with WSL install Ubuntu 18 or newer: https://docs.microsoft.com/en-us/windows/wsl/install-win10

Install X-Server xMing app
There are several X servers you could install on Windows, but we recommend Xming. Download it and install it on your Windows 10 PC.
https://sourceforge.net/projects/xming/

xming.png

The installation process is simple: You can just accept the default settings. It will then automatically launch and run in your system tray, waiting for you to run graphical programs.

Set Your Display Environment Variable
Now, you’ll need to set the DISPLAY environment variable to point at the X server running on your Windows 10 PC. If you don’t do this, graphical applications will simply fail to launch.

To do this, run the following command in the Bash environment on your Ubuntu:

export DISPLAY=:0

wsl-export-display.png

This setting only applies to your current Bash session. If you close the window, Bash will forget it. You’ll have to run this command each time you reopen Bash and want to run a graphical application.

Install Epiphany v. 3.28.x
On Ubuntu bash run as sudo user the following installation command

sudo apt-get update
sudo apt-get install epiphany-browser

If you want to native debug the RPi with another Linux distribution and Docker you can try to use Fedora 32. The Podman needs to be used to get a working docker Podman with installation command dnf install podman podman-docker.
Please note that RPi native debug process with Fedora 32 wasn't tested from our side.

  1. Install xMing https://sourceforge.net/projects/xming/ as mentioned above
  2. Install and activate WSL2 with Ubuntu
  3. In WSL2 terminal install epiphany browser sudo apt install epiphany-browser
  4. Redirect window from WSL2 to the xMing by runnig this in the WSL2 terminal export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
  5. Get internal WSL2 IP address ifconfig eth0 | grep "inet "
  6. Modify the xMing configuration file, usually located in C:\Program Files (x86)\Xming\X0.hosts and add there the WSL2 IP address from the step above
  7. Restart the xMing (turn it off and on)
  8. In the same WSL2 terminal as before start the epiphany browser epiphany-browser

Enjoy.

Troubleshooting:
If you are debugging older webkit 2.26.1, you need to downgrad webkit2gtk-driver library.

On Ubuntu run as sudo user:

sudo apt-get update
sudo apt-get install epiphany-browser

You can verify you have the correct version by running:

sudo apt list epiphany-browser


Listing... Done
epiphany-browser/bionic-updates,now **3.28.6**-0ubuntu1 amd64 [installed]

Enable Native debug via Box

  1. Open device detail page of your Raspberry Pi
  2. Navigate to Settings
  3. Click Native under Debug section

native_debug.png

Launch Epiphany and start debugging

Once Epiphany is installed, just launch it via

epiphany-browser

The Epiphany browser will launch. Then navigate to the inspector://IP.ADDRESS.OF.RPi:9998

epiphany-inspector.png

From this point on you can start debugging, see console logs, manipulate DOM, etc.

FAQ

I cannot see the Inspected target
Please confirm you installed correct version of the Epiphany - 3.28.x. In the About you should see the following details:

epiphany-version.png

Unable to init server: Could not connect: Connection refused
This means you forgot to either turn on the xMING on Windows, or you didn't run export DISPLAY=:0 in the Ubuntu bash.

 

 

 

Was this article helpful?
0 out of 0 found this helpful
Share