Forum Rule: Always post complete source code & details to reproduce any issue!
Results 1 to 3 of 3

Thread: Doc bug: Wire Library page

  1. #1

    Doc bug: Wire Library page

    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 Code:
    // 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.

  2. #2
    Senior Member+ Theremingenieur's Avatar
    Join Date
    Feb 2014
    Location
    Colmar, France
    Posts
    1,997
    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.

  3. #3
    Quote Originally Posted by Theremingenieur View Post
    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?

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •