/FlashStorage_RTL8720

The FlashStorage_RTL8720 library aims to provide a convenient way to store and retrieve user's data using the non-volatile flash memory of Realtek RTL8720DN, RTL8722DM, RTM8722CSM, etc. It's using the buffered read and write to minimize the access to Flash. It now supports writing and reading the whole object, not just byte-and-word.

Primary LanguageCMIT LicenseMIT

FlashStorage_RTL8720 Library

arduino-library-badge GitHub release GitHub contributions welcome GitHub issues

Donate to my libraries using BuyMeACoffee

Table of Contents

Why do we need this FlashStorage_RTL8720 library

Features

The FlashStorage_RTL8720 library, inspired by Cristian Maglie's FlashStorage, provides a convenient way to store and retrieve user's data using FlashStorage, from the non-volatile flash memory of RTL8720.

The flash memory, generally used to store the firmware code, can also be used to store / retrieve more user's data and faster than from EEPROM. Thanks to the buffered data writing and reading, the flash access time is greatly reduced to increase the life of the flash.

Currently supported Boards

  1. RTL8720DN, RTL8722DM, RTM8722CSM, etc. boards

Prerequisites

  1. Arduino IDE 1.8.19+ for Arduino. GitHub release
  2. Arduino AmebaD core 3.1.4+ for Realtek RTL8720DN, RTL8722DM and RTM8722CSM. GitHub release

Installation

Use Arduino Library Manager

The best and easiest way is to use Arduino Library Manager. Search for FlashStorage_RTL8720, then select / install the latest version. You can also use this link arduino-library-badge for more detailed instructions.

Manual Install

Another way to install is to:

  1. Navigate to FlashStorage_RTL8720 page.
  2. Download the latest release FlashStorage_RTL8720-main.zip.
  3. Extract the zip file to FlashStorage_RTL8720-main directory
  4. Copy whole FlashStorage_RTL8720-main folder to Arduino libraries' directory such as ~/Arduino/libraries/.

VS Code & PlatformIO

  1. Install VS Code
  2. Install PlatformIO
  3. Install FlashStorage_RTL8720 library by using Library Manager. Search for FlashStorage_RTL8720 in Platform.io Author's Libraries
  4. Please visit documentation for the other options and examples at Project Configuration File

Packages' Patches

1. For RTL8720DN boards using AmebaD core

To avoid compile error relating to PROGMEM, you have to copy the file Realtek AmebaD core pgmspace.h into Realtek AmebaD directory (~/.arduino15/packages/realtek/hardware/AmebaD/3.1.4/cores/ambd/avr/pgmspace.h).

Supposing the Realtek AmebaD core version is 3.1.4. This file must be copied into the directory:

  • ~/.arduino15/packages/realtek/hardware/AmebaD/3.1.4/cores/ambd/avr/pgmspace.h

Whenever a new version is installed, remember to copy this file into the new version directory. For example, new version is x.yy.zz This file must be copied into the directory:

  • ~/.arduino15/packages/realtek/hardware/AmebaD/x.yy.zz/cores/ambd/avr/pgmspace.h

Limited number of writes

The flash memory has a limited amount of write cycles. Typical flash memories can perform about 10000 writes cycles to the same flash block before starting to "wear out" and begin to lose the ability to retain data.

