Project Members:

Monarco Hat Realtime Clock SRAM Support Package for RETAIN data

Download Package

I2C MCP7941x realtime clock

This chip is the follow-up of the famous DS1307 realtime clock (RTC).
It enables you to use RETAIN declared variables in your code on a Raspberry Pi or Beaglebone.

This RTC chip is used in the Monarco Hat but it can also be installed separatly as a standalone RTC add-on solution on a break-out board.
By adding a battery backed SRAM MCP7941x realtime clock to your Raspberry setup you obtain a hardware realtime clock and SRAM capability.

The RTC time itself can be accessed via several "of the shelve" libraries, so I did not bother to implement it (sorry).
However, obtaining current date and time is demonstrated in the provided example code with help of such an "of the shelve" library.


v0.0.2.1 stable initial public release

devdescr.xml: vendor id set to 0003, device id set to 0009, see https://forge.codesys.com/drv/io-drivers/database/Home/ for details.

      <Id>0003 0009</Id>


Install the .package file, it provides the library, example and an eula.

For a quick start, open the example code from the package installation directory. You can declare any type of variable as RETAIN.
If you have several POU's in your program containing RETAIN data, the total accumulated maximum size may not exceed 64 Bytes.

Anytime you write the retained data in your program, the SRAM gets updated with the new values.
Whenever your runtime stops or reboots, the values are stored in the battery buffered SRAM.
If your runtime resumes, the data is restored from SRAM to the userdata auto-magically.

abyMyRetainedBytes : ARRAY [0..63] OF BYTES; // maximum size of retained data in SRAM of mcp7491x

RETAIN data size restriction of 64 Bytes

If your total RETAIN data exceeds 64 Bytes, anything over this maximum is simply ignored and will not be retained!
Beware, no error messages or feedback is given if the data exceeds this size

You can verify this behaviour by opening the test program, re-edit the code for array's of e.g. 96 bytes size, fill it and then cold start the controller.
When you enable the runtime, only 64 bytes get reloaded from SRAM.

abyMyRetainedBytes : ARRAY [0..95] OF BYTES; // Exceeds maximum size of retained data in SRAM of mcp7491x, indexes [64..95] are simply ignored as they will not physically fit in the SRAM.

Performance as performed with the example code

Tested on a Raspberry Pi 3B+ with singlecore runtime license and using the example code from the package, this so you can verify these results for yourself if you wish.
If you have any meaningful feedback, please let me know. I will add your testresults to this page.

Test procedure:
1) Use a single task, configure it as in the table.
1) Go online, flush the SRAM, then verify the array contents, then Cold reset the controller and press run and check the array again. The array should be empty.
2) Write the Test sequence, then Cold reset the controller and press run and check the array again, the array should be filled with correct value's.

Tested using Raspberry Pi 3B+ hardware with a Single Core License

Tasktime Prio Result
250ms 1 No issue's
100ms 1 No issue's
50ms 1 No issue's
25ms 1 No issue's
5ms 1 No issue's
1ms 1 No issue's

As seen in the table, tasktimes as quick as 1 milliseconds is working correct.
Beware, as your mileage may vary because of various reasons e.g. bigger programcode, more tasks, multitasking, etc, etc!

Installing the MCP7941 for SRAM/RTC usage in CODESYS

You can use this driver in combination with the Monarco HAT or any other pcb which uses the MCP7941x Realtimeclock (RTC).
It will provide you with 64 bytes battery buffered SRAM Retain support in CODESYS on a Raspberry Pi based hardware, as the Pi has no native SRAM support.

Getting and setting the time is not implemented in this library but can easily be achieve with several other common flavoured libraries in CODESYS.

MCP7941x hardware setup

In order to set up a MCP7941x real time clock, start by connecting it to the RPi and a quartz crystal.
The following a rough sketch on how to connect the pins to point one in the right direction - in practice, one might need capacitors to smooth signals or resitors to pull-up the SCL- and SDA-interface, depending for example on the battery and quartz crystal used.

X1: Connect to external 32.768 kHz quartz crystal 
X2: Connect to external 32.768 kHz quartz crystal
VBAT: Connect to external battery
VSS: Connect to GND (e.g. RPi-Pin 9)
VCC: Connect to RPi-Pin 1 (3.3V)
MFP: -
SCL: Connect to RPi-Pin 5 (GPIO3_SCL1)
SDA: Connect to RPi-Pin 3 (GPIO3_SDA1)

installing the i2c software tools

After connecting the hardware, activated the i2c bus of via

sudo raspi-config

