This post contains instructions on how to connect a real-time clock and EEPROM module to the Raspberry Pi running Raspberry Pi OS using a hardware or software I²C bus. The large chip on the module is the DS3231 which is the real-time clock, and the much smaller 8-pin chip is a 32K bit (4K bytes) AT24C32 EEPROM. This post is actually a rewrite of a post first put up in February. There are differences between Raspberry Pi OS and Raspbian Buster even if both are based on Debian 10 and the 4.19 Linux kernel. The major difference for our purposes is that in Buster, loading the real-time clock driver automatically enabled the I²C controller and this is no longer the case in the new version of the Raspberry operating system. I would speculate that the instructions contained here would therefore apply if Raspbian is still being used on the Raspberry Pi.

There are some teething problems with the new distribution. The device tree overlay for the software I²C controller is not functional. The problem has already been solved but the new overlay must be loaded manually as explained below. This step will not be necessary with the next release of the Raspberry Pi OS.

Table of content

1. I²C on the Raspberry Pi
2. Useful Software
3. Using the Hardware Clock Connected to the Hardware I²C Bus
4. Using the Flash Memory Connected to the Hardware I²C Bus
5. Using the Hardware Clock Connected to a Software I²C Bus
6. Using the Flash Memory Connected to the Software I²C Bus
7. Multiples I²C Buses
8. Compute Module and Raspberry Pi 4
9. The Second Hardware I²C Bus
10. Reading the DS3231 Temperature Sensor
11. RTC/EEPROM Module Backup Power

I²C on the Raspberry Pi

I²C (Inter-Integrated Circuit or TWI - Two Wire Interface) is a serial communication protocol frequently used to connect many devices such as clocks, displays, EEPROM memories, and sensors to a micro-controller. The communication, which is not very fast, is done using two signals and a connection to ground.

• SDA - Serial Data Line
• SCL - Serial Clock Line

All Raspberry Pi models have a hardware I²C bus on pins 3 (SDA) and 5 (SCL) of GPIO connector which has 26 or 40 pins depending on the model. However, the bus is not enabled by default and until it is activated pins 3 and 5 are general I/O pins. If the GPIO connector of the Raspberry Pi has 40 pins, there is a second I²C hardware bus which is assigned to the identification of the extension cards (so called HATs) using pins 27 (ID_SD) and 28 (ID_SC). Unfortunately, use of this bus is not recommended even in the absence of a HAT. However, additional software I²C buses can be created by adding kernel modules.

While several devices can be connected to the I²C bus simultaneously, only two devices can exchange data at any given time. The device that initiates the connection is the master, the recipient is the slave. There can be more than one master on the bus, but data exchange between masters is impossible, as well as between slaves. In addition, a slave cannot initiate communication with a master. See Understanding the I²C Bus, Texas Instruments Application Report SLVA704, p. 3. by Jonathan Valdez and Jared Becker (juin 2015).

In principle, a device can be master or slave; never both simultaneously. In practice, most simpler devices are only slaves and only micro-controllers have the possibility of being a slave in addition to being a master, but this is not always the case. Indeed, it seems that the Raspberry Pi is not able to put its I²C bus in slave mode.

As one would expect in Linux, an I²C bus is represented by a file in the device directory /dev. As an example, there are three I²C buses activated on an Orange Pi PC 2.

Here is the list of I²C devices on a Raspberry Pi 3 B whose hardware I²C bus has been enabled.

Even though this model has a 40 pin header and the hardware I²C bus for HAT identification is enabled, a device linked to the bus is not made available by the system.

Useful Software

Three software utilities are used below. There are i2cdetect and ic2get which are contained in the package i2c-tools. The first displays the address of the devices connected to an I²C bus. The second can read the registers of an I²C slave. Installing the package i2c-tools is very simple.

To make life easier, I added the default user on the Pi to the i2c group. Otherwise it will be necessary to obtain root privileges when executing any utility in that package. In other words, whenever i2cdetect and i2cget are invoked, it will be necessary to use the sudo prefix if the user is not part of the i2c group. Adding the default user is not complex at all.

However, you will need to restart the session (by logging out and then back in) to update the user permissions.

Installing the program eeprog that can write to and read from EEPROM is a little more complex. The utility must be compiled from the source code. In addition, several versions of eeprog are available on the Web. The only ones that work are based on the "tear" fork of eeprog developed by Kris Rusocki among which the version by Ján Sáreník on GitHub.

