All, I've uploaded a new v10.0 library to the top post and GitHub. Documentation has been updated.
This has passed all my testing but it is a pretty involved change in some parts, so post here if you have any problems with it. There are three major changes (first three below), and some extra cleanup and fixes. The changes are:
1. Unbound SCL, SDA pin assignment. The library now supports
setSCL() and
setSDA() functions, and in general any place that used to take a pins enum value will now accept a SCL,SDA pin pair (in that order). This includes the begin() function. The enum values will remain supported so there is no risk of breaking existing code. This is primarily to add compatibility to any code written against standard Teensy Wire. Refer to the top-post or GitHub for the full array of valid pin settings.
New functions are (where '^' indicates optional parameters):
- begin(mode, address, ^pinSCL, ^pinSDA, ^i2c_pullup, ^rate, ^i2c_op_mode);
- begin(mode, address1, address2, ^pinSCL, ^pinSDA, ^i2c_pullup, ^rate, ^i2c_op_mode);
- pinConfigure(pinSCL, pinSDA, ^pullup);
- setSCL(pin);
- setSDA(pin);
- getSCL();
- getSDA();
Examples:
Code:
[FONT=courier new]Wire.begin(I2C_MASTER, 0x00, I2C_PINS_18_19, I2C_PULLUP_EXT, 400000); // Wire bus, SCL pin 19, SDA pin 18, ext pullup, 400kHz
Wire.begin(I2C_MASTER, 0x00, 19, 18); // equivalent to above, will default to ext pullup at 400kHz
Wire.begin(I2C_MASTER, 0x00, 16, 18); // similar to above, but using SCL pin 16 and SDA pin 18[/FONT]
Note that this change impacted the
Wire.i2c->currentPins internal variable, which is now replaced by
Wire.i2c->currentSCL and
Wire.i2c->currentSDA. This is not normally something someone would use, but be aware if you run into a 'currentPins not defined' error (possibly on old example code).
2. Added Master callback functions. These callbacks were initially added to trigger when background transfers complete (
sendTransmission() and
sendRequest()), however they will also trigger on foreground transfers. There is also a error function callback which will trigger on any error that terminates a Master transfer. These can be used to do exit status and error checking in common functions instead of explicitly coding everywhere. Additions are:
- onTransmitDone(function) - where function() is called when Master Transmit is complete
- onReqFromDone(function) - where function() is called when Master Receive is complete
- onError(function) - where function() is called upon any I2C error which terminates the Master bus operation (eg. NAK, timeout, acquire fail, etc)
- basic_master_callback - an added example which demonstrates the above functions
3. Error counters. An error counting system was added which can track bus errors over long durations. It tracks seven different types of errors. This functionality is gated by a define
I2C_ERROR_COUNTERS, which by default is enabled, but it can be disabled if there is any performance concern (refer to top of i2c_t3.h file). There are two supporting functions, one to return error count, and the other to zero the count. The functions are:
- getErrorCount(counter)
- zeroErrorCount(counter)
- where counter is an enum value with one of the following settings:
- I2C_ERRCNT_RESET_BUS
- I2C_ERRCNT_TIMEOUT
- I2C_ERRCNT_ADDR_NAK
- I2C_ERRCNT_DATA_NAK
- I2C_ERRCNT_ARBL
- I2C_ERRCNT_NOT_ACQ
- I2C_ERRCNT_DMA_ERR
4. Misc cleanup and fixes.
- Added default settings on many function arguments and did some cleanup. With the exception of old style Arduino calls (Wire.begin() and Wire.begin(addr) which are 100kHz), more complex calls will use default pins, external pullups, 400kHz, and ISR mode if those settings are not explicitly set.
- Also fixed some blocking conditions that could occur in immediate mode
- Updated all docs