Manual setup on stock Raspberry Pi OS

Tested base: Raspberry Pi OS (64-bit), Debian 13 “Trixie”, kernel 6.18.

Priorities

Work top to bottom. P0 makes the device usable at all; the rest can wait.

	Change	Needed for	Page
P0	SSH or HDMI access	Doing everything else - the built-in screen is dark on stock OS	this page
P0	TypixDeck overlays + `config.txt` block	Built-in screen, touch, backlight, internal USB	this page
P1	dwc2-fixed kernel (CM5 only)	Sound from the built-in USB sound card on CM5	USB audio kernel
P1	STC3117 battery driver	Battery percentage in the desktop	Battery & fans
P1	Keyboard hwdb quirk	Square key no longer opens Settings on GNOME / Phosh / Plasma	this page
P2	Fan control + CM5 fan curve	Fan speed follows temperature, runs harder in the case	Battery & fans
P2	Telemetry service	CPU temp, fan, throttling on the ESP32-S3 status screen	Telemetry
P2	Desktop scale 1.25	Readable UI on the 3.2“ 1024×768 panel	this page
P2	MCU flashing tools	Updating the ESP32-S3 / keyboard from the device	Flashing Firmware
P3	Phosh + wayvnc	Touch-first desktop and remote desktop	Phosh

P0.1 Get a shell

On stock Raspberry Pi OS the built-in DPI screen stays dark until the overlays below are installed, so do the setup over SSH or on an HDMI monitor:

SSH (recommended): in Raspberry Pi Imager’s Customisation step set a user name and password and turn on Enable SSH. If the system is already installed and you have a monitor and keyboard, run sudo systemctl enable --now ssh.
HDMI: the micro-HDMI port works on stock OS with no changes.

P0.2 Compile and install the overlays

The overlays are kept as .dts source and compiled on the device, exactly as the image build does:

sudo apt install -y git device-tree-compiler
git clone --depth 1 -b typixdeck https://github.com/TypixNode/pi-gen.git ~/typixdeck-pi-gen
cd ~/typixdeck-pi-gen/typixdeck-stage/01-overlays/files
for ov in vc4-kms-dpi-3inch2-1024x768 gt911-touch-3inch2-1024x768 \
          pwm-backlight-3inch2-bcm pwm-backlight-3inch2-rp1 stc3117-gauge; do
  sudo dtc -@ -I dts -O dtb -o /boot/firmware/overlays/$ov.dtbo $ov.dts
done

dtc prints some unit_address_vs_reg warnings for the display and touch sources; they are harmless, the output is identical to the shipped .dtbo files.

Overlay	What it is
`vc4-kms-dpi-3inch2-1024x768`	3.2“ 1024×768 DPI panel (HD317001C40, JD9168S): `panel-dpi`, RGB666 (18-bit, `cpadhi`), 53 MHz pixel clock, H front/sync/back 46/30/44, V 15/5/15 (1144×803 total, ≈57.8 Hz)
`gt911-touch-3inch2-1024x768`	GT911 touch on a bit-banged I2C bus (SDA GPIO10, SCL GPIO11, 4 µs), interrupt GPIO27, declared at both GT911 addresses 0x14 and 0x5D, 1024×768
`pwm-backlight-3inch2-bcm`	Backlight for CM4 / CM3 / Zero-class: BCM `pwm` channel 0 on GPIO18 (ALT5), 20 kHz
`pwm-backlight-3inch2-rp1`	Backlight for CM5: RP1 `pwm0` channel 2 on GPIO18, 20 kHz
`stc3117-gauge`	Battery gauge, used on the battery page

What was changed compared with a plain panel overlay, and why:

The backlight moved out of the touch overlay into two PWM overlays. The original touch overlay also declared a gpio-backlight on GPIO18; one pin cannot be owned by gpio-backlight and pwm-backlight at once, and PWM gives dimming. CM5 and the BCM283x chips need different bindings (RP1 pwm0 channel 2 vs. BCM pwm channel 0 with ALT5).
The backlight attaches itself to /panel, so DRM switches it on together with the panel. Without that, pwm-backlight finds the PWM off at boot, sets bl_power=4 and the screen stays black. It also means the backlight overlay must be loaded after the DPI overlay.
On the BCM overlay #pwm-cells is 3; with 2 the PWM request fails with -EINVAL, the panel waits for its backlight forever and vc4 rebinds in a loop (black screen).
Touch is declared at both 0x14 and 0x5D because the GT911 picks its address from the reset strap; whichever is absent simply does not probe. The overlay keeps the touchscreen-inverted-x, touchscreen-inverted-y and touchscreen-swapped-x-y parameters in case your panel is mounted differently.

