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. **Safety first:** power the board only after wiring is complete. Work on an anti-static surface when possible.
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: **Quick checklist:**
- **Wire hardware**
- The board is connected to the network. - **Prepare system & install dependencies**
- You can reach it over SSH, for example `ssh root@<board-ip>`. - **Configure boot and serial**
- Replace `<board-ip>` with the actual IP address of your Zero 2W. - **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 ```bash
ssh root@<board-ip> 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. 2. Update and install required packages:
### 1.2 Update the system and install dependencies
Run the following on the Zero 2W:
```bash ```bash
apt update apt update
apt install -y \ # core packages
git \ apt install -y git build-essential device-tree-compiler v4l-utils libcamera-apps ffmpeg curl ca-certificates
build-essential \
raspberrypi-kernel-headers \ # kernel headers: try the Raspberry Pi package first; if it's unavailable,
device-tree-compiler \ # install headers that match the running kernel instead.
v4l-utils \ if apt-cache policy raspberrypi-kernel-headers | grep -q Candidate; then
libcamera-apps \ apt install -y raspberrypi-kernel-headers
ffmpeg \ else
curl \ apt install -y linux-headers-$(uname -r)
ca-certificates fi
``` ```
Notes: Notes:
- Prefer `raspberrypi-kernel-headers` on official Raspberry Pi OS images when available.
- `raspberrypi-kernel-headers` is required to build the kernel module. - If `raspberrypi-kernel-headers` is not found (example: "Unable to locate package"),
- `device-tree-compiler` is required to build `sc235hai.dtbo`. use `linux-headers-$(uname -r)` as the matching headers alternative — this is
- `v4l-utils`, `libcamera-apps`, and `ffmpeg` are used for verification and testing. 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.
### 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 **3. Configure boot and serial**
Change into the driver directory: 1. Edit the firmware config file:
```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 ```bash
nano /boot/firmware/config.txt nano /boot/firmware/config.txt
``` ```
Make sure the following lines are present: 2. Add or verify these lines (append if missing):
```ini ```ini
camera_auto_detect=0 camera_auto_detect=0
@ -134,15 +77,15 @@ gpio=40=op,dh
dtoverlay=sc235hai 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. Optional: Enable serial console or camera debug UART if you use the serial port for logs — adjust `config.txt` or `raspi-config` accordingly.
- `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: Reboot after making changes:
```bash ```bash
reboot 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 ```bash
lsmod | grep -i sc235hai lsmod | grep -i sc235hai
@ -160,199 +180,77 @@ dmesg | grep -i sc235
media-ctl -p media-ctl -p
ls /dev/video* ls /dev/video*
ls /dev/media* 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 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. 1. Copy `mediamtx` binary and `mediamtx.yml` to the board (if not present):
### 5.1 Check that MediaMTX files are present
```bash ```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. 2. Stop any running instance:
### 5.2 Stop any old instance
```bash ```bash
pkill -f mediamtx 2>/dev/null || true 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 ```bash
setsid /root/mediamtx /root/mediamtx.yml >/var/log/mediamtx.log 2>&1 </dev/null & 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 pgrep -af mediamtx
tail -n 50 /var/log/mediamtx.log 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 rtsp://<board-ip>:8554/cam
``` ```
### 6.1 VLC Test from a client:
- VLC: open the RTSP URL.
Open: - ffplay:
```text
rtsp://<board-ip>:8554/cam
```
### 6.2 ffplay
```bash ```bash
ffplay "rtsp://<board-ip>:8554/cam" ffplay "rtsp://<board-ip>:8554/cam"
``` ```
### 6.3 OpenCV - OpenCV quick test (Python):
```python ```python
import cv2 import cv2
cap = cv2.VideoCapture("rtsp://<board-ip>:8554/cam") cap = cv2.VideoCapture("rtsp://<board-ip>:8554/cam")
while True: ret, frame = cap.read()
ret, frame = cap.read() print('frame ok', ret)
if ret:
cv2.imshow("SC235HAI", frame)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cap.release() 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. If you want, I can produce a one-page printable checklist or a minimal field checklist file.
- 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.