Getting current i2c master clock frequency used by Wire

[Bill Perry]

Currently, the Wire library has a way to set/alter the i2c master clock frequency but does not have a way to get the current/actual master i2c clock frequency being used.
Wire.setClock() is a void function.

There are times where being able to get the current master clock frequency can be useful.
In some types of applications it can also be useful to know the actual master clock frequency vs what was requested.


The pic32 core has created Wire API method functions to do this.
The API functions do not alter the existing Wire API so any existing code that uses Wire is not affected.

Here is what was done in the pic32 core.
setClock() was changed to return the actual clock frequency instead of being a void.
Note that the actual clock frequency can be different than the requested frequency.
If the object is currently in slave mode, zero is returned.

A new method getClock() was also added that simply returns the current actual master clock frequency.
If the object is currently in slave mode, zero is returned.

It is useful to have both functions as this allows not only getting the current actual clock frequency selected when setting the clock but also the ability
to get the current frequency without modifying the current frequency.
We did have a discussion about returning the previous frequency from setClock() instead of the new/current actual frequency but that can complicate things when trying to get the actual frequency and creates an inconsistency with getClock()
We also discussed leaving setClock() as a void but then there is no way to return failure status for things like the bus being in slave mode.
In the end, we opted for both setClock() and getClock() to have consistent return values.
If an entity wants to know what the clock frequency is prior to calling setClock() it can always simply call getClock() to get it.

To help sketches and libraries know if this functionality exists two defines were created
WIRE_HAS_SETCLOCK
WIRE_HAS_GETCLOCK

Each one indicates that this functionality exists.
i.e.
if WIRE_HAS_SETCLOCK is defined the Wire library has a setClock() function that returns the actual frequency selected.
if WIRE_HAS_GETCLOCK is defined the Wire library has a getClock() function that returns the actual master clock frequency  currently in use.

I would think that adding these to the Wire API would not be too controversial.
I would be happy to generate the pull requests for the AVR core and I could also probably handle the DUE as well.
From my recollection when I looked at this a while back, the DUE core uses some low level i2c code that is not available so to work around that,
the functions could return the clock frequency requested instead of the actual clock. While not ideal it would provide most of desired functionality.
But if there is a way to get the actual frequency on core used with DUE, obviously that would be much better.

Thoughts?

I'd like to get some feedback on this before I go off to do the code updates and created a PR.

--- bill

[Steve Weinrich]

Sounds good to me. 

Sent from my iPhone

--
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+...@arduino.cc.

[Rob Tillaart]

Hi Bill
Sounds good to me. It doesn't break any existing interface and adds useful functionality.

I would use it in libraries to increase i2c clock to optimum speed for that special device and set it back afterwards. Recently worked with FRAM which did a fine job @ 800 KHz. But not all devices can handle this speed.

So in short +1

Thanks

--
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]

What about having something like the SPI libs beginTransaction(...) and endTransaction()?

[Bill Perry]

Forgot to post the to the list:

While anything is possible, the primary goal of this proposal was to minimize the changes and preserve backward compatibility with the existing Wire API.
It is a simple enhancement to the existing setClock() API function and new API function, getClock() to get the current clock rate without modifying the existing clock rate.

Shifting the Wire API to use a different type of transaction API is much bigger change.

Also, with the existing Wire library API, multiple libraries potentially share the i2c bus and hence the same configured clock.
i.e one library can set a clock that affects another library's transfers and currently there is no way to obtain the currently configured clock rate.

 --- bill