The problem with the original versions of eeprog is that in writing they use too high a frequency. It has to be slowed down. The I²C frequency of the AT24C32 EEPROM depends on the voltage. It may be possible to save data to the EEPROM if running at 5 volts using the original version of eeprog. The synchronization signal (SCL) of the EEPROM can reach 400 KHz. However, the memory is connected to 3.3 volts to be compatible with Raspberry Pi GPIO that. The I²C operating frequency of the EEPROM decreases rapidly when the voltage is reduced. I don't know the exact value of this frequency at 3.3 volts, but at 2.7 volts the maximum frequency is reduced to 100 KHz.

Neither i2c-tools nor eeprog are needed for normal operation of the clock and flash memory. We can therefore eliminate everything later if desired. Here's how.

Using the Hardware Clock Connected to the Hardware I²C Bus

The connection of the module is easy since the connections are clearly labelled on the board. At a minimum, it is necessary to connect four pins from the latter to the corresponding pins of the Raspberry Pi GPIO connector: the power and ground (VCC and GND) and the data and synchronization signals (SDA and SCL) of the I²C bus. At this point, I did not install a battery, for reasons explained later.

Initially, the I²C and the clock drivers can be installed temporarily. Two commands are needed to carry out these two tasks. Then, it is a simple matter to check that the devices have been created.

The i2c-1 device (also called an I²C controller) was created, as well as the rtc0 device which communicates with the clock via the i2c-1 controller. The command i2cdetect displays the addresses of the I²C devices connected to the hardware bus.

Two devices were found. The first is flash memory (EEPROM) at address 0x57 and the second is the clock at address 0x68. The UU displayed instead of the address 68 is an indication that a driver is handling the device.

Clearly the hardware clock is working. It may be surprising to see that the time is correct in the absence of a battery. The explanation is simple. The operating system, or more precisely the component systemd-timesync, obtains the current time from an SNTP reference server on the Web when the Raspberry Pi starts. As soon as the i2c-rtc module is installed, the system adjusts the hardware clock.

Since everything works, the I²C real-time clock can be added to the system permanently by adding the dtparam command to enable the I²C controller and the dtoverlay command to load the real-time driver in the operating system configuration file.

It is not necessary to activate the I²C protocol with the raspi-config utility. Previously, I said that we also had to modify the script that adjusts the time of the hardware clock when the i2c-rtc module is loaded. Here's how.

Normally the script does nothing, because its execution is stopped by the initial test, at least in distributions using systemd including Raspberry Pi OS. It is necessary to remove this test or to disable it by adding leading "#" at the start of the lines which transform them into comments.

Using the Flash Memory Connected to the Hardware I²C Bus

If you installed the clock as described in the previous section, you can immediately check that it is possible to write and read the AT24C32 EEPROM . Otherwise, the I²C bus is not yet enabled.

The temporary installation of the i2c1 module that implements the hardware I²C bus on GPIO pins 2 and 3 is very simple.

If the addresses of the I²C devices connected to bus 1 are displayed when the bus is controlled by i2c1, at least two are observed.

Address 0x57 is used by the AT24C32 EEPROM (in reality it is a default address that can be modified with some soldering). Address 0x68 is that of the hardware clock. Because only the I²C bus is activated and because there is no driver for the clock, i2detect shows the latter's address, 0x68 and not UU as in the previous section or below.

If the i2c-rtc module was installed rather than i2c1, then i2cdetect displays UU instead of 0x68 indicating that the clock driver is loaded.

Since the I²C bus is enabled and the address of the EEPROM is known, one can write a string in the memory and then read it to make sure that access is possible.

Using the Hardware Clock Connected to a Software I²C Bus

Older Rapsberry Pi models have only one readily available I²C hardware bus; the exceptions are the Pi model 4 and the Compute module. If GPIO pin 2 or 3 is used for other purposes, a software I²C bus can be created with the module i2c-rtc-gpio to which the RTC can be connected using different GPIO pins.

As you can see, GPIO23 and GPIO24 will be used for the SDA and SCL signals respectively. If the i2c-rtc module had been added to the configuration file /boot/config.txt, it must be removed and the Pi must be restarted. If the module had been temporarily loaded, it can be removed with dtoverlay. As soon as you know there is no more device for the clock, you can install i2c-rtc-gpio.

Just as in Raspbian Buster the overlay could not be loaded at runtime, but at least it was not necessary to reboot because of a segmentation fault. It can be loaded at boot time if the system configuration file is modified.

After a reboot, the software I²C bus and the clock device are installed correctly.

Using the Flash Memory Connected to the Software I²C Bus

If the i2c-rtc-gpio module has been installed as explained in the previous section, then you can communicate with flash memory at address 0x57 on device i2c-3. If the module has flash memory but no hardware clock, then add the i2c-gpio module instead.

