From 767b631e59de193710e0d80576b97f111c90c1aa Mon Sep 17 00:00:00 2001 From: yuquanjun Date: Thu, 28 May 2026 14:48:36 +0800 Subject: [PATCH] docs: add step-by-step bring-up guide and checklist; fallback for kernel headers --- CHECKLIST.md | 77 ++++++++++ README.md | 420 +++++++++++++++++++-------------------------------- 2 files changed, 236 insertions(+), 261 deletions(-) create mode 100644 CHECKLIST.md diff --git a/CHECKLIST.md b/CHECKLIST.md new file mode 100644 index 0000000..c5d68fb --- /dev/null +++ b/CHECKLIST.md @@ -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 :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. diff --git a/README.md b/README.md index 4053abb..e5a3d82 100644 --- a/README.md +++ b/README.md @@ -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@`. -- Replace `` 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 ): ```bash 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. - -### 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@:/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@:/root/ +``` + +Or on the board (git clone): + +```bash +cd /root +git clone 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@:/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 :8554/cam ``` -### 6.1 VLC - -Open: - -```text -rtsp://:8554/cam -``` - -### 6.2 ffplay +Test from a client: +- VLC: open the RTSP URL. +- ffplay: ```bash ffplay "rtsp://:8554/cam" ``` -### 6.3 OpenCV +- OpenCV quick test (Python): ```python import cv2 - cap = cv2.VideoCapture("rtsp://: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@ -lsmod | grep -i sc235hai -setsid /root/mediamtx /root/mediamtx.yml >/var/log/mediamtx.log 2>&1 :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. \ No newline at end of file +If you want, I can produce a one-page printable checklist or a minimal field checklist file.