P0.3 The `config.txt` block

First turn off the global on-board audio line - on CM4 / CM3 it drives the same PWM block the backlight needs (it is switched back on for CM5 below, where audio does not use it):

sudo sed -i 's|^dtparam=audio=on$|#dtparam=audio=on  # TypixDeck: PWM is used by the backlight|' /boot/firmware/config.txt

Then append this block to /boot/firmware/config.txt (it is exactly what TypixDeck OS appends):

# --- TypixDeck hardware ---
[cm4]
otg_mode=1
[cm5]
dtoverlay=dwc2,dr_mode=host

[all]
dtoverlay=vc4-kms-dpi-3inch2-1024x768
dtoverlay=gt911-touch-3inch2-1024x768
enable_uart=0

# PWM backlight overlays MUST come after the DPI overlay (they attach to /panel)
[cm5]
dtoverlay=pwm-backlight-3inch2-rp1
[cm4]
dtoverlay=pwm-backlight-3inch2-bcm
[pi3]
dtoverlay=pwm-backlight-3inch2-bcm
[pi0]
dtoverlay=pwm-backlight-3inch2-bcm

# On-board audio is safe where it does not sit on the BCM283x PWM block
[pi5]
dtparam=audio=on
[cm5]
dtparam=audio=on

# Fan controller (EMC2301) and CM5 fan curve - see the battery & fans page
[cm4]
dtoverlay=i2c-fan,emc2301,i2c_csi_dsi
[cm5]
dtoverlay=i2c-fan,emc2301,i2c_csi_dsi0
dtparam=cooling_fan=on
dtparam=fan_temp0_speed=130
dtparam=fan_temp1_speed=180
dtparam=fan_temp2_speed=220
dtparam=fan_temp3_speed=255

# STC3117 battery gauge - see the battery & fans page
[cm4]
dtoverlay=stc3117-gauge
[cm5]
dtoverlay=stc3117-gauge,i2c_csi_dsi0
[all]
# --- end TypixDeck hardware ---

Reboot. The built-in screen, touch and backlight now work; the battery line needs the driver from the battery page before it does anything.

What the USB lines do

The internal USB devices (keyboard, ESP32-S3 sound card and status screen) sit behind an FE2.1 multi-TT USB 2.0 hub:

CM4 - otg_mode=1: use the BCM2711’s built-in XHCI controller instead of the legacy dwc2 one. XHCI schedules the full-speed isochronous split transactions of the USB sound card correctly; through dwc2 the card enumerates but plays silence.
CM5 - dtoverlay=dwc2,dr_mode=host: on the CM5 the module’s USB pins are wired only to the dwc2 controller, so force it into host mode. dwc2 has the split bug above, which is why the CM5 also needs the dwc2-fixed kernel for sound. Everything else on USB works without it.

Other lines

enable_uart=0 - the UART pins belong to the DPI bus.
The Wi-Fi antenna is left at the module default (the module’s PCB antenna). To use the external U.FL connector add dtparam=ant2 yourself; it depends on where the antenna sits, so TypixDeck OS leaves it as a choice in its Toolbox.

P1 Keyboard: stop the square key from opening Settings

The square key toggles the built-in screen between the Pi and the ESP32-S3. The ESP32 learns about it over the keyboard’s I2C link; older keyboard firmware also sends F13 to the Pi, which xkb maps to XF86Tools, and GNOME / Phosh / Plasma open Settings on it (the default labwc desktop ignores it). Swallow it with a udev hwdb rule:

sudo tee /etc/udev/hwdb.d/90-typixdeck-keebdeck.hwdb >/dev/null <<'EOF'
# TypixDeck KeebDeck 6R11C (USB c182:6b11): drop the F13 the square key sends
evdev:input:b0003vC182p6B11*
 KEYBOARD_KEY_70068=reserved
EOF
sudo systemd-hwdb update && sudo udevadm trigger

Current keyboard firmware sends nothing for the key, so updating the keyboard (Flashing Firmware) fixes it as well.

P2 Desktop scale 1.25 (default labwc desktop)

At scale 1.0 the 3.2“ panel is too dense and the Control Centre only offers 1.0 / 1.5 / 2.0. TypixDeck OS writes a kanshi profile at 1.25:

mkdir -p ~/.config/kanshi
cat > ~/.config/kanshi/config <<'EOF'
profile {
    output DPI-1 enable scale 1.250000 mode 1024x768@57.782 position 0,0 transform normal
}
EOF
pkill -HUP kanshi

Things TypixDeck OS removes

Optional: sudo apt purge rpi-connect rpi-connect-lite (remote-access agent) and, if you do not use Phosh, squeekboard (on-screen keyboard - the deck has a real one).