- Why do we need this FlashStorage_STM32 library
- Changelog
- Prerequisites
- Installation
- Limited number of writes
- Usage
- Examples
- Examples from other libraries
- Example StoreNameAndSurname
- FAQ
- Troubleshooting
- Releases
- Issues
- TO DO
- DONE
- Contributions and Thanks
- Contributing
- License
- Copyright
Why do we need this FlashStorage_STM32 library
The FlashStorage_STM32 library, inspired by Cristian Maglie's FlashStorage, provides a convenient way to store and retrieve user's data using emulated-EEPROM, from the non-volatile flash memory of STM32F/L/H/G/WB/MP1.
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.
- STM32F/L/H/G/WB/MP1 boards with / without integrated EEPROM
- Nucleo-144
- Nucleo-64
- Nucleo-32
- Discovery
- Generic STM32F0, STM32F1, STM32F2, STM32F3, STM32F4, STM32F7
- STM32L0, STM32L1, STM32L4
- STM32G0, STM32G4
- STM32H7
- STM32WB
- STM32MP1
- LoRa boards
- 3-D printer boards
- Generic Flight Controllers
- Midatronics boards
- Fix compiler warnings.
- Initial release to support STM32F/L/H/G/WB/MP1 board with / without integrated EEPROM
Arduino IDE 1.8.13+for ArduinoArduino Core for STM32 v1.9.0+for STM32F/L/H/G/WB/MP1 boards.
The best and easiest way is to use Arduino Library Manager. Search for FlashStorage_STM32, then select / install the latest version.
You can also use this link
Another way to install is to:
- Navigate to FlashStorage_STM32 page.
- Download the latest release
FlashStorage_STM32-main.zip. - Extract the zip file to
FlashStorage_STM32-maindirectory - Copy whole
FlashStorage_STM32-mainfolder to Arduino libraries' directory such as~/Arduino/libraries/.
- Install VS Code
- Install PlatformIO
- Install FlashStorage_STM32 library by using Library Manager. Search for FlashStorage_STM32 in Platform.io Author's Libraries
- Use included platformio.ini file from examples to ensure that all dependent libraries will installed automatically. Please visit documentation for the other options and examples at Project Configuration File
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 put() orcommit() functions too often and make sure that in the entire life of the micro the number of calls to put() orcommit() 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).
Include FlashStorage_STM32.h to get an EEPROM emulation with the internal flash memory.
See EmulateEEPROM sketch for an example.
The API is very similar to the well known Arduino EEPROM.h API but with 4 additional functions:
bool isValid()returnstrueif data in the emulated-EEPROM is valid (the data written to flash at least once byEEPROM.commit()orEEPROM.put()). Otherwise emulated-EEPROM data is "undefined" and the function returnsfalse.void commit()store the EEPROM data in flash. Use this with care: Every call writes the complete emulated-EEPROM 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_commitASAPprivate variable (default istrueto be safe). If _commitASAP is false, the call toEEPROM.put()won't force theEEPROM.commit()to extend the flash life. You'll have to remember to callEEPROM.commit()manually to save the emulated-EEPROM data into flash or data will be lost.bool getCommitASAP()to return the current value of_commitASAP.
- EEPROM_Clear
- EEPROM_CRC
- EEPROM_get
- EEPROM_iteration
- EEPROM_put
- EEPROM_read
- EEPROM_update
- EEPROM_write
- EmulateEEPROM
- FlashStoreAndRetrieve
- StoreNameAndSurname
1. Library WiFiManager_Generic_Lite
2. Library WiFiManager_NINA_Lite
3. Library Ethernet_Manager_STM32
and mamy more to come.
Example StoreNameAndSurname
// Demonstrate how to use FlashStorage_STM32 with an API that is similar to the EEPROM library to Store and retrieve structured data.
#include <FlashStorage_STM32.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_STM32_VERSION);
Serial.print("EEPROM length: ");
Serial.println(EEPROM.length());
// Check signature at address 0
int signature;
// Create a "Person" variable and call it "owner"
uint16_t storedAddress = 0;
Person owner;
EEPROM.get(storedAddress, signature);
// If the EEPROM is empty then no WRITTEN_SIGNATURE
if (signature == WRITTEN_SIGNATURE)
{
EEPROM.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");
EEPROM.put(0, 0);
Serial.println("Done clearing signature in emulated EEPROM. You can reset now");
}
else
{
Serial.println("EEPROM is empty, writing WRITTEN_SIGNATURE and some example data:");
EEPROM.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 emulated-EEPROM
EEPROM.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...
}Yes, you can declare a struct with more fields and call a EEPROM.put() to store the entire structure. See the StoreNameAndSurname for how to do it.
Not with STM32.
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 emulated-EEPROM, provided that you keep in mind the limits as in Limited number of writes
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.
- Fix compiler warnings.
- Initial release to support STM32F/L/H/G/WB/MP1 board with / without integrated EEPROM
- STM32F/L/H/G/WB/MP1 boards with / without integrated EEPROM
- Nucleo-144
- Nucleo-64
- Nucleo-32
- Discovery
- Generic STM32F0, STM32F1, STM32F2, STM32F3, STM32F4, STM32F7
- STM32L0, STM32L1, STM32L4
- STM32G0, STM32G4
- STM32H7
- STM32WB
- STM32MP1
- LoRa boards
- 3-D printer boards
- Generic Flight Controllers
- Midatronics boards
Submit issues to: FlashStorage_STM32 issues
- Search for bug and improvement.
- Similar features for remaining Arduino boards
- Basic emulated-EEPROM for STM32F/L/H/G/WB/MP1.
- Similar features for remaining Arduino boards such as SAMD21, SAMD51, etc.
- Add Table of Contents
Many thanks for everyone for bug reporting, new feature suggesting, testing and contributing to the development of this library.
- Inspired by Cristian Maglie's FlashStorage.
 ⭐️ Cristian Maglie |
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
- The library is licensed under MIT
Copyright 2021- Khoi Hoang