vision/README.md

# linefollower_eye

ESP32-S3 camera board that finds a coloured blob and reports its position over I2C. Meant to sit on a robot as the “eye”, with something like a Pico as the master.

## What it does

The ESP runs HSV blob detection on the camera. A MicroPython master can turn the camera on, set colour, and poll for a target. Optionally it can join Wi‑Fi so you can open a browser page to tune the colour live.

Target position from `read_target()` is relative to the image centre (320x240). Positive x is right, positive y is up. No target returns `None`.

## Hardware

ESP pins for the I2C slave:

- SDA: GPIO19
- SCL: GPIO20
- Address: 0x42

Example Pico wiring:

- GP0 (SDA) -> ESP GPIO19
- GP1 (SCL) -> ESP GPIO20
- GND shared
- Use external pull-ups on SDA/SCL (about 2k2–4k7 to 3V3)

Camera and Wi‑Fi stay off until the master enables them.

## Firmware

ESP-IDF project for ESP32-S3. Build and flash as usual:

```
idf.py build
idf.py -p PORT flash monitor
```

## MicroPython master

Files live in `mp_i2c_master/`. Copy `vision.py` (and `main.py` if you want the demo) onto the board.

```python
from vision import Vision
import time

eye = Vision(sda=0, scl=1)
eye.start() # start the camera and blob algorithm

eye.set_hsv(4, 128, 116) # Set target colour (HSV)
eye.set_rgb(255, 255, 255) # Set RGB LED to max white

# Optional: browser UI for tuning colour  
#eye.set_wifi("rr workshop", "ourpassword")
#print(eye.wifi_ip())
        
while True:
    target = eye.read_target()
    if target is None:
        print("no target")
    else:
        x, y = target
        print("target at ({}, {})".format(x, y))
    time.sleep(0.07)
```

Useful calls:

- `eye.start()` — camera on and local detection
- `eye.set_hsv(h, s, v)` / `eye.set_tolerance(...)` — colour (or tune in the browser)
- `eye.set_wifi(ssid, password)` / `eye.wifi_off()` / `eye.wifi_ip()`
- `eye.read_target()` — `(x, y)` or `None`
- `eye.set_rgb(r, g, b)`

## Web UI

After Wi‑Fi is up, open the ESP’s IP in a browser. You get the live image, colour picker / eyedropper, mask options, and timing. Colour changes there are what the I2C master reads next.

## Other folders

- `pc_vision/` — older desktop viewer; the on-device web UI replaces it for tuning
- `main/` — ESP firmware