add keyword timeout to I2C -- only used for bitbangioi

[jerryneedell]

Implemented the keyword "timeout" for bitbangio I2C clock-stretching ( based on code in extmod/machine_i2c.c) --- also added the keyword to busio to keep the API consistent, but it is ignored for busio.

If a timeout occurs a TimeoutError Exception is thrown.

[dhalbert]

Does busio native I2C do clock stretching automatically or have its own register for timeouts?

[jerryneedell]

I could not find any treatment of clock stretching so I assumed it was handled internally by the hardware. The spec does not call for a timeout. There is no limit. By implementing one in bitbangio we are adding a “feature”.

[jerryneedell]

@deshipu noted this in the I2C spec https://www.nxp.com/docs/en/user-guide/UM10204.pdf

SMBus has a time-out feature which resets devices if a communication takes too long.
This explains the minimum clock frequency of 10 kHz to prevent locking up the bus. I 2 C
can be a ‘DC’ bus, meaning that a slave device stretches the master clock when
performing some routine while the master is accessing it. This notifies the master that the
slave is busy but does not want to lose the communication. The slave device will allow
continuation after its task is complete. There is no limit in the I 2 C-bus protocol as to how
long this delay can be, whereas for a SMBus system, it would be limited to 35 ms.
SMBus protocol just assumes that if something takes too long, then it means that there is
a problem on the bus and that all devices must reset in order to clear this mode. Slave
devices are not then allowed to hold the clock LOW too long.

Should we change the default timeout to 35ms? - it is now 255 microseconds.
Or should we leave it as is and let the user experiment with it if it times out.

[tannewt]

Native ASF I2C has clock stretching that's count based. I'm not sure what the time in practice is.

[tannewt]

Looks great! Thanks @jerryneedell !