Home

Awesome

SPIMemory Build Status DOI

GitHub release GitHub commits GitHub issues GitHub pull requests license Join the chat at https://gitter.im/SPIMemory/community

Arduino library for Flash & FRAM Memory Chips (SPI based only)

<sup> Download the latest stable release from here. Please report any bugs in issues.</sup>

This Arduino library is for use with flash and FRAM memory chips that communicate using the SPI protocol. In its current form it supports identifying the flash/FRAM 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.

<hr>

IDE Compatibility (actually tested with)

<hr>

Platform compatibility

Micro controllersDev boards tested withNotes
ATmega328PArduino Uno, Arduino Micro, <br> Arduino Fio, Arduino Nano-
ATmega32u4Arduino Leonardo, Arduino Fio v3-
ATmega2560Arduino Mega-
ATSAMD21G18 (ARM Cortex M0+)Adafruit Feather M0, <br> Adafruit Feather M0 Express, <br> Adafruit ItsyBitsy M0 Express-
AT91SAM3X8E (ARM Cortex M3)Arduino Due-
nRF52832 (ARM Cortex M4F)Adafruit nRF52 Feather-
ATSAMD51J19 (ARM Cortex M4)Adafruit Metro M4-
STM32F091RCT6Nucleo-F091RC
STM32L0Nucleo-L031K6
ESP8266Adafruit ESP8266 Feather, <br> Sparkfun ESP8266 Thing-
ESP32Adafruit ESP32 Feather, <br> Sparkfun ESP32 ThingOnboard flash memory. Refer to footnote<sup>£</sup> below.
SimbleeSparkfun Simblee-

<sup>£ </sup><sub> ESP32 boards usually have an SPI Flash already attached to their default SS pin, so the user has to explicitly declare the ChipSelect pin being used with the constructor</sub>

<hr>

Flash memory compatibility - Actually tested with

ManufacturerFlash ICNotes
WinbondW25Q16BV <br> W25Q64FV <br> W25Q64JV <br> W25Q80BV <br> W25Q256FVShould work with the W25QXXXBV, W25QXXXFV & <br> W25QXXXJV families
MicrochipSST25VF064C <br> SST26VF016B <br> SST26VF032B <br> SST26VF064BShould work with the SST25 & SST26 families
Cypress/SpansionS25FL032P <br> S25FL116K <br> S25FL127SShould work with the S25FL family
ON SemiconductorLE25U40CMC
AMICA25L512A0
MicronM25P40
AdestoAT25SF041
MacronixMX25L4005 <br> MX25L4005
Giga devicesGD25Q16C(Used on the Adafruit ItsyBitsy M0 Express)
Should work with any flash memory that is compatible with the SFDP standard as defined in JESD216B
<hr>

FRAM memory compatibility - Actually tested with

ManufacturerFlash ICNotes
Cypress/SpansionFM25W256Should work with the FM25W family
<hr>

Installation

Option 1

Option 2

Usage

SPIFlash

Note on SFDP discovery

As of v3.2.1, SFDP parameter discovery is an user controlled option. To get the library to work with SFDP compatible flash memory chips that are not officially supported by the library, the user must uncomment '//#define USES_SFDP' in 'SPIMemory.h'.

Notes on Address overflow and Error checking

SPIFram <sup>^</sup>

<sup>^</sup> <sub> Currently in BETA. The methods in SPIFram are not final and subject to change over the next few revisions.</sub>

The library enables the following functions:

<hr>

Non-Read/Write functions

