sc235hai_driver/README.md

SC235HAI Zero 2W — Step-by-step Hardware & Bring-up Guide

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.

Safety first: power the board only after wiring is complete. Work on an anti-static surface when possible.

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. Wire the camera hardware

• 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 ):

ssh root@<board-ip>

2. Update and install required packages:

apt update
# 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:

• 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.

---

3. Configure boot and serial

1. Edit the firmware config file:

nano /boot/firmware/config.txt

2. Add or verify these lines (append if missing):

camera_auto_detect=0
dtparam=i2c_vc=on
gpio=4=op,dh
gpio=40=op,dh
dtoverlay=sc235hai

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/).

Optional: Enable serial console or camera debug UART if you use the serial port for logs — adjust config.txt or raspi-config accordingly.

Reboot after making changes:

reboot

---

4. Obtain the SC235HAI driver source

Either copy the existing sc235hai_driver folder to the board or clone the repo on the Pi.

From your workstation (copy):

scp -r sc235hai_driver root@<board-ip>:/root/

Or on the board (git clone):

cd /root
git clone <your-repo-url> sc235hai_driver

Change to the driver directory:

cd /root/sc235hai_driver

---

5. Build and install the driver

1. Build the kernel module:

make

This should create sc235hai.ko in the driver folder.

2. Compile the device-tree overlay:

dtc -@ -I dts -O dtb -o sc235hai.dtbo sc235hai.dts

3. Install the built artifacts into the system locations:

cp sc235hai.ko /lib/modules/$(uname -r)/extra/
cp sc235hai.dtbo /boot/firmware/overlays/
depmod -a

4. Load the module manually to test:

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:

echo sc235hai > /etc/modules-load.d/sc235hai.conf

Then reboot:

reboot

---

7. Verify the driver after reboot

After the board restarts, SSH back in and run:

lsmod | grep -i sc235hai
dmesg | grep -i sc235
media-ctl -p
ls /dev/video*
ls /dev/media*
libcamera-hello --list-cameras

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.

---

8. Prepare MediaMTX for streaming

1. Copy mediamtx binary and mediamtx.yml to the board (if not present):

scp mediamtx mediamtx.yml root@<board-ip>:/root/

2. Stop any running instance:

pkill -f mediamtx 2>/dev/null || true

---

9. Start MediaMTX and test RTSP

Start MediaMTX in the background and save logs:

setsid /root/mediamtx /root/mediamtx.yml >/var/log/mediamtx.log 2>&1 </dev/null &
pgrep -af mediamtx
tail -n 50 /var/log/mediamtx.log

Typical RTSP URL:

rtsp://<board-ip>:8554/cam

Test from a client:

• VLC: open the RTSP URL.
• ffplay:

ffplay "rtsp://<board-ip>:8554/cam"

• OpenCV quick test (Python):

import cv2
cap = cv2.VideoCapture("rtsp://<board-ip>:8554/cam")
ret, frame = cap.read()
print('frame ok', ret)
cap.release()

---

10. Troubleshooting (quick checks)

• 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.

If you want, I can produce a one-page printable checklist or a minimal field checklist file.