feat: change sccb APIs for sharing i2c port with other devices

[WangYuxin-esp]

• Leave the allocation, configuration and deallocation of the i2c bus under the control of application code.
• Configure the pin_sccb_sda and pin_sccb_scl pins to -1, then pass the initialized i2c port number to sccb_i2c_port to share the I2C port with other devices.

[jepler]

I raised a similar issue in #434. However, I think this PR in its current form doesn't meet our needs. Thanks to @igrr for pointing me here.

In CircuitPython, we do not know statically which i2c port number will be associated with the camera. Rather, it is determined at runtime by CircuitPython, which tracks which i2c port number(s) are available itself and assumes no other part of the system allocates i2c ports.

Suppose the product has two I2C buses, one for the camera SCCB and one for a sensor. The application code might say:

camera_bus = busio.I2C(...) # assume this allocates I2C port 0
sensor_bus = busio.I2C(...) # assume this allocates I2C port 1

camera = esp32_camera.Camera(..., i2c=camera_bus, ...) # the camera must use bus 0

but the application must also operate if the I2C buses are constructed in the opposite order:

sensor_bus = busio.I2C(...) # allocates I2C port 0
camera_bus = busio.I2C(...) # allocates I2C port 1

camera = esp32_camera.Camera(..., i2c=camera_bus, ...) # the camera must use bus 1

Furthermore, consider the case where instead of having two separate buses, there's just a single bus with a sensor and a camera:

combined_bus = busio.I2C(...) # allocates I2C port 0

sensor = Sensor(i2c=combined_bus)

camera = esp32_camera.Camera(..., i2c=combined_bus, ...) # so the camera must use bus 0
camera.deinit()

# At this point, `combined_bus` must remain valid so that `sensor` can still be used

So, for CircuitPython we want to leave the allocation, configuration and deallocation of the i2c bus under the control of CircuitPython. The bus number cannot be statically determined, and the camera may never deallocate/deinitialize the i2c bus. In practice, it's OK if constructing the camera configures the bus, since all devices on the bus have to be compatible in settings anyway.

[igrr]

Thanks for the explanation @jepler!

@WangYuxin-esp could you please look at the solution proposed in #434 and see if it meets your needs? If yes, would you mind updating the PR as suggested there?

[WangYuxin-esp]

Thanks for the explanation @jepler!
The current solution can help solve the issue of I2C bus multiplexing. However, the current PR does not address the issue of I2C deactivation after calling cam.deinit() when multiple devices share an I2C bus.

[WangYuxin-esp]

I can update this PR, or please @jepler create a new one.

[jepler]

I can, but my other duties would prevent me from submitting a PR for this for at least 2 weeks.

[WangYuxin-esp]

@jepler I have changed the relevant code about sccb. PTAL.

[igrr]

Really good update, thanks @WangYuxin-esp! Have left some mostly minor comments.

[igrr]

Latest version looks good to me, thanks for addressing my comments!
Let's wait a bit for @jepler to have a look before we merge this.

[wuyuanyi135]

I feel lucky when I am currently designing a product with insufficient IO pins and then see this PR. Looking forward to merging this feature!

[me-no-dev]

@WangYuxin-esp all looks great, but I would like you to make the rename from pin_sscb_* to pin_sccb_* in camera_config_t as a separate pull request. That change is not critical for the functionality that this PR intends to add, but will break a lot of working code. Please do this change and I will merge the code immediately :)

[igrr]

@me-no-dev the sscb -> sccb rename seems to be a non-breaking one as far as I can tell, due to

    union {
        int pin_sccb_sda;           /*!< GPIO pin for camera SDA line */
        int pin_sscb_sda __attribute__((deprecated("please use pin_sccb_sda instead")));           /*!< GPIO pin for camera SDA line (legacy name) */
    };
    union {
        int pin_sccb_scl;           /*!< GPIO pin for camera SCL line */
        int pin_sscb_scl __attribute__((deprecated("please use pin_sccb_scl instead")));           /*!< GPIO pin for camera SCL line (legacy name) */
    };

(pin_sscb_sda and pin_sscb_scl will still work, will produce deprecation warning)

[me-no-dev]

Ha! Seems I have misread the changes... 🤷‍♂️ merging now.