Proposal for "Beginner's guide" wiki article

[thomas4f]

Hello,

I recently built a raspberry pi-powered digital picture frame and found this awesome project. Thank you!

Although the "Getting Started" wiki article serves its purpose, perhaps a "companion" article that provides some additional details would be helpful for novice Raspberry Pi users?

Granted, there are other articles on the Internet that covers how to build a Raspberry Pi digital picture frame, but they may be long-winded and recommend installing an entire Desktop Environment, which I found is not necessary.

Since I*m in the habit of documenting how I deploy/configure my projects, I thought I'd share my step-by-step gist, which I tried to make concise and to-the-point. Feel free to add it to the wiki if you consider it to add any value.

Furthermore, the "Getting Started" as well as "Running As Service" articles suggest different methods of configuring the OS depending on the Raspberry Pi model. I don't own a Raspberry Pi 4 to test with, but I suspect a dual approach may not be necessary if the OS and software is configured in the way that I documented.

Edited to add: If someone would be willing to try and confirm whether my instructions above do in fact work as expected on a Raspberry Pi 4 I'd be very interested to hear the result.

[paddywwoof]

@thomasedoff

Thanks for that comprehensive description, and especially the Configure Xorg lines - I wasn't aware of that method to avoid sudo in the systemctl file (it might be that Wolgang or Helge mention it, and I am just behind the times!)

Did you use Wolfgang's, also excellent, documentation here. I think it would be a good idea to put a link to it as it covers a lot of different eventualities. The "problem" is that there are now a host of different hardware, OS and graphic card setups and people might miss that your instructions might not work unless they are using a Raspberry Pi 2 - there are problems getting reasonable frame rate with bullseye unless Galmor is selected in raspi-config - it might be worth putting that fact in bold, or highlighting it in some way before someone with a RPi4 starts following your instructions.

[thomas4f]

@paddywwoof

Thank you for the feedback. For clarity, although it is not (yet) explicitly mentioned in the gist, it is based upon Raspberry Pi OS / Debian 11 (“bullseye”). In my testing on a Pi 2, I did not notice any issues with FPS regardless of GL, Glamor or use_glx settings when deploying it as I documented it.

But, now that you mention it, I do vaguely remember seeing poor FPS when I initially familiarized myself with project and deployed a "full" Desktop install.

I'll do some more testing (also with a Raspberry Pi 3) and update the gist accordingly.

Edit: I could use glxgears, but is there any way to record/display the FPS from within pi3d or picframe?

[helgeerbe]

Thanks for the guide. Please do some testing with 'Glamor'.
I guess, starting with "bullseye" we can clean up and simplify the documentation. It seems to me, that @thomasedoff description should work with pi's all kind of hardware flavors (beside different settings e. g. memory_split).

[paddywwoof]

Hi, I think there is a bit of variability depending on what's being rendered i.e. 'vertex' workload or 'fragment' workload. I think I found that the speed of the (new) mesa drivers was more pixel dependent that the original Broadcom GLES ones. I'm not sure of the size of your display but it looks quite small (c.f. 4k monsters)

Keeping track of FPS inside the pi3d.Display has cropped up before. As there is functionality in the main loop for throttling to a specified FPS this would be an almost zero cost statistic to keep. I will have a look at doing that.

Paddy

[thomas4f]

Hello all,

I did some testing and these are my findings.

