Wire library behavior and documentation corrections

Community Suggestions for the Arduino Project
1

Hi everyone... Spent a big part of yesterday working on a TMP102 precision temperature sensor library and, in the process, fixing my own bugs and tripping over the Wire library subtleties and documentation issues. I'm wondering where to post corrections and enhancements to the documentation? The Wire reference says: Corrections, suggestions, and new documentation should be posted to the Forum but I can't find a specific place appropriate for that task. I tried searching "Wire" and "Wire documentation" (with quotes) but came up with nothing relevant.

How about here, I guess? In the meantime I will write an off-line document and then link to it here, or if someone can point to a better place to post this stuff so that the documentation gets improved, that would be great.

BTW I do intend to release the TMP102 library when it's complete. I did find some OS library starts out there but the ones I found were incomplete or had major bugs so it seemed easier to just write one. It's a pretty cool, 13-bit, direct to digital temperature transducer which can convert over -55C to 150C! We need to measure up to and past 125C so it's good for that. It's a tiny SOT563 package so we can fit it next to a high power LED heatsink pad to monitor it's temperature. Resolution is 0.0625 deg C. See TMP102 data sheet, product information and support | TI.com

2

In Arduino 1.0.3, it seems Wire.requestFrom(address, quantity, stop) insists that address (7 bits) must be cast to int. Wire.beginTransmission(address) has no such requirement.
In my case I declare address as:

const uint8_t TMP102_ADDR = 0x48; // base address (four possible values)

and get this error:

TMP102_proof:344: error: ISO C++ says that these are ambiguous, even though the worst conversion for the first is better than the worst conversion for the second:
D:\arduino-1.0.3\libraries\Wire/Wire.h:63: note: candidate 1: uint8_t TwoWire::requestFrom(int, int, int)
D:\arduino-1.0.3\libraries\Wire/Wire.h:61: note: candidate 2: uint8_t TwoWire::requestFrom(uint8_t, uint8_t, uint8_t)

If I declare the TMP102_ADDR as int the error goes away.

I have not looked at the Wire source code (yet).

3

In my version of 1.0.3 Wire.h has this:

    uint8_t requestFrom(uint8_t, uint8_t);                   <----- line 56
    uint8_t requestFrom(uint8_t, uint8_t, uint8_t);          <----- line 57
4

OK in my Wire.h from 1.0.3 here are lines 60..63 -There is nothing in the header about mods or versions newer than "Modified 2012 by Todd Krein...".

uint8_t requestFrom(uint8_t, uint8_t);
uint8_t requestFrom(uint8_t, uint8_t, uint8_t); << line 61, this is what I am trying to use
uint8_t requestFrom(int, int);
uint8_t requestFrom(int, int, int);

So I am confused (which doesn't take much!)... how does Arduino and the compiler know which declaration to use? The 2nd would be the closest... so I first wonder how my line numbers can differ?

If I open the Wire.h from within the Arduino 1.0.3 zip, and compare: whoa! They are not the same. It would appear Teensyduino has quietly modified the libraries without leaving any comments that it did so.
Here is my Teensyduino-modified version:
#include <inttypes.h>
#include "Arduino.h" <-- line 26
...
extern "C" void i2c0_isr(void); <-- line 30, not present in original version

Original version:
#include <inttypes.h>
#include "Stream.h" <-- line 26

This begs the obvious question: when another utility (in this case Teensy) has a need to modify standard libraries like Wire.h, what is the accepted protocol? I would imagine a comment at every change, or at least in the header? Or?? As more Arduino variations are introduced how is this to be dealt with as sanely as possible?

Continuing on, there is no declaration with the "stop" parameter of type boolean as stated in the reference doc at arduino-1.0.3/reference/WireRequestFrom.html. The data type of address and quantity is not specified in the document.

Out of curiosity I try:

Wire.requestFrom(TMP102_ADDR, (uint8_t)2, (uint8_t)true); << 3rd param cast violates the ref but not Wire.h

and this seems to make my call unambiguous enough for the compiler to match up correctly.

So I am not sure why I have learned here since I don't know if this error comes from the core Wire library or the modified version. But the Wire docs also aren't consistent with the source files. So there's plenty of ambiguity...

It would seem that the included references should describe the correct data types of each function parameter. In Java, the javadoc tool takes your appropriately written source files and creates a nice clear reference doc which describes the type, use, bounds, defaults and other aspects of each parameter and return type. Is there a similar, widely accepted tool for C docs? If so I would like to write my library to utilize it and then publish the document with it.

5

Hi Bruce. I must confess, the Teensyduino installer makes a tremendous number of changes. I probably should add more comments where things are altered. I actually put a lot of effort into making sure the changes don't alter the way the IDE handles every official Arduino board. But comments inside libraries are a much lower priority.

On 1.0.X, there's really no sane way to patch the libraries. The only reason this hasn't become a terrible nightmare is because most other 3rd party boards that require substantial changes, like Maple and Chipkit, tend to fork the entire IDE rather than distributing a package to install into the original. When I started Teensy over 4 years ago, I didn't like the idea of forking (it seems like not collaborating to me), so I created that installer. Forking would have been much easier.

The Arduino Team has been working on these issues for the new 1.5.X version. Some of the original 1.5.X "platform" code was contributed by Rick Anderson and/or Mark Sproul, actually a couple years ago as I recall. Christian (of the Arduino Team) has been working quite a bit recently on even more improvements, to allow 3rd party boards to work better.

I must also confess, so far I have not used the 1.5.X version much. I've studied the code only briefly, so everything I say here may not be fully accurate. 1.5.X is also still a work-in-progress, and to be honest as long as users aren't demanding I support 1.5.x, I'm waiting for it to settle a bit (see the comments in that discussion) before I add Teensy support for it.

However, I do know 1.5.X has provisions for 3rd party boards (or "packages" and "platforms") to provide their own copies of modified libraries. It also has a platform.txt file which allows 3rd party boards to customize the build process. Third party boards can also install their own compiler toolchain. It's designed, at least in theory, to allow a 3rd party board to customize almost everything.

So really, the new 1.5.X version's "platform" features are the answer to your question. Later this year, I imagine 1.5.X will replace 1.0.X as the main version of Arduino everyone uses. I absolutely do intend to support it, using to the fullest extent possible whatever 3rd party installation methods Christian and the rest of the Arduino Team define.