SpiFlashRK (community library)

Summary

Particle library for SPI NOR flash chips

Example Build Testing

Library Read Me

This content is provided by the library maintainer and has not been validated or approved.

SpiFlashRK

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.

Instantiating an object

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.

Connecting the hardware

For the primary SPI (SPI):

For the secondary SPI (SPI1):

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

Electron (image removed)

• Photon using Secondary SPI (SPI1)

Photon SPI1 (image removed)

• Photon using Primary SPI and a poorly hand-soldered 8-SOIC adapter

SOIC Adapter (image removed)

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 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.

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 void `readData(size_t addr,void * buf,size_t bufLen)`

Reads data synchronously. Reads data correctly across page boundaries.

Parameters

• 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.

Parameters

• 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).

Parameters

• 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)

Version History

0.0.9 (2020-10-30)

• 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().

0.0.7 (2020-10-29)

• SPI transaction implementation fixed to use actual beginTransaction()/endTransaction() for compatible with multiple SPI devices.

0.0.6 (2020-05-04)

• Fix compiler error for undefined conversion to SpiClass with 1.5.1-rc.1.

Browse Library Files