COMFILE Technology's Documentation Library

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== ComfilePi's Bookworm OS ======

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.

===== Upstream Raspberry Pi Changes =====

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/

==== Migration from X11 to Wayland ====


The most significant upstream change from Raspberry Pi is the move from [[https://en.wikipedia.org/wiki/X_Window_System|X11]] to [[https://en.wikipedia.org/wiki/Wayland_(protocol)|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 [[https://github.com/any1/wayvnc|wayvnc]], making it accessible to open source clients like [[https://tigervnc.org/|TigerVNC]].
==== Moved /boot to /boot/firmware ====

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 ====

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.

==== GPIO Command Line Interface ====

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 [[https://github.com/raspberrypi/utils/tree/master/pinctrl|the pinctrl documentation]].
===== COMFILE Technology Changes =====

==== One config.txt File for All Models ====

The ComfilePi Bookworm OS image's default //config.txt// file now has configurations for all CPi panel PC models, [[https://www.raspberrypi.com/documentation/computers/config_txt.html#the-edid-filter|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.

==== ComfilePi Desktop Menu ====

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.

{{ :comfilepi:bookworm:comfilepi-menu.png }}


==== New Partition Layout ====

The  ComfilePi Bookworm OS now has the following partition layout:

^  Label  ^  Size                  ^  Mount Point    ^  File System  ^  Description                                                  ^
| bootfs  | 256MB                  | /boot/firmware  | FAT32         | System firmware (i.e. bootloader, kernel, and configuration)  |
| datafs  | 1GB                    | /data           | Ext4          | User data partition                                           |
| rootfs  | Fills Remaining Space  | /               | Ext4          | Root file system (i.e. the actual operating system)           |

This layout was created to make it easier to [[#enabling_disabling_the_read-only_file_system_overlay|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 [[https://gparted.org/|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.
==== Preserving Changes to System Files ====

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:

  - Disable the read-only file system overlay, and reboot
  - Move the file from the //rootfs// partition to an analogous location on the //datafs// partition.
  - [[https://manpages.debian.org/bookworm/coreutils/ln.1.en.html|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''
  - 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 [[https://manpages.debian.org/bookworm/network-manager/nmcli.1.en.html|nmcli]] can be used as one normally would to configure those connections without having to first disable the read-only file system overlay.



==== Enabling/Disabling 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...

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

**Important** Due to [[https://github.com/RPi-Distro/raspi-config/pull/225|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:
  - Run ''sudo cpi-enable-overlay''
  - Reboot

To disable the read-only file system overlay:
  - Run ''sudo cpi-disable-overlay''
  - Reboot

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

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.

==== The ComfilePi Debian Package Repository ====

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.

==== Installing .NET ====

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 [[https://dotnet.microsoft.com/en-us/download/dotnet/scripts|installation script]] as documented [[:comfilepi:dotnet_core_development#install_the_net_sdk_on_the_comfilepi|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 [[:comfilepi:dotnet_core_development:remote_debugger:index|debugging .NET 5+ applications]] out of box and more convenient.  It installs the ''vsdbg'' executable to ///opt/Microsoft/vsdbg///.