Project Members:

• aliazzz (admin)

Monarco Hat Realtime Clock SRAM Support Package

I2C MCP7941x

This chip is the follow-up of the famous DS1307 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 hardware setup you obtain a hardware realtime clock and SRAM.
The RTC time itself can be accessed via several "of the shelve" libraries, so I did not bother to implement it.
However, obtaining current date and time is demonstrated in the provided example code with help of an "of the shelve" library.

Changelog

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.

    <DeviceIdentification>
      <Type>500</Type>
      <Id>0003 0009</Id>
      <Version>0.0.2.1</Version>
    </DeviceIdentification>

Library usage

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 automaticly.

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

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.

VAR RETAIN
abyMyRetainedBytes : ARRAY [0..96] OF BYTES; ( exceeds maximum size of retained data in SRAM of mcp7491x, indexes [64..96] are simply ignored as they will not physically fit in the SRAM. )
END_VAR

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.

Raspberry Pi 3B+ Single Core License

As seen in the table, task as quick as 10 microseconds ( T#10us or 10x10^-6 ) are working correct. I havent tested anything faster.
Beware, 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 real time clock.
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

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

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

The steps below work for any device, so we try to find out which module claims the device with the following steps;

ls /sys/bus/i2c/devices

yields something like;

1-0018  1-006f  i2c-1

now enter following (since we are searching for the 6f process);

sudo cat /sys/bus/i2c/devices/1-006f/modalias

will yield something like

i2c:mcp7941x

Now, the output will tell which driver is used.
To identify if this is an alias use;

sudo grep mcp7941x /lib/modules/`uname -r`/modules.alias

which hopefully you will get some output like

alias
alias i2c:mcp7941x rtc_ds1307
alias of:N*T*Cmicrochip,mcp7941xC* rtc_ds1307
alias of:N*T*Cmicrochip,mcp7941x rtc_ds1307

We identified which driver has been hogging our resource.
So now we can try to unload it from the modules but this is only possible if it is a loadable module (must not be a compiled kernel).

sudo rmmod rtc_ds1307

otherwise you will see the following error:

ERROR: Module rtc_ds1307 does not exist in /proc/modules

Enjoy!

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

Monarco Hat Realtime Clock SRAM Support Package