qjyu
/
sc235hai_driver
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add step-by-step bring-up guide and checklist; fallback for kernel headers

This commit is contained in:
yuquanjun 2026-05-28 14:48:36 +08:00
parent 616af22128
commit 767b631e59
2 changed files with 236 additions and 261 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
CHECKLIST.md Normal file
View File

@ -0,0 +1,77 @@
# SC235HAI Quick Checklist
One-page, copyable checklist for field use.
Wiring
- Connect camera CSI ribbon to carrier board.
- Connect SDA/SCL (I2C VC) to camera sensor.
- Connect camera GND to Pi GND.
- Ensure control GPIOs (e.g. GPIO4, GPIO40) are connected as required.
- Apply power only after wiring verified.
System prep (on Pi)
```bash
apt update
apt install -y git build-essential raspberrypi-kernel-headers device-tree-compiler v4l-utils libcamera-apps ffmpeg curl ca-certificates
```
Boot & config
- Edit `/boot/firmware/config.txt` and ensure:
```ini
camera_auto_detect=0
dtparam=i2c_vc=on
gpio=4=op,dh
gpio=40=op,dh
dtoverlay=sc235hai
```
- Reboot: `reboot`
Driver: obtain & build
- Copy or clone driver to `/root/sc235hai_driver`.
```bash
cd /root/sc235hai_driver
make
dtc -@ -I dts -O dtb -o sc235hai.dtbo sc235hai.dts
```
Install driver & overlay
```bash
cp sc235hai.ko /lib/modules/$(uname -r)/extra/
cp sc235hai.dtbo /boot/firmware/overlays/
depmod -a
modprobe sc235hai
```
Autoload (optional)
- Add module to `/etc/modules-load.d/sc235hai.conf`:
```bash
echo sc235hai > /etc/modules-load.d/sc235hai.conf
reboot
```
Verify
```bash
lsmod | grep -i sc235hai
dmesg | grep -i sc235
media-ctl -p
ls /dev/video* /dev/media*
libcamera-hello --list-cameras
```
MediaMTX (stream)
- Copy `mediamtx` and `mediamtx.yml` to `/root/` if missing.
```bash
pkill -f mediamtx 2>/dev/null || true
setsid /root/mediamtx /root/mediamtx.yml >/var/log/mediamtx.log 2>&1 </dev/null &
tail -n 50 /var/log/mediamtx.log
```
- RTSP URL: `rtsp://<board-ip>:8554/cam`
Quick troubleshooting
- No module: `find /lib/modules/$(uname -r) -name 'sc235hai.ko*'`
- Overlay missing: check `/boot/firmware/overlays/sc235hai.dtbo`
- No camera nodes: re-check wiring and `dmesg` for errors
- No stream: check `/var/log/mediamtx.log` and libcamera
Contact
- Keep a copy of `dmesg` and `/var/log/mediamtx.log` when asking for help.

420
README.md
View File

