Skip to content

Arduino Library for SPI Flash memory chips
Compare
Choose a tag to compare
@Marzogh Marzogh released this 26 Mar 05:22
· 193 commits to stable since this release
v3.1.0
f3a76a0
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

SPIFlash Build Status DOI

GitHub release
GitHub commits
GitHub issues
GitHub pull requests
license

Please report any bugs in issues

Important note from developer

The term 'SPI Flash' is a fairly common way to refer to Flash memory chips that communicate over the SPI protocol and there are a number of libraries that are named SPIFlash. When I first started work on this library in 2014, it was mostly as an exercise to improve my embedded systems programming skills. When I asked for it to be included in the list of Arduino libraries, I did not really expect it to go very far or get very popular. But, before I knew it, I was releasing new versions every other month and I found the number of users got way bigger than I imagined it would. The amount of traffic the GitHub repository gets still surprises me.

A few months ago, @LowPowerLab raised an issue (#83) about the problems the name of this library was causing the users of his library - also called SPIFlash. The fact that this library is in the Arduino Library manager meant that his users were being asked to upgrade their version of SPIFlash when the libraries were actually different. I can understand how much of an annoyance this can be for a user.

@LowPowerLab's version of SPIFlash has been around for longer than this one and his library is a major part of his commercial line of development boards. Since I am a hobbyist developer (I'm a full-time geneticist & a part-time dabbler in ecology - if you're curious) and this library is not a commercial product with branding and trademarks to worry about, the least I can do is change the name of this library so it stops being an annoyance to @LowPowerLab's customers.

On a side note, if you did not know already, @LowPowerLab makes and sells a fantastic line of Arduino compatible boards - the Moteino series - and has developed a fantastic IoT protocol to use with them to add smarts to your home. In January this year, I finally got around to getting my hands on some of his boards and have been playing around with them. They are fantastic! I'd strongly recommend you check them out - if you haven't already done so.

I asked the Arduino developers if there was a way to migrate this library to a new name without breaking the upgrade path (Issue #6904) and was told that it was not possible. The only way is to pull my version of SPIFlash from the library manager and ask for a renamed version to be included in the library manager after.

So, this is what I have decided to do.:

  • This version - v3.1.0 - will be the last version to be released under the SPIFlash name.
  • Anyone downloading this version of the library will be able to read this notice in the ReadMe file.
  • Anyone using this version of the library will see a notice in their Serial output directing them to this notice in the ReadMe file. (this can be removed by commenting out the #define PRINTNAMECHANGEALERT in SPIFlash.h)
  • Version 3.2.0 will be released in a couple of months (in May most likely) under a new name - SPIMemory.
  • This version of SPIFlash will be removed from the library manager then and replaced with the new one.

The only change will have to be made in end-user code will be to change the #include SPIFlash.h to #include SPIMemory.h. After the name change, rest assured that older versions will remain accessible and the development history of the library will be preserved.

I apologise for any trouble this might cause you as the end user, but, given the facts, it is the only thing I can do to be fair to @LowPowerLab

Thanks again for using SPIFlash and I hope you will continue to find it useful in whatever new name it will take on.

Arduino library for Flash Memory Chips (SPI based only)

Download the latest stable release (v3.1.0) from here. Please report any bugs in issues.

This Arduino library is for use with flash memory chips that communicate using the SPI protocol. In its current form it supports identifying the flash chip and its various features; automatic address allocation and management; writing and reading a number of different types of data, ranging from 8-bit to 32-bit (signed and unsigned) values, floats, Strings, arrays of bytes/chars and structs to and from various locations; sector, block and chip erase; and powering down for low power operation.

  • For details of the Flash chips compatible with this library please refer to the list below.

Compatibility

Arduino IDEs supported (actually tested with)
  • IDE v1.5.x
  • IDE v1.6.0-v1.6.5
  • IDE v1.6.9-v1.6.12
  • IDE v1.8.1-v1.8.5
Boards
Completely supported
  • Arduino Uno
  • Arduino Leonardo
  • Arduino Due
  • Arduino Zero
  • Nucleo-F091RC
  • Adafruit Feather M0
  • Adafruit Feather M0 Express
  • ESP8266 Boards (On the Arduino IDE)
  • Simblee Boards (On the Arduino IDE)
  • Arduino Mega
  • Arduino Micro
  • Arduino Fio
In BETA
  • ESP32 Boards (Tested on the Adafruit ESP32 Feather) The library is known to work with the ESP32 core as of the current commit 8ba91b9 on 07.11.2017. ESP32 support will remain in beta till the ESP32 core can be installed via the Arduino boards manager.
    NOTE: ESP32 boards usually have an SPIFlash already attached to their SS pin, so the user has to declare the ChipSelect pin being used when the constructor is declared - for example
SPIFlash flash(33);
Flash memory compatibility
Completely supported (Actually tested with)
  • Winbond
    • W25Q16BV
    • W25Q64FV
    • W25Q80BV
    • W25Q256FV
  • Microchip
    • SST25VF064C
    • SST26VF064B
  • Cypress/Spansion
    • S25FL116K
    • S25FL127S
Should work with (Similar enough to the ones actually tested with)
  • Winbond (All SPI Flash chips)
  • Microchip (SST25 & SST26 series)
  • Cypress/Spansion (S25FL series)

Installation

Option 1
  • Open the Arduino IDE.
  • Go to Sketch > Include Library > Manage libraries.
  • Search for SPIFlash.
  • Install the latest version.
Option 2
  • Click on the 'Clone or download' button above the list of files on this page .
  • Select Download ZIP. A .zip file will download to your computer.
  • Unzip the archive and rename resulting folder to 'SPIFlash'
  • Move the folder to your libraries folder (~/sketches/libraries)

Change log

v3.1.0

  • Library name change notice inserted into flash.begin(). This notice can be dismissed by commenting out the instance of #define PRINTNAMECHANGEALERT in SPIFlash.h. Please refer to the Readme file for further details.
Bugs Squashed:

  • An error with how _addressCheck() works with data that spans the memory boundary - when rolling over from address '_chip.capacity' to address '0x00' - has been fixed. In previous versions this caused issues with writing complex data structures across the memory boundary and led to many _writeErrorCheck() failures. Fixes issue #112

  • An error with how _writeErrorCheck() worked has been resolved. Writing structs is now as stable as other functions are. Fixes #106

Enhancements & Optimizations:

  • A new function - 'flash.eraseSection(address, size)' - has been introduced in this version. When a user requires a large and variable (between writes) amount of data to be written to the flash memory on the fly and to have the correct amount of space erased to fit the data, this function will automatically calculate and erase the right amount of space to fit the data. Please note that if the the amount of data being written is consistently the same size, the pre-existing 'flash.eraseSector()', 'flash.eraseBlock32K()' and 'flash.eraseBlock64K()' functions will operate a lot faster.

  • Updated Diagnostics.ino to include eraseSection().

  • All I/O functions now check to see if the flash chip is powered down. If it is, they prevent the function from running and returns an error. A new error code 'CHIPISPOWEREDDOWN' will be returned upon calling flash.error().

New flash memory chips supported:
  • S25FL127S
Assets 2
Loading