Acknowledgment: This library is a minor update to the original SpiFlashRK library by @ricckas7
Particle library for SPI NOR flash memory chips
This library provides access to SPI NOR flash chips on the Particle platform. It's a low-level access that allows byte-level write-to-0 and sector-level erase-to-1.
You probably won't use this library directly; it's intended by be used as the hardware interface for a library that provides easier access, wear-leveling, flash translation, etc.. I recommend the SpiffsParticleRK library.
The full browsable API documentation can be found here.
You typically instantiate an object to interface to the flash chip as a global variable:
SpiFlashISSI spiFlash(SPI, A2);
Use an ISSI flash, such as a IS25LQ080B. In this case, connected to the primary SPI with A2 as the CS (chip select or SS).
SpiFlashWinbond spiFlash(SPI, A2);
Use a Winbond flash, such as a W25Q32. In this case, connected to the primary SPI with A2 as the CS (chip select or SS).
SpiFlashWinbond spiFlash(SPI1, D5);
Winbond flash, connected to the secondary SPI, SPI1, with D5 as the CS (chip select or SS).
SpiFlashMacronix spiFlash(SPI1, D5);
Macronix flash, such as the MX25L8006EM1I-12G. In this case connected to the secondary SPI, SPI1, with D5 as the CS (chip select or SS). This is the recommended for use on the E-Series module. Note that this is the 0.154", 3.90mm width 8-SOIC package.
SpiFlashP1 spiFlash;
This is the external flash on the P1 module. This extra flash chip is entirely available for your user; it is not used by the system firmware. You can only use this on the P1; it relies on system functions that are not available on other devices.
For the primary SPI (SPI):
Name | Flash Alt Name | Particle Pin | Example Color |
---|---|---|---|
SS | CS | A2 | White |
SCK | CLK | A3 | Orange |
MISO | DO | A4 | Blue |
MOSI | D1 | A5 | Green |
For the secondary SPI (SPI1):
Name | Flash Alt Name | Particle Pin | Example Color |
---|---|---|---|
SS | CS | D5 | White |
SCK | CLK | D4 | Orange |
MISO | DO | D3 | Blue |
MOSI | D1 | D2 | Green |
Note that the SS/CS line can be any available GPIO pin, not just the one specified in the table above.
- Electron using Primary SPI
- Photon using Secondary SPI (SPI1)
- Photon using Primary SPI and a poorly hand-soldered 8-SOIC adapter
The API is described in the SpiFlashRK.h file. But you will rarely need to use the low-level API directly.
public void
begin
()
Call begin, probably from setup(). The initializes the SPI object.
public bool
isValid
()
Returns true if there is a flash chip present and it appears to be the correct manufacturer code.
public uint32_t
jedecIdRead
()
Gets the JEDEC ID for the flash device.
A 32-bit value containing the manufacturer ID and the two device IDs:
- byte[0] manufacturer ID mask 0x00ff0000
- byte[1] device ID 1 mask 0x0000ff00
- byte[2] device ID 2 mask 0x000000ff
public void
readData
(size_t addr,void * buf,size_t bufLen)
Reads data synchronously. Reads data correctly across page boundaries.
-
addr
The address to read from -
buf
The buffer to store data in -
bufLen
The number of bytes to read
public void
writeData
(size_t addr,const void * buf,size_t bufLen)
Writes data synchronously. Can write data across page boundaries.
-
addr
The address to read from -
buf
The buffer to store data in -
bufLen
The number of bytes to write
public void
sectorErase
(size_t addr)
Erases a sector. Sectors are sectorSize bytes and the smallest unit that can be erased.
This call blocks for the duration of the erase, which take take some time (up to 500 milliseconds).
addr
Address of the beginning of the sector. Must be at the start of a sector boundary.
public void
chipErase
()
Erases the entire chip.
This call blocks for the duration of the erase, which take take some time (several secoonds). This function uses delay(1) so the cloud connection will be serviced in non-system-threaded mode.
public inline size_t
getPageSize
() const
Gets the page size (default: 256)
public inline
SpiFlashBase
&
withPageSize
(size_t value)
Sets the page size (default: 256)
public inline size_t
getSectorSize
() const
Gets the sector size (default: 4096)
public inline
SpiFlashBase
&
withSectorSize
(size_t value)
Sets the sector size (default: 4096)
- Increased Macronix chip erase timeout from 6000 to 240000 ms to deal with larger chips (like the MX25L25645G).
- Add support for 4-byte addressing mode for chips larger than 128 Mbit (16 Mbyte). See set4ByteAddressing().
- SPI transaction implementation fixed to use actual beginTransaction()/endTransaction() for compatible with multiple SPI devices.
- Fix compiler error for undefined conversion to SpiClass with 1.5.1-rc.1.