跳转到内容
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 “下一步”