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.
Instantiating an object
You typically instantiate an object to interface to the flash chip as a global variable:
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).
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).
Winbond flash, connected to the secondary SPI, SPI1, with D5 as the CS (chip select or SS).
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.
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.
Connecting the hardware
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
The API is described in the SpiFlashRK.h file. But you will rarely need to use the low-level API directly.
Members
public voidbegin()
Call begin, probably from setup(). The initializes the SPI object.
public boolisValid()
Returns true if there is a flash chip present and it appears to be the correct manufacturer code.
public uint32_tjedecIdRead()
Gets the JEDEC ID for the flash device.
Returns
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 voidreadData(size_t addr,void * buf,size_t bufLen)
Reads data synchronously. Reads data correctly across page boundaries.
Parameters
addrThe address to read frombufThe buffer to store data inbufLenThe number of bytes to read
public voidwriteData(size_t addr,const void * buf,size_t bufLen)
Writes data synchronously. Can write data across page boundaries.
Parameters
addrThe address to read frombufThe buffer to store data inbufLenThe number of bytes to write
public voidsectorErase(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).
Parameters
addrAddress of the beginning of the sector. Must be at the start of a sector boundary.
public voidchipErase()
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_tgetPageSize() const
Gets the page size (default: 256)
public inlineSpiFlashBase&withPageSize(size_t value)
Sets the page size (default: 256)
public inline size_tgetSectorSize() const
Gets the sector size (default: 4096)
public inlineSpiFlashBase&withSectorSize(size_t value)
Sets the sector size (default: 4096)
