Raspberry Pi OS Legacy Lite（32 位）下调试树莓派 Camera Rev 1.3 / OV5647

一、问题背景

最近在树莓派上调试一个老款官方摄像头模块，型号信息如下：

raspberry pi camera rev 1.3
P5V04A SUNNY

这类模组本质上通常按 OV5647 传感器来处理。

我遇到的问题主要有 3 个：

摄像头最开始无法识别。
修改 /boot/firmware/config.txt 后虽然可以识别，但图形界面一度进不去了。
通过 SSH 远程启动摄像头时，无法把预览窗口稳定显示在树莓派本地 DSI 屏幕桌面上。

这篇文章把整个排查过程整理下来，给遇到类似问题的同学一个参考。

二、我的环境

系统：Raspberry Pi OS Legacy Lite (32-bit)
摄像头：Raspberry Pi Camera Rev 1.3 / OV5647
屏幕：DSI 屏幕
连接方式：SSH

建议先确认系统版本：

bash 复制代码

cat /etc/os-release

还可以确认当前相机工具版本：

bash 复制代码

rpicam-hello --version

我机器上的输出类似这样：

text 复制代码

rpicam-apps build: v1.9.0 ...
rpicam-apps capabilites: egl:1 qt:1 drm:1 libav:1
libcamera build: v0.5.2...

说明系统已经是 rpicam/libcamera 这一套新相机栈，而不是更老的 raspistill 时代。

三、第一步：先判断摄像头有没有被系统识别

最直接的检测命令：

bash 复制代码

rpicam-hello --list-cameras

如果只是做无界面拍照测试，可以直接运行：

bash 复制代码

rpicam-still -n -o test.jpg

参数说明：

-n：不打开预览窗口
-o test.jpg：输出图片到当前目录

如果能拍出图片，说明摄像头链路基本是通的。

四、摄像头无法识别时，先改 config.txt

我的摄像头一开始识别不了，后来修改了：

bash 复制代码

sudo nano /boot/firmware/config.txt

和摄像头相关的核心配置保留为：

ini 复制代码

dtparam=audio=on
camera_auto_detect=0
display_auto_detect=1
dtoverlay=ov5647
dtoverlay=vc4-kms-v3d
max_framebuffers=2
disable_fw_kms_setup=1
disable_overscan=1
arm_boost=1

这里有两个关键点：

1. 老款 Camera Rev 1.3 需要按 `ov5647` 指定 overlay

ini 复制代码

camera_auto_detect=0
dtoverlay=ov5647

如果自动识别失败，手动指定 ov5647 往往就能让系统找到这颗传感器。

2. 不要把显示驱动 overlay 覆盖掉

很多人改相机配置时会误把下面这一行删掉：

ini 复制代码

dtoverlay=vc4-kms-v3d

这行是图形显示驱动，不是摄像头驱动。如果只保留 dtoverlay=ov5647，有可能导致桌面显示异常或无法正常进入图形环境。

修改完重启：

bash 复制代码

sudo reboot

五、修改后可以识别，但拍照时报超时错误

虽然系统已经识别到了 OV5647，但拍照时还是失败，执行：

bash 复制代码

rpicam-still -n -o test.jpg

得到的关键日志如下：

text 复制代码

INFO Camera camera_manager.cpp:220 Adding camera '/base/soc/i2c0mux/i2c@1/ov5647@36'
INFO RPI vc4.cpp:440 Registered camera /base/soc/i2c0mux/i2c@1/ov5647@36 to Unicam device
ERROR V4L2 v4l2_videodevice.cpp:1825 /dev/video0[10:cap]: Failed to queue buffer 0: Input/output error
ERROR RPISTREAM rpi_stream.cpp:276 Failed to queue buffer for Unicam Image
ERROR: Device timeout detected, attempting a restart!!!

这组日志非常关键。

它说明：

I2C 层面已经识别到传感器了
驱动也已经注册成功
真正失败发生在开始采集图像数据的时候

也就是说，这时问题通常已经不是"驱动没装好"，而更像是"摄像头链路硬件不稳定"。

六、怎么判断不是供电问题

我还检查了供电状态：

bash 复制代码

vcgencmd get_throttled

输出：

text 复制代码

throttled=0x0

这表示没有欠压，也没有降频记录。

