My FRAM module routines

[victorf]

Monday, June 12, 2006

I have been developing a zx-24 system for a while now. The application requires
that some system information, that will be user modifiable, be stored in non-
volatile memory. I elected to NOT use the persistant memory of the ZX-24, but
instead chose the Ramtron FM24C256 FRAM module. This is a 32 X 8kB EEPROM with
an I2C interface and a device ID of bx1010_0000. Because of it's ferroelectric
structure it, for all practical purposes, has an infinite read/write cycle for
any cell. It can retain data for up to 45 years. I elected to use this memory in
order to gain a bit of experience with it and to learn a bit about using an I2C
interface.

The first order of business was to see if someone had done any code to use the
I2C capabilities of the ZX-24. I found spamiam's Ramtron_24C_API.bas in the
ZBasic files forum. With this as the starting point, I rolled my own. Most
programmers have developed their own coding style and I am no exception. I want
to thank spamiam for posting his work. There is nothing special about the code
save for the fact that I tend to use functions instead of subroutines. I like
the ability to use the function like this:

If MyFunction = 10 then 'my coding style

end if

I started development by only considering the use of the ZX-24's hardware I2C
which is what I use in my project. After I got things working, I re-did the code
so that one could use other than the hardware interface. This can be seen in the
function FRAMWrite where the I2CChannel, SDA, SCL and FRAM write protect pin,
WPPin, are user definable. Let's take a look at FRAMWrite:

Function FRAMWrite( ByVal I2CChannel as Byte, _
ByVal SDAPin as Byte, _
ByVal SCLPin as Byte, _
ByVal WPPin as Byte, _
ByVal FRAMDevice as Byte, _
ByVal FRAMAddress as UnsignedInteger, _
ByVal Bytes2Write as Byte, _
ByRef WriteData() as Byte)as Integer

The first four parameters define the channel you wish to use. The hardware
channel is channel 0. The hardware device channels are "hardwired" as constants
in the FramI2c module should you care to use them. The FRAMDevice is the device
address of the FRAM you wish to write too. The FM24C256 has three address lines
and therefore any one of 8 devices (address bx0000_0000 to bx0000_0111) can be
written to). My application's FRAM is at FRAMDevice = 0.
The FRAMAddress is where within the chosen FRAM you wish to start writing.
Bytes2Write says how many bytes will be written and the byte array WritData()
contains the data to write. The function returns a positive number when
successful which is the bytes written (should equal Bytes2Write). It returns a
negative value on error the meaning of which is documented in the function
comments. I strongly suggest that you read my comments at the beginning of each
function to understand the return codes. Also notice that the function sets the
write protect pin low to enable the write and sets it high (disabled) when
exiting. I insure that the FRAM is write-protected in my main module at start-
up.

Here is FRAMRead:

Function FRAMRead( ByVal I2CChannel as Byte, _
ByVal SDAPin as Byte, _
ByVal SCLPin as Byte, _
ByVal FRAMDevice as Byte, _
ByVal FRAMAddress as UnsignedInteger, _
ByVal Bytes2Read as Integer, _
ByRef ReadData() as byte)as Integer

Notice that there is no need to manipulate the write protect pin in order to
read from the FRAM. Therefore there is no need to include the pin number in the
parameter list. Other than that, this function call apes FRAMWrite. Again, I
caution you to read the beginning remarks in the function to understand the
error handling. You will need to read the discussion of the I2CCmd in the ZBasic
Syslib as FRAMRead merely returns the error code from the I2CCmd.

I have included my application template module, TPMod.bas in the .ZIP file so
you can see how I handle the calls to the FramI2c module. I have helper
functions there, WriteDataToFram and ReadDataFromFram that do all the work in
the main module. They are a little easier to call as their parameter lists are
shorter. Please notice the use of aliases to load and unload the data for the
FRAM. This simlifies the job by handling the data size as some of the data is
boolean, some is byte and some is unsigned integers. You must write byte data to
the FRAM.

Also in the .ZIP file is FramI2C.bas and a ExpressPCB schematic of my system
board so you can see how the FRAM device relates to the ZX-24

Now the disclaimer. I have only used these routines in the hardware mode. They
have worked well. I have not tested them with any other channels. Perhaps
someone will do that and report their experiences to me. Criticism is requested
and desired so we can make these routines more useful. As I always say, any
enlightenment will be appreciated. Feel free to e-mail me directly if you wish
at victorf@windreader.com

Vic