setWireTimeout() sets the timeout for Wire transmissions in controller mode.
When called without parameters, a default timeout is configured that should be sufficient to prevent lockups in a typical single-controller configuration.
This function is part of the Wire library. See the Wire main page for more information.
Wire.setWireTimeout(timeout, reset_on_timeout)Wire.setWireTimeout()timeout: timeout value in microseconds. If set to 0, timeout checking is disabled. Allowed data types: uint32_t.reset_on_timeout: if true, the Wire hardware will be automatically reset on timeout. Allowed data types: bool.Nothing.
#include <Wire.h>
void setup() {
Wire.begin(); // Join I2C bus (address optional for controller)
#if defined(WIRE_HAS_TIMEOUT)
Wire.setWireTimeout(3000 /* us */, true /* reset_on_timeout */);
#endif
}
void loop() {
// Send a command to the peripheral device
Wire.beginTransmission(8);
Wire.write(123);
byte error = Wire.endTransmission();
if (error) {
Serial.println("Error occurred when writing");
if (error == 5)
Serial.println("It was a timeout");
}
delay(100);
// Read the result
#if defined(WIRE_HAS_TIMEOUT)
Wire.clearWireTimeoutFlag();
#endif
byte len = Wire.requestFrom(8, 1);
if (len == 0) {
Serial.println("Error occurred when reading");
#if defined(WIRE_HAS_TIMEOUT)
if (Wire.getWireTimeoutFlag())
Serial.println("It was a timeout");
#endif
}
delay(100);
}
Understanding timeouts: Timeouts are almost always an indication of an underlying problem, such as misbehaving devices, noise, insufficient shielding, or other electrical problems. Timeouts will prevent your sketch from locking up, but not solve these problems. When a timeout happens, some previously read or written data may also be corrupted. Additional measures (such as checksums or reading back written values) and recovery strategies (such as a full system reset) may be needed. When possible, the underlying cause should be fixed instead.
How timeouts work: A timeout condition is typically triggered when waiting for some part of the transaction to complete (e.g., waiting for the bus to become available, waiting for an ACK bit, or waiting for the entire transaction to complete). When a timeout occurs, the transaction is aborted and endTransmission() or requestFrom() will return an error code or zero bytes respectively.
Hardware reset: If reset_on_timeout was set to true and the platform supports this, the Wire hardware is also reset, which can help clear any incorrect state inside the Wire hardware module.
Timeout flag: When a timeout is triggered, a flag is set that can be queried with getWireTimeoutFlag() and must be cleared manually using clearWireTimeoutFlag() (it is also cleared when setWireTimeout() is called).
Recommended values: A typical timeout would be 25 ms (which is the maximum clock stretching allowed by the SMBus protocol), but shorter values will usually also work. Make sure to adapt the timeout to accommodate for clock stretching or multi-controller configurations if needed.
Portability: This function was not available in the original version of the Wire library and might still not be available on all platforms. Code that needs to be portable across platforms and versions can use the WIRE_HAS_TIMEOUT macro, which is only defined when Wire.setWireTimeout(), Wire.getWireTimeoutFlag(), and Wire.clearWireTimeoutFlag() are all available.
Default values: The default timeout settings are available from the WIRE_DEFAULT_TIMEOUT and WIRE_DEFAULT_RESET_WITH_TIMEOUT macros. If you require the timeout to be disabled, it is recommended you disable it explicitly using setWireTimeout(0), even though that may be the current default.