跳到內容
TypixNode Wiki

原版 Raspberry Pi OS 手動適配

測試基線：Raspberry Pi OS（64 位），Debian 13 “Trixie”，核心 6.18。

優先順序

Section titled “優先順序”

從上往下做。P0 決定裝置能不能用，其餘的可以晚點再弄。

改動 解決什麼 頁面
P0 SSH 或 HDMI 做其餘所有步驟的前提——原版系統下內建螢幕是黑的 本頁
P0 TypixDeck overlay + config.txt 配置塊 內建螢幕、觸控、背光、內部 USB 本頁
P1 dwc2 修復核心（僅 CM5） CM5 上內建 USB 音效卡出聲 USB 音訊核心
P1 STC3117 電量計驅動 桌面顯示電池電量 電量計與風扇
P1 鍵盤 hwdb 規則 方塊鍵不再在 GNOME / Phosh / Plasma 裡開啟設定 本頁
P2 風扇控制 + CM5 風扇曲線 風扇隨溫度調速，機殼內轉得更積極 電量計與風扇
P2 遙測服務 ESP32-S3 狀態螢幕上顯示 CPU 溫度、風扇、降頻 遙測服務
P2 桌面縮放 1.25 3.2“ 1024×768 螢幕上介面看得清 本頁
P2 MCU 刷寫工具 在裝置上升級 ESP32-S3 / 鍵盤韌體 刷寫韌體
P3 Phosh + wayvnc 觸控優先的桌面與遠端桌面 Phosh

P0.1 先拿到一個終端

Section titled “P0.1 先拿到一個終端”

原版 Raspberry Pi OS 在裝好下面的 overlay 之前，內建 DPI 螢幕一直是黑的，所以請通過 SSH 或 HDMI 顯示器完成配置：

  • SSH（推薦）： 在 Raspberry Pi Imager 的 自訂設定 裡設好使用者名稱和密碼，並開啟 開啟 SSH。 如果系統已經裝好、手邊有顯示器和鍵盤，執行 sudo systemctl enable --now ssh。
  • HDMI： micro-HDMI 口在原版系統下不需要任何改動就能用。

P0.2 編譯並安裝 overlay

Section titled “P0.2 編譯並安裝 overlay”

overlay 以 .dts 原始碼形式儲存，在裝置上編譯——和映像建置時的做法完全一樣：

Terminal window
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 對螢幕和觸控的原始碼會列印一些 unit_address_vs_reg 警告，無害，編譯結果與映像裡的 .dtbo 完全一致。

overlay 作用
vc4-kms-dpi-3inch2-1024x768 3.2“ 1024×768 DPI 螢幕（HD317001C40，JD9168S）：panel-dpi，RGB666（18 位，cpadhi），畫素時鐘 53 MHz，水平前肩/同步/後肩 46/30/44，垂直 15/5/15（總幅面 1144×803，≈57.8 Hz）
gt911-touch-3inch2-1024x768 GT911 觸控，走軟體模擬 I2C（SDA GPIO10、SCL GPIO11、4 µs），中斷 GPIO27，同時宣告 GT911 的兩個地址 0x14 和 0x5D，1024×768
pwm-backlight-3inch2-bcm CM4 / CM3 / Zero 系背光：BCM pwm 通道 0，GPIO18（ALT5），20 kHz
pwm-backlight-3inch2-rp1 CM5 背光：RP1 pwm0 通道 2，GPIO18，20 kHz
stc3117-gauge 電量計，見電量計頁面

