Proposal for additional Wire (I2C) lib API's

[Sandeep Mistry]

Hi everyone,

I would like to propose a few additional API's to the Wire library to allow users to supply an external buffer for sending and receiving data in I2C master mode. The current use cases for the API's are:

• to avoid extra overheads of using Wire's internal buffer and Stream API's
  
• when the size of Wire's internal buffer is not large enough to interact with various I2C devices. (On SAMD the current buffer size to RX and TX is 64 bytes)

The signature of the new API's are as follows:

    uint8_t sentTo(uint8_t address, uint8_t buffer[], size_t quantity);

    uint8_t sentTo(uint8_t address, uint8_t buffer[], size_t quantity, bool stopBit);

    uint8_t requestFrom(uint8_t address, uint8_t buffer[], size_t quantity);

    uint8_t requestFrom(uint8_t address, uint8_t buffer[], size_t quantity, bool stopBit);

There is also a pull request open for the SAMD core that implements this: https://github.com/arduino/ArduinoCore-samd/pull/269

We would any appreciate feedback on the proposal above.

Thanks,

Sandeep

[Thomas Roell]

Looks like a great addition.

Couple of questions comment:

(1) Naming. requestFrom is ok, but sendTo() to be "transmitTo()" to mirror beginTransmission(). Not that this is the best naming, but it would be more consistent.

(2) The AVR core implements an interesting API:

     uint8_t TwoWire::requestFrom(uint8_t address, uint8_t quantity, uint32_t iaddress, uint8_t isize, uint8_t sendStop)

      So "iaddress" is a 32 bit quantity and "isize" decided how many bytes of this are send. Would it be possible to add something like this to the suggested APIs as well ?

(3) What is the maximum number for "quantity" ? Some devices will use DMA or other techniques where a limit to say 255 bytes might be desireable. Clearly anything above 65536 is uninteresting ... 

(4) Those are for master mode only ... 

- Thomas

   

--
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+unsubscribe@arduino.cc.

[Sandeep Mistry]

Hi Thomas,

Thanks for the feedback!

(1) Naming. requestFrom is ok, but sendTo() to be "transmitTo()" to mirror beginTransmission(). Not that this is the best naming, but it would be more consistent.

Good suggestion, I agree "transmitTo(...)" is more consistent. Another option is "writeTo", but I feel your "transmitTo()" suggestion is better.

 

(2) The AVR core implements an interesting API:

     uint8_t TwoWire::requestFrom(uint8_t address, uint8_t quantity, uint32_t iaddress, uint8_t isize, uint8_t sendStop)

      So "iaddress" is a 32 bit quantity and "isize" decided how many bytes of this are send. Would it be possible to add something like this to the suggested APIs as well ?

I briefly looked at this one, it looks like it does a write request with the iaddress first (without stop bit) then performs a read request. So a nice short cut operation for reading values from register based I2C devices.

We can certainly expand on adding this API, but for now I'd like to finalize the external buffer APIs proposed.

 

(3) What is the maximum number for "quantity" ? Some devices will use DMA or other techniques where a limit to say 255 bytes might be desireable. Clearly anything above 65536 is uninteresting ... 

So in my proposals "size_t" is used as the type quantity. "requestFrom(...")" in the SAMD core uses this for the quantity type. AVR currently uses "uint8_t" or "int" for quantity - we'll need to sort out this inconsistency.

I don't think we should impose a limit, the I2C device I'm working with has operations that require read and writes up to 256 bytes.

 

(4) Those are for master mode only ... 

Yes, just like "beginTransmission(...)", "endTransmission(...", and "requestFrom(...)". For now the intended use case is reading or writing to I2C devices in master mode that need to send or receive more than 64 bytes.

 

[Dennis Lee Bieber]

On Tue, 17 Oct 2017 11:49:12 -0400, Sandeep Mistry
<s.mi...@arduino.cc> declaimed the following:

>Hi Thomas,
>
>Thanks for the feedback!
>
>(1) Naming. requestFrom is ok, but sendTo() to be "transmitTo()" to mirror
>> beginTransmission(). Not that this is the best naming, but it would be more
>> consistent.
>>
>
>Good suggestion, I agree "transmitTo(...)" is more consistent. Another
>option is "writeTo", but I feel your "transmitTo()" suggestion is better.
>

Given that "requestFrom" implies some(one|thing) is asking for
something, I'd consider "replyTo", implying a response to a previous
request, to be a more appropriate name (to me, the counter for "transmitTo"
feels like it would be "receiveFrom")
--
Wulfraed Dennis Lee Bieber AF6VN
wlf...@ix.netcom.com HTTP://wlfraed.home.netcom.com/

[Thomas Roell]

Sandeep,

On Tue, Oct 17, 2017 at 9:49 AM, Sandeep Mistry <s.mi...@arduino.cc> wrote:

Hi Thomas,

Thanks for the feedback!

(1) Naming. requestFrom is ok, but sendTo() to be "transmitTo()" to mirror beginTransmission(). Not that this is the best naming, but it would be more consistent.

Good suggestion, I agree "transmitTo(...)" is more consistent. Another option is "writeTo", but I feel your "transmitTo()" suggestion is better.

I see you point about "writeTo()" (as it bypasses the write-buffer). But then "requestFrom()" needs to be "readFrom()" .... 

Please also don't forget that multiple other APIs have the same issue, like the UDP class for example. There "sendPacket()" makes more sense (beginPacket() / write() / endPacket(), the SigFox library could benefit there). So from this angle perhaps "sendTransmission()" ?

 

 

(2) The AVR core implements an interesting API:

     uint8_t TwoWire::requestFrom(uint8_t address, uint8_t quantity, uint32_t iaddress, uint8_t isize, uint8_t sendStop)

      So "iaddress" is a 32 bit quantity and "isize" decided how many bytes of this are send. Would it be possible to add something like this to the suggested APIs as well ?

I briefly looked at this one, it looks like it does a write request with the iaddress first (without stop bit) then performs a read request. So a nice short cut operation for reading values from register based I2C devices.

We can certainly expand on adding this API, but for now I'd like to finalize the external buffer APIs proposed.

Sure. This one however would cover the most important case that user have in practice. Reading a bunch of data from a sensor, directly.

 

 

(3) What is the maximum number for "quantity" ? Some devices will use DMA or other techniques where a limit to say 255 bytes might be desireable. Clearly anything above 65536 is uninteresting ... 

So in my proposals "size_t" is used as the type quantity. "requestFrom(...")" in the SAMD core uses this for the quantity type. AVR currently uses "uint8_t" or "int" for quantity - we'll need to sort out this inconsistency.

I don't think we should impose a limit, the I2C device I'm working with has operations that require read and writes up to 256 bytes.

Imposing a reasonable limit seems wise. Otherwise if you implement this on more complex hardware using DMA, you had do add the code to deal with a count of 0x00ffffff, and actually test it. I would not know how to test this, other than with a logic analyzer. The hardware platform I am dealing with has a DMA limit of 65535. Everything above requires more complex code, code that is dead code in all realistic scenarios. I can see 256 bytes a bad limit, but 65535 (a 16 bit quantity) good enough.