{"id":27122682,"url":"https://github.com/thebigpotatoe/effortless-spiffs","last_synced_at":"2025-10-15T12:10:17.284Z","repository":{"id":40244835,"uuid":"230705391","full_name":"thebigpotatoe/Effortless-SPIFFS","owner":"thebigpotatoe","description":"A class designed to make reading and storing data on the ESP8266 and ESP32 effortless","archived":false,"fork":false,"pushed_at":"2021-03-19T14:49:17.000Z","size":57,"stargazers_count":38,"open_issues_count":7,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-05T05:01:51.295Z","etag":null,"topics":["arduino","arduino-library","easy-to-use","effortless-spiffs","esp32","esp8266","platformio","spiffs"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thebigpotatoe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-29T05:05:19.000Z","updated_at":"2024-12-30T19:28:12.000Z","dependencies_parsed_at":"2022-09-06T00:40:13.790Z","dependency_job_id":null,"html_url":"https://github.com/thebigpotatoe/Effortless-SPIFFS","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thebigpotatoe%2FEffortless-SPIFFS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thebigpotatoe%2FEffortless-SPIFFS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thebigpotatoe%2FEffortless-SPIFFS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thebigpotatoe%2FEffortless-SPIFFS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thebigpotatoe","download_url":"https://codeload.github.com/thebigpotatoe/Effortless-SPIFFS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648878,"owners_count":20972944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library","easy-to-use","effortless-spiffs","esp32","esp8266","platformio","spiffs"],"created_at":"2025-04-07T11:50:09.533Z","updated_at":"2025-10-15T12:10:12.245Z","avatar_url":"https://github.com/thebigpotatoe.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Effortless-SPIFFS\n\n[![GitHub release](https://img.shields.io/github/release/thebigpotatoe/Effortless-SPIFFS.svg)](https://github.com/thebigpotatoe/Effortless-SPIFFS/releases)\n[![arduino-library-badge](https://www.ardu-badge.com/badge/Effortless-SPIFFS.svg?)](https://www.ardu-badge.com/Effortless-SPIFFS)\n[![PlatformIO Build Status](https://github.com/thebigpotatoe/Effortless-SPIFFS/workflows/PlatformIO%20CI/badge.svg)](https://github.com/thebigpotatoe/Effortless-SPIFFS/actions?query=workflow%3A%22PlatformIO+CI%22)\n[![Arduino Build Status](https://github.com/thebigpotatoe/Effortless-SPIFFS/workflows/Arduino/badge.svg)](https://github.com/thebigpotatoe/Effortless-SPIFFS/actions?query=workflow%3A%22PlatformIO+CI%22)\n[![GitHub License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/thebigpotatoe/Effortless-SPIFFS/blob/master/LICENSE)\n\nA class designed to make reading and storing data on the __ESP8266__ and __ESP32__ effortless. This library aims to make access to SPIFFS much easier to allow users to get on with writing the important stuff rather than debugging why storage isn't working.\n\n## :exclamation: IMPORTANT :exclamation:\n\nWhen using in a project or exploring the example make sure to set your SPIFFS size correctly for your project/board. While the library will not fail when trying to open files from a non existent SPIFFS partition, failure to set the size will mean the library and hence project will not work as intended.\n\nThe library has a very handy method `checkFlashConfig()` to check this for you. Using this method at the start of your sketch with a meaningful `Serial.print()` statement will save you a lot of time wondering why things are not working in production.\n\nFor more info on setting the SPIFFS size see:\n\n- [ESP8266 SPIFFS in Arduino](https://cdn.instructables.com/ORIG/FST/OP12/IZT6TEBJ/FSTOP12IZT6TEBJ.png?auto=webp\u0026frame=1\u0026width=1024\u0026fit=bounds\u0026md=f16daccb8697a6bd8728838feb18d9de)\n- [ESP8266 SPIFFS in PlatformIO](https://docs.platformio.org/en/latest/platforms/espressif8266.html#flash-size)\n- [ESP32 SPIFFS in Arduino](https://user-images.githubusercontent.com/26627719/44614648-d76f9980-a852-11e8-8383-d6ae74a2ff5b.png)\n- [ESP32 SPIFFS in PlatformIO](https://docs.platformio.org/en/latest/platforms/espressif32.html#partition-tables)\n\n## Quick Start\n\nThe example below is all you need to get going with opening and saving data from a variable. Be sure to also check out the example `Effortless_Spiffs_Basic.ino` for detailed understanding of how to use this library with all data types.\n\n``` c++\n#include \u003cEffortless_SPIFFS.h\u003e\n\neSPIFFS fileSystem;\nfloat myVariable;\n\nvoid setup(){\n    Serial.begin(115200);\n    Serial.println();\n}\n\nvoid loop() {\n    // Open the storage file and save data to myVariable\n    if (fileSystem.openFromFile(\"/Float.txt\", myVariable)) {\n        Serial.print(\"Successfully read file and parsed data: \");\n        Serial.println(myVariable, 6);\n    }\n\n    // Set myVariable to a random value\n    myVariable = (float)random(1, 1000) / (float)random(1000, 65563);\n    Serial.print(\"myVariable is now: \");\n    Serial.println(myVariable, 6);\n\n    // Write the data back to the SPIFFS\n    if (fileSystem.saveToFile(\"/Float.txt\", myVariable)) {\n        Serial.println(\"Successfully wrote data to file\");\n    }\n\n    // Delay between loops\n    delay(10000);\n}\n```\n\n## Usage\n\n### As an Object\n\nThis library can be used directly by creating an object using the eSIFFS class. When declaring the class there is an optional input for a reference to a Print object to help with debugging.\n\n``` c++\n// Definition\neSPIFFS();\neSPIFFS(\u0026Print);\n\n// Usage\neSPIFFS fileSystem;\neSPIFFS fileSystem(\u0026Print);\n```\n\n### Extending a Class\n\nEach method in the class definition of eSPIFFS is defined as virtual so that it can be overriden by a child class if desired. The definitions of these are described below.\n\n``` c++\nvirtual inline bool checkFlashConfig()\nvirtual inline bool getFileSize(const char* _filename)\nvirtual bool openFile(const char* _filename, char* _output, size_t _len = 0)\nvirtual bool saveFile(const char* _filename, const char* _input)\n```\n\nThere are two functions however which are not virtual; `openFromFile` and `saveToFile`. These are instead template functions which rely on an implementation of `std::enable_if` and `std::is_same`. These functionality provided by these can be extended to new types by using the same format template function as the eSPIFFS class.\n\n``` c++\ntemplate \u003cclass T\u003e\ntypename Effortless_SPIFFS_Internal::enable_if\u003cEffortless_SPIFFS_Internal::is_same\u003cT, bool\u003e::value, __NewTypeHere__\u003e::type\neSPIFFS::openFromFile(const char* _filename, NewType\u0026 _output)\n```\n\n## Helper Methods\n\n### Check that SPIFFS size is correct\n\neSPIFFS checks if the SPIFFS system is correct in the Arduino IDE using `checkFlashConfig` each time `saveFile` and `openFile` are called. This is to ensure that SPIFFS can be read and written to before doing any useful work. This method uses Serial debug outputs to tell the user how to set up spiffs if passed a serial reference. This function is public and inline to optimise for frequent calls.\n\n``` c++\n// Definition\ninline bool checkFlashConfig()\n\n// Usage\neSPIFFS fileSystem();\nbool spiffsSetCorrectly = fileSystem.checkFlashConfig();\n```\n\n#### Getting the file size\n\nThe eSPIFFS class will get the file size of any file given a path. Th method `getFileSize` is used internally and is extended to the public API to make finding the length of a file easy. If a file is not found or not able to be read, the value will be 0.\n\n``` c++\n// Definition\ninline size_t getFileSize(const char* fileName)\n\n// Usage\neSPIFFS fileSystem();\nsize_t fileSize = fileSystem.getFileSize(\"/Example.file\");\n```\n\n## Saving data to files\n\nThe eSPIFFS API allows users to store data to the SPIFFS two possible methods; by passing a const char* or a variable reference of your choice.\n\n### Saving data to file from a const char* C String\n\nThe first method `saveFile` is used to store data into SPIFFS is via a const char* C string. The function takes a filename and a const char* pointer to a string which is then printed to SPIFFS. The file will return true if the data was written and false if there was an issue.\n\n``` c++\n// Definition\nbool saveFile(const char* _filename, const char* _input)\n\n// Usage\neSPIFFS fileSystem();\nconst char* myString = \"Hello World\";\nfileSystem.saveFile(\"Example.file\", myString);\n```\n\n#### Saving data to file using a variable\n\nThe second method `saveToFile` is used to store data is to use a reference to a variable of the users choice. This function wraps `saveFile` by parsing the users variable to a C String and saving that. The arguments it takes are filename and a reference value to any standard type. It also supports String, std::string, and ArduinoJson DynamicJsonDocuments. This method will also return true on a successful write to SPIFFS and false if there is an error.\n\n``` c++\n// Definition\nbool saveToFile(const char*, \u0026bool);\nbool saveToFile(const char*, \u0026float);\nbool saveToFile(const char*, \u0026double);\nbool saveToFile(const char*, \u0026signed char);\nbool saveToFile(const char*, \u0026unsigned char);\nbool saveToFile(const char*, \u0026signed int);\nbool saveToFile(const char*, \u0026unsigned int);\nbool saveToFile(const char*, \u0026signed short);\nbool saveToFile(const char*, \u0026unsigned short);\nbool saveToFile(const char*, \u0026signed long);\nbool saveToFile(const char*, \u0026unsigned long);\nbool saveToFile(const char*, \u0026char*);\nbool saveToFile(const char*, \u0026const char*);\nbool saveToFile(const char*, \u0026String);\nbool saveToFile(const char*, \u0026std::string);\nbool saveToFile(const char*, \u0026ArduinoJson::DynamicJsonDocument);\n\n// Usage\neSPIFFS fileSystem();\nfloat myVariable = 324.890;\nfileSystem.saveToFile(\"Example.file\", myVariable);\n```\n\n## Opening data from files\n\nThe eSPIFFS API extends access to the SPIFFS of your ESP8266 in two ways; by modifying a C String or by storing a parsed value to a passed variable reference.\n\n### Opening files as a string\n\nThe first method `openFile` accesses data stored in the SPIFFS is through a modified const char* value. This method takes a filename, a char pointer to an output C String buffer, and the size of the number of bytes to read from the file. The function will return true if it stored the data in the char pointer and false if it failed for any reason.\n\n\u003e It should be noted that if the number of bytes asked to read will be automatically limited to the size of the file. Using the getFileSize() method before this is useful to set a char array of the correct size.\n\n``` c++\n// Definition\nbool openFile(const char* filename, char* outputString, size_t numBytesToRead = 0);\n\n// Usage\neSPIFFS fileSystem();\nsize_t fileSize = getFileSize(\"/Example.file\");\nchar* fileContents[fileSize + 1];  // Dont forget about the null terminator for C Strings\nfileSystem.openFile(\"/Example.file\", fileContents, fileSize);\nSerial.print(\"Data stored in fileContents is: \")\nSerial.println(fileContents);\n```\n\n### Opening Files with a Variable Reference\n\nThe second method `openFromFile` wraps `openFile` to return a parsed value to a variable of your choice. It takes a file name as well as a reference to your variable where it will store parsed data. The method returns true if a value was parsed and stored correctly and false if it failed at any point. If the function failed it will not modify the original data in the variable reference. This method supports all basic types plus String, std::string, and ArduinoJson DynamicJsonDocuments\n\n``` c++\n// Definitions\nbool openFromFile(const char*, \u0026bool);\nbool openFromFile(const char*, \u0026float);\nbool openFromFile(const char*, \u0026double);\nbool openFromFile(const char*, \u0026signed char);\nbool openFromFile(const char*, \u0026unsigned char);\nbool openFromFile(const char*, \u0026signed int);\nbool openFromFile(const char*, \u0026unsigned int);\nbool openFromFile(const char*, \u0026signed short);\nbool openFromFile(const char*, \u0026unsigned short);\nbool openFromFile(const char*, \u0026signed long);\nbool openFromFile(const char*, \u0026unsigned long);\nbool openFromFile(const char*, \u0026char*);\nbool openFromFile(const char*, \u0026const char*);\nbool openFromFile(const char*, \u0026String);\nbool openFromFile(const char*, \u0026std::string);\nbool openFromFile(const char*, \u0026ArduinoJson::DynamicJsonDocument);\n\n// Usage\neSPIFFS fileSystem();\nfloat myVariable;\nfileSystem.openFromFile(\"/Example.file\", myVariable);\nSerial.print(\"Data stored in myVariable is: \")\nSerial.println(myVariable, 6);\n```\n\n## Contributing and Feedback\n\nThis is my first Arduino library and while I have tried to optimise it there is most likely room for improvement. Any feedback in the form of issues or pull request are welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebigpotatoe%2Feffortless-spiffs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthebigpotatoe%2Feffortless-spiffs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebigpotatoe%2Feffortless-spiffs/lists"}