Introduction: Using ESP8266 SPIFFS
Did you know each ESP8266 allows you to partition the system flash such that you can use it to store both code and support a file system?
This filing system can be used to store infrequently changing data such as; web pages, configurations, sensor calibration data etc.
This short Instructable details how to use SPIFFs, configure your Arduino IDE to upload files direct to your ESP8266 and figure out how much flash your device has.
What parts do I need?
System entry requirements;
- Your Arduino IDE has been set up to programme the ESP8266 (Setting Up the Arduino IDE to Program the ESP8266-01)
- An ESP8266-01 programming device (Practical Circuit Construction With Strip Board, Step 9 onwards)
- An ESP8266-01
What software do I need?
- Arduino IDE 1.6.9
What skills do I need?
To set the system up, use the source code (provided) you will need the following;
- Knowledge of Arduino and it's IDE,
- Some knowledge of the ESP8266,
- Some Patience.
- So what is SPIFFS,
- Installing the Arduino ESP8266 filesystem uploader,
- How can I tell how much flash memory my ESP8266 has?
- How to upload files to your ESP8266 SPIFFS,
- How to test your SPIFFS and see it in action,
- References used.
Note 1 : Actually the ESP8266 flash also supports OTA updates, however the scope of this Instructable is limited to that of the SPIFFS functionality.
Note 2 : Whilst the examples given uses the ESP8266-01 it works equally well with the ESP8266-07, ESP8266-12, ESP8266-12E, ESP8266-13, as implied by the Instructable image.
Step 1: So What Is SPIFFS
Which stands for SPI Flash Filing System was designed for SPI flash devices on constrained embedded microprocessor systems with little RAM.
What SPIFFS does:
- Specifically designed for low ram usage
- Uses statically sized ram buffers, independent of number of files
- Posix-like api: open, close, read, write, seek, stat, etc
- Implements static wear leveling to prolong the life of system flash
What SPIFFS does not do:
- SPIFFS does not support directories and uses a flat structure. Creating a file with path tmp/myfile.txt will create a file called tmp/myfile.txt instead of a myfile.txt under directory tmp.
- It is not a real time stack. One write operation might take much longer than another. So is best used at start up, shut down or when time critical activities are not scheduled.
- Presently, it does not detect or handle bad blocks.
Step 2: Installing the Arduino ESP8266 Filesystem Uploader
To install the Arduino ESP8266 filesystem uploader carry out the following;
- Go here and download a copy of 'ESP8266FS-0.2.0.zip,
- Unzip the file,
- Drop the esp8266fs.jar file into Arduino tool directory (the path will look something like [home_dir]\Arduino\tools\ESP8266FS\tool\esp8266fs.jar),
- In my case (as in pic 1 above);
- C:\Users\Win 7\Documents\Arduino\tools\ESP8266FS\tool
- I needed to create;
- C:\Users\Win 7\Documents\Arduino\
- Restart Arduino IDE.
If you have got it correct you will see a new menu item 'ESP8266 Sketch Data Upload' under under 'Tools' as in pic 2 above.
Step 3: How Can I Tell How Much Flash Memory My ESP8266 Has?
Given most of these ESP8266 devices are sourced from Chinese suppliers who are less than forthcoming in releasing clear and concise product data, one way to figure out how big your flash is to read the chip details (assuming they haven't been scrubbed) and carrying out an internet search. I did this for two of my ESP8266-01s;
- BergMicro 25Q80ASSIG 1602 : 8M/bit
- Winbond 25Q80DVSIG 1626 : 8M/bit
Here the former and latter are 1M byte. The problem with this method of identification is it simply won't work with the ESP8266 variants which house all the active components under an RF shielding can such as the ESP8266-07 and ESP8266-12E etc.
Consequently, I found the most reliable and quickest method was to programme the device with the CheckFlashConfig.ino' sketch and review the output from the serial monitor as in Pic 1 above.
You can download the full Arduino ESP8266 Core from here;
and the CheckFlashConfig Source from here;
Alternatively, copy given below.
Step 4: How to Upload Files to Your ESP8266 SPIFFS
Carryout the following to upload your files to the ESP8266 SPIFFS;
- Ensure you have a sub-directory within your sketch directory named 'data',
- Place the files you wish to upload into the 'data' directory,
- From 'Tools' menu, select the correct ESP8266 device and choose the 'Flash Size' with the SPIFFS you require ie. '1M (256K SPIFFS)'. See pics 1 and 2 above,
- Ensure the serial monitor dialogue box is closed,
- Prepare the ESP8266 device for upload;
- Hold down 'Flash',
- Pulse 'Reset'
- Release 'Flash',
Note 1 : If an error message such as the one in Pic 4 occurs indicating 'SPIFFS Upload failed!'. Try unplugging/re-plugging your device's USB to serial adapter (FTDI) and repeating steps 1...7.
Note 2 : SPIFFS content can be uploaded independently of programme code.
Note 3 : If 'Flash Size' is changed, then programme code and SPIFFS will need to be reloaded.
Step 5: How to Test Your SPIFFS and See It in Action
To see a working example of SPIFFs carryout the following;
- Download the 'SPIFFsUsage.ino' sketch below,
- Unzip it and drop it into your Arduino sketches directory
- Mine is here; C:\Users\Win 7\Documents\Arduino\My Progs
- You will note there is a sub-directory named 'data' within which is a text filenamed 'testfile.txt'
- Select the flash geometry of your target system and the code space/SPIFFs size split you require (Tools->Flash Size),
- Ensure the serial monitor dialogue box is closed,
- Upload the text file to your ESP8266 device as described above in Step 4,
- Open the serial monitor dialogue box and set the baud rate to 115200,
- Upload 'SPIFFsUsage.ino' to ESP8266 device.
Once you have completed the upload, the code will execute and your serial monitor dialogue will display text as in pic 1 above.
It serves to show the contents of 'testfile.txt';
- Has been successfully uploaded,
- Located in the file system,
- Opened for read,
- Read until the end of file has been reached,
- Opened for append,
- A single line written to the file,
- The file has been re-read, displaying the recently appended line to the end of the file.
Note : If the ESP8266 is powered down or reset, upon each successive execution a new line is automatically appended and displayed.
Step 6: Conclusion
Use of SPIFFS is a great way to store infrequently changing data though it should not be considered for applications requiring many write accesses as it will eventually cause flash to fail. A typical worked example of how long flash is likely to last is given here.
Using the on-board filing system could save on I/O count where SPI SD card functionality is being considered for an I/O constrained device such as the ESP8266-01 where it is a very simple way to add secondary store without the need for 4 /I/O lines.
Step 7: References Used
SPIFFS (SPI Flash File System)
Performance and Optimizing
SPIFFS GIT HUB Home page
Arduino ESP8266 filesystem uploader
Arduino plugin which packs sketch data folder into SPIFFS filesystem image, and uploads the image to ESP8266 flash memory. Tested with the following Arduino IDE versions: 1.6.5-r2, 1.6.6
but works with Arduino IDE 1.6.12
Arduino Forum SPIFFs example
Arduino GIT HUB Core
Worked example of flash wear
More detail on SPIFFS
1 Person Made This Project!
- handy.andy.buckley made it!