FRAM_I2C

Arduino library for I2C FRAM.

Description

FRAM is a library to read from and write to (over I2C) an FRAM module. The library has (since 0.5.0) four classes

FRAM 16 bit address.
FRAM32 32 (17) bit address.
FRAM11 11 bit address.
FRAM9 9 bit address.

Currently only the MB85RC1MT is known to use 32 bit. FRAM32 can also address 16 bit devices although there is some overhead in footprint.

FRAM stands for Ferroelectric RAM - https://en.wikipedia.org/wiki/Ferroelectric_RAM

FRAM memory is much faster than EEPROM and almost as fast as (Arduino UNO) RAM. Another important feature FRAM has in common with EEPROM is that FRAM keeps its content after a reboot as it is non-volatile, even for years. That makes it ideal to store configuration or logging data in a project.

Types of FRAM that should work with this library:

TYPE	SIZE	TESTED	NOTES	uses	ref
MB85RC04	512	Y	no deviceID register	FRAM9	#35
MB85RC16	2 KB	Y	no deviceID register	FRAM11	#28
MB85RC64T	8 KB	Y		FRAM
MB85RC64V	8 KB	Y	no deviceID register	FRAM	#38
MB85RC128A	16 KB	N	no deviceID register	FRAM
MB85RC256V	32 KB	Y		FRAM
MB85RC512T	64 KB	Y		FRAM
MB85RC1MT	128 KB	Y		FRAM32	#19

MB85RC128A and MB85RC64V have no size / deviceID, clear() will not work correctly, unless one calls setSizeBytes(16 * 1024) or setSizeBytes(8 * 1024) to set the size manually.

For the FRAM9 and FRAM11 the size problem is solved (hard coded) in their class.

Notes

Not all types of FRAM are tested. Please let me know if you have verified one that is not in the list.
If there is no deviceID getSize() will not work correctly.
- ==> fixed for FRAM9 and FRAM11
Address = 0x50 (default) .. 0x57, depends on the lines A0..A2.
MB85RC1MT uses even addresses only as it uses the next odd one internally. So 0x50 uses 0x51 internally for the upper 64 KB block. This latter will not be shown on an I2C scanner (to be tested).
Not tested: expect the MB85RC1MT can be addressed with 2 instances of FRAM too with adjacent addresses.

Interface

#include "FRAM.h"

Constructors

FRAM(TwoWire *wire = &Wire) Constructor with optional Wire interface.
FRAM32(TwoWire *wire = &Wire) Constructor with optional Wire interface, specific for MB85RC1MT type of device, 17 bit address.
FRAM11(TwoWire *wire = &Wire) Constructor with optional Wire interface, specific for devices with 11 bit address e.g. Cypress/Infineon 24CL16B.
FRAM9(TwoWire *wire = &Wire) Constructor with optional Wire interface, specific for devices with 9 bit address e.g. MB85RC04.

Begin

int begin(uint8_t address = 0x50, int8_t writeProtectPin = -1) address and writeProtectPin is optional. Note the MB85RC1MT only uses even addresses.
int begin(int sda, int scl, uint8_t address = 0x50, int8_t writeProtectPin = -1) idem for ESP32 a.o.
bool isConnected() checks if the address set by begin() is visible on the I2C bus.

Write & read

Support for basic types and two calls for generic objects, use casting if needed.
In the FRAM32 class these functions have an uin32_t memAddr.

void write8(uint16_t memAddr, uint8_t value) uint8_t
void write16(uint16_t memAddr, uint16_t value) uint16_t
void write32(uint16_t memAddr, uint32_t value) uint32_t
void write64(uint16_t memAddr, uint64_t value) uint64_t
void writeFloat(uint16_t memAddr, float value) float
void writeDouble(uint16_t memAddr, double value) double
- For boards that have an 8 byte double.
void write(uint16_t memAddr, uint8_t * obj, uint16_t size) other types / sizes.
- typical used for structs or text.
uint8_t read8(uint16_t memAddr)
uint16_t read16(uint16_t memAddr)
uint32_t read32(uint16_t memAddr)
uint64_t read64(uint16_t memAddr)
float readFloat(uint16_t memAddr)
double readDouble(uint16_t memAddr)
- For board that have 8 byte double.
void read(uint16_t memAddr, uint8_t uint8_t * obj, uint16_t size)
- One needs to allocate memory as the function won't.
uint32_t clear(uint8_t value = 0) clears the whole FRAM by writing value to all addresses
- default value is all zero's.
- Returns the number of bytes written.
- clear() does not work for MB85RC128A unless setSizeBytes() is used.

