sc235hai_driver/README.md

# SC235HAI/SC231AI Camera Driver for Raspberry Pi Zero 2W

## 概述

这是一个用于树莓派 Zero 2W 的 SC235HAI/SC231AI MIPI CSI-2 摄像头传感器的 V4L2 内核驱动。

## 硬件规格

- **传感器**: 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

## 硬件连接

### 电源
- AVDD: 2.8V (模拟电源)
- DOVDD: 1.8V (I/O 电源)
- DVDD: 1.2V (数字核心电源)

### 控制信号
- **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` - 内核模块编译配置

## 编译安装

### 在树莓派上编译

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

### 配置

编辑 `/boot/firmware/config.txt` 添加：

```ini
# 禁用相机自动检测
camera_auto_detect=0

# 使能 I2C VC
dtparam=i2c_vc=on

# 配置电源控制 GPIO
gpio=4=op,dh
gpio=40=op,dh

# 加载驱动 overlay
dtoverlay=sc235hai
```

## 使用方法

### 检查设备

```bash
# 查看视频设备
ls /dev/video*

# 查看媒体拓扑
media-ctl -d /dev/media3 -p

# 查看驱动加载状态
dmesg | grep sc235
```

### 拍照

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

### 录像

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

### 转换为 JPG/MP4

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

## 已知问题

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 网络直播。

### 快速启动

```bash
# SSH 连接到 Zero 2W
ssh root@<board-ip>

# 下载并启动 RTSP 服务器
cd /root
./deploy-rtsp.sh start

# 查看日志
cat /var/log/mediamtx.log

# 停止服务
./deploy-rtsp.sh stop
```

### 在 Windows/macOS/Linux 上播放

#### VLC 方式
```bash
vlc "rtsp://<board-ip>:8554/cam"
```

#### ffplay 方式
```bash
ffplay "rtsp://<board-ip>:8554/cam"
```

#### Python + OpenCV 方式
```python
import cv2
cap = cv2.VideoCapture("rtsp://<board-ip>:8554/cam")
while True:
    ret, frame = cap.read()
    if ret:
        cv2.imshow("SC235HAI", frame)
        if cv2.waitKey(1) & 0xFF == ord('q'):
            break
cap.release()
cv2.destroyAllWindows()
```

### 配置说明

编辑 `mediamtx.yml` 调整以下参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| rpiCameraWidth | 1920 | 分辨率宽 |
| rpiCameraHeight | 1080 | 分辨率高 |
| rpiCameraFPS | 30 | 帧率 |
| rpiCameraCodec | hardwareH264 | 编码器（硬件H264） |
| rpiCameraIDRPeriod | 60 | I 帧间隔 |
| rtspAddress | :8554 | RTSP 监听端口 |

### 架构

```
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 / 流媒体播放器
```

### ISP 处理流程

驱动通过 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 协议发送

### 性能指标

- **帧率**: 30 fps
- **分辨率**: 1920x1080
- **编码**: H.264 (硬件加速)
- **码率**: 自适应 (~2-4 Mbps)
- **延迟**: ~500ms

## 更新日志

### 2026-04-19
- 添加 V4L2 完整 control 接口（EXPOSURE/GAIN/VBLANK/HBLANK/PIXEL_RATE/LINK_FREQ）
- 支持 libcamera v0.6.0 ISP 处理
- 集成 MediaMTX RTSP 服务器
- 实现网络视频直播

### 2026-04-14
- 初始版本发布
- 支持 1920x1080@30fps RAW10 输出
- 添加完整的传感器寄存器初始化
- 集成到 Raspberry Pi Zero 2W 平台