和普通的螢幕 overlay 相比改了什麼、為什麼：

  • 背光從觸控 overlay 裡拆出來，改成兩個 PWM overlay。 原來的觸控 overlay 還在 GPIO18 上聲明瞭 gpio-backlight；同一個引腳不能同時被 gpio-backlight 和 pwm-backlight 佔用，而 PWM 才能調光。 CM5 和 BCM283x 系列的繫結寫法不同（RP1 pwm0 通道 2 對比 BCM pwm 通道 0 + ALT5）。
  • 背光掛到 /panel 節點上，DRM 開啟螢幕時會一併開啟背光。不這樣做的話，pwm-backlight 開機時檢測到 PWM 是關的，就把 bl_power 設成 4，螢幕一直黑著。這也意味著背光 overlay 必須在 DPI overlay 之後載入。
  • BCM 版 overlay 的 #pwm-cells 是 3；寫成 2 的話 PWM 申請會返回 -EINVAL，螢幕一直等背光， vc4 反覆重新繫結（黑畫面）。
  • 觸控同時宣告 0x14 和 0x5D，因為 GT911 的地址由復位時序決定；不存在的那個地址只是不會 probe。 overlay 保留了 touchscreen-inverted-x、touchscreen-inverted-y、touchscreen-swapped-x-y 引數，螢幕裝向不同時可以用。

P0.3 config.txt 配置塊

Section titled “P0.3 config.txt 配置塊”

先關掉全域性的板載音訊——在 CM4 / CM3 上它佔用的正是背光需要的那組 PWM（下面會在 CM5 上重新開啟， CM5 的音訊不用它）：

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

然後把下面這段追加到 /boot/firmware/config.txt 末尾（與 TypixDeck 系統追加的內容完全一致）：

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

重啟。內建螢幕、觸控、背光現在都能用了；電量計那幾行要先裝好電量計頁面 裡的驅動才會生效。

USB 那幾行做了什麼

Section titled “USB 那幾行做了什麼”

內部 USB 裝置（鍵盤、ESP32-S3 音效卡與狀態螢幕）都掛在一顆 FE2.1 多 TT USB 2.0 hub 後面：

  • CM4——otg_mode=1：改用 BCM2711 內建的 XHCI 控制器，不用舊的 dwc2。XHCI 能正確排程 USB 音效卡的全速等時 split 事務；走 dwc2 時音效卡能識別但放不出聲。
  • CM5——dtoverlay=dwc2,dr_mode=host：CM5 模組的 USB 引腳只連到 dwc2 控制器，所以強制它進入 host 模式。dwc2 有上面說的 split 問題，所以 CM5 還需要 dwc2 修復核心 才能出聲；除了聲音，其餘 USB 功能不需要它。

其他幾行

Section titled “其他幾行”
  • enable_uart=0——UART 引腳被 DPI 匯流排佔用。
  • Wi-Fi 天線保持模組預設（模組自帶的 PCB 天線）。要用外接 U.FL 天線介面請自行加 dtparam=ant2； 效果取決於天線擺放位置，所以 TypixDeck 系統把它留給使用者在工具箱裡選。

P1 鍵盤：讓方塊鍵不再開啟“設定”

Section titled “P1 鍵盤：讓方塊鍵不再開啟“設定””

方塊鍵用來在樹莓派和 ESP32-S3 之間切換內建螢幕。ESP32 通過鍵盤的 I2C 通道獲知這個按鍵；舊版鍵盤 韌體同時還會向樹莓派發送 F13，xkb 把它對映成 XF86Tools，GNOME / Phosh / Plasma 會因此開啟 設定（預設的 labwc 桌面會忽略它）。用一條 udev hwdb 規則把它吞掉：

Terminal window
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

新版鍵盤韌體對這個鍵什麼都不發，所以升級鍵盤韌體（見刷寫韌體）同樣能解決。

P2 桌面縮放 1.25（預設 labwc 桌面）

Section titled “P2 桌面縮放 1.25（預設 labwc 桌面）”

1.0 倍時 3.2“ 螢幕上的介面太密，而控制中心只提供 1.0 / 1.5 / 2.0。TypixDeck 系統寫入一個 1.25 倍的 kanshi 配置：

Terminal window
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

TypixDeck 系統刪掉的東西

Section titled “TypixDeck 系統刪掉的東西”

可選：sudo apt purge rpi-connect rpi-connect-lite（遠端訪問代理）；如果不用 Phosh， 還可以刪 squeekboard（螢幕鍵盤——這臺機器有實體鍵盤）。

下一步

Section titled “下一步”