所以到这里基本可以排除：

供电不足
电源适配器不稳定

七、这类超时错误最常见的根因

当日志已经显示：

能发现 ov5647@36
但拍照时报 Failed to queue buffer
同时伴随 Device timeout detected

大概率是下面这些问题：

摄像头排线插反了。
排线没有插到底。
排线老化或损坏。
摄像头模组本体损坏。
树莓派上的 CSI 接口接触不良。

建议按这个顺序排查

先彻底关机，不要带电插拔排线。

bash 复制代码

sudo poweroff

把树莓派端和摄像头端的排线都重新插一遍。
确认金手指方向正确、排线完全插到底。
优先换一根排线测试。
如果有条件，用另一台树莓派或另一块摄像头交叉验证。

这一步非常重要，因为软件已经把能做的基本做完了，继续改参数意义不大。

八、关于"改完 config.txt 后进不了图形界面"

这里有一个容易混淆的点。

如果你安装的是：

text 复制代码

Raspberry Pi OS Legacy Lite (32-bit)

那它本身就是 Lite 版本，默认没有完整桌面环境。进入命令行并不一定代表系统坏了。

但如果你原本是有桌面的，改完配置后桌面确实起不来，那么最常见原因就是：

把 dtoverlay=vc4-kms-v3d 删了
加入了不适合当前系统的新旧混用参数

比如下面这些旧教程里常见的参数，在新相机栈里不建议乱加：

ini 复制代码

start_x=1
gpu_mem=128

如果只是用 rpicam/libcamera，一般先不要加这些老参数，避免把旧相机栈和新相机栈混在一起。

九、通过 SSH 让摄像头预览显示在树莓派桌面上

这是这次排查里最容易踩坑的一步。

1. 如果只想"本地屏幕上直接显示预览"

最简单的命令是：

bash 复制代码

rpicam-hello -t 0

说明：

-t 0 表示一直预览
按 Ctrl+C 退出

如果树莓派接了本地显示器，有时会直接以 DRM/KMS 方式显示。

2. 但通过 SSH 想显示在"桌面窗口"里，事情没那么简单

我试过下面几种命令：

bash 复制代码

nohup rpicam-hello -t 0 >/tmp/rpicam.log 2>&1 &
nohup env DISPLAY=:0 rpicam-hello --qt-preview -t 0 >/tmp/rpicam.log 2>&1 &
nohup env XDG_RUNTIME_DIR=/run/user/$(id -u) WAYLAND_DISPLAY=wayland-1 DISPLAY=:0 rpicam-hello --qt-preview -t 0 >/tmp/rpicam.log 2>&1 &

结果都没有成功在 DSI 屏幕桌面上显示。

3. 问题的关键点

后面确认到以下事实：

系统支持 Qt 预览：qt:1
实际 Wayland socket 是 wayland-0，不是 wayland-1
rpicam-hello 默认更偏向 DRM/KMS 预览，不一定会成为桌面窗口
从 SSH 启动桌面窗口时，必须连接到已经存在的本地图形会话

查看 Wayland socket：

bash 复制代码

ls /run/user/$(id -u)/wayland-*

我的输出是：

text 复制代码

/run/user/1000/wayland-0
/run/user/1000/wayland-0.lock

4. 更合理的 Wayland 方式

可以尝试前台验证：

bash 复制代码

env XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 QT_QPA_PLATFORM=wayland \
rpicam-hello --qt-preview --preview 0,0,800,480 -t 0

说明：

XDG_RUNTIME_DIR 指向本地登录用户的运行目录
WAYLAND_DISPLAY=wayland-0 使用实际存在的 Wayland 会话
QT_QPA_PLATFORM=wayland 强制 Qt 走 Wayland，而不是错误切到 X11
--preview 0,0,800,480 可以指定窗口大小和位置

5. 但这个前提不能忽略

要想通过 SSH 启动桌面窗口，必须满足：

树莓派本地桌面已经启动
本地用户已经登录图形会话
你的 SSH 用户和本地图形会话用户一致，或者你能访问它的 Wayland 会话

否则命令即使启动，也没有地方可以真正把窗口画出来。

6. 一个更稳妥的思路

如果你的目标只是"远程看到树莓派上的预览画面"，其实更推荐：

