How to build a gorgeous digital photo frame with a Raspberry Pi based on 2023 Bookworm

The recent 2023 Raspberry Pi operating system update Bookworm has introduced several breaking changes that required a complete rewrite of the instructions.

I am very grateful that the developers of Pi3D PictureFrame, Paddy and Helge, have taken on the challenge.

For more background, I recommend reading the original Raspberry Pi setup article and the background article on PictureFrame, the software that creates those wonderful image transitions.

Installation of Raspberry Pi OS

The easiest way to install Raspberry Pi is to download the Raspberry Pi Imager.

Select your Raspberry Pi model, and choose Raspberry Pi OS Lite (64-bit) under “Operating System” and “Raspberry Pi (other)”.

Under “Storage”, select your SD card. Click “Next”, add your OS customization data, and enter some default settings like the name of your pi (hostname), password, wifi, and language & time settings.

Finish by clicking on “Write”.

Once you’re done, remove the SD card from your Mac/PC and insert it into your Raspberry Pi. Connect your power supply and wait for the boot process to finish.

In my original configuration article, there are a lot more details, so if you are struggling with this part, go back and take the time to read it.

After you have connected to your Pi via the Terminal enter

sudo apt update
sudo apt upgrade -y
sudo apt install python3-venv git libsdl2-dev wayfire wlr-randr -y

to run the latest updates and to install some Python libraries.

Reboot with

sudo reboot

Then, open system configuration with

sudo raspi-config

Make the following changes:

• Under 1 System Options, choose S5 Boot/Auto Login and B2 Console Autologin
• Under 2 Display Options, choose D2 Screen Blanking and say “No”.

Go back, finish, and reboot. Connect again via Terminal.

Installing Samba network settings

Install the file-sharing software using the SMB (SAMBA) network protocol. This allows you to access your Raspberry Pi on your network to add images and program files easily and remotely.

In Terminal, install Samba, add a user and your password

sudo apt install samba -y
sudo smbpasswd -a pi

Change the SAMBA config file with

sudo nano /etc/samba/smb.conf

I recommend deleting every line by typing CTRL + K. Just hold down the keys until all lines are deleted.

Then, copy and paste this text into the file:

[global]
client min protocol = SMB2
client max protocol = SMB3
vfs objects = catia fruit streams_xattr
fruit:metadata = stream
fruit:model = RackMac
fruit:posix_rename = yes
fruit:veto_appledouble = no
fruit:wipe_intentionally_left_blank_rfork = yes
fruit:delete_empty_adfiles = yes
security = user
encrypt passwords = yes
workgroup = WORKGROUP
server role = standalone server
obey pam restrictions = no
map to guest = never
[pi]
comment = Pi Directories
browseable = yes
path = /home/pi
read only = no
create mask = 0775
directory mask = 0775

Hit CTRL + O to write the file to disk, then CTRL + X to exit the editor.

If you have any troubles with the Samba configuration, please look at my more detailed article here.

Finally, restart SAMBA:

sudo /etc/init.d/smbd restart

You should now see the name of your Raspberry Pi in your network. Connect to it using your username “pi” (in our example) and your password.

Whenever you reboot your Raspberry Pi, file sharing will automatically start.

Note: If you have a problem editing the SAMBA config file, have a look at this article.

Two add-ons to extend your SD card life and improve your Wi-Fi connection

There are two add-ons that you can install later, but I would still recommend that you take a look at my respective articles:

If you want your SD card to last longer, then I recommend installing Log2Ram. You will find the instructions here.

And if you have problems with your Wi-Fi connection, doing this may actually help. It did, for sure, in my case.

Installing Pi3D PictureFrame

Now, install the best image viewer software that no money can buy, the one and only Pi3D PictureFrame!

You should definitely read the main article on this wonderfully handcrafted piece of software.

What is new with Bookworm is that it requires the use of a virtual Python environment to prevent any unintended spillover from PictureFrame onto other Python applications.

Install the Python virtual environment with

