Description
Recently, some new timeout API methods were added to the AVR Wire library (see arduino/ArduinoCore-avr#42), which should be documented. Given there is no repository for the library reference, I'm going to report this here. While looking at the Wire docs at https://www.arduino.cc/en/Reference/Wire I noticed that the end() method is also not documented yet.
Please find a proposal for documentation below, comments welcome. I've tried to match the formatting (heading levels etc.) to the existing doc pages, but it's likely that this still needs some handwork to integrate. Also, there's a fair chance that I've written this in too much detail or technically too complex for the novice audience, so feedback on that aspect is also welcome.
Wire
Just above the "Note" section, add:
Recent versions of the Wire library can use timeouts to prevent a lockup in the face of certain problems on the bus, but this is not enabled by default (yet) in current versions. It is recommended to always enable these timeouts when using the Wire library. See the Wire.setWireTimeout function for more details.
Wire.end()
Description
Disable the Wire library, reversing the effect of Wire.begin(). To use the Wire library again after this, call Wire.begin() again.
Syntax
Wire.end()
Parameters
None.
Returns
None.
Portability Notes
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_END macro, which is only defined when Wire.end() is available.
Wire.endTransmission()
Under "Returns", add:
- 5:timeout
Wire.setWireTimeout()
Description
Sets the timeout for Wire transmissions in master mode.
On platforms that support it, these timeouts can help handle unexpected situations on the Wire bus, such as another device or a short-circuit that keeps the bus blocked indefinitely, or noise that looks like a start condition, making it look there is another master active that keeps the bus claimed.
Note that these timeouts are almost always an indication of an underlying problem, such as misbehaving devices, noise, insufficient shielding, or other electrical problems. These timeouts will prevent your sketch from locking up, but not solve these problems. In such situations there will often (also) be data corruption which doesn't result in a timeout or other error and remains undetected. So when a timeout happens, it is likely that some data previously read or written is also corrupted. Additional measures might be needed to more reliably detect such issues (e.g. checksums or reading back written values) and recover from them (e.g. full system reset). This timeout and such additional measures should be seen as a last line of defence, when possible the underlying cause should be fixed instead.
Syntax
Wire.setWireTimeout(timeout, reset_on_timeout)
Wire.setWireTimeout()
Parameters
timeout a timeout: timeout in microseconds, if zero then timeout checking is disabled
reset_on_timeout: if true then Wire hardware will be automatically reset on timeout
When this function is called without parameters, a default timeout is configured that should be sufficient to prevent lockups in a typical single-master configuration.
Returns
None.
Example Code
#include <Wire.h>
void setup() {
Wire.begin(); // join i2c bus (address optional for master)
#if defined(WIRE_HAS_TIMEOUT)
Wire.setWireTimeout(3000 /* us */, true /* reset_on_timeout */);
#endif
}
byte x = 0;
void loop() {
/* First, send a command to the other device */
Wire.beginTransmission(8); // transmit to device arduino/Arduino#8
Wire.write(123); // send command
byte error = Wire.endTransmission(); // run transaction
if (error) {
Serial.println("Error occured when writing");
if (error == 5)
Serial.println("It was a timeout");
}
delay(100);
/* Then, read the result */
#if defined(WIRE_HAS_TIMEOUT)
Wire.clearWireTimeoutFlag();
#endif
byte len = Wire.requestFrom(8, 1); // request 1 byte from device arduino/Arduino#8
if (len == 0) {
Serial.println("Error occured when reading");
#if defined(WIRE_HAS_TIMEOUT)
if (Wire.getWireTimeoutFlag())
Serial.println("It was a timeout");
#endif
}
delay(100);
}
Notes and Warnings
How this timeout is implemented might vary between different platforms, but typically a timeout condition is triggered when waiting for (some part of) the transaction to complete (e.g. waiting for the bus to become available again, waiting for an ACK bit, or maybe waiting for the entire transaction to be completed).
When such a timeout condition occurs, the transaction is aborted and endTransmission() or requestFrom() will return an error code or zero bytes respectively. While this will not resolve the bus problem by itself (i.e. it does not remove a short-circuit), it will at least prevent blocking potentially indefinitely and allow your software to detect and maybe solve this condition.
If reset_on_timeout was set to true and the platform supports this, the Wire hardware is also reset, which can help to clear any incorrect state inside the Wire hardware module. For example, on the AVR platform, this can be required to restart communications after a noise-induced timeout.
When a timeout is triggered, a flag is set that can be queried with getWireTimeoutFlag() and must be cleared manually using clearWireTimeoutFlag() (and is also cleared when setWireTimeout() is called).
Note that this timeout can also trigger while waiting for clock stretching or waiting for a second master to complete its transaction. So make sure to adapt the timeout to accomodate for those cases if needed. A typical timeout would be 25ms (which is the maximum clock stretching allowed by the SMBus protocol), but (much) shorter values will usually also work.
Portability Notes
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.clearWireTimeout() are all available.
When this timeout feature was introduced on the AVR platform, it was initially kept disabled by default for compatibility, expecting it to become enabled at a later point. This means the default value of the timeout can vary between (versions of) platforms. The default timeout settings are available from the WIRE_DEFAULT_TIMEOUT and WIRE_DEFAULT_RESET_WITH_TIMEOUT macro.
If you require the timeout to be disabled, it is recommended you disable it by default using setWireTimeout(0), even though that is currently the default.
See Also
- Wire.getWireTimeoutFlag()
- Wire.clearWireTimeoutFlag()
- Wire.endTransmission()
- Wire.requestFrom()
Wire.getWireTimeoutFlag()
Description
Checks whether a timeout has occured since the last time the flag was cleared.
This flag is set is set whenever a timeout occurs and cleared when Wire.clearWireTimeoutFlag() is called, or when the timeout is changed using Wire.setWireTimeout().
Timeouts might not be enabled by default. See the documentation for Wire.setWireTimeout() for more information on how to configure timeouts and how they work.
Syntax
Wire.getWireTimeoutFlag()
Parameters
None.
Returns
bool: The current value of the flag
Portability Notes
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.clearWireTimeout() are all available.
See Also
- Wire.clearWireTimeoutFlag()
- Wire.setWireTimeout()
Wire.clearWireTimeoutFlag()
Description
Clear the timeout flag.
Timeouts might not be enabled by default. See the documentation for Wire.setWireTimeout() for more information on how to configure timeouts and how they work.
Syntax
Wire.clearTimeout()
Parameters
None.
Returns
None.
Portability Notes
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.clearWireTimeout() are all available.
See Also
- Wire.getWireTimeoutFlag()
- Wire.setWireTimeout()
Activity
bperrybap commentedon Sep 26, 2020
What about WIRE_HAS_END macro? It is used to indicate the existence of end()
Also, it seems like the macros WIRE_HAS_END should show up somewhere on the end() web page
Llkewise it seems like WIRE_HAS_TIMEOUT should show up somewhere on the pages for
setTimeout(), Wire.getWireTimeoutFlag(), Wire.clearWireTimeoutFlag() i.e. all the pages that are for functions that exist when the macro exists.
Perhaps add a section called "NOTES" or "OTHER INFORMATION" to the documentation web pages for the information about the macro.
matthijskooijman commentedon Sep 28, 2020
Thanks, forgot about that one. I added it now.
Good point. It was already on the
setWireTimeout()page above, but I now added it to all three (and changed the wording ongetWireTimeout()to be more complete).I added a "Portability Notes" section now, which seems more specific.
bperrybap commentedon Sep 28, 2020
Sounds great.
freddyrios commentedon Oct 2, 2020
Got here after reading arduino/ArduinoCore-avr#42 and related issues/pr.
It would be great to also add a note about it directly to the Wire page too https://www.arduino.cc/en/Reference/Wire. Having it visible like that can potentially safe a lot of pain.
Also should there be some extra warning or links about the concerns mentioned here (if confirmed to be valid)? arduino/ArduinoCore-avr#42 (comment). The claim seems to be that is a good idea to take timeout cases as a warning sign of hardware issues in some cases, that if left alone can be lead to other issues.
bperrybap commentedon Oct 2, 2020
@freddyrios,
The concerns are valid. If there are timeout errors and there are not multi masters on the bus, then there is some sort of h/w issue causing bit errors on the bus. The effects of those bit errors are unpredictable.
Not only that, but most bit errors on the bus can not be detected. The only bit errors that can be detected are those that happen to occur during the address, or the status portion of the transfer because they cause some sort of issue like trying to address a non existent slave, or confuse the master into thinking that there is another master on the bus.
But I do agree with you that it would be a good idea to have some sort of note/information about the potential causes of timeouts and seriousness of i2c bus signal corruption.
matthijskooijman commentedon Oct 3, 2020
Good suggestion, I added a small paragraph to the first post.
There was already this bit:
But, you make a good point, so I added a more specific warning to the main description.
How do these look?
bperrybap commentedon Oct 3, 2020
IMO, there needs to be a bit more more about timeouts.
The language around timeouts does not seem strong enough. It does not mention some of the other possible things that could and often do happen and can go undetected when there are issues like misbehaving slaves and/or bus noise.
Things like data corruption or writing/reading to the wrong slave.
And that this data corruption cause the need to re-initialize or restart the slave.
So getting a timeout likely means that a slave will have to be full re-initialized since there is now way to know what data/commands the slave has received.
In the real-world cases I've seen, there is often quite a bit of data corruption before a lockup (now timeout) would happen.
The reason I think additional text is needed, is that in issue thread about adding the timeout, it seems like several of the posters seem to be of the incorrect assumption that just having a timeout in the Wire library and retries on top of that either in a higher level library that uses Wire, or in the sketch, can fix things. But that is definitely not the case.
For example, on i2c LCDs, you can end up with lots of garbage on the display from data corruption before the lockup/timeout.
So even if you did do a retry on an operation when there was a timeout, it would likely not keep the display from getting corrupted.
In some cases like a hd44780 LCD with a PCF8574 based backpack, the i2c data corruption can cause the host and the LCD to lose nibble sync from garbage commands. When out of nibble sync, the display will continue to be corrupted as the host sends more data/commands since it is being misinterpreted.
The only way to get back into nibble sync is to start the full initialization over.
freddyrios commentedon Oct 5, 2020
The way it reads now for me is there is a note in the Wire page leads you to the method doc that has this fairly up in the text:
Sounds good to me, as very early it is talking about the actual problems underneath. Of course the more info to help us outside avoids the pitfalls the better. Links to any relevant topics that points people in the right direction(s) to help solve the real root causes would be incredibly helpful (and almost certainly get people to give it a shot).
bperrybap commentedon Oct 5, 2020
My issue is with
It hints that even though there are may be timeouts, that the system is still capable of properly functioning.
There will never be proper operation when timeouts are occurring due to signal corruption. When there is enough signal corruption to cause a timeout, there is plenty more that is also causing silent/undetected data corruption.
So, IMO, the message could/should have a bit stronger message than just saying it is "not recommended".
It should indicate that the presence of timeouts very likely indicates the presence of other issues which cannot be detected and are silently occurring like data corruption.
matthijskooijman commentedon Oct 8, 2020
The way I meant this is that if there are bus lockups or other problems, that you should not just enable timeouts and except it to make things run properly.
But we can make it stronger, how about this?
I don't want to go into too much detail here, also since this page is about the Wire library in general, not necessarily specific to the AVR hardware. But external links could probably be added, if anyone knows of appropriate ones.
bperrybap commentedon Oct 8, 2020
I like the added detail. Here is an additional tweak:
Not sure how much, if any, information to provide on how to identify/solve potential issues.
It is kind of can of worms and it is a pretty complex subject getting into analog electrical issues.
Although It might be worth mentioning some of the more common issues, such as poor wiring/connections, or attempting to use "long" wires (I know, we would need to try to somehow describe what "long" means)
Since posts related to these issues do come up from time to time on the forum.
I think the most important thing is the information about timeouts that hopefully gets the message out that Wire library lockups or timeouts are an indication of other h/w issues that cannot be fully resolved in s/w in the sketch or the library.
ermtl commentedon Nov 21, 2020
I2C using both a strong low state and a weak high state with a pullup resistor, it's very susceptible to all kinds of electrical noises that are not the sign of h/w issues. Position your device close to a dimmer controlled brushed motor and see the error count increase, or just be in a thunderstorm. Shielding can be effective but has it's limits.
A way to approach the problem is to consider I2C as a transmission protocol that might have errors and see what could be done about it. Designers of the OneWire protocol that's electrically similar with a pullup and a long line added CRC checks to all communications, but nearly all I2C circuits don't have that.
Fortunately, the protocol itself includes a 'start' condition that resets the state machine of any I2C compliant device, making each transaction independent (errors don't propagate) and a lot can be done in software, the exact details depend on the chip used, but here are a few hints:
If the sensor value fails the plausibility test, replace it with either the previous value, the default value or an average of the previous and default value. Have a counter for such occurrences. This can handle both I2C errors and sensor malfunctions
As a side note, the problem with hd44780 LCD with a PCF8574 backpack is tricky and very specific. It occurs because this display is 'write only' and there is no way to read from it and know if the nibbles are in the correct order or inverted causing display corruption. This is a very rare case as all other devices I can think of have some ability to be read that would allow such a problem to be detected. From a reliability point of view, the hd44780 LCD + PCF8574 combination is not a good solution. If it needs to be used, a periodic display reset sequence (the only way to reorder the nibbles) should be implemented, the delay being a compromise between how long a garbled display can be tolerated and the short visible glitch that's visible each time the display is reset.
matthijskooijman commentedon Nov 21, 2020
@ermtl, most of what you write seems like good advice, though I'm not entirely sure what you intend with this? I'm not sure if this much detail is appropriate for this reference documentation page, or did you have something else in mind?
Concerning timeouts, two additional remarks:
29 remaining items