Doc bug: Wire Library page

gwideman

Well-known member
Hi all, but mostly for Paul, or at least his vast documentation department :),

Regarding page: "Wire Library" https://www.pjrc.com/teensy/td_libs_Wire.html.

There are a couple of serious problems with the sample code on that page, such that someone following that code will end up in a puzzling dead end unless they have a scope.

1. The more serious of the two problems is that a couple of the library functions don't do what the code thinks they do. I'm wondering if it was written using a long-ago version of Wire, and those library functions have changed since then?

The culprit section is:

HTML:
// read 1 byte, from address 0
  Wire.requestFrom(80, 1);
  while(Wire.read()) {
    num = Wire.receive();
  }

This appears to think that read() returns true if there's data available, and receive() actually fetches the data. With the current library, read() actually returns a byte of data, and receive() has a comment that it's only there for backward compatibility with some old version of the library.

So, I think this example should feature Wire.available() to check data is available, and use Wire.read() to read the byte of data.

But that said, it's not clear the point of the while loop. Is it to slurp all available data? But only 1 byte was requested? Or was it intended to wait for data ready? Not sure.

2. The second issue is more of a gotcha:

Code:
  // set the 24C256 eeprom address to 0
  Wire.beginTransmission(80);
  Wire.write(0);  // address high byte
  Wire.write(0);  // address low byte
  Wire.endTransmission();

It would be super helpful to note that different devices with their different capacities, may have different numbers of address bytes. For example, the 24LC16 has only a single byte of address.

Hope that helps.
 
I'd leave these "as is" for pedagogic reasons. People should never simply and blindly copy and paste example code but study and fully understand a library's API documentation or, still better, its source code and then be able to write their own flawless code. ;)
 
I'd leave these "as is" for pedagogic reasons. People should never simply and blindly copy and paste example code but study and fully understand a library's API documentation or, still better, its source code and then be able to write their own flawless code. ;)

Who exactly is going to be helped by documentation that is incorrect? What possibly pedagogic purpose does that serve?
 
Back
Top