On my Raspberry Pi 2 Model B Rev 1.1 and Raspberry Pi 3 Model B Rev 1.2 there are no major differences between using the default drivers in Bullseye and those installed by gldriver-test, provided that Glamor is enabled (because if it isn't performance slows to a crawl).

I did the testing with glxgears at 1920x1080 1024x768 as such:

vblank_mode=0 xinit /usr/bin/glxgears -samples 2 -fullscreen

The results, in brief (they are extremely similar on the two devices):

Setting	Result
Default	65.044 FPS
gldriver-test w/o Glamor	5.137 FPS
gldriver-test w/ Glamor	67.015 FPS

Edit: Regarding these results, see my post below discussing some confusion on what gldriver-test actually is.

During my testing, I did realize that installing gldriver-test (either with sudo apt-get install gldriver-test or sudo raspi-config nonint do_gldriver) does NOT enable Glamor. So evidently there was a mistake in my documentation, since gldriver-test was included in the list of dependencies.

So, with a model 2 or 3 connected to a non-4k display, my assessment is that you can go either with the default driver or with gldriver-test and glamor. I don't know the first thing about variability as the result of vertex/fragment workloads, but if someone would be wiling to confirm that gldriver-testt+glamor "typically" works better in most scenarios/on most devices, it would be easier to make a decision on how to structure the documentation.

For now, I've simply removed gldriver-test from the list of dependencies as opposed to suggesting the installation of experimental drivers without any significant performance improvements. But another option would be to simply add another section that may be specific to - for example - the model 4. The good news is that it would be very short and not in conflict with the current instructions.

As far as I can tell, the only additions would be something in the lines of:

# Model 4/Zero/foo/bar owners, consider the following settings.
sudo raspi-config nonint do_gldriver  # Enable experimental desktop GL driver
sudo raspi-config nonint do_glamor 0 # Enable glamor graphics acceleration

And oh, I also added a recommendation to enable glx in the picframe config.

I'd be happy to hear your thoughts on all of this! :)

By the way, when (re)installing my devices, I took notes of what dependencies solves what errors. Perhaps this could be added to the Q/A.

ImportError: libopenjp2.so.7: cannot open shared object file: No such file or directory
libopenjp2-7

AttributeError: 'NoneType' object has no attribute 'glActiveTexture'
libgles-dev

Original error was: libcblas.so.3: cannot open shared object file: No such file or directory
libatlas3-base

AttributeError: module 'pyxlib.glx' has no attribute 'XRenderFindVisualFormat'
libxrender-dev

[thomas4f]

Hello again,

I was quite tired last night. Considering the similar results between the "Default" and "gldriver-test w/ Glamor" results, could it be that the latter is enabled by default in Bullseye?

Assuming that G2 GL (Full KMS) OpenGL desktop driver with full KMS in raspi-config corresponds to vc4-kms-v3d in /boot/config.txt, that would seem to be the case. Since dtoverlay=vc4-kms-v3d was NOT commented out by default (e.g. it's enabled).

Actually, in my previous post, I mistakenly confused the gldriver-test packge with the full kms driver. I realize now that that package contains systemd services pertaining to fbturbo and glamor, and not the actual driver.

Speaking of, /usr/lib/systemd/scripts/glamor_test.sh suggests that there are some specific configuration for the Model 4:

#!/bin/bash

# Glamor should run unless the platform is not Pi 4 and the legacy driver is not in use.

if ! raspi-config nonint is_pifour && raspi-config nonint is_kms ; then
        if ! [ -e /usr/share/X11/xorg.conf.d/20-noglamor.conf ] ; then
                cat > /usr/share/X11/xorg.conf.d/20-noglamor.conf << EOF
Section "Device"
        Identifier "kms"
        Driver "modesetting"
        Option "AccelMethod" "none"
EndSection
EOF
        fi
else
        if [ -e /usr/share/X11/xorg.conf.d/20-noglamor.conf ] ; then
                rm /usr/share/X11/xorg.conf.d/20-noglamor.conf
        fi
fi

Also, given the fact that it works so well (at least of the box on Model 2 and 3) it is curious that the gldriver-test package is installed automatically by raspi-config simply by ENTERING the A2 GL Driver menu, regardless of the user making a change or not.

As you can tell, I am slightly confused. Perhaps someone more knowledgeable about the drivers could bring some clarity. But I'll redo the tests now that I have a slightly better understanding of how raspi-config interacts with the system and how Xorg loads modules/submodules.

[helgeerbe]

I updated my frame on pi 3B+ to bullseye (update, not fresh install).

My screen resolution is 1920x1200, so I expect a lower framerate. But I never came near your numbers.

GPU memory is set to 256. I boot to console and run your glxgears test over ssh.

G1 Legacy Default no GL driver
18 frames in 5.2 seconds = 3.441 FPS

G2 Full KMS w/o glamor
18 frames in 5.1 seconds = 3.526 FPS

G2 Full KMS w glamor
94 frames in 5.0 seconds = 18.654 FPS

[paddywwoof]

I've just (eventually) got round to testing a few things on bullseye and bullseye 64. I realize that there need to be a bit of tidying up in the standard instructions: raspi-config looks to have changed quite a lot. However following @thomasedoff instructions, on the RPi4 at any rate, everything seems to run pretty well, so I think you are right that this is, in fact, a much better way to set things up (and I humbly withdraw my previous comments!). I had difficulty installing pillow using pip - it said it couldn't find it as a wheel and tried to compile it but was missing jpeg header files, resulting in several pages of red text. Could well have been something I missed from previous steps but I just apt install python3-pillow to bypass it... I probably ought to go through the process again and pay more attention!

I only have a fairly small monitor for testing RPis but I thought it might be worth having a FPS testing routine that would see how much vertex and fragment capacity the different drivers have, it would be more comparable across different setups. See below, it assumes that it is in the pi3d_demos folder which has the relevant images that it loads from the pi3d_demos/textures folder, if you don't want to clone that then just change the paths to a couple of images you do have, also take out the line import demo which is only to force loading of the locally hacked develop branch of pi3d.

import time
import demo
import pi3d

DIMS = [1, 2, 4, 8]
SIDES = [8, 32, 128, 256]
TEST_TM = 3.0

display = pi3d.Display.create()
full_width = display.width
full_height = display.height
shader = pi3d.Shader("uv_reflect")
pattern = pi3d.Texture("textures/PATRN.PNG")
normal = pi3d.Texture("textures/mudnormal.jpg")
camera = pi3d.Camera()

for factor in DIMS:
    (width, height) = (full_width // factor, full_height // factor)
    display.resize(x=(full_width-width)//2, y=(full_height-height)//2, w=width, h=height)
    for sides in SIDES:
        sphere = pi3d.Sphere(sides=sides, slices=sides, z=1.25)
        sphere.scale(1.0, 1.0, 0.25)
        sphere.set_draw_details(shader, [pattern, normal, pattern],  2, 0.2)
        sphere.set_material((1.0, 0.8, 0.0))
        frames = 0
        start_tm = time.time()
        while display.loop_running():
            sphere.rotateIncZ(0.111)
            sphere.draw()
            tm = time.time()
            frames += 1
            if tm > (start_tm + TEST_TM):
                break
        print("{:.1f}fps screen pixels:{}, vertices{}".format(
            frames / (tm - start_tm),
            width * height,
            sphere.buf[0].array_buffer.shape[0]))

[thomas4f]

Hello,

Thank you for the feedback!

@helgeerbe, it appears as if the resolution during my previous tests was 1024x768 (not 1920x1080), as reported by xrandr (as well as the display OSD):

DISPLAY=:0 xrandr -q
Screen 0: minimum 320 x 200, current 1024 x 768, maximum 2048 x 2048
HDMI-1 connected primary 1024x768+0+0 (normal left inverted right x axis y axis) 800mm x 335mm

Switching on-the-fly to 1920x1080 (my display does not support 1920x1200) with xrandr while running glxgears the the results become:

DISPLAY=:0 xrandr -s 1920x1080

(II) modeset(0): Allocate new frame buffer 1920x1080 stride
254 frames in 5.0 seconds = 50.705 FPS
236 frames in 5.0 seconds = 47.179 FPS
236 frames in 5.0 seconds = 47.165 FPS

Sorry about that!

I just did another test using an extremely simple setup on a Raspberry Pi 3 Model B+. No tweaks, changing drivers or other stuff. All defaults.

System info:

Raspberry Pi 3 Model B Plus Rev 1.3
Debian 11.3 (32-bit)
glamor X acceleration enabled on VC4 V3D 2.1
Resolution: 1024x768

The test routine is as follows:

sudo apt-get update
sudo apt-get upgrade -y

sudo apt-get install -y --no-install-recommends \
  xserver-xorg \
  xserver-xorg-legacy \
  xinit \
  mesa-utils \
  x11-xserver-utils
  
sudo sed -i 's/\(^allowed_users=\).*/\1anybody/' /etc/X11/Xwrapper.config
sudo bash -c 'echo "needs_root_rights=yes" >> /etc/X11/Xwrapper.config'

sudo reboot

cat /proc/cpuinfo 
cat /etc/os-release

vblank_mode=0 xinit /usr/bin/glxgears -samples 2 -fullscreen -- /usr/bin/Xorg -verbose 6

335 frames in 5.0 seconds = 66.931 FPS

The full output of the session.

As you can see, glamor is enabled by default (at least on this specific device).

I'll update this post with the test provided by @paddywwoof shortly.

Update

Expanding on the routine above, here's how I prepared my system for- and ran paddy's script:

sudo apt-get install -y --no-install-recommends \
  libgles-dev \
  libatlas3-base \
  python3-pip

# Note, looks like piwheels.org was down for a few hours today, contributing the the build failures pointed out above. A temporary workaround was to install missing dependencies via APT instead. Normally this should not be necessary!
# sudo apt-get install -y --no-install-recommends python3-pillow

python3 -m pip install pi3d

mkdir /home/pi/textures

wget https://github.com/pi3d/pi3d_demos/raw/master/textures/PATRN.PNG -P /home/pi/textures/
wget https://github.com/pi3d/pi3d_demos/raw/master/textures/mudnormal.jpg -P /home/pi/textures/

cat << EOF > /home/pi/demo.py
import time
import pi3d

DIMS = [1, 2, 4, 8]
SIDES = [8, 32, 128, 256]
TEST_TM = 3.0

display = pi3d.Display.create()
full_width = display.width
full_height = display.height
shader = pi3d.Shader("uv_reflect")
pattern = pi3d.Texture("/home/pi/textures/PATRN.PNG")
normal = pi3d.Texture("/home/pi/textures/mudnormal.jpg")
camera = pi3d.Camera()

for factor in DIMS:
    (width, height) = (full_width // factor, full_height // factor)
    display.resize(x=(full_width-width)//2, y=(full_height-height)//2, w=width, h=height)
    for sides in SIDES:
        sphere = pi3d.Sphere(sides=sides, slices=sides, z=1.25)
        sphere.scale(1.0, 1.0, 0.25)
        sphere.set_draw_details(shader, [pattern, normal, pattern],  2, 0.2)
        sphere.set_material((1.0, 0.8, 0.0))
        frames = 0
        start_tm = time.time()
        while display.loop_running():
            sphere.rotateIncZ(0.111)
            sphere.draw()
            tm = time.time()
            frames += 1
            if tm > (start_tm + TEST_TM):
                break
        print("{:.1f}fps screen pixels:{}, vertices{}".format(
            frames / (tm - start_tm),
            width * height,
            sphere.buf[0].array_buffer.shape[0]))
EOF

vblank_mode=0 xinit /usr/bin/python3 /home/pi/demo.py

... And the results, still on a ("default") model 3 plus at 1024x768:

33.3fps screen pixels:786432, vertices99
32.7fps screen pixels:786432, vertices1155
30.1fps screen pixels:786432, vertices16899
25.5fps screen pixels:786432, vertices66563
126.0fps screen pixels:196608, vertices99
125.4fps screen pixels:196608, vertices1155
108.1fps screen pixels:196608, vertices16899
75.5fps screen pixels:196608, vertices66563
489.8fps screen pixels:49152, vertices99
476.4fps screen pixels:49152, vertices1155
310.3fps screen pixels:49152, vertices16899
152.2fps screen pixels:49152, vertices66563
786.9fps screen pixels:12288, vertices99
783.8fps screen pixels:12288, vertices1155
587.3fps screen pixels:12288, vertices16899
207.4fps screen pixels:12288, vertices66563

The above results were previously capped at 75fps due to me forgetting to set vblank_mode when running the demo. This has been updated.

[helgeerbe]

OK, we have the same hardware and the same driver settings. If I reduce the geometry (1920x1200 is the physical resolution) I have better frame rates.

vblank_mode=0 xinit /usr/bin/glxgears -geometry 1024x768+0+0 -samples 2 -- /usr/bin/Xorg -verbose 6

225 frames in 5.0 seconds = 44.807 FPS
225 frames in 5.0 seconds = 44.856 FPS
225 frames in 5.0 seconds = 44.841 FPS

... And the results, of @paddywwoof tests model 3 plus at 1920x1200:

11.5fps screen pixels:2304000, vertices99
11.1fps screen pixels:2304000, vertices1155
10.5fps screen pixels:2304000, vertices16899
9.7fps screen pixels:2304000, vertices66563
40.0fps screen pixels:576000, vertices99
41.8fps screen pixels:576000, vertices1155
39.3fps screen pixels:576000, vertices16899
32.6fps screen pixels:576000, vertices66563
118.4fps screen pixels:144000, vertices99
162.4fps screen pixels:144000, vertices1155
133.7fps screen pixels:144000, vertices16899
85.5fps screen pixels:144000, vertices66563
447.6fps screen pixels:36000, vertices99
402.5fps screen pixels:36000, vertices1155
238.6fps screen pixels:36000, vertices16899
125.0fps screen pixels:36000, vertices66563

[sapnho]

Let's just make sure that all these changes also work with 4K monitors as this is where the issue with Bullseye really came up.

[thomas4f]

Yep!

To sum up, I've tested:

• Raspberry Pi 2 Model B Rev 1.1
• Raspberry Pi 3 Model B Rev 1.2
• Raspberry Pi 3 Model B Plus Rev 1.3

... All with, what I assume, is acceptable results for resolutions up to 1920x1080. But I can't really say for sure because I have not seen any posts describing what FPS people are expecting to see at different resolutions. But with respect to the fact that the default setting in configuration.yaml is fps: 20.0, it's looking good.

That said, I don't think the method I suggested actually change anything in terms of drivers or configuration. It's just a (in my opinion), "clean" way to deploy a current OS and software stack without any unnecessary components. As I understand it, the solution for getting reasonable frame rate with bullseye is to run Full KMS (aka VC4 V3D) with glamor enabled. This is the default (at least on the models I tried), and the guide stick to those defaults.

I am hesitant to think that bullseye have introduced severe regressions affecting modern hardware as the model 4. Hopefully someone with a model 4 will post their results for 4k to confirm.

[thomas4f]

Hello again,

I think I just confirmed some (to me) weird behavior affecting non-model 4 devices. I'm not sure if this has contributed to people reporting intermittent FPS issues.I touched on the subject a couple of days ago, but it was 3 AM and I wasn't able to make sense of it.

Here goes ...

• As soon as you enter the the A2 GL Driver menu in raspi-config, the script checks for- and installs gldriver-test if it's missing.
• When setting up gldriver-test, the glamor-test service is installed, started and enabled.
• The service executes /usr/lib/systemd/scripts/glamor_test.sh, which has the following code:
• if ! raspi-config nonint is_pifour && raspi-config nonint is_kms ; then [create] /usr/share/X11/xorg.conf.d/20-noglamor.conf.
• Since my device is NOT a model 4, and kms IS enabled, glamor is disabled (via 20-noglamor.conf).

E.g: On non-model 4 devices, although it being enabled by default, glamor is automatically disabled simply by entering the GL Driver menu without explicitly asking or notifying the user. Regardless of the user actually making any changes within the menu. Which, as regards to picframe, evidently has a detrimental effect on performance.

This can easily be resolved by re-enabling glamor with sudo raspi-config nonint do_glamor 0. But I don't understand the logic behind this procedure.

[paddywwoof]

I need to check this out again (I'm using the RPi monitor for my normal desktop at the moment but will swap back later) but on RPi4 with bullseye 32 and 64 bit I couldn't find any GL driver settings, including glamor. Maybe the tool has been "fixed" and introduced some errors. I will also try bullseye on some other Pis I have lying around here.

Thanks again for helping streamline this aspect of setting the system up.

Paddy

[helgeerbe]

I reinstalled bulleseye on my

• Raspberry Pi 3 Model B Plus
• Display 1920x1200

following @thomasedoff gist step-by-step gist.

The following changes where necessary.

1. DISPLAY ON/OFF

The firmware command vcgencmd display_power does no longer work. You have to use xset to turn the display on/off

To install xset

sudo apt-get install x11-xserver-utils

Enable screen blanking

sudo raspi-config nonint do_blanking 0                         # Enable Xorg screen blanking

2. Graphics acceleration

On raspi 3 glamor graphics acceleration is disabled by default.

Enable glamor and extend memory:

sudo raspi-config nonint do_glamor 1
sudo raspi-config nonint do_memory_split 256

3. Configure picframe

At the moment, graphic acceleration is not as performant on bullseye as on the legacy systems like buster. So I changed the fps from 20 to 14 to get a smother blending.

sed -i 's/\(^  fps: \).*/\114/' /home/pi/picframe_data/config/configuration.yaml

4. Autostart picframe on boot

By default screen blanking and screensaver timeouts are activated under X. So before running picframe it has to be deactivated.

This could be done in a shell script:

cat << EOF > /home/pi/start_picframe.sh
#!/bin/sh

xset -display :0 dpms 0 0 0 &
xset -display :0 s off &
/usr/bin/python3 /home/pi/.local/bin/picframe /home/pi/picframe_data/config/configuration.yaml
EOF

So the start script for the service looks like

cat << EOF > /home/pi/.config/systemd/user/picframe.service
Description=PictureFrame

[Service]
ExecStart=xinit /home/pi/start_picframe.sh
Restart=always

[Install]
WantedBy=default.target
EOF

5. Silent boot

To get rid off the boot messages and the logo

1. Quit boot: Add quiet to the /boot/cmdline.txt
2. Disable Pi logo's: Add logo.nologo to the /boot/cmdline.txt file
3. Mute kernel logs (only show critical errors): Add loglevel=3 to the /boot/cmdline.txt file
4. Remove blinking cursor: Add vt.global_cursor_default=0 to the /boot/cmdline.txt file

So my /boot/cmdline.txt looks like this now

console=serial0,115200 console=tty1 root=PARTUUID=539f5085-02 rootfstype=ext4 fsck.repair=yes rootwait quiet logo.nologo loglevel=3 vt.global_cursor_default=0

This should leave you with only a black screen until the terminal shortly appears and picframe is started.

5 What's missing

Actual picframe's internal display on/off is not working. I will add a config item in configuration.yml to decide which method should be used to blank the screen.

display_power: 0                          # default=0. choices={0, 1}, 0 will use legacy `vcgencmd` and 1 will use `xset` to blank the display

[sapnho]

Thanks Helge! It's a pity that #3 is still not how it used to be with Buster. Especially on a large 4K screen, I would expect it to be still quite visible.

[helgeerbe]

Just committed display_power setting into dev branch.

I will create a guide in the wiki based on @thomasedoff work. I assume, it should work with Pi3 and Pi4.

Writing this, I'm wondering if the GPU memory setting (raspi-config) has still some performance impact under bullesye?

[rock-meister]

Is there an updated "Beginner's guide" with the proposed changes? I looked in the wiki and could find it.
Thanks

[paddywwoof]

I think @sapnho is busily looking at his instructions on thedigitalpictureframe.com w.r.t these changes

[paddywwoof]

I'm thinking there might be quite a few changes needed soon if the latest RPi (so the supported OS?) is planning to use Wayland instead of X server for the desktop. Maybe wait till after that before redoing the wiki!

[rock-meister]

I see that Raspberrypi has released the port of Debian Bookworm which has Wayland. Has anybody installed picframe successfully on it? It's not clear how to replace X server package... I am assuming that one would use QTile... any pointers would be helpful.
Thanks

I'm thinking there might be quite a few changes needed soon if the latest RPi (so the supported OS?) is planning to use Wayland instead of X server for the desktop. Maybe wait till after that before redoing the wiki!

[paddywwoof]

Hi @rock-meister just starting to work my way through some of the issues with bookworm see #333 (comment) From what I've seen so far Wayland shouldn't be a problem, at least on the full desktop OS all of pi3d seems to run OK. Proviso: Only run on RPi4 so far and I've not tried any of @thomasedoff tips as listed in this thread so running on a RPiZero might be a different story.

[paddywwoof]

@rock-meister I've updated my findings on #333 It still has a different process for Raspberry Pi versions before 4. We shall see soon what differences there are for version 5!

[rock-meister]

Thanks, @paddywwoof. I have Raspberry Pi 3B+ and will try the instructions over the weekend.