So BEWARE: IMPROPER USE OF THIS LIBRARY CAN QUICKLY AND PERMANENTLY DESTROY THE FLASH MEMORY OF YOUR MICRO, in particular you should avoid to call the FlashStorage.writeByte(), FlashStorage.writeWord() functions, without calling FlashStorage.setCommitASAP(false), too often. Also make sure that in the entire life of the number of calls to write or commit() stay well below the above limit of 10000 (it's a good rule-of-thumb to keep that number in mind even if the manufacturer of the micro guarantees a bigger number of cycles).

The same caution must be taken if you're using the FlashStorage API (see below) with the FlashStorage.commit() function.

Usage

Using the alternative FlashStorage API

Include FlashStorage_RTL8720.h to get a FlashStorage with the internal flash memory.

See FlashStoreAndRetrieve sketch for an example.

The API is very similar to the FlashStorage_SAMD.h API, with these functions:

  • void writeByte(uint32_t offset, uint8_t data)
  • uint8_t readByte(uint32_t offset)
  • void updateByte(uint32_t offset, uint8_t value)
  • void writeWord(uint32_t offset, uint32_t data)
  • uint32_t readWord(uint32_t offset)
  • void updateWord(uint32_t offset, uint32_t value)
  • template< typename T > T &get( uint32_t offset, T &t )
  • template< typename T > const T &put( uint32_t offset, const T &t )
  • void readFlashToBuffer()
  • bool isValid()
  • uint16_t length()
  • void setCommitASAP(bool value = true)
  • bool getCommitASAP()
  • void eraseFlashSector()

  • bool isValid() returns true if data in the FlashStorage is valid (the data written to flash at least once by FlashStorage.commit() or FlashStorage.put()). Otherwise FlashStorage data is "dirty" and the function returns false.

  • void commit() store the FlashStorage buffer data in FlashStorage. Use this with care: Every call writes the complete FlashStorage buffer data to flash. This will reduce the remaining flash-write-cycles. Don't call this method in a loop or you will kill your flash soon.

  • void setCommitASAP(bool value = true) to set or clear the _commitASAP private variable (default is true to be safe). If _commitASAP is false, the call to FlashStorage.put(), etc won't force the FlashStorage.commit() to extend the flash life. You'll have to remember to call FlashStorage.commit() manually to save the FlashStorage buffered data into FlashStorage or data will be lost.

  • bool getCommitASAP() to return the current value of _commitASAP.

Examples

  1. FlashStorage_Clear
  2. FlashStorage_CRC
  3. FlashStorage_get
  4. FlashStorage_iteration
  5. FlashStorage_put
  6. FlashStorage_read
  7. FlashStorage_update
  8. FlashStorage_write
  9. FlashStoreAndRetrieve
  10. StoreNameAndSurname
  11. multiFileProject New

Example StoreNameAndSurname

FlashStorage_RTL8720/examples/StoreNameAndSurname/StoreNameAndSurname.ino

Lines 15 to 106 in bd12b4e

#define FLASH_DEBUG 1
// Can be included as many times as necessary, without `Multiple Definitions` Linker Error
#include <FlashStorage_RTL8720.h>
const int WRITTEN_SIGNATURE = 0xBEEFDEED;
// Create a structure that is big enough to contain a name
// and a surname. The "valid" variable is set to "true" once
// the structure is filled with actual data for the first time.
typedef struct
{
char name[100];
char surname[100];
} Person;
void setup()
{
Serial.begin(115200);
while (!Serial);
delay(200);
Serial.print(F("\nStart StoreNameAndSurname on "));
Serial.println(BOARD_NAME);
Serial.println(FLASH_STORAGE_RTL8720_VERSION);
Serial.print("FlashStorage length: ");
Serial.println(FlashStorage.length());
// Check signature at address 0
int signature;
// Create a "Person" variable and call it "owner"
uint16_t storedAddress = 0;
Person owner;
FlashStorage.get(storedAddress, signature);
// If the FlashStorage is empty then no WRITTEN_SIGNATURE
if (signature == WRITTEN_SIGNATURE)
{
FlashStorage.get(storedAddress + sizeof(signature), owner);
// Say hello to the returning user!
Serial.print("Hi ");
Serial.print(owner.name);
Serial.print(" ");
Serial.print(owner.surname);
Serial.println(", nice to see you again :-)");
Serial.println("Clearing WRITTEN_SIGNATURE for next try");
FlashStorage.put(0, 0);
Serial.println("Done clearing signature in FlashStorage. You can reset now");
}
else
{
Serial.println("FlashStorage is empty, writing WRITTEN_SIGNATURE and some example data:");
FlashStorage.put(storedAddress, WRITTEN_SIGNATURE);
// ...in this case we ask for user data.
Serial.setTimeout(30000);
Serial.print("Insert your name : ");
String name = Serial.readStringUntil('\n');
Serial.println(name);
Serial.print("Insert your surname : ");
String surname = Serial.readStringUntil('\n');
Serial.println(surname);
// Fill the "owner" structure with the data entered by the user...
name.toCharArray(owner.name, 100);
surname.toCharArray(owner.surname, 100);
// ...and finally save everything into FlashStorage
FlashStorage.put(storedAddress + sizeof(signature), owner);
// Print a confirmation of the data inserted.
Serial.print("<< Your name: ");
Serial.print(owner.name);
Serial.print(". Your surname: ");
Serial.print(owner.surname);
Serial.println(" >> have been saved. Thank you!");
}
}
void loop()
{
// Do nothing...
}

Debug Terminal Output Samples

1. StoreNameAndSurname on Rtlduino RTL8720DN

1.1 First Start

Start StoreNameAndSurname on Rtlduino RTL8720DN
FlashStorage_RTL8720 v1.1.0
FlashStorage length: 4096
EEPROM is empty, writing WRITTEN_SIGNATURE and some example data:
Insert your name : First_Name
Insert your surname : Last_Name

<< Your name: First_Name. Your surname: Last_Name >> have been saved. Thank you!

1.2 After Restart

Start StoreNameAndSurname on Rtlduino RTL8720DN
FlashStorage_RTL8720 v1.1.0
FlashStorage length: 4096
Hi First_Name Last_Name, nice to see you again :-)
Clearing WRITTEN_SIGNATURE for next try
Done clearing signature in FlashStorage. You can reset now

