Hardware Prerequisites

Read the documentation on Installing coin battery and mounting it on the correct GPIO pins for your version of Raspberry Pi board.

Example of Raspberry Pi RTC Modules with documentation:

Install Software

Add the modules from the kernel. The documentation should give you required modules paired with chipset mcp7941x, ds1307 or etc.

/etc/modules|/etc/modules-load.d/i2c.conf

Add these modules so they're loaded on boot. You can modprobe each one individually if you don't want to reboot.

mcp7941x

Contents of /etc/modules

i2c_dev
i2c_bcm2708
i2c:mcp7941x

ds1307

Contents of /etc/modules-load.d/i2c.conf

i2c_dev
i2c_bcm2708
rtc-ds1307

/media/mmcblk0p1/config.txt

You will need to mount this as read-write in diskless mode

mount -o remount,rw /media/mmcblk0p1

Add these two parameters to the bottom

Contents of /media/mmcblk0p1/config.txt

dtparam=i2c1=on
dtparam=i2c_arm=on

mount -o remount,ro /media/mmcblk0p1

Then you will need to reboot.

Binding the hardware clock device

Read the documentation for the mounted RTC module to get an I2C address for hardware binding. You will want to make sure the device is created when hwclock starts, if it isn't already created. To the bottom of /etc/conf.d/hwclock add this:

mcp7941x

Contents of /etc/conf.d/hwclock

...
start_pre() {
    if [ -d "/sys/class/i2c-adapter/i2c-1/i2c-dev/i2c-1" ]; then
        einfo "Creating RTC device";
        echo mcp7941x 0x6f > /sys/class/i2c-adapter/i2c-1/new_device
    fi
}

For the time being this is necessary but in the future when issue 1032 you should be able to just add

Contents of /media/mmcblk0p1/config.txt

...
dtparam=i2c-rtc,mcp7941x

ds1307

Contents of /etc/conf.d/hwclock

...
start_pre() {
    einfo "Creating RTC device";
    echo ds1307 0x68 > /sys/bus/i2c/devices/i2c-1/new_device
}

In diskless mode save to /media/mmcblk0p1/config.txt.

In system disk mode save to /boot/usercfg.txt.

Testing hardware bind

Before test hardware bind, reboot or run line echo … from /etc/conf.d/hwclock example

echo ds1307 0x68 > /sys/bus/i2c/devices/i2c-1/new_device

Display hardware clock

hwclock

Output should display time

 hwclock: Wed Mar 12 17:41:09 2025  0.000000 seconds

Or error similar below

 hwclock: ioctl 0x80247009 failed: Invalid argument

meaning hardware bind is successful.

Write system time to RTC module

hwclock -w

Run hwclock again to check the time.

Starting hwclock on boot

The hwclock service needs to be started for the hardware clock device to actually do anything. Check if hwclock has been started by running this command:

rc-status | grep hwclock

If it outputs

 hwclock                                                           [  started  ]

hwclock has already started. Otherwise start it manually and add it to the default init.d runlevel, so that it starts at boot time:

rc-service hwclock start

rc-update add hwclock default

If you are running Alpine Linux in the diskless mode (non-persistent root filesystem), save the configuration by:

lbu commit -d