sc235hai_driver/README.md

# SC235HAI Zero 2W Installation and RTSP Testing Guide

This guide covers the full workflow for a clean Raspberry Pi Zero 2W system after first boot:

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.

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.

---

## 1. Prerequisites

### 1.1 Connect to the board

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

```bash
apt update
apt install -y \
  git \
  build-essential \
  raspberrypi-kernel-headers \
  device-tree-compiler \
  v4l-utils \
  libcamera-apps \
  ffmpeg \
  curl \
  ca-certificates
```

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.

---

## 2. Build the SC235HAI driver

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

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

Make sure the following lines are present:

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

Meaning of the settings:

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

Save the file and reboot:

```bash
reboot
```

---

## 4. Verify the driver after reboot

After the board comes back, reconnect over SSH and run:

```bash
lsmod | grep -i sc235hai
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.

---

## 5. Start MediaMTX for RTSP streaming

This workflow does not use the deployment script. It starts `mediamtx` directly.

### 5.1 Check that MediaMTX files are present

```bash
ls -l /root/mediamtx /root/mediamtx.yml
```

If the files are missing, copy them to `/root/` first.

### 5.2 Stop any old instance

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

### 5.3 Start MediaMTX directly

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

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

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

### 6.3 OpenCV

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

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

The key points are:

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