2. FlashStorage_read on Rtlduino RTL8720DN

The following is the sample terminal output when running example FlashStorage_read on Rtlduino RTL8720DN

Start FlashStorage_read on Rtlduino RTL8720DN
FlashStorage_RTL8720 v1.1.0
FlashStorage length: 4096
0	100
1	101
2	102
3	103
4	104
5	105
...

FAQ

Can I use a single object to store more stuff?

Yes, you can declare a complex struct with more fields and call a FlashStorage.put() to store the entire structure. See the StoreNameAndSurname for how to do it.

The content of the FlashStorage is erased each time a new sketch is uploaded?

Not with RTL8720DN, RTL8722DM, RTM8722CSM, etc.

Do you recommend to use FLASH instead of EEPROM?

No. If your board provides an integrated-EEPROM, it's advisable to use that because EEPROM has longer lifetime, number of write cycles, etc.

In the absence of an integrated-EEPROM or its size is too small for your use-case, you can use this library to use a small portion flash memory as FlashStorage, provided that you keep in mind the limits as in Limited number of writes

Troubleshooting

If you get compilation errors, more often than not, you may need to install a newer version of the core for Arduino boards.

Sometimes, the library will only work if you update the board core to the latest version because I am using newly added functions.

Issues

Submit issues to: FlashStorage_RTL8720 issues

TO DO

  1. Search for bug and improvement.
  2. Similar features for remaining Arduino boards

DONE

  1. Basic FlashStorage for RTL8720.
  2. Add Table of Contents
  3. Fix multiple-definitions linker error.
  4. Add astyle using allman style. Restyle the library

Contributions and Thanks

Many thanks for everyone for bug reporting, new feature suggesting, testing and contributing to the development of this library.

  1. Inspired by Cristian Maglie's FlashStorage.
cmaglie
⭐️ Cristian Maglie

Contributing

If you want to contribute to this project:

  • Report bugs and errors
  • Ask for enhancements
  • Create issues and pull requests
  • Tell other people about this library

License

  • The library is licensed under MIT

Copyright

Copyrigh (c) 2021- Khoi Hoang