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 <board-ip>):

```bash
ssh root@<board-ip>
```

2. Update and install required packages:

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

```bash
nano /boot/firmware/config.txt
```

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

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

```bash
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):

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

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

2. Stop any running instance:

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

---

**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 &
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:

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

- OpenCV quick test (Python):

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