Project Members:

• aliazzz (admin)

Monarco Hat Realtime Clock SRAM Support Package for RETAIN data

Monarco HAT / MCP7941x

RPi natively has no Real Time Clock and SRAM support. The i2c MCP7941x chip is the successor for the famous DS1307 Real Time Clock (RTC) and Monarco HAT implements MCP7941x as an RTC.
After correct install and configuration under the host OS, this RTC will provide you with 64 bytes battery buffered SRAM Retain support in CODESYS on a Raspberry Pi based hardware.
Obtaining the current date and time is achieved through usage of standard CODESYS libraries like SysLibRTC or CAA libraries.

This chip can also be installed as a standalone RTC add-on solution on a break-out board. By wiring a battery backed SRAM MCP7941x RTC chip to your Raspberry/Beaglebone setup you gain both an RTC and RETAIN SRAM capability.

MCP7941x hardware/wiring setup

In order to set up a MCP7941x RTC, 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 resistors to pull-up the SCL- and SDA- lines, 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)

MCP7941x software setup

NOTE: Default this chip is configured for access from linux OS, so you cannot get access to the SRAM from CODESYS as linux has permanently claimed this resource.
So if you want to use the SRAM under CODESYS you myst performa configuration on the linux OS side

1. Enable usage in CODESYS
2. Permanent Linux access setup

Enable usage in CODESYS

installing the i2c software tools after connecting
the hardware and activation of the i2c bus.

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 Raspberry Pi 1 or)
sudo i2cdetect -y 1  # (if using Raspberry Pi 2 or later)

Note: 
The MCP7941x has two i2c adresses: 0x57 and 0x6f, if the addresses both 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

This output should now look something like this;

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: -- -- -- -- -- -- -- --

6f ?

The MCP7941x is now ready for use with CODESYS =) and you can skip to chapter manual RTC-sync

However, if the table shows UU the RTC module has been loaded and is permanently activated for exclusive OS only usage, please continue below.

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: -- -- -- -- -- -- -- --

UU shows up

If you see "UU" instead of 0x6f for your RTC after the previous steps, this likely is caused by loading of the
incorrect rtc_ds1307 driver or by permanently claim the RTC access by linux.

This can have 2 causes, either you

1. configure the Hat for the first time and you have not blacklisted loading of the incorrect rtc_ds1307 driver yet
2. deliberately permanently claimed the RTC access

Loading of the incorrect driver (rtc_ds1307 module)

This is triggered in the OS by the plug&play mechanism of the Monarco HAT onboard EEPROM.
So we have to prevent Linux to load the incorrectr driver by blacklisting it and thus "free" its resource on the i2c bus.
Not to worry, we must do some extra configuring.

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

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

Now reboot the RPi and run

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 is now ready for use with CODESYS =)

Claim RTC resource for exclusive OS only usage (UU)

In order to claim a permanent linux OS access add, first follow the all the previous steps to enable the RTC for use in CODESYS (see above),
and continue to follow then follow the below steps. Basicly you UNDO freeing the RTC for CODESYS.

In "/etc/modules"

sudo nano /etc/modules

add

rtc-mcp7941x

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

In "/boot/config.txt"

sudo nano /boot/config.txt

add

dtoverlay=i2c-rtc,mcp7941x

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 is permanently activated for exclusive OS only usage.
CODESYS cannot use the SRAM from the RTC if the resource is in permanent use of the OS.

manual RTC-sync

Normally a deamon syncs the clock but you can also consider triggering a manual sync for the clock.
You can override the standard deamon as follows (not mandatory);

In "/lib/udev/hwclock-set"

sudo nano /lib/udev/hwclock-set

comment out the lines;

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

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

CODESYS usage

RETAIN data size <= 64 Bytes

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 RETAIN size should 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, no extra code needed.

Example 1) 64 bytes in a single declaration;

VAR RETAIN
    abyRetainData : ARRAY [0..63] OF BYTES; // maximum size RETAIN in SRAM of mcp7491x
END_VAR

Example 2) 64 bytes via multiple declarations;

VAR RETAIN
    abyRetainData1 : ARRAY [0..31] OF BYTES; //32 Bytes
END_VAR

VAR RETAIN
    iSomeValue1, iSomeValue2 : INT; // 2* 2 Bytes (4)
    rSomeOtherValue1, rSomeOtherValue2 : REAL; // 2 * 4 Bytes (8)
    dwYetAnotherValue1: DWORD; // 4 Bytes (4)
    // 4+8 + 4 = 16 Bytes
END_VAR

VAR RETAIN
    R : ARRAY [0..15] OF BYTES; //16 Bytes 
END_VAR

RETAIN data size > 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 any feedback feedback is given if the data exceeds this size!

You can verify this behavior 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.

Example 3) >64 bytes in a single declaration;

VAR RETAIN
    abyMyRetainedBytes : ARRAY [0..95] OF BYTES; // Exceeds maximum size, indexes [64..95] are ignored as they will not physically fit in the SRAM.
END_VAR

Example 4) >64 bytes via multiple declarations;

VAR RETAIN
    abyRetainData1 : ARRAY [0..48] OF BYTES; //48 Bytes
END_VAR

VAR RETAIN
    iSomeValue1, iSomeValue2 : INT; // 2* 2 Bytes (4)
    rSomeOtherValue1, rSomeOtherValue2 : REAL; // 2 * 4 Bytes (8)
    dwYetAnotherValue1: DWORD; // 4 Bytes (4)
    // 4+8 + 4 = 16 Bytes
END_VAR

VAR RETAIN
    R : ARRAY [0..32] OF BYTES; //32 Bytes 
END_VAR

Performance

Tested on a Raspberry Pi 3B+ with single core runtime license and using the example code from the package, you are welcome to verify if you wish.

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.

Raspberry Pi CODESYS SL (no MC) run on 3B+ hardware with Raspbian Buster latest release

As seen in the table, tasktimes as quick as 1 milliseconds are working correct.
Beware, your mileage may vary, due to hardware/OS/tasktime etc etc