@ -1,130 +1,73 @@
# SC235HAI Zero 2W Installation and RTSP Testing Guide
# SC235HAI Zero 2W — Step-by-step Hardware & Bring-up Guide
This guide covers the full workflow for a clean Raspberry Pi Zero 2W system after first boot:
This document is a concise, step-by-step guide to wire the SC235HAI camera, prepare a Raspberry Pi Zero 2W system, build and deploy the `sc235hai` driver, and verify RTSP streaming with MediaMTX.
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.
**Safety first:** power the board only after wiring is complete. Work on an anti-static surface when possible.
Assumptions:
- 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.
**Quick checklist:**
- **Wire hardware**
- **Prepare system & install dependencies**
- **Configure boot and serial**
- **Clone, build, and install driver**
- **Enable autoload and reboot**
- **Start MediaMTX and test RTSP**
---
## 1. Prerequisites
**1. Wire the camera hardware**
### 1.1 Connect to the board
- Power: provide a stable 5V (or platform-specific) power supply to the Pi.
- CSI / Camera connector: connect the camera board to the Pi's CSI ribbon per your carrier board layout.
- I2C (camera control): ensure SDA / SCL lines are connected between the Pi camera I2C (VC) header and the sensor.
- GPIOs used by overlay: follow the design notes — the overlay expects control GPIOs (for example GPIO4, GPIO40) to be available and pulled high during startup.
- Ground: connect camera ground to Pi ground.
If you have a custom carrier board, confirm the pinout in your schematic before applying power.
---
**2. Prepare the Raspberry Pi Zero 2W system**
1. SSH into the board (replace <board-ip>):
```bash
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.
### 1.2 Update the system and install dependencies
Run the following on the Zero 2W:
2. Update and install required packages:
```bash
apt update
apt install -y \
git \
build-essential \
raspberrypi-kernel-headers \
device-tree-compiler \
v4l-utils \
libcamera-apps \
ffmpeg \
curl \
ca-certificates
# core packages
apt install -y git build-essential device-tree-compiler v4l-utils libcamera-apps ffmpeg curl ca-certificates
# kernel headers: try the Raspberry Pi package first; if it's unavailable,
# install headers that match the running kernel instead.
if apt-cache policy raspberrypi-kernel-headers | grep -q Candidate; then
apt install -y raspberrypi-kernel-headers
else
apt install -y linux-headers-$(uname -r)
fi
```
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.
- Prefer `raspberrypi-kernel-headers` on official Raspberry Pi OS images when available.
- If `raspberrypi-kernel-headers` is not found (example: "Unable to locate package"),
use `linux-headers-$(uname -r)` as the matching headers alternative — this is
already valid on your Zero 2W when `linux-headers-$(uname -r)` is installed.
- `device-tree-compiler` (`dtc`) is used to build overlays from `.dts` files.
---
## 2. Build the SC235HAI driver
**3. Configure boot and serial**
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`:
1. Edit the firmware config file:
```bash
nano /boot/firmware/config.txt
```
Make sure the following lines are present:
2. Add or verify these lines (append if missing):
```ini
camera_auto_detect=0
@ -134,15 +77,15 @@ gpio=40=op,dh
dtoverlay=sc235hai
```
Meaning of the settings:
Explanation:
- `camera_auto_detect=0` prevents automatic camera detection from overriding the custom overlay.
- `dtparam=i2c_vc=on` enables the camera I2C bus.
- `gpio=...` lines drive required GPIOs high at boot (example pins used by this hardware).
- `dtoverlay=sc235hai` loads the overlay at boot (overlay must be installed to `/boot/firmware/overlays/`).
- `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.
Optional: Enable serial console or camera debug UART if you use the serial port for logs — adjust `config.txt` or `raspi-config` accordingly.
Save the file and reboot:
Reboot after making changes:
```bash
reboot
@ -150,9 +93,86 @@ reboot
---
## 4. Verify the driver after reboot
**4. Obtain the SC235HAI driver source**
After the board comes back, reconnect over SSH and run:
Either copy the existing `sc235hai_driver` folder to the board or clone the repo on the Pi.
From your workstation (copy):
```bash
scp -r sc235hai_driver root@<board-ip>:/root/
```
Or on the board (git clone):
```bash
cd /root
git clone <your-repo-url> sc235hai_driver
```
Change to the driver directory:
```bash
cd /root/sc235hai_driver
```
---
**5. Build and install the driver**
1. Build the kernel module:
```bash
make
```
This should create `sc235hai.ko` in the driver folder.
2. Compile the device-tree overlay:
```bash
dtc -@ -I dts -O dtb -o sc235hai.dtbo sc235hai.dts
```
3. Install the built artifacts into the system locations:
```bash
cp sc235hai.ko /lib/modules/$(uname -r)/extra/
cp sc235hai.dtbo /boot/firmware/overlays/
depmod -a
```
4. Load the module manually to test:
```bash
modprobe sc235hai
lsmod | grep -i sc235hai
dmesg | grep -i sc235
```
If `lsmod` shows `sc235hai` and `dmesg` shows sensor initialization, the build and install were successful.
---
**6. Enable driver autoload at boot**
Ensure the `dtoverlay=sc235hai` line is present in `/boot/firmware/config.txt` (see step 3). If you prefer module-based autoloading instead of DT overlay, add the module name to `/etc/modules-load.d/sc235hai.conf`:
```bash
echo sc235hai > /etc/modules-load.d/sc235hai.conf
```
Then reboot:
```bash
reboot
```
---
**7. Verify the driver after reboot**
After the board restarts, SSH back in and run:
```bash
lsmod | grep -i sc235hai
@ -160,199 +180,77 @@ dmesg | grep -i sc235
media-ctl -p
ls /dev/video*
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
libcamera-hello --list-cameras
```
If the camera appears in the output, the system-side detection is working.
Checks:
- `lsmod` should show `sc235hai` loaded.
- `dmesg` should show successful probe messages and no obvious errors.
- `/dev/video*` or `/dev/media*` device nodes should exist.
- `libcamera-hello --list-cameras` should show the camera.
If the camera is not listed, re-check wiring, overlay, and dmesg error lines.
---
## 5. Start MediaMTX for RTSP streaming
**8. Prepare MediaMTX for streaming**
This workflow does not use the deployment script. It starts `mediamtx` directly.
### 5.1 Check that MediaMTX files are present
1. Copy `mediamtx` binary and `mediamtx.yml` to the board (if not present):
```bash
ls -l /root/mediamtx /root/mediamtx.yml
scp mediamtx mediamtx.yml root@<board-ip>:/root/
```
If the files are missing, copy them to `/root/` first.
### 5.2 Stop any old instance
2. Stop any running instance:
```bash
pkill -f mediamtx 2>/dev/null || true
```
### 5.3 Start MediaMTX directly
---
**9. Start MediaMTX and test RTSP**
Start MediaMTX in the background and save logs:
```bash
setsid /root/mediamtx /root/mediamtx.yml >/var/log/mediamtx.log 2>&1 </dev/null &
```
This runs MediaMTX in the background and writes logs to `/var/log/mediamtx.log`.
### 5.4 Check the process and logs
```bash
pgrep -af mediamtx
tail -n 50 /var/log/mediamtx.log
```
If everything is working, you should see something similar to:
Typical RTSP URL:
```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
Test from a client:
- VLC: open the RTSP URL.
- ffplay:
```bash
ffplay "rtsp://<board-ip>:8554/cam"
```
### 6.3 OpenCV
- OpenCV quick test (Python):
```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
ret, frame = cap.read()
print('frame ok', ret)
cap.release()
cv2.destroyAllWindows()
```
If the image displays correctly, the driver, sensor, MediaMTX, and network path are all working.
---
## 7. Common issues
### 7.1 `modprobe sc235hai` cannot find the module
Check whether the module is installed for the current kernel:
```bash
find /lib/modules/$(uname -r) -name 'sc235hai.ko*'
```
If nothing is found, rebuild and reinstall:
```bash
cd /root/sc235hai_driver
make
cp sc235hai.ko /lib/modules/$(uname -r)/extra/
depmod -a
```
### 7.2 `lsmod` does not show `sc235hai`
Check whether `config.txt` contains:
```ini
dtoverlay=sc235hai
```
Then reboot again.
### 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
**10. Troubleshooting (quick checks)**
The key points are:
- Module not found: ensure `sc235hai.ko` is installed under `/lib/modules/$(uname -r)/extra/` and run `depmod -a`.
- Overlay not loaded: confirm `/boot/firmware/overlays/sc235hai.dtbo` exists and `dtoverlay=sc235hai` is in `config.txt`.
- No devices: check wiring and `dmesg | grep -i sc235` for errors.
- MediaMTX has no image: verify libcamera sees the camera first; then check `/var/log/mediamtx.log`.
- RTSP errors: ensure client can reach the board on port `8554` and no firewall blocks it.
- `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.
If you want, I can produce a one-page printable checklist or a minimal field checklist file.