@@ -90,9 +90,28 @@ void TwoWire::setClock(uint32_t clock)
9090/* **
9191 * Sets the TWI timeout.
9292 *
93+ * This limits the maximum time to wait for the TWI hardware. If more time passes, the bus is assumed
94+ * to have locked up (e.g. due to noise-induced glitches or faulty slaves) and the transaction is aborted.
95+ * Optionally, the TWI hardware is also reset, which can be required to allow subsequent transactions to
96+ * succeed in some cases (in particular when noise has made the TWI hardware think there is a second
97+ * master that has claimed the bus).
98+ *
99+ * When a timeout is triggered, a flag is set that can be queried with `getWireTimeoutFlag()` and is cleared
100+ * when `clearWireTimeoutFlag()` or `setWireTimeoutUs()` is called.
101+ *
102+ * Note that this timeout can also trigger while waiting for clock stretching or waiting for a second master
103+ * to complete its transaction. So make sure to adapt the timeout to accomodate for those cases if needed.
104+ * A typical timeout would be 25ms (which is the maximum clock stretching allowed by the SMBus protocol),
105+ * but (much) shorter values will usually also work.
106+ *
107+ * In the future, a timeout will be enabled by default, so if you require the timeout to be disabled, it is
108+ * recommended you disable it by default using `setWireTimeoutUs(0)`, even though that is currently
109+ * the default.
110+ *
93111 * @param timeout a timeout value in microseconds, if zero then timeout checking is disabled
94112 * @param reset_with_timeout if true then TWI interface will be automatically reset on timeout
95113 * if false then TWI interface will not be reset on timeout
114+
96115 */
97116void TwoWire::setWireTimeout (uint32_t timeout, bool reset_with_timeout){
98117 twi_setTimeoutInMicros (timeout, reset_with_timeout);
@@ -101,7 +120,7 @@ void TwoWire::setWireTimeout(uint32_t timeout, bool reset_with_timeout){
101120/* **
102121 * Returns the TWI timeout flag.
103122 *
104- * @return true if timeout has occured
123+ * @return true if timeout has occured since the flag was last cleared.
105124 */
106125bool TwoWire::getWireTimeoutFlag (void ){
107126 return (twi_manageTimeoutFlag (false ));
0 commit comments