用 VNC
或者用 Raspberry Pi Connect

这样思路更顺，也更符合远程桌面的使用方式。

十、我这次排障后得出的结论

这次问题并不是单点故障，而是几个问题叠加在一起：

1. 摄像头识别问题

通过手动指定：

ini 复制代码

camera_auto_detect=0
dtoverlay=ov5647

系统已经可以识别到 OV5647。

2. 图形界面问题

要保留：

ini 复制代码

dtoverlay=vc4-kms-v3d

不能为了加相机配置，把显示驱动配置弄丢。

3. 真正的拍照失败原因

从日志看，更像是 CSI 链路硬件问题，而不是软件问题。

优先排查：

排线
接口
摄像头模组本体

4. SSH 下桌面预览问题

不是一句 DISPLAY=:0 就能解决，尤其在 Bookworm/Wayland 或类似新图形栈里，要正确设置：

XDG_RUNTIME_DIR
WAYLAND_DISPLAY
QT_QPA_PLATFORM

并且前提是本地桌面会话真实存在。

十一、建议保留的排查命令清单

1. 查看系统版本

bash 复制代码

cat /etc/os-release

2. 查看相机列表

bash 复制代码

rpicam-hello --list-cameras

3. 无预览拍照测试

bash 复制代码

rpicam-still -n -o test.jpg

4. 查看当前相机工具能力

bash 复制代码

rpicam-hello --version

5. 查看 config.txt 中非注释配置

bash 复制代码

grep -v '^\s*#' /boot/firmware/config.txt | sed '/^\s*$/d'

6. 查看供电状态

bash 复制代码

vcgencmd get_throttled

7. 查看 Wayland socket

bash 复制代码

ls /run/user/$(id -u)/wayland-*

8. 通过 Wayland 启动 Qt 预览

bash 复制代码

env XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 QT_QPA_PLATFORM=wayland \
rpicam-hello --qt-preview --preview 0,0,800,480 -t 0

十二、参考资料

Raspberry Pi documentation: Camera software

https://www.raspberrypi.com/documentation/computers/camera_software.html
Raspberry Pi documentation: config.txt

https://www.raspberrypi.com/documentation/computers/config_txt.html
Raspberry Pi documentation: Camera hardware/tutorial

https://www.raspberrypi.com/documentation/accessories/camera.html
Raspberry Pi OS 下载页

https://www.raspberrypi.com/software/operating-systems/

十三、写在最后

如果你的日志和我类似，已经出现了：

text 复制代码

Adding camera ... ov5647@36
Registered camera ...
Failed to queue buffer ...
Device timeout detected ...

那就不要再把时间都花在配置文件上了。

这时更应该优先检查排线、接口和摄像头硬件本身。

Raspberry Pi OS Legacy Lite（32 位）下调试树莓派 Camera Rev 1.3 / OV5647

一、问题背景

二、我的环境

三、第一步：先判断摄像头有没有被系统识别

四、摄像头无法识别时，先改 config.txt

1. 老款 Camera Rev 1.3 需要按 ov5647 指定 overlay

2. 不要把显示驱动 overlay 覆盖掉

五、修改后可以识别，但拍照时报超时错误

六、怎么判断不是供电问题

七、这类超时错误最常见的根因

建议按这个顺序排查

八、关于"改完 config.txt 后进不了图形界面"

九、通过 SSH 让摄像头预览显示在树莓派桌面上

1. 如果只想"本地屏幕上直接显示预览"

2. 但通过 SSH 想显示在"桌面窗口"里，事情没那么简单

3. 问题的关键点

4. 更合理的 Wayland 方式

5. 但这个前提不能忽略

6. 一个更稳妥的思路

十、我这次排障后得出的结论

1. 摄像头识别问题

2. 图形界面问题

3. 真正的拍照失败原因

4. SSH 下桌面预览问题

十一、建议保留的排查命令清单

1. 查看系统版本

2. 查看相机列表

3. 无预览拍照测试

4. 查看当前相机工具能力

5. 查看 config.txt 中非注释配置

6. 查看供电状态

7. 查看 Wayland socket

8. 通过 Wayland 启动 Qt 预览

十二、参考资料

十三、写在最后

1. 老款 Camera Rev 1.3 需要按 `ov5647` 指定 overlay