PRINTDECKDOCS

Software

Printdeck OS

A small, read-only Linux system for the Printdeck, with two system slots.

A small, read-only Linux system for the Printdeck Raspberry Pi 5. It has the Printdeck program, Wi-Fi, mDNS (printdeck.local) and NTP. It has no package manager, no shell and no SSH. Buildroot makes it from source.

The debug image is the same system with SSH, sudo, a shell and tools such as strace and tcpdump.

Install

  1. Download printdeck.img.xz from the latest release.
  2. Write it to an SD card with Raspberry Pi Imager ("Use custom").
  3. Put the card in the Pi, and connect the power.

To write the image with dd:

xz -dc printdeck.img.xz | sudo dd of=/dev/sdX bs=4M conv=fsync status=progress

The image also starts from a USB drive. A Pi 5 starts from USB when no SD card is in it. To set this, run sudo raspi-config on Raspberry Pi OS: Advanced Options > Boot Order.

The first start

  1. Tap your Wi-Fi network and type its password. For a hidden network, tap Hidden.
  2. Write down the address and the password of the deck, then tap Finish.

To see the address and the password again, open Machine > Wi-Fi and help.

To see the boot messages, hold a finger on the screen for one second during the start. Start the Pi again to go back.

The setup screen of the deck with a list of Wi-Fi networks
The setup: the Wi-Fi network
The summary of the setup with the address and the password of the deck
The setup: the address and the password

Set up before the first start

Put the disk in a computer. Fill in printdeck.txt on the PRINTDECK partition:

SettingWhat it does
wifi_ssid, wifi_password, wifi_countryThe Wi-Fi network. The Pi clears the password in the file after it reads it.
ssh_keyA public SSH key for the user printdeck (debug image only)
printer.cfg (a file, next to printdeck.txt)The Klipper configuration (see "Klipper")
hostname, timezoneThe name on the network (printdeck.local) and the time zone
display_rotate, touch_invert_x, preheat_tool, ...The settings of the touch screen (see "Settings")

The login

The first start makes a password of four words, for example stamp-ocean-cider-brick. The password logs in to the web pages. In the debug image, it is also the password of the user printdeck for SSH and sudo. It is in /var/lib/printdeck/password.

The web pages

Open http://printdeck.local in a browser and log in with the password. The web server uses plain HTTP, so use it only on your own network.

Slicers

The Printdeck uses the OctoPrint API that slicers use to send files and start prints. The slicers see a printer named "Printdeck". The files go to /var/lib/klipper/gcodes.

The webcam of the API is the USB camera of the deck, or the deck screen when it has no camera:

They need the API key (X-Api-Key, or ?apikey=), or the login of the remote screen. The camera runs only while somebody looks.

Klipper

The Klipper configuration is /var/lib/klipper/config/printer.cfg. To use your own:

  1. Put your file on the PRINTDECK partition as printer.cfg.
  2. Start the Pi. It copies the file to Klipper, and renames the file on the partition to printer.cfg.imported.

The last line of printer.cfg must be this include. The import adds it:

[include /usr/share/printdeck/klipper/printdeck.cfg]

The firmware on the printer board must match the Klipper version in deck/internal/klipper/klipper.version. Machine > Maintenance > Firmware writes it.

If your configuration has a CANCEL_PRINT macro, the Cancel key runs it.

The deck can also run a simulated printer: open Machine, then Maintenance, then Simulated printer. The manual has the steps.

Settings

The settings of the deck are in /etc/printdeck/deck.env. To change one, put it in printdeck.txt in lower case, for example display_rotate=90. Then start the Pi again. The Screen row of Settings overrides display_rotate.

Update

The disk has two system slots, A and B. An update writes the other slot.

  1. Open http://printdeck.local/system.
  2. Choose printdeck-update.tar.xz (or printdeck-debug-update.tar.xz), and click Install.

Machine > Software update on the touch screen downloads and installs a release.

Update during a print

You can install an update while a print runs. The print continues:

  1. The Printdeck writes the other slot slowly, at a low priority: 4 MB a second, with nice 19 and the idle I/O class. Klipper reads the G-code file from the same SD card.
  2. The Printdeck does not restart. Machine shows "Update ready · restarts after this print".
  3. After the print, the Printdeck restarts into the new slot when the printer is idle: no print, no heater on, no touch for 2 minutes, and the bed at 35 °C or cooler. After 30 minutes, a warm bed does not stop the restart.

When no print runs, Restart now on the update page restarts at once.

During the print, "Restart the screen now" on the update page runs the screen program of the update. The screen is dark for a few seconds. Klipper keeps the print. The time lapse frames of the print and the share link continue. The key shows only when the screen program of the update works with the running Klipper: both have the same interface version. After the print, the Printdeck restarts into the new slot as above, and Klipper then updates too.

With curl:

curl -c cookies -d password=PASSWORD http://printdeck.local/login
curl -b cookies -F bundle=@os/out/printdeck-update.tar.xz http://printdeck.local/system/update

With the header X-Printdeck-Progress: 1, the request returns at once with {"error":""}, and GET /system/update/progress gives the steps. During a print, the answer is {"error":"","staged":true}: the update waits for the end of the print.

The Pi restarts into the new slot. If Klipper and the touch screen start, the new slot becomes the default. If they fail, the Pi starts the old slot again.

The system page in a browser: the version, the slot, the services, and the forms for the update, the backup and the restore
The system page, with demo values

How it works

PartitionFile systemContents
1 PRINTDECKFATautoboot.txt (the A/B switch) and printdeck.txt
2 boot A, 3 boot BFATKernel, device trees, overlays, config.txt, cmdline.txt
4 root A, 5 root BEROFSThe system, read-only
6 dataext4The changes to /etc, /var, /home and /root. It fills the disk after the first start.

Size

The release image has only what Printdeck uses. It has no Python, no sound, no shell, no BusyBox, no SSH, no sudo and no Bluetooth. board/release-prune.sh keeps a list of programs and their libraries, and removes the rest.

The kernel has only the modules in board/linux-modules.txt. The display driver (vc4) is built in, so the start screen fills the display from the first frame. The kernel start screen comes from board/firmware/printdeck-logo.tga. After a change to the start screen, run go test ./internal/ui -run SplashLogo -update-logo in deck, then os/build.sh linux-rebuild.

The kernel config

board/linux.config is the bcm2712 defconfig, reduced with make localmodconfig to the modules of board/linux-modules.txt. To add a module:

  1. Add its name to board/linux-modules.txt.
  2. Make the config again in the build container (below). Use CROSS_COMPILE=aarch64-linux-, with the cross compiler of output/per-package/linux/host/bin in PATH.
  3. Set these options to y in board/linux.config: CONFIG_DRM, CONFIG_DRM_VC4, CONFIG_SND, CONFIG_SND_SOC and CONFIG_I2C_BRCMSTB.
cd ~/.cache/printdeck-os/output/build/linux-custom
make ARCH=arm64 bcm2712_defconfig
make ARCH=arm64 LSMOD=/path/to/os/board/linux-modules.txt localmodconfig
make ARCH=arm64 savedefconfig   # then copy defconfig to board/linux.config

Files

PathWhat it is
build.sh, docker/The build script and its container
configs/printdeck_defconfigThe Buildroot configuration
board/Boot files, partitions, the kernel config, and the post-build scripts
board/rootfs/The files of the root file system: services and settings
package/The Buildroot package of the Printdeck program

Build

The build of the image is on the Build and release page.