diff --git a/README.md b/README.md index 4a29853..4053abb 100644 --- a/README.md +++ b/README.md @@ -1,194 +1,253 @@ -# SC235HAI/SC231AI Camera Driver for Raspberry Pi Zero 2W +# SC235HAI Zero 2W Installation and RTSP Testing Guide -## 概述 +This guide covers the full workflow for a clean Raspberry Pi Zero 2W system after first boot: -这是一个用于树莓派 Zero 2W 的 SC235HAI/SC231AI MIPI CSI-2 摄像头传感器的 V4L2 内核驱动。 +1. Install build dependencies. +2. Download or copy the SC235HAI driver source. +3. Build and install the kernel module and device-tree overlay. +4. Configure boot-time autoload. +5. Start MediaMTX directly and verify RTSP streaming. -## 硬件规格 +Assumptions: -- **传感器**: SmartSens SC231AI (兼容 SC235HAI) -- **芯片 ID**: 0xCB6A -- **分辨率**: 1920x1080 -- **帧率**: 30 fps -- **接口**: MIPI CSI-2, 2-lane -- **数据速率**: 371.25 Mbps -- **输出格式**: RAW10 Bayer BGGR -- **I2C 地址**: 0x30 (7-bit) -- **MCLK**: 27MHz +- The board is connected to the network. +- You can reach it over SSH, for example `ssh root@`. +- Replace `` with the actual IP address of your Zero 2W. -## 硬件连接 +--- -### 电源 -- AVDD: 2.8V (模拟电源) -- DOVDD: 1.8V (I/O 电源) -- DVDD: 1.2V (数字核心电源) +## 1. Prerequisites -### 控制信号 -- **GPIO 4**: LDO_EN (摄像头主电源使能,必须设置为高电平) -- **GPIO 40**: cam1_regulator (2.8V 稳压器使能) - -### MIPI CSI-2 -- 连接到树莓派 Zero 2W 的 CSI 摄像头接口 (22-pin FPC) -- 使用 csi1 控制器 - -## 文件说明 - -- `sc235hai.c` - V4L2 传感器驱动源码 -- `sc235hai.dts` - 设备树 overlay 源码 -- `Makefile` - 内核模块编译配置 - -## 编译安装 - -### 在树莓派上编译 +### 1.1 Connect to the board ```bash -# 安装内核头文件 -sudo apt-get install raspberrypi-kernel-headers - -# 编译驱动 -cd sc235hai_driver -make - -# 编译设备树 overlay -dtc -@ -I dts -O dtb -o sc235hai.dtbo sc235hai.dts - -# 安装 -sudo cp sc235hai.ko /lib/modules/$(uname -r)/extra/ -sudo cp sc235hai.dtbo /boot/firmware/overlays/ -sudo depmod -a +ssh root@ ``` -### 配置 +If your image does not use `root` directly, log in with the default user first and then switch to the account you use for deployment. -编辑 `/boot/firmware/config.txt` 添加: +### 1.2 Update the system and install dependencies + +Run the following on the Zero 2W: + +```bash +apt update +apt install -y \ + git \ + build-essential \ + raspberrypi-kernel-headers \ + device-tree-compiler \ + v4l-utils \ + libcamera-apps \ + ffmpeg \ + curl \ + ca-certificates +``` + +Notes: + +- `raspberrypi-kernel-headers` is required to build the kernel module. +- `device-tree-compiler` is required to build `sc235hai.dtbo`. +- `v4l-utils`, `libcamera-apps`, and `ffmpeg` are used for verification and testing. + +### 1.3 Copy the driver source to the board + +If the source code is still on your PC, copy it to the board: + +```bash +scp -r sc235hai_driver root@:/root/ +``` + +If the source is already present on the board, skip this step. + +--- + +## 2. Build the SC235HAI driver + +Change into the driver directory: + +```bash +cd /root/sc235hai_driver +``` + +### 2.1 Build the kernel module + +```bash +make +``` + +This should produce `sc235hai.ko`. + +### 2.2 Build the device-tree overlay + +```bash +dtc -@ -I dts -O dtb -o sc235hai.dtbo sc235hai.dts +``` + +This should produce `sc235hai.dtbo`. + +### 2.3 Install the built artifacts + +```bash +cp sc235hai.ko /lib/modules/$(uname -r)/extra/ +cp sc235hai.dtbo /boot/firmware/overlays/ +depmod -a +``` + +Explanation: + +- `sc235hai.ko` is an out-of-tree loadable kernel module, not built directly into the kernel image. +- `sc235hai.dtbo` is the overlay that adds the sensor node to the system. + +### 2.4 Load the module manually for a quick test + +```bash +modprobe sc235hai +``` + +Then confirm it loaded: + +```bash +lsmod | grep -i sc235hai +dmesg | grep -i sc235 +``` + +If `sc235hai` appears in the output, the module itself is working. + +--- + +## 3. Enable boot-time autoload + +Edit `/boot/firmware/config.txt`: + +```bash +nano /boot/firmware/config.txt +``` + +Make sure the following lines are present: ```ini -# 禁用相机自动检测 camera_auto_detect=0 - -# 使能 I2C VC dtparam=i2c_vc=on - -# 配置电源控制 GPIO gpio=4=op,dh gpio=40=op,dh - -# 加载驱动 overlay dtoverlay=sc235hai ``` -## 使用方法 +Meaning of the settings: -### 检查设备 +- `camera_auto_detect=0` disables Raspberry Pi camera auto-detection so the custom sensor setup is not overridden. +- `dtparam=i2c_vc=on` enables the camera-side I2C bus. +- `gpio=4=op,dh` drives GPIO 4 high as an output. +- `gpio=40=op,dh` drives GPIO 40 high as an output. +- `dtoverlay=sc235hai` loads the SC235HAI overlay during boot. + +Save the file and reboot: ```bash -# 查看视频设备 +reboot +``` + +--- + +## 4. Verify the driver after reboot + +After the board comes back, reconnect over SSH and run: + +```bash +lsmod | grep -i sc235hai +dmesg | grep -i sc235 +media-ctl -p ls /dev/video* - -# 查看媒体拓扑 -media-ctl -d /dev/media3 -p - -# 查看驱动加载状态 -dmesg | grep sc235 +ls /dev/media* ``` -### 拍照 +What to check: + +1. `lsmod` should show `sc235hai`. +2. `dmesg` should not show a probe failure. +3. Video and media device nodes should exist. + +To confirm libcamera sees the sensor: ```bash -# 捕获单帧 RAW10 图像 -v4l2-ctl -d /dev/video0 \ - --set-fmt-video=width=1920,height=1080,pixelformat=BG10 \ - --stream-mmap --stream-count=1 \ - --stream-to=photo.raw +libcamera-hello --list-cameras ``` -### 录像 +If the camera appears in the output, the system-side detection is working. + +--- + +## 5. Start MediaMTX for RTSP streaming + +This workflow does not use the deployment script. It starts `mediamtx` directly. + +### 5.1 Check that MediaMTX files are present ```bash -# 捕获 60 帧 (2秒@30fps) -v4l2-ctl -d /dev/video0 \ - --set-fmt-video=width=1920,height=1080,pixelformat=BG10 \ - --stream-mmap --stream-count=60 \ - --stream-to=video.raw +ls -l /root/mediamtx /root/mediamtx.yml ``` -### 转换为 JPG/MP4 +If the files are missing, copy them to `/root/` first. + +### 5.2 Stop any old instance ```bash -# RAW10 转 JPG -ffmpeg -f rawvideo -pix_fmt bayer_bggr16le -s 1920x1080 \ - -i photo.raw -q:v 2 photo.jpg - -# RAW10 转 MP4 -ffmpeg -f rawvideo -pix_fmt bayer_bggr16le -s 1920x1080 -r 30 \ - -i video.raw -c:v libx264 -preset ultrafast -crf 23 video.mp4 +pkill -f mediamtx 2>/dev/null || true ``` -## 已知问题 - -1. **图像偏暗**: 当前驱动使用传感器默认曝光/增益设置,图像较暗。需要调整曝光参数或添加 V4L2 控制接口。 -2. **仅支持 RAW 格式**: 传感器直接输出 Bayer RAW10 数据,需要通过 ffmpeg 或 ISP 转换为 RGB/YUV。 -3. **缓冲区警告**: v4l2-ctl 可能显示 "4096 != 4147200" 警告,不影响功能。 - -## 技术细节 - -### 寄存器初始化 - -驱动包含 144 个寄存器的完整初始化序列,来自厂商提供的配置文件: -- 30fps 配置 -- 2-lane MIPI -- 371.25 Mbps 数据速率 - -### V4L2 子系统集成 - -- 使用 `v4l2_async` 框架异步注册 -- 实现 `v4l2_subdev_pad_ops` 进行格式协商 -- 支持 `pm_runtime` 电源管理 - -## 作者 - -硬件团队 - -## 许可 - -GPL v2 - -## RTSP 网络流服务器 - -本驱动集成 libcamera 支持,可通过 MediaMTX 实现 RTSP 网络直播。 - -### 快速启动 +### 5.3 Start MediaMTX directly ```bash -# SSH 连接到 Zero 2W -ssh root@ - -# 下载并启动 RTSP 服务器 -cd /root -./deploy-rtsp.sh start - -# 查看日志 -cat /var/log/mediamtx.log - -# 停止服务 -./deploy-rtsp.sh stop +setsid /root/mediamtx /root/mediamtx.yml >/var/log/mediamtx.log 2>&1 :8554/cam" +pgrep -af mediamtx +tail -n 50 /var/log/mediamtx.log ``` -#### ffplay 方式 +If everything is working, you should see something similar to: + +```text +path cam ... ready +``` + +That means the RTSP path is available. + +--- + +## 6. Play and verify the RTSP stream + +The RTSP URL is usually: + +```text +rtsp://:8554/cam +``` + +### 6.1 VLC + +Open: + +```text +rtsp://:8554/cam +``` + +### 6.2 ffplay + ```bash ffplay "rtsp://:8554/cam" ``` -#### Python + OpenCV 方式 +### 6.3 OpenCV + ```python import cv2 + cap = cv2.VideoCapture("rtsp://:8554/cam") while True: ret, frame = cap.read() @@ -196,65 +255,104 @@ while True: cv2.imshow("SC235HAI", frame) if cv2.waitKey(1) & 0xFF == ord('q'): break + cap.release() cv2.destroyAllWindows() ``` -### 配置说明 +If the image displays correctly, the driver, sensor, MediaMTX, and network path are all working. -编辑 `mediamtx.yml` 调整以下参数: +--- -| 参数 | 默认值 | 说明 | -|------|--------|------| -| rpiCameraWidth | 1920 | 分辨率宽 | -| rpiCameraHeight | 1080 | 分辨率高 | -| rpiCameraFPS | 30 | 帧率 | -| rpiCameraCodec | hardwareH264 | 编码器(硬件H264) | -| rpiCameraIDRPeriod | 60 | I 帧间隔 | -| rtspAddress | :8554 | RTSP 监听端口 | +## 7. Common issues -### 架构 +### 7.1 `modprobe sc235hai` cannot find the module -``` -SC235HAI 传感器 - ↓ MIPI CSI-2 (2-lane) -Unicam (CSI 接收器) → ISP (Raspberry Pi V3D ISP) - ↓ YUV420 -libcamera (0.6.0) → rpicam-apps - ↓ H.264 编码(硬件) -MediaMTX → RTSP/HLS/WebRTC/SRT - ↓ -VLC / ffplay / 流媒体播放器 +Check whether the module is installed for the current kernel: + +```bash +find /lib/modules/$(uname -r) -name 'sc235hai.ko*' ``` -### ISP 处理流程 +If nothing is found, rebuild and reinstall: -驱动通过 libcamera 实现的 ISP 处理: -1. **Raw Bayer** (1920x1080-SBGGR10) 从传感器捕获 -2. **Demosaicing** - Bayer to RGB 转换 -3. **Color Space** - RGB to YUV420 转换 -4. **ISP Pipeline** - 曝光、增益、白平衡、去噪等 -5. **H.264 编码** - 硬件编码器压缩 -6. **网络传输** - RTSP 协议发送 +```bash +cd /root/sc235hai_driver +make +cp sc235hai.ko /lib/modules/$(uname -r)/extra/ +depmod -a +``` -### 性能指标 +### 7.2 `lsmod` does not show `sc235hai` -- **帧率**: 30 fps -- **分辨率**: 1920x1080 -- **编码**: H.264 (硬件加速) -- **码率**: 自适应 (~2-4 Mbps) -- **延迟**: ~500ms +Check whether `config.txt` contains: -## 更新日志 +```ini +dtoverlay=sc235hai +``` -### 2026-04-19 -- 添加 V4L2 完整 control 接口(EXPOSURE/GAIN/VBLANK/HBLANK/PIXEL_RATE/LINK_FREQ) -- 支持 libcamera v0.6.0 ISP 处理 -- 集成 MediaMTX RTSP 服务器 -- 实现网络视频直播 +Then reboot again. -### 2026-04-14 -- 初始版本发布 -- 支持 1920x1080@30fps RAW10 输出 -- 添加完整的传感器寄存器初始化 -- 集成到 Raspberry Pi Zero 2W 平台 +### 7.3 MediaMTX starts but there is no image + +Check these in order: + +1. `dmesg | grep -i sc235` +2. `libcamera-hello --list-cameras` +3. `tail -n 50 /var/log/mediamtx.log` + +If libcamera cannot see the camera, the problem is usually in the driver, overlay, or hardware connection, not in MediaMTX. + +### 7.4 RTSP playback errors + +Make sure: + +- The board and the client are on the same network. +- Port `8554` is not blocked by a firewall. +- The MediaMTX log does not show a startup failure. + +--- + +## 8. One-shot command sequence + +If the source is already in `/root/sc235hai_driver`, you can run the whole sequence like this: + +```bash +apt update +apt install -y git build-essential raspberrypi-kernel-headers device-tree-compiler v4l-utils libcamera-apps ffmpeg curl ca-certificates +cd /root/sc235hai_driver +make +dtc -@ -I dts -O dtb -o sc235hai.dtbo sc235hai.dts +cp sc235hai.ko /lib/modules/$(uname -r)/extra/ +cp sc235hai.dtbo /boot/firmware/overlays/ +depmod -a +nano /boot/firmware/config.txt +reboot +``` + +After reboot: + +```bash +ssh root@ +lsmod | grep -i sc235hai +setsid /root/mediamtx /root/mediamtx.yml >/var/log/mediamtx.log 2>&1 :8554/cam +``` + +--- + +## 9. Summary + +The key points are: + +- `sc235hai` is installed as an out-of-tree kernel module, not compiled into the kernel itself. +- The device-tree overlay is loaded at boot using `dtoverlay=sc235hai`. +- MediaMTX can be started directly on the board for RTSP testing. + +If you want, I can also turn this into a shorter field checklist or a troubleshooting-only version. \ No newline at end of file diff --git a/deploy-rtsp.sh b/deploy-rtsp.sh deleted file mode 100644 index ddf730b..0000000 --- a/deploy-rtsp.sh +++ /dev/null @@ -1,84 +0,0 @@ -#!/bin/bash -# deploy-rtsp.sh - SC235HAI RTSP Streaming Server Deployment -# Usage: ./deploy-rtsp.sh [start|stop|restart] - -set -e - -RTSP_DIR="/root" -MEDIAMTX_VERSION="v1.9.3" -MEDIAMTX_URL="https://github.com/bluenviron/mediamtx/releases/download/${MEDIAMTX_VERSION}/mediamtx_${MEDIAMTX_VERSION}_linux_arm64v8.tar.gz" -MEDIAMTX_BIN="${RTSP_DIR}/mediamtx" -MEDIAMTX_CONFIG="${RTSP_DIR}/mediamtx.yml" -RTSP_PORT=8554 - -download_mediamtx() { - if [ ! -f "$MEDIAMTX_BIN" ]; then - echo "[INFO] Downloading mediamtx ${MEDIAMTX_VERSION}..." - cd "$RTSP_DIR" - curl -L -o mediamtx.tar.gz "$MEDIAMTX_URL" - tar -xzf mediamtx.tar.gz mediamtx mediamtx.yml - rm -f mediamtx.tar.gz - chmod +x "$MEDIAMTX_BIN" - echo "[OK] mediamtx installed at $MEDIAMTX_BIN" - else - echo "[OK] mediamtx already installed" - fi -} - -start_rtsp() { - download_mediamtx - - # Kill any existing instance - pkill -f "mediamtx" 2>/dev/null || true - sleep 1 - - # Copy config from script directory if present - SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - if [ -f "${SCRIPT_DIR}/mediamtx.yml" ]; then - cp "${SCRIPT_DIR}/mediamtx.yml" "$MEDIAMTX_CONFIG" - echo "[OK] Using mediamtx.yml from script directory" - fi - - # Start mediamtx - cd "$RTSP_DIR" - nohup "$MEDIAMTX_BIN" "$MEDIAMTX_CONFIG" > /var/log/mediamtx.log 2>&1 & - PID=$! - sleep 3 - - # Verify it's running - if kill -0 $PID 2>/dev/null; then - echo "[OK] MediaMTX started (PID: $PID)" - echo "[OK] RTSP stream available at: rtsp://$(hostname -I | awk '{print $1}'):${RTSP_PORT}/cam" - else - echo "[ERROR] Failed to start MediaMTX" - cat /var/log/mediamtx.log - return 1 - fi -} - -stop_rtsp() { - pkill -f "mediamtx" 2>/dev/null || true - echo "[OK] MediaMTX stopped" -} - -restart_rtsp() { - stop_rtsp - sleep 1 - start_rtsp -} - -case "${1:-start}" in - start) - start_rtsp - ;; - stop) - stop_rtsp - ;; - restart) - restart_rtsp - ;; - *) - echo "Usage: $0 {start|stop|restart}" - exit 1 - ;; -esac