<hr>
begin(_chipsize)
setClock(clockSpeed)
error(_verbosity)
getManID()
getJEDECID()
getUniqueID()
getAddress(sizeOfData)
sizeofStr()
getCapacity()
getMaxPage()
functionRunTime()
<hr>
Read commands
<hr> <sub> All read commands take a last boolean argument 'fastRead'. This argument defaults to FALSE, but when set to TRUE carries out the Fast Read instruction so data can be read at up to the memory's maximum frequency. </sub> <sub> All read commands only take a 32-bit address variable instead of the optional 16-bit page number & 8-bit offset variables in previous versions of the library (< v3.0.0) </sub>
readAnything(address, value)
readByte(address)
readChar(address)
readWord(address)
readShort(address)
readULong(address)
readLong(address)
readFloat(address)
readStr(address, outputStr)
readAnything(address, value)
<hr>
Write commands
<hr> <sub> All write commands take a boolean last argument 'errorCheck'. This argument defaults to TRUE, but when set to FALSE will more than double the writing speed. This however comes at the cost of checking for writing errors. Use with care. </sub>

<sub> All write commands only take a 32-bit address variable instead of the optional 16-bit page number & 8-bit offset variables in previous versions of the library (< v3.0.0) </sub>

writeByte(address, data)
writeChar(address, data)
writeWord(address, data)
writeShort(address, data)
writeULong(address, data)
writeLong(address, data)
writeFloat(address, data)
writeStr(address, data)
writeAnything(address, value)
<hr>
Continuous read/write commands
<sub> All write commands take a boolean last argument 'errorCheck'. This argument defaults to TRUE, but when set to FALSE will more than double the writing speed. This however comes at the cost of checking for writing errors. Use with care. </sub> <hr>
readByteArray(address, *data_buffer, bufferSize)
writeByteArray(address, *data_buffer, bufferSize)
readCharArray(address, *data_buffer, bufferSize)
writeCharArray(address, *data_buffer, bufferSize)
<hr>
Erase commands
<sub> All erase commands only take a 32-bit address variable instead of the optional 16-bit page number & 8-bit offset variables in previous versions of the library (< v3.0.0) </sub> <hr>
eraseSector(address)
eraseBlock32K(address)
eraseBlock64K(address)
eraseChip()
eraseSection(address, sizeOfData)
<hr>
Suspend/Resume commands
<hr>
suspendProg()
resumeProg()
<hr>
Power operation commands
<hr>
powerDown()
powerUp()
<hr>
Error codes explained

Note: If you are unable to fix the error/s, please raise an issue here with the details of your flash chip and what you were doing when this error occurred. Please follow the issue template that show up at the link

Error codeExplanation
0x00Function executed successfully
0x01*constructor_of_choice*.begin() was not called in void setup()
0x02Unable to identify chip. <br> Is this chip officially supported?
0x03Unable to identify capacity. <br> Is this chip officially supported? <br> If not, please define a CAPACITY constant and include it in flash.begin(CAPACITY).
0x04Chip is busy. Make sure all pins have been connected properly.
0x05Page overflow has been disabled and the address called exceeds the memory
0x06Unable to Enable Writing to chip. <br> Please make sure the HOLD & WRITEPROTECT pins are pulled up to VCC.
0x07This sector already contains data. <br> Please make sure the sectors being written to are erased.
0x08You are running low on RAM. <br> Please optimise your code for better RAM usage
0x09Unable to suspend/resume operation. <br> Please raise an issue.
0x0AWrite Function has failed errorcheck. <br> Please raise an issue.
0x0BCheck your wiring. Flash chip is non-responsive.
0x0CThis function is not supported by the memory hardware.
0x0DUnable to enable 4-byte addressing. <br> Please raise an issue.
0x0EUnable to disable 4-byte addressing. <br> Please raise an issue.
0x0FThe chip is currently powered down.
0x10The Flash chip does not support SFDP.
0x11Unable to read Erase Parameters from chip. <br> Reverting to library defaults.
0x12Unable to read erase times from flash memory. <br> Reverting to library defaults.
0x13Unable to read program times from flash memory. <br> Reverting to library defaults.
0x14No Chip Select pin defined in the custom SPI Array. <br> Refer to section about Constructor for information on how to use custom SPI pins.
0xFEUnknown error. <br> Please raise an issue.
<hr>