Perhaps not surprisingly, the i2c-rtc-gpio module could not be loaded at runtime.

Even worse, the Pi would not boot if the configuration file was modified to load the overlay at boot time by inserting the following line.

The Pi would just hang at this point. I removed the SD card, inserted it into the destkop SD card reader and removed the offending dtoverlay=i2c-gpio line from the /boot/config.txt file with a text editor. It was then possible to boot the Pi again from the corrected SD card.

This problem has been fixed but not yet integrated into the distribution. Following the indications by PhilE, here is how to get around the problem.

As can be seen, the new overlay (which will be part of the 5.4 kernel) can be loaded at run-time without problem. The 0x68 address will not be shown if there is no I²C clock. The EEPROM can be accessed as before but the I²C bus must be adjusted; it is now i2c-3.

Multiples I²C Busses

it is possible to enable more than one I²C bus, even on the first models of the Raspberry Pi. As a first example, the hardware bus and the software bus described above will be enabled simultaneously. Here is the relevant part of the /boot/config.txt file that creates these two serial communication channels.

It is not necessary to install the real-time clock on the hardware bus. With the following configuration, the clock on the software bus will be activated

The usual commands can be issued after rebooting to confirm that the two RTC-EEPROM modules are available on the two I²C busses and that the RTC driver is using the real-time clock connected to the software bus.

On the Raspberry Pi 3 B, the i2c-rtc-gpio will create bus 3 or else the software controller will not be installed. To be more precise, if the overlays are in the following order in /boot/config.txt

then the RTC driver is loaded and it uses the software I²C controller on bus 3 and the i2c-gpio overlay cannot install the software I²C controller because of the bus number conflict.

If the overlays are in the following order in /boot/config.txt

then the RTC driver is not loaded.

Contrary to comments read on the forums, there does not seem to be any constraints on the I²C bus number or on the bus creation sequence.

The only constraint is that there must not be any conflict in the bus number. It is even possible to create load software I²C controller on bus 1 if the hardware I²C bus is not enable.

Also it seems that bus 0 and 2 are reserved by the system.

Compute Module and Raspberry Pi 4

I have neither a Compute Module nor a Raspberry Pi 4, so what I am about to say is not based on experience and it may therefore be completely wrong. It seems very clear that there are more than 2 hardware I²C buses on these devices. Look at the list of device tree overlays related to I²C that are available.

Most maps of the Raspberry Pi GPIO connector only show the default function of the I/O pins. Hardware buses 3 to 6, do not show up on those maps because they only appear as so called "alternate" functions of some I/O pins. One exception is the Raspberry Pi 4 Model B Default GPIO Pinout with PoE Header by Element 14 which as a well laid out yet compact map of the 6 alternate functions of all 30 I/O pins of the 40 pin GPIO header (the other 10 pins are power and ground connections). Unfortunately, the map is an image so a text search for say SDA3 can't be performed to find out on which pins it is available. There is another map on the Raspberry Pi Forums by clicky that clearly differentiates the additional I²C buses available on the Model 4 only. The authoritative source for mere mortals, may be the PDF document entitled BCM2711 ARM Peripherals Version 1, 5th February 2020, by Raspberry Pi (Trading) Ltd. Look at pages 98 to 100 of Section 5.3. Alternative Function Assignments of Chapter 5. General Purpose I/O (GPIO).

When looking at the documentation for some of these hardware I²C controllers, there was a mention of "combined transactions" which puzzled me.

The following reply by Phil Elwell (pelwell) to an issue entitled smbus read_i2c_block_data Fails on Latest Kernel #828

My theory is that the I2C device you are trying to control does not support repeated starts. If you find that everything springs into life with the old driver, try repeating your test after turning on the "combined" module parameter ...

One thing that has become obvious from reading about I²C connexion problems especially with the alternate I²C buses is that care must be exercised with the termination of the SDA and SCL lines. This is not a problem with the module that is used here, One can plainly see the bank of pull-up resistors near the EEPROM chip. Howver, if a device without such pull-ups is being used, then it seems that the internal pull-ups of the Raspberry Pi may not be sufficient (i.e. may have too high a value to be able to pull the lines to 3.3 volts when neither the slave nor master is asserting the line low).

The Second Hardware I²C Bus

If the Raspberry Pi GPIO connector has 40 pins, there is a second hardware I²C bus which identifies expansion cards (HAT) using pins 27 (ID_SD) and 28 (ID_SC). In principle, this bus should not be used. There are many warnings about this. The Raspberry Foundation says it not once but twice in its instructions on designing expansion cards. In the paragraphs entitled GPIO Requirements and ID EEPROM there is the same passage:

