- Important Change from v1.1.0
- Why do we need this FlashStorage_STM32F1 library
- Changelog
- Prerequisites
- Installation
- Packages' Patches
- HOWTO Fix
Multiple DefinitionsLinker Error - Limited number of writes
- Usage
- Examples
- Example FlashStoreAndRetrieve
- Debug Terminal Output Samples
- FAQ
- Troubleshooting
- Issues
- TO DO
- DONE
- Contributions and Thanks
- Contributing
- License
- Copyright
Please have a look at HOWTO Fix Multiple Definitions Linker Error
Why do we need this FlashStorage_STM32F1 library
The FlashStorage_STM32F1 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 STM32F1/F3, including non-genuine CH32F103xx, CS32F103xx, etc. boards.
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, the library supports both new STM32 core v2.0.0 and previous STM32 core v1.9.0
- STM32F1/F3 boards with / without integrated EEPROM
- NUCLEO_F103RB, DISCO_F100RB
- BLUEPILL_F103C6, BLUEPILL_F103C8, BLUEPILL_F103CB
- BLACKPILL_F103C8, BLACKPILL_F103CB
- Generic STM32F1, STM32F3
- VCCGND_F103ZET6_MINI, VCCGND_F103ZET6,
- HY_TINYSTM103TB, MAPLEMINI_F103CB
- BLUEBUTTON_F103R8T, BLUEBUTTON_F103RBT, BLUEBUTTON_F103RCT, BLUEBUTTON_F103RET
- GENERIC_F100C4TX, GENERIC_F100C8TX, GENERIC_F100CBTX
- GENERIC_F103C4TX, GENERIC_F103C6TX, GENERIC_F103C6UX, GENERIC_F103C8TX, GENERIC_F103CBTX, GENERIC_F103CBUX
- GENERIC_F100R8TX, GENERIC_F100RBTX
- GENERIC_F103R4HX, GENERIC_F103R6HX, GENERIC_F103R4TX, GENERIC_F103R6TX, GENERIC_F103R8HX, GENERIC_F103RBHX, GENERIC_F103R8TX
- GENERIC_F103RBTX, GENERIC_F103RCTX, GENERIC_F103RDTX, GENERIC_F103RETX, GENERIC_F103RCYX, GENERIC_F103RDYX, GENERIC_F103REYX
- GENERIC_F103RFTX, GENERIC_F103RGTX
- GENERIC_F103T4UX, GENERIC_F103T6UX, GENERIC_F103T8UX, GENERIC_F103TBUX
- GENERIC_F103V8HX, GENERIC_F103VBHX, GENERIC_F103V8TX, GENERIC_F103VBTX, GENERIC_F103VBIX, GENERIC_F103VCHX, GENERIC_F103VDHX
- GENERIC_F103VEHX, GENERIC_F103VCTX, GENERIC_F103VDTX, GENERIC_F103VETX, GENERIC_F103VFTX, GENERIC_F103VGTX,
- GENERIC_F103ZCHX, GENERIC_F103ZDHX, GENERIC_F103ZEHX, GENERIC_F103ZCTX, GENERIC_F103ZDTX, GENERIC_F103ZETX, GENERIC_F103ZFHX,
- GENERIC_F103ZGHX, GENERIC_F103ZFTX, GENERIC_F103ZGTX
- MALYANM200_F103CB, AFROFLIGHT_F103CB
- NUCLEO_F302R8, NUCLEO_F303RE, NUCLEO_F303K8, DISCO_F303VC
- BLACKPILL_F303CC, OLIMEXINO_STM32F3
- GENERIC_F302R6TX, GENERIC_F302R8TX, GENERIC_F303RBTX, GENERIC_F303RCTX, GENERIC_F303RDTX, GENERIC_F303RETX
- GENERIC_F303CBTX, GENERIC_F303CCTX
- GENERIC_F303K6TX, GENERIC_F303K8TX
- GENERIC_F303VBTX, GENERIC_F303VCTX
- GENERIC_F334K4TX, GENERIC_F334K6TX, GENERIC_F334K8TX
- SPARKY_F303CC
Arduino IDE 1.8.19+for Arduino.Arduino Core for STM32 v2.3.0+for STM32 boards.
The best and easiest way is to use Arduino Library Manager. Search for FlashStorage_STM32F1, then select / install the latest version.
You can also use this link
Another way to install is to:
- Navigate to FlashStorage_STM32F1 page.
- Download the latest release
FlashStorage_STM32F1-main.zip. - Extract the zip file to
FlashStorage_STM32F1-maindirectory - Copy whole
FlashStorage_STM32F1-mainfolder to Arduino libraries' directory such as~/Arduino/libraries/.
- Install VS Code
- Install PlatformIO
- Install FlashStorage_STM32F1 library by using Library Manager. Search for FlashStorage_STM32F1 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
For Generic STM32F4 series boards, such as STM32F407VE, using LAN8720, please use STM32 core v2.2.0 as breaking core v2.3.0 creates the compile error.
To use LAN8720 on some STM32 boards
- Nucleo-144 (F429ZI, NUCLEO_F746NG, NUCLEO_F746ZG, NUCLEO_F756ZG)
- Discovery (DISCO_F746NG)
- STM32F4 boards (BLACK_F407VE, BLACK_F407VG, BLACK_F407ZE, BLACK_F407ZG, BLACK_F407VE_Mini, DIYMORE_F407VGT, FK407M1)
you have to copy the files stm32f4xx_hal_conf_default.h and stm32f7xx_hal_conf_default.h into STM32 stm32 directory (~/.arduino15/packages/STM32/hardware/stm32/2.2.0/system) to overwrite the old files.
Supposing the STM32 stm32 core version is 2.2.0. These files must be copied into the directory:
~/.arduino15/packages/STM32/hardware/stm32/2.2.0/system/STM32F4xx/stm32f4xx_hal_conf_default.hfor STM32F4.~/.arduino15/packages/STM32/hardware/stm32/2.2.0/system/STM32F7xx/stm32f7xx_hal_conf_default.hfor Nucleo-144 STM32F7.
Whenever a new version is installed, remember to copy this file into the new version directory. For example, new version is x.yy.zz, these files must be copied into the corresponding directory:
~/.arduino15/packages/STM32/hardware/stm32/x.yy.zz/system/STM32F4xx/stm32f4xx_hal_conf_default.h- `~/.arduino15/packages/STM32/hardware/stm32/x.yy.zz/system/STM32F7xx/stm32f7xx_hal_conf_default.h
To use Serial1 on some STM32 boards without Serial1 definition (Nucleo-144 NUCLEO_F767ZI, Nucleo-64 NUCLEO_L053R8, etc.) boards, you have to copy the files STM32 variant.h into STM32 stm32 directory (~/.arduino15/packages/STM32/hardware/stm32/2.3.0). You have to modify the files corresponding to your boards, this is just an illustration how to do.
Supposing the STM32 stm32 core version is 2.3.0. These files must be copied into the directory:
~/.arduino15/packages/STM32/hardware/stm32/2.3.0/variants/NUCLEO_F767ZI/variant.hfor Nucleo-144 NUCLEO_F767ZI.~/.arduino15/packages/STM32/hardware/stm32/2.3.0/variants/NUCLEO_L053R8/variant.hfor Nucleo-64 NUCLEO_L053R8.
Whenever a new version is installed, remember to copy this file into the new version directory. For example, new version is x.yy.zz, these files must be copied into the corresponding directory:
~/.arduino15/packages/STM32/hardware/stm32/x.yy.zz/variants/NUCLEO_F767ZI/variant.h~/.arduino15/packages/STM32/hardware/stm32/x.yy.zz/variants/NUCLEO_L053R8/variant.h
The current library implementation, using xyz-Impl.h instead of standard xyz.cpp, possibly creates certain Multiple Definitions Linker error in certain use cases.
You can include this .hpp file
// Can be included as many times as necessary, without `Multiple Definitions` Linker Error
#include "FlashStorage_STM32F1.hpp" //https://github.com/khoih-prog/FlashStorage_STM32F1in many files. But be sure to use the following .h file in just 1 .h, .cpp or .ino file, which must not be included in any other file, to avoid Multiple Definitions Linker Error
// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
#include "FlashStorage_STM32F1.h" //https://github.com/khoih-prog/FlashStorage_STM32F1Check the new multiFileProject example for a HOWTO demo.
Have a look at the discussion in Different behaviour using the src_cpp or src_h lib #80
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_STM32F1.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
- multiFileProject New
Example FlashStoreAndRetrieve
The following is the sample terminal output when running example EEPROM_get on STM32F1 BLUEPILL_F103C8 with 64KB Flash
Start EEPROM_get on BLUEPILL_F103C8
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x800F800
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 64
[FLASH] USING_FLASH_SECTOR_NUMBER = 62
EEPROM doesn't store valid data, writing WRITTEN_SIGNATURE and some example data
Float written to EEPROM: 123.456
Done writing custom object to EEPROM:
===============
Field1: 3.14159
Field2: 65
Name: Working!
===============
Reset to see how you can retrieve the values by using EEPROM_get!Start EEPROM_get on BLUEPILL_F103C8
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x800F800
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 64
[FLASH] USING_FLASH_SECTOR_NUMBER = 62
EEPROM has valid data with WRITTEN_SIGNATURE. Now read some example data
Read float from EEPROM: 123.456
Read custom object from EEPROM:
===============
Field1: 3.14159
Field2: 65
Name: Working!
===============The following is the sample terminal output when running example FlashStoreAndRetrieve on STM32F1 BLUEPILL_F103C8 with 64KB Flash
Start FlashStoreAndRetrieve on BLUEPILL_F103C8
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x800FC00
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 64
[FLASH] USING_FLASH_SECTOR_NUMBER = 63
Number = 0x0
Done writing to emulated EEPROM. You can reset nowStart FlashStoreAndRetrieve on BLUEPILL_F103C8
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x800FC00
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 64
[FLASH] USING_FLASH_SECTOR_NUMBER = 63
Number = 0x1
Done writing to emulated EEPROM. You can reset nowThe following is the sample terminal output when running example EEPROM_write on STM32F1 BLUEPILL_F103C8 with 128KB Flash
Start EEPROM_write on BLUEPILL_F103C8
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x801F800
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 128
[FLASH] USING_FLASH_SECTOR_NUMBER = 126
Done writing emulated EEPROM. Time spent (ms) = 29
Done writing emulated EEPROM. Time spent (ms) = 0
Done writing emulated EEPROM. Time spent (ms) = 0
Done writing emulated EEPROM. Time spent (ms) = 0
Done writing emulated EEPROM. Time spent (ms) = 0
Done writing emulated EEPROM. Time spent (ms) = 0The following is the sample terminal output when running example EmulatedEEPROM on STM32F1 BLUEPILL_F103C8 with 128KB Flash
Start EmulatedEEPROM on BLUEPILL_F103C8
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x801FC00
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 128
[FLASH] USING_FLASH_SECTOR_NUMBER = 127
EEPROM is empty, writing WRITTEN_SIGNATURE and some example data:
-> 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
Done writing to emulated EEPROM. You can reset now to testStart EmulatedEEPROM on BLUEPILL_F103C8
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x801FC00
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 128
[FLASH] USING_FLASH_SECTOR_NUMBER = 127
EEPROM has been written.Signature = 0xBEEFDEED
Here is the content of the next 16 bytes:
-> 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 11913
Clearing WRITTEN_SIGNATURE for next try
Done clearing signature in emulated EEPROM. You can reset nowThe following is the sample terminal output when running example FlashStoreAndRetrieve on STM32F1 GENERIC_F103RCTX with 2564KB Flash
| STLink | <---> | GENERIC_F103RCTX |
|---|---|---|
| SWCLK | <---> | SWCLK / PA14 |
| SWDIO | <---> | SWDIO / PA13 |
| GND | <---> | GND |
| 3.3v | <---> | 3.3V |
Start FlashStoreAndRetrieve on GENERIC_F103RCTX
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x803F800
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 256
[FLASH] USING_FLASH_SECTOR_NUMBER = 254
Number = 0xFFFFFFFF
Done writing to emulated EEPROM. You can reset nowStart FlashStoreAndRetrieve on GENERIC_F103RCTX
FlashStorage_STM32F1 v1.1.0
EEPROM length: 1019
Start Flash Address: 0x803F800
[FLASH] REGISTERED_NUMBER_FLASH_SECTORS (KB) = 256
[FLASH] USING_FLASH_SECTOR_NUMBER = 254
Number = 0x0
Done writing to emulated EEPROM. You can reset nowYes, 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 STM32F1/F3.
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.
Submit issues to: FlashStorage_STM32F1 issues
- Search for bug and improvement.
- Similar features for remaining Arduino STM32 boards
- Basic emulated-EEPROM for STM32F1/F3.
- Add support to new STM32 core v1.9.0
- Similar features for remaining Arduino boards such as SAMD21, SAMD51, etc.
- Add Table of Contents
- Add support to new STM32 core v2.2.0+
- Add
EEPROM.put()andEEPROM.get()functions to read/write the whole struct in emulated-EEPROM - Fix
multiple-definitionslinker error. - Clean-up by reducing the number of library files
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 LGPLv3
Copyright (c) 2021- Khoi Hoang