(Template functions, see issue #13, #42)

uint16_t writeObject(uint16_t memAddr, T &obj) writes an object to memAddr (and following bytes).
- Returns memAddr + sizeof(obj) to get the next address to write to.
uint16_t readObject(uint16_t memAddr, T &obj) reads an object from memAddr and next bytes.
- Returns memAddr + sizeof(obj) to get the next address to read from.

(Experimental 0.5.1, see issue #30)

int32_t readUntil(uint16_t memAddr, char * buffer, uint16_t bufferLength, char separator) Reads FRAM from an address into buffer until separator is encountered. The separator is replaced by an '\0' - end of char array. ReadUntil() returns the length of the buffer. To get the address of the next "field" one must add memAddr += (length + 1).
If the separator is not found after bufferLength characters the function returns -1. However the buffer does contain the data read, which might be useful. Handle with care as buffer has probably no '\0' end char.
int32_t readLine(uint16_t memAddr, char * buffer, uint16_t bufferLength) Similar to readUntil(), reads a line from FRAM including the '\n'. This '\n' is mandatory as end separator!.
Note: The buffer needs one extra char for the delimiting '\0' end char. To get the address of the next "field" one must add memAddr += length. This is an minor but important difference with readUntil(). Note: the returning buffer contains the '\n' so one need to take care when printing the buffer.

ReadUntil

readUntil() can be used to read lines and/or fields from an FRAM filled with text. For example logging written with the FRAM_logging.ino example. Note: if memAddr + bufferLength >= size of FRAM, memory wrapping may occur. The library does not check, so the user should.

Note: internally readUntil() reads bufferLength bytes to fill the buffer. Then it searches for the separator. This is chosen to optimize performance for relative small buffers that are used most. For large buffers this fetching of the whole buffer will take much time. This can results in less responsiveness. Increasing the I2C bus speed might compensate this a bit.

Finally the FRAM_readUntil.ino sketch has a readUntil() implementation that uses a per byte fetching.

Write-protect

Will work only if a writeProtectPin was defined in begin()

bool setWriteProtect(bool b) make the FRAM write-protected by pulling the WP line HIGH or LOW.
- Returns true if a writeProtectPin was defined in begin(). Otherwise the FRAM cannot be write protected.
bool getWriteProtect() get current write protect status.
- returns status (true/false).
- Returns false if the writeProtectPin was not defined.

Metadata

These may not work for devices that have no deviceID register.
So use with care.

uint16_t getManufacturerID() see table below. Returns 0x0FFF means getMetaData() had a read error.
uint16_t getProductID() idem. Proprietary. Returns 0x0FFF means getMetaData() had a read error.
uint16_t getSize() returns the size in kiloBYTE. If the FRAM has no device ID register, the size cannot be read.
- FRAM9 will return 0 as it is less than 1 KB. use GetSizeBytes() instead.
uint32_t getSizeBytes() returns the size in BYTES.
- Useful for iterating over the whole memory, or testing the upper boundary.
void setSizeBytes(uint32_t value) sets the size in bytes for getSizeBytes(). To be used only if getSize() cannot determine the size. As far as known this is for the MB85RC128A and MB85RC64V only. See also remark in Future section below. Can also be used to "virtually" reduce the size, e.g. to speed up clear() if the FRAM is used only partial.

Manufacturers ID

Name	ID	Notes
Fujitsu	0x00A
Ramtron	0x004
getMetaData read error	0xFFF	See #38

Additions for manufacturers ID's are welcome.

Sleep

(0.3.6 added - experimental)

void sleep() puts the FRAM in sleep mode so it uses less power. Still needs a power test for several types of FRAM.
bool wakeup(uint32_t trec = 400) tries to wake up the device with a default recovery time of 400 microseconds. Returns true if connected after the call.

According to the data sheets there are only three FRAM devices support the sleep command. So use with care.

TYPE	SIZE	SLEEP (datasheet)	CURRENT	CONFIRMED	NOTES
MB85RC04	512	not supported	-	N
MB85RC16	2 KB	not supported	-	N
MB85RC64T	8 KB	Y Page 11	4.0 uA*	N
MB85RC128A	16 KB	not supported	-	N
MB85RC256V	32 KB	not supported	-	Y
MB85RC512T	64 KB	Y Page 12	4.0 uA*	N
MB85RC1MT	128 KB	Y Page 12	3.6 uA	Y	See #17

current with * are from datasheet

Current

Indicative power usage in uA in three modi (if supported).

TYPE	SIZE	STANDBY	WRITE	SLEEP	NOTES
MB85RC04	512			-
MB85RC16	2 KB			-
MB85RC64T	8 KB			4.0 uA
MB85RC128A	16 KB			-
MB85RC256V	32 KB	10.22 uA	93.48 uA	-
MB85RC512T	64 KB			4.0 uA
MB85RC1MT	128 KB	11.7 uA	46-721 uA	3.6 uA	See #17

TODO: fill the table

FRAM_RINGBUFFER

Since version 0.4.2 a separate class FRAM_RINGBUFFER is added to this repo. Its interface is straightforward and described in FRAM_RINGBUFFER.md. The FRAM_ringbuffer.ino examples shows how the class can be used.

FRAM_MULTILANGUAGE

Since version 0.5.2 the FRAM_ML class is added. Its purpose is to store tables of strings in FRAM. Its interface is described in FRAM_MULTILANGUAGE.md.

See examples.

FRAM11 + FRAM9

0.5.0 added, see issue #28
0.5.3 redo FRAM9 and FRAM11, see #35

Experimental support for smaller FRAM's with 11 and 9 bits addresses.

FRAM11 e.g. Cypress/Infineon 24CL16B (see #28)
FRAM9 e.g. MB85RC04 (see #35) Note getSize() will return 0 as it is only 0.5 KB and rounded down. Use getSizeBytes() to get 512.

Future

Must

improve documentation
test more types of FRAM
- FRAM11 / FRAM9
- other people might help.

Should

Improve getSize() to have clear() working properly.
- MB85RC128A only (hard code fall back?).
- getSize() scanning FRAM like EEPROM library?
investigate a faster strategy for readUntil()
- search for separator per block (e.g. 16 bytes) read.
Investigate getManufacturerID() and getProductID() for FRAM9/11.
- need hardware + data sheets.

Could

improve FRAM32 that can write over the 64 KB border without problems.
- Would need extra checking ==> overhead.
- now it is responsibility of the user.
- do we want/need this?
write() and writeBlock() might write beyond the end of FRAM
- now it is responsibility of the user.
- range check would degrade performance
- error flag ?
extend examples
- FRAM (8x) concatenated as one continuous memory.
  - a wrapper class?
fill power usage table (documentation)
- is in data sheet.
improve comments where needed.

Wont

extend current clear() with partial clear(begin, end, value)?
- can be done by writeBlock() calls by user too
- would need more complex end checking
- ==> wont for now
dump(stream) or printable interface?
- Print interface? expensive in performance per char..
- see example FRAM_hexdump.ino
remember last written address? why?
do we need a write(memAddr, char * buffer) for completeness?
- it is just a wrapper

Support

If you appreciate my libraries, you can support the development and maintenance. Improve the quality of the libraries by providing issues and Pull Requests, or donate through PayPal or GitHub sponsors.

Thank you,

danny24 / fram_i2c Goto Github PK

fram_i2c's Introduction