Within the set of pins available on the GPIO header, ID_SC and ID_SD (GPIO0/SCL and GPIO1/SDA) are reserved for board detection / identification. The only allowed connections to the ID_ pins are an ID EEPROM plus 3.9K pull up resistors. Do not connect anything else to these pins!

The same warning is on the schematics of the various models. In a tutorial on the I²C protocol, Sparkfun adds "It's only there to talk to EEPROMs at addresses 0x50 during boot time. User access at runtime is problematic. If you want a general purpose I²C bus on the B +, you'll need to use I2C-1, on pins 3 and 5 of the 40-pin connector ”. However, the tutorial continues with the procedure for using the bus. It requires i2c_vc module that can be loaded with the dtparam utility. Before installing it, let's see the information that the utility displays about this module.

Since the device is in place, I took the chance to connect the clock module with flash memory to pins 27 (SDA) and 28 (SCL) of the second I²C bus (and also to ground and to 3.3 volts of course) taking care to turn off the power before proceeding. After that it was easy to verify that it was possible to use flash memory.

There does not seem to be a module that supports the clock with this I²C bus. However, I was able to verify that it is possible to access the DS3231 chip with a Python script which is described in more detail in another post.

To install a controller for this hardware I²C bus permanently, add a line in the configuration file.

I have not tested the use of this bus with the other hardware I²C bus or other software buses, but I think it should work. That said, it is definitely not recommended and may not even be possible to use the i2c0 controller. As indicated at the end of the general help command of the dtparam utility, there could be a conflict with the Pi camera.

Similarly, it is very likely that there would be a conflict with any I²C device connected to this bus if it uses address 0x50.

Almost at the same time, Seamus de Mora provided the same information in more detail in a new "recipe" entitled Move your Real-Time Clock (RTC) from channel I2C1 to I2C0 on his PiFormulae GitHub page.

Clearly I should revisit this whole topic and run tests with the newest Raspberry Pi OS, an RTC, flash memory and a Raspberry Pi Camera.

Reading the DS3231 Temperature Sensor

To ensure accuracy, the DS3231 chip protects against variations caused by temperature changes. Therefore, it incorporates a temperature sensor which can be accessed. The temperature of the chip is in registers 0x11 and 0x12 which can be read with the i2cget utility .

The problem is that the rtc0 device which owns ic2-1. The device module is named rtc_ds1307.

Removing that module will give access to the DS3231 through I²C bus.

Register 0x11 contains the integer part of the temperature in degrees Celsius, while the two most significant bits of register 0x12 contain the fractional part of the temperature in quarters of a degree Celsius. Now 0x40 = 01000000 of which the two most significant bits are 01. So the temperature is 20 + 1 * (1/4) = 20.25 °C which was reasonable.

The rtc_ds1307 module can be reinstalled and the clock will work again.

RTC/EEPROM Module Backup Power

The module includes support for a button battery cell whose function is to keep the clock running when there's no power. There is a rather basic circuit to constantly charge the battery when power is supplied to the module. Initially the rechargeable LIR2032 was supplied with these modules. Unsurprisingly, the modules I got from two vendors lately didn't have batteries included. The new regulations regarding the transportation of lithium-ion batteries are much more severe so that sellers avoid shipping them.

There is an Arduino Forum discussion about the backup battery which begins in November 2014 and which remains active. Let me sum up this long debate.

• The LIR2032 is a rechargeable battery with a nominal voltage of 3.6 / 3.7 volts which must be charged at 4.2 volts.
• Some believe that the voltage will be too high if 5 volts supply the module. Others do clever calculations to conclude that the effective voltage after the diode and the resistor is close to 4.2 volts.
• There is no consensus on the true charging voltage when attempts are made to measure it.
• Some believe that the charging circuit will do nothing if the module is powered at 3.3 volts
• A Li-ion battery at its maximum admissible voltage (4.2 volts for the LIR2032) must not be charged. "It is important to note that Li-Ion cells will not tolerate trickle charging at all after they are fully charged. If current is continuously forced into a fully charged Li-Ion cell (even a very minute current) the cell will be damaged. For this reason, Li-Ion cells are charged using constant voltage (CV) chargers, and not constant current (CC) chargers". (Texas Instruments Characteristics of Rechargeable Batteries).

For these reasons, at least one dealer removes the 200 ohm resistor to deactivate the circuit and recommends the use of a non-rechargeable CR2032 lithium battery. Since it is difficult to find the LIR2032 locally at a reasonable price and since I highly doubt the efficacy of the circuit to charge the battery when the module is supplied at 3.3 volts, I followed the dealer lead with the modules in my possession.