Choose Advanced Options -> "activate I2C" -> "Yes" and exit the tool.
Now update the repository and install i2c-tools

sudo apt-get update
sudo apt-get install i2c-tools

check the adressing/connections

Once you have it installed check that the RTC has been detected using:

sudo i2cdetect -y 0  # (if using v1 Raspberry Pi or)
sudo i2cdetect -y 1  # (if using v2 Raspberry Pi)

This will look something like;

aliazzz@Raspbian:~ $ sudo i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- 18 -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- 57 -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 6f
70: -- -- -- -- -- -- -- --

The MCP7941x has two i2c adresses: 0x57 and 0x6f, if the addresses show up they are ready for communication.
0x57 leads to the EEPROM, a status register and a unique ID register whereas 0x6f is the address that leads to the SRAM and RTC itself

The MCP7941x is now ready for use with CODESYS

installing the MCP7941 for permanent use under linux

NOTE: If you install this chip for linux use, you cannot get access to the SRAM from CODESYS as linux has permanently claimed this resource!
Continue at your own risk

In order to establish a permanent linux OS connection add, first follow the steps to enable the RTC for use in CODESYS (see above)
Once the above steps are completed, follow the below steps.

In "/etc/modules"

sudo nano /etc/modules



Edit the file and close it via alt-x and save the changes

In "/boot/config.txt"

sudo nano /boot/config.txt



Again, edit the file and close it via alt-x and save the changes.

Now reboot,
After reboot the 'sudo i2cdetect' yields;

aliazzz@Raspbian:~ $ sudo i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- 18 -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- 57 -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- UU
70: -- -- -- -- -- -- -- --

The RTC module has been loaded and activated and the RTC is used by linux.

In "/lib/udev/hwclock-set"

sudo nano /lib/udev/hwclock-set

comment out the lines;

#if [ -e /run/systemd/system ] ; then
#   exit 0

Now, synchronize the RTC using the command

sudo hwclock -w

From now on, the RTC will keep the time and resynchronize the RPi's system time automatically on startup or manually by entering

sudo hwclock -r

The RTC is now in permanent use of the Linux OS!
CODESYS cannot use the SRAM from the RTC if the resource is in permanent use of the OS.

On a Monarco HAT UU shows up but you did not install the RTC for use on the linux side..

As for loading the rtc_ds1307 module, this is caused by the plug&play mechanism of the Monarco HAT and its onboard EEPROM.
For details, see https://www.raspberrypi.org/blog/introducing-raspberry-pi-hats/, namely this:
"The EEPROM holds the board manufacturer information, GPIO setup and a thing called a ‘device tree‘ fragment – basically a description of the attached hardware that allows Linux to automatically load the required drivers."

To disable automatic loading of the driver, use the following:

sudo -s
echo "blacklist rtc_ds1307" > /etc/modprobe.d/monarco-rtc.conf

The same can be done for the onboard DS2482-100 1-Wire controller (not sure how 1-Wire bus is handled in Codesys)

sudo -s
echo "blacklist ds2482" > /etc/modprobe.d/monarco-onewire.conf


Enjoy your RETAIN data support for CODESYS on Raspberry Pi platform!

Monarco Hat Realtime Clock SRAM Support Package

Download Package


  • giuliano

    giuliano - 2020-02-11

    Very happy to read this post. But I can't find where you set the runtime to use sram for retain variables instead of file (that is the default setting I think). Thanks

    • aliazzz

      aliazzz - 2020-02-11


      Thank you!

      Retain data is normally not supported by the raspberry pi runtime by design of the hardware. Raspberry Pi has to my knowledge never been released with built in SRAM or battery backed up ram or similar.
      This library focuses purely on realisation of retain data with an mcp7941x RTC Chip with built in SRAM.
      If you wish to implement a workaround via a textfile, you are free to do so yourself as it is not part of the mcp7941x RTC Chip.

      With kind regards


      Last edit: aliazzz 2020-02-11
    • Ingo

      Ingo - 2020-02-11

      AFAIK the driver doesn't change the retain strategy, but it stores and restores the data additionally into the external chip.

      @aliazzz what is the interval in which the data is stored?

      • aliazzz

        aliazzz - 2020-02-11

        Ehm, to rephrase it: the Retain mechanism in Codesys will compile but will not work in the standard raspberry pi hardware. This package enables the user to leverage battery backed up hardware sram support in a raspberry pi via the retain mechanisme which will work in combination with this library.

        The smallest working stable interval for me is T#1msec (see table)
        Your mileage may vary!


        Last edit: aliazzz 2020-02-11

Log in to post a comment.