The ComfilePi Bookworm OS is derived from the Raspberry Pi's Bookworm OS, which itself is derived from Debian's Bookworm OS.

The ComfilePi Bookworm OS introduces several significant changes to the prior Bullseye, Buster, and Stretch OS releases – some introduced by upstream Raspberry Pi, and some introduced by COMFILE Technology.

If you have an existing solution currently deployed to Stretch, Buster, or Bullseye OS variants, it is recommended that you do not upgrade to Bookworm unless you have a compelling reason to do so. If you are embarking on a new solution, it is recommended that you do upgrade to Bookworm.

See the following blog posts from Raspberry Pi to become familiar with the changes introduced in the upstream Raspberry Pi OS.

• https://www.raspberrypi.com/news/bookworm-the-new-version-of-raspberry-pi-os/
• https://www.raspberrypi.com/news/a-new-release-of-raspberry-pi-os/

The most significant upstream change from Raspberry Pi is the move from X11 to Wayland and the labwc compositor. X11 applications will still run under Wayland and labwc through the XWayland compatibility layer, but features such as autostart, DPMS, and fullscreen may operate, or need to be configured, differently.

Along with Wayland, VNC is now enabled using wayvnc, making it accessible to open source clients like TigerVNC.

The bootfs partition is now mounted at /boot/firmware instead of /boot. Files such as /boot/config.txt and /boot/comdline.txt must now be found at /boot/firmware/config.txt and /boot/firmware/cmdline.txt respectively.

Automatically running programs when the system boots must now be done by editing the $HOME/.config/labwc/autostart file. For the ComfilePi Bookworm OS, the $HOME directory for the default user has been moved to the datafs partition, so any changes to any files in the $HOME directory will be retained even when the read-only file system overlay is enabled.

Bookwoorm now introduces the pinctrl command for configuring and controlling GPIO pins from a terminal. This supersedes the raspi-gpio and gpio commands in prior OS variants. For more information see the pinctrl documentation.

The ComfilePi Bookworm OS image's default config.txt file now has configurations for all CPi panel PC models, filtered by EDID. Therefore, it is no longer necessary to replace the config.txt file with the model-specific one prior to booting, though doing so is recommended.

The desktop menu, now has a ComfilePi menu with a number of utilities and example programs to make it easier to use and learn the features of the ComfilePi panel PCs.

The ComfilePi Bookworm OS now has the following partition layout:

This layout was created to make it easier to enable the read-only file system overlay, effectively making the bootfs and rootfs partitions read-only, while still having a place to write data to (i.e. the datafs partition).

If the datafs partition is too small, and your SD card, eMMC, or other storage medium is large enough, you can use gparted, or other disk partitioning utility, to adjust partition sizes as needed. Currently, the rootfs partition must be the last partition of the disk to maintain compatibility with some configuration utilities of the Raspberry Pi.

If you need a file on the rootfs partition to be read-write even when the read-only file system overlay is enabled, consider the following method:

1. Disable the read-only file system overlay, and reboot
2. Move the file from the rootfs partition to an analogous location on the datafs partition.
3. Create a symbolic link on the rootfs partition that points to the file on the datafs partition. e.g. ln -s /data/etc/default/locale /etc/default/locale
4. Reenable the read-only file system overlay and reboot

Once rebooted, any write to the rootfs file (e.g. /etc/default/locale) will actually be written to the corresponding datafs file (e.g. /data/etc/default/locale) even while the read-only file system overlay is enabled.

Several system configuration files are already symbolically linked to the datafs partition by default. For example, the files /etc/NetworkManager/system-connections/ethernet.nmconnection and /etc/NetworkManager/system-connections/wifi.nmconnection that hold the Ethernet and WiFi settings respectively are already symbolically linked to corresponding files on the datafs partition, so nmcli can be used as one normally would to configure those connections without having to first disable the read-only file system overlay.

The read-only file system overlay is not enabled by default, however, after configuring the operating system, enabling the read-only file system overlay is highly recommended as it can…

1. …protect the bootfs and rootfs file systems from corruption
2. …increase the longevity of the storage device's flash memory, and
3. …provide the ability to withstand an abrupt loss of power without requiring shutdown.

Important Due to this bug, please do not use raspi-config or the Raspberry Pi Configuration program to enable or disable the read-only file system overlay. Use the following procedures instead:

To enable the read-only file system overlay:

1. Run sudo cpi-enable-overlay
2. Reboot

To disable the read-only file system overlay:

1. Run sudo cpi-disable-overlay
2. Reboot

You can also use the Readonly File System Overlay application from the ComfilePi desktop menu to enable/disable the readonly file system overlay.

To make room for the datafs partition and to better optimize the Bookworm OS for typical use cases, we've removed a number of different software packages. One of those is gvfs which is responsible for automounting USB drives. If you need USB drives to be automatically mounted as they had been in prior OS releases, simply run sudo apt install gvfs to install that feature.

COMFILE Technology has created a ComfilePi Debian package repository so users can obtain our operating system features and updates using the apt package manager. The repository is already configured by default in the ComfilePi Bookworm OS image. Packages from the ComfilePi repository are named with a cpi- prefix (e.g. cpi-dotnet-sdk-8.0).

To install packages from the ComfilePi repository, run sudo apt update followed by sudo apt isntall cpi-package-name. Running sudo apt update followed by sudo apt full-upgrade will also upgrade packages installed from the ComfilePi repository.

Microsoft has not yet released .NET 8~9 Debian packages for ARM64 devices, so installing the .NET SDK or .NET runtime must be done through an installation script as documented here.

To make installing .NET more convenient we've published the following packages to the ComfilePi package repository:

• cpi-dotnet-aspnetcore-runtime-8.0
• cpi-dotnet-aspnetcore-runtime-9.0
• cpi-dotnet-runtime-8.0
• cpi-dotnet-runtime-9.0
• cpi-dotnet-sdk-8.0
• cpi-dotnet-sdk-9.0

Installing one of those packages will automatically download and run Microsoft's installation script, and make any necessary OS configuration changes.

At this time, only one of the above .NET packages can be installed at a time; installing another will automatically uninstall the first.

The cpi-aspnetcore-runtime-8.0 package is installed by default.

A package called cpi-vsdbg is also installed by default to make debugging .NET 5+ applications out of box and more convenient. It installs the vsdbg executable to /opt/Microsoft/vsdbg/.