树莓派 OV5647 摄像头（V1.3）配置完全指南

原创已于 2026-03-05 22:15:22 修改 · 856 阅读

7 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#树莓派

于 2026-02-27 22:32:34 首次发布

📷 树莓派 OV5647 摄像头（V1.3）配置完全指南 (2026 修订版)

适用硬件：

主板：Raspberry Pi 4B / 3B+ / Zero 2 W / CM4
摄像头：OV5647 500万像素 (Raspberry Pi Camera Module V1.3)
系统：Raspberry Pi OS Bullseye (11) 或 Bookworm (12)

核心变化提示：

Bullseye 起，旧版 raspistill/picamera 已被弃用，全面转向 libcamera。
Bookworm 起，默认使用 Wayland 显示服务器，且 /boot/config.txt 路径可能变为 /boot/firmware/config.txt。

一、物理连接与方向检查（至关重要）

在运行任何命令前，请确保物理连接正确。90% 的故障源于排线插反或未插到底。

✅ 正确的排线方向

接口位置	蓝色胶条/标签朝向	金属触点朝向	备注
树莓派主板端	朝向 USB/网口中心	朝向板子边缘/HDMI	卡扣拉起插入，按下锁紧
摄像头模块端	背对电路板元件	朝向电路板铜箔	务必插到底，直到感觉受阻

⚠️ 警告：如果方向插反，虽然通常不会烧毁硬件，但会导致 detected=0 或 timeout 错误。

二、系统配置步骤

1. 修改启动配置文件

根据系统版本，配置文件路径可能不同：

Bullseye 及更早: /boot/config.txt
Bookworm 及更新: /boot/firmware/config.txt

# 自动检测并编辑正确的文件
sudo nano $(ls /boot/config.txt /boot/firmware/config.txt 2>/dev/null | head -n 1)

添加或修改以下内容（确保没有冲突项）：

[all]
# 1. 启用旧版 MMAL 支持 (仅当必须使用 raspistill 时需要，libcamera 不需要，但建议保留以防兼容性问题)
start_x=1

# 2. 【关键】禁用自动检测，防止系统与手动驱动冲突
camera_auto_detect=0

# 3. 手动加载 OV5647 驱动
dtoverlay=ov5647

# 4. 启用 I2C 接口 (OV5647 依赖 I2C 通信)
dtparam=i2c_arm=on

# 5. 分配足够的 GPU 内存 (建议 128MB，若运行桌面环境可设为 256MB)
gpu_mem=128

保存退出 (Ctrl+O, Enter, Ctrl+X)，然后重启：

sudo reboot

2. 启用 I2C 接口 (双重保险)

虽然 config.txt 已开启，但建议通过工具确认状态：

sudo raspi-config

进入 Interface Options -> I2C -> 选择 Yes。
进入 Camera (如果有此选项) -> 选择 Yes (这会尝试启用旧驱动，若与手动配置冲突请忽略，以 config.txt 为准)。

三、验证硬件状态

重启后，按顺序执行以下检查：

3.1 检查内核识别

vcgencmd get_camera

✅ 成功: supported=1 detected=1, libcamera interfaces=1
- detected=1: 硬件已连通。
- libcamera interfaces=1: 驱动已正确加载给 libcamera。
❌ 失败: detected=0
- 原因: 排线松动、方向错误、或 camera_auto_detect 未关闭。
- 对策: 断电重插排线，检查 dmesg。

3.2 检查 I2C 总线

sudo i2cdetect -y 1

✅ 成功: 在地址 0x36 处显示 36。

     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
30: -- -- -- -- -- -- 36 -- -- -- -- -- -- -- -- --

❌ 失败: 全为 --。
- 原因: I2C 未启用或物理连接完全断开。

3.3 查看内核日志

dmesg | grep -i "ov5647\|unicam"

正常: ov5647 10-0036: OV5647 camera module detected
异常: probe ... failed with error -121 (远程 I/O 错误，通常是排线问题)。

四、拍照与录像测试 (Libcamera)

Bullseye 之后，强烈建议只使用 libcamera 套件。

4.1 列出可用摄像头

libcamera-still --list-cameras

输出应包含 ov5647 字样及支持的分辨率模式。

4.2 拍摄单张照片

# 基础用法
libcamera-still -o image.jpg

# 推荐用法：指定分辨率、延时 2 秒(防抖动)、预览窗口
libcamera-still -t 2000 --width 2592 --height 1944 -o image_high_res.jpg

4.3 录制视频

# 录制 10 秒视频
libcamera-vid -t 10000 -o video.h264

# 无限录制 (按 Ctrl+C 停止)，不保存文件仅预览
libcamera-vid -t 0 --output /dev/null

4.4 Python 开发 (Picamera2)

旧版 picamera 库已不再维护，请使用 picamera2：

from picamera2 import Picamera2
import time

picam2 = Picamera2()
config = picam2.create_preview_configuration(main={"size": (1280, 720)})
picam2.configure(config)
picam2.start()
time.sleep(2)
picam2.capture_file("test_python.jpg")
picam2.stop()
print("Photo captured!")

安装: sudo apt install python3-picamera2

五、进阶故障排查 (Troubleshooting)

如果上述步骤仍无法工作，请对照下表：

现象	可能原因	解决方案
`detected=0`	排线未插好/方向反	断电后重新插拔，确保蓝色标签朝向网口。
`No cameras available`	`camera_auto_detect=1` 冲突	编辑 config.txt，确保设置 `camera_auto_detect=0`。
`Camera frontend has timed out`	数据链路不通 (MIPI 故障)	1. 更换排线 (排线内部断裂常见)。2. 降低分辨率/帧率测试。3. 检查电源供电是否不足。
`i2cdetect` 找不到 0x36	I2C 未启用或硬件损坏	确认 `dtparam=i2c_arm=on` 已添加并重启；若仍无，可能是摄像头模块损坏。
黑屏但有日志	光线太暗或曝光未锁定	OV5647 在暗处会自动延长曝光导致看似黑屏，尝试增加环境光或添加 `--exposure normal`。
Bookworm 系统报错	Wayland/权限问题	尝试在终端前加 `sudo` 测试；或检查用户是否在 `video` 组 (`sudo usermod -aG video $USER`)。

💡 特别提示：关于 Bookworm (Debian 12)

如果你升级到了最新的 Bookworm 系统：

配置文件路径通常为 /boot/firmware/config.txt。
默认显示服务器是 Wayland。如果在桌面环境下预览窗口不显示，尝试切换回 X11 (在 raspi-config -> Advanced Options -> Compositor / Wayland 中调整)，或者确保在终端运行而非通过 SSH X11 转发（SSH 转发预览需要 -n 参数禁用预览）。

六、常用参数速查表 (`libcamera-still`)

参数	说明	示例
`-o`	输出文件名	`-o photo.jpg`
`-t`	预览时间 (毫秒)	`-t 2000` (2秒)
`--width` / `--height`	分辨率	`--width 1920 --height 1080`
`--rotation`	旋转角度	`--rotation 180` (倒置)
`--hflip` / `--vflip`	水平/垂直翻转	`--hflip`
`--gain`	模拟增益 (ISO)	`--gain 2.0`
`--shutter`	快门速度 (微秒)	`--shutter 20000`
`--encoding`	编码格式	`--encoding png` (默认 jpg)

结语：
OV5647 是一款经典的摄像头，但在现代树莓派系统上需要正确的手动配置。只要 vcgencmd get_camera 显示 detected=1，剩下的软件问题通常都能通过调整 libcamera 参数解决。如果始终无法 detected=1，请优先怀疑排线和摄像头模块本身的硬件故障。