mkdir venv_picframe
python -m venv /home/pi/venv_picframe
source venv_picframe/bin/activate

Now, install PictureFrame with

pip install picframe

A number of necessary packages will be downloaded, and when you see

Successfully installed IPTCInfo3-2.1.4 Pillow-9.5.0 PyYAML-6.0.1 defusedxml-0.7.1 ninepatch-0.2.0 numpy-1.26.1 paho-mqtt-1.6.1 pi-heif-0.13.1 pi3d-2.49 picframe-2023.7.26.post1

you will know that it has worked.

Finally enter

pip uninstall picframe -y
pip uninstall pi3d -y
pip install git+https://github.com/tipam/pi3d
pip install git+https://github.com/helgeerbe/picframe@sdl2

Configuring PictureFrame

Now configure PictureFrame. You will be asked three questions for the basic configuration settings. Just hit Enter to keep the default for now. You can always change these settings later.

mkdir {Pictures,DeletedPictures}
picframe -i /home/pi/

We need to make one change in the configuration file right away. Open it with

nano ~/picframe_data/config/configuration.yaml

Search for this entry (in the upper section)

use_sdl2: False

and change it to

use_sdl2: True

Save and close.

Autostarting PictureFrame

Starting PictureFrame is a bit more complex than before, but Helge did a great job hiding the complexity with a few scripts.

Enter

nano start_picframe.sh

and paste the paragraph below

#!/bin/bash
wlr-randr --output HDMI-A-1 --off
export SDL_VIDEODRIVER=wayland 
source /home/pi/venv_picframe/bin/activate 
picframe &  
wlr-randr --output HDMI-A-1 --on

Save and close and make the file executable with

chmod +x ./start_picframe.sh

Next, enter

mkdir ~/.config/systemd/user/ -p
nano ~/.config/wayfire.ini

and paste this paragraph

[core]
plugins = autostart
xwayland = false

[autostart]
picframe = /home/pi/start_picframe.sh

Save, close, and then create yet another new file with

nano ~/.config/systemd/user/picframe.service

and paste this paragraph

[Unit]
Description=PictureFrame

[Service]
ExecStart=/usr/bin/wayfire
Restart=always

[Install]
WantedBy=default.target

Enable the service and reboot. Don’t forget to connect your display before rebooting.

systemctl --user enable picframe.service
sudo reboot

If you can see the image below, you have installed Pi3D PictureFrame on Raspberry Pi Bookworm successfully!

Add a few pictures to the Pictures directory via the network from another computer (that is why you installed Samba), and they will appear after 200 seconds (the default setting, which you have probably not changed at this point.

Customize PictureFrame to your needs in the configuration.yaml file. For all the details about fine-tuning, read this article.

Et voilà, you got Pi3D Picture Frame running with the latest Raspberry Pi operating system, Bookworm!

As it stands, your picture frame installation is now complete. But for tinkering (it never stops), knowing how to manually control the app’s launch is helpful.

More on starting and stopping

Turning the picture frame script on and off is controlled by the systemctl service.

If you want to know more about how this works, I recommend my article, “The ultimate guide on using systemd to autostart scripts on the Raspberry Pi“.

Starting and stopping PictureFrame at boot

• Enable service systemctl --user enable picframe.service
• Disable service systemctl --user disable picframe.service

This setting survives a reboot. If you choose the disable option, you will boot in the console only, and PictureFrame will not start automatically.

Manually starting and stopping PictureFrame

• Start service systemctl --user start picframe.service
• Stop service systemctl --user stop picframe.service
• Stop restart systemctl --user restart picframe.service

Still be be figured out

Only one major issue still needs to be figured out to complete the full migration of Pi3D PictureFrame.

Currently, there is no way of blanking the screen, i.e., turning the HDMI output on/off via a software command. All the previous methods, and even those that I described here, fall short.

A big Thank You to Helge, Paddy, and all the forum members who have made this migration happen.

Thank you for your support and motivation.