Update README and remove the script not used

This commit is contained in:
yuquanjun 2026-05-28 08:59:21 +08:00
parent 96cf5579bd
commit 6ea3301e27
2 changed files with 282 additions and 268 deletions

466
README.md
View File

@ -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@<board-ip>`.
- Replace `<board-ip>` 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@<board-ip>
```
### 配置
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@<board-ip>:/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@<board-ip>
# 下载并启动 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 </dev/null &
```
### 在 Windows/macOS/Linux 上播放
This runs MediaMTX in the background and writes logs to `/var/log/mediamtx.log`.
### 5.4 Check the process and logs
#### VLC 方式
```bash
vlc "rtsp://<board-ip>: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://<board-ip>:8554/cam
```
### 6.1 VLC
Open:
```text
rtsp://<board-ip>:8554/cam
```
### 6.2 ffplay
```bash
ffplay "rtsp://<board-ip>:8554/cam"
```
#### Python + OpenCV 方式
### 6.3 OpenCV
```python
import cv2
cap = cv2.VideoCapture("rtsp://<board-ip>: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@<board-ip>
lsmod | grep -i sc235hai
setsid /root/mediamtx /root/mediamtx.yml >/var/log/mediamtx.log 2>&1 </dev/null &
tail -n 50 /var/log/mediamtx.log
```
On your client machine, open:
```text
rtsp://<board-ip>: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.

View File

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