The library can be downloaded from Github: https://github.com/felias-fogg/SoftI2CMaster.
The standard I2C library for the Arduino is the Wire library. While this library is sufficient most of the time, there are situations when it cannot be used:
I adapted Peter Fleury's I2C software library that is written in AVR assembler, extremely light weight and very fast. Even on an ATtiny running with 1MHz, one can still operate the bus with 33 kHz, which implies that you can drive slave devices that use the SMBus protocol (which timeout if the the bus frequency is below 10 kHz). If you want a solution running on an ARM MCU, scroll down to the end.
Just download the Zip-File from github, uncompress, rename the directory to SoftI2CMaster and move it into the libraries folder. In case you have not installed a library before, consult the the respective help page.
In order to use the library, you have to import it using the include statement:
In the program text before the include statement, some compile-time parameters have to be specified, such as which pins are used for the data (SDA) and clock (SCL) lines. These pins have to be specified in a way so that port manipulation commands can be used. So instead of specifying the number of the digital pin (0-19) the port (PORTB, PORTC, PORTD) and the port pin has to be specified. The mapping is explained here. For example, if you want to use digital pin 2 for SCL and digital pin 14 (= analog pin 0) for SDA, you have to specify port pin 2 of PORTD for SCL and port pin 0 of PORTC for SDA:
#define SCL_PIN 2
#define SCL_PORT PORTD
#define SDA_PIN 0
#define SDA_PORT PORTC
There are a few other constants that you can define in order to control the behavior of the library.
#define I2C_TIMEOUT ...
Since slave devices can stretch the low period of the clock indefinitely, they can lock up the MCU. In order to avoid this, one can define I2C_TIMEOUT. Specify the number of milliseconds after which the I2C functions will time out. Possible values are 0 (no time out) to 10000 (i.e., 10 seconds).
#define I2C_NOINTERRUPT 1
With this definition you disable interrupts between issuing a start condition and terminating the transfer with a stop condition. Usually, this is not necessary. However, if you have an SMbus device that can timeout, one may want to use this feature. Note however, that in this case interrupts become unconditionally enabled after calling
#define I2C_CPUFREQ ...
If you are changing the CPU frequency dynamically using the clock prescale register CLKPR and intend to call the I2C functions with a frequency different from F_CPU, then define this constant with the correct frequency. For instance, if you used a prescale factor of 8, then the following definition would be adequate:
#define I2C_CPUFREQ (F_CPU/8)
#define I2C_FASTMODE 1
The standard I2C bus frequency is 100kHz. Often, however, devices permit for faster transfers up to 400kHz. If you want to allow for the higher frequency, then the above definition should be used.
#define I2C_SLOWMODE 1
In case you want to slow down the transfer to 25kHz, you can use this definition (in this case, do not define
I have measured the maximum bus frequency with different processor frequencies. The results are displayed in the following table.
|I2C slow mode kHz||25||25||25||25||25||25|
|I2C standard mode kHz||40||80||100||100||100||100|
|I2C fast mode kHz||40||80||150||300||400||400|
The following functions are provided by the library:
setup(). Will return
falseif SDA or SCL is on a low level, which means that the bus is locked.
i2c_startfunction. However, it tries repeatedly to start the transfer until the device sends an acknowledge.
trueif the device replies with an ACK.
true, then a NAK is sent after receiving the byte finishing the read transfer sequence.
As a small example, let us consider reading the values from the BMA020 acceleration sensor.
Meanwhile, I have written a wrapper around SoftI2CMaster that emulates the Wire library (master mode only). It is another c++-header file called
SoftWire.h which you need to include instead of
SoftI2CMaster.h. Directly after this include statement you need to create a
This interface sacrifices some of the advantages of the original library, in particular its small footprint, but comes handy if you need a replacement of the original Wire library. The following table lists the memory requirements. As one can see,
SoftI2CMaster will be particularly useful on smaller processors.
The entire code had to be included in the header file, because the communication ports in the code need to be determined at compile time. This implies that this header file should only be included once per project (usually in the sketch).
Another shortcoming is that one cannot use ports H and above on an ATmega256. The reason is that these ports are not directly addressable.
Finally, as mentioned, the code runs only on AVR MCUs (because it uses assembler). If you want to use a software I2C library on the ARM platform, you could use https://github.com/felias-fogg/SlowSoftI2CMaster, which uses only C++ code. Because of this, it is much slower, but on a Genuino/Arduino Zero, the I2C bus runs with 100kHz. There is also a Wire-like wrapper available for this library: https://github.com/felias-fogg/SlowSoftWire.