I2C byte write return value

[kgills]

The return value for the i2c_byte_write in i2c_api.h does not match the documentation for the write function in I2C.h.

[0xc0170]

Can you please be more specific, I'll have a look

[kgills]

/** Write single byte out on the I2C bus
 *
 *  @param data data to write out on bus
 *
 *  @returns
 *    '1' if an ACK was received,
 *    '0' otherwise
 */
int write(int data);

/** Write one byte.
 *  @param obj The i2c object
 *  @param data Byte to be written
 *  @return 1 if NAK was received, 0 if ACK was received, 2 for timeout.
 */
int  i2c_byte_write(i2c_t *obj, int data);

The C++ layer directly calls into the hal layer. The documented return values for these functions do not match.

[kgills]

Any update on this?

[kgills]

Please say something. I think it's pretty obvious that there's something wrong here.

[0xc0170]

The problem comes:

int I2C::write(int data) {
    return i2c_byte_write(&_i2c, data);
}

Looking at HAL implementations, the documentation for the i2c_byte_write is wrong and should be fixed. The documentation to HAL was added later, many implementation (most of?) should follow what write() method defines. There are some implementations (KL25Z) which have it reversed, we should fix it. Thanks for reporting.

[0xc0170]

Here's summary from our targets implementations, I checked some vendors, random targets (like F4/F0 for STM, assuming the implementations are similar between families, might not be the case but we dont care for this table):

Silabs - ack = 1
Freescale - ack = 0
Atmel - ack = 0
STM - can't guess from the code, seems like timeout is 0 (might mean its nak), ack = 1 ?
NXP - ack = 1

I got a fix for the documentation, and we might need to fix all those targets.