Skip to content

Commit 013dc8b

Browse files
MarzoghMarzogh
committed
Replace docs placeholders with full beginner-focused content
1 parent ee940c3 commit 013dc8b

6 files changed

Lines changed: 269 additions & 88 deletions

File tree

‎docs/api/errors.md‎

Lines changed: 42 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,49 @@
11
# Errors and Diagnostics
22

3-
## Retrieval
3+
## How to read errors
44

5-
- `error()` returns the last error code.
6-
- `error(VERBOSE)` prints diagnostic context.
5+
- `error()` returns the last error code as a byte.
6+
- `error(VERBOSE)` prints a message to serial and still returns the code.
77

8-
## Error classes
8+
## Error Code Table
99

10-
- initialization/state errors
11-
- address/boundary errors
12-
- write-enable and busy-state errors
13-
- verification failures
14-
- unsupported hardware/function errors
10+
These values come from `src/diagnostics.h`.
1511

16-
## Operational guidance
12+
| Code | Name | Meaning |
13+
| --- | --- | --- |
14+
| `0x00` | `SUCCESS` | Function completed successfully |
15+
| `0x01` | `CALLBEGIN` | `begin()` was not called |
16+
| `0x02` | `UNKNOWNCHIP` | Chip ID not recognized |
17+
| `0x03` | `UNKNOWNCAP` | Capacity not identified |
18+
| `0x04` | `CHIPBUSY` | Chip remained busy past timeout |
19+
| `0x05` | `OUTOFBOUNDS` | Address exceeded memory limits with overflow disabled |
20+
| `0x06` | `CANTENWRITE` | Write-enable latch could not be set |
21+
| `0x07` | `PREVWRITTEN` | Target area already contains data |
22+
| `0x08` | `LOWRAM` | Low RAM condition detected |
23+
| `0x09` | `SYSSUSPEND` | Suspend/resume state error |
24+
| `0x0A` | `ERRORCHKFAIL` | Post-write verification failed |
25+
| `0x0B` | `NORESPONSE` | No chip response over SPI |
26+
| `0x0C` | `UNSUPPORTEDFUNC` | Function unsupported by chip |
27+
| `0x0D` | `UNABLETO4BYTE` | Could not enable 4-byte addressing |
28+
| `0x0E` | `UNABLETO3BYTE` | Could not return to 3-byte addressing |
29+
| `0x0F` | `CHIPISPOWEREDDOWN` | Operation attempted while powered down |
30+
| `0x10` | `NOSFDP` | SFDP not available |
31+
| `0x11` | `NOSFDPERASEPARAM` | SFDP erase parameters unavailable |
32+
| `0x12` | `NOSFDPERASETIME` | SFDP erase timing unavailable |
33+
| `0x13` | `NOSFDPPROGRAMTIMEPARAM` | SFDP program timing unavailable |
34+
| `0x14` | `NOCHIPSELECTDECLARED` | Custom SPI constructor missing chip select |
35+
| `0xFE` | `UNKNOWNERROR` | Unknown error state |
1736

18-
Capture and map key error codes into firmware telemetry for faster field debugging.
37+
## Fast Debug Sequence (Beginners)
38+
39+
1. Call `begin()` in `setup()` and print `getJEDECID()`.
40+
2. If zero or invalid, check wiring and chip-select pin.
41+
3. Call `error(VERBOSE)` after each failed operation.
42+
4. For flash writes, erase region before writing.
43+
5. Keep `errorCheck=true` until your setup is stable.
44+
45+
## Best Practices
46+
47+
- Keep a small serial log of operation + returned error code.
48+
- For production firmware, map key error codes into telemetry counters.
49+
- Use `FlashDiagnostics` example sketch for initial bring-up.

‎docs/api/index.md‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,40 @@
11
# API Reference
22

3-
This section is the authoritative API surface summary.
3+
This section provides two ways to find what you need:
44

5-
Each function entry should describe:
5+
- **By task** (beginner-friendly)
6+
- **By full function list** (complete call-by-call reference)
67

7-
- purpose
8-
- preconditions
9-
- return semantics
10-
- side effects
11-
- failure behavior
8+
## Start by Task
129

13-
## Fast Navigation
10+
| Task | Recommended calls |
11+
| --- | --- |
12+
| Initialize memory chip | `begin`, `setClock` |
13+
| Check chip identity | `getJEDECID`, `getManID`, `getUniqueID` |
14+
| Find free write location | `getAddress`, `sizeofStr` |
15+
| Write/read one primitive value | `writeByte`/`readByte`, `writeULong`/`readULong`, etc. |
16+
| Write/read strings | `writeStr`, `readStr` |
17+
| Write/read structs | `writeAnything`, `readAnything` |
18+
| Write/read buffers | `writeByteArray`/`readByteArray`, `writeCharArray`/`readCharArray` |
19+
| Erase flash data | `eraseSector`, `eraseBlock32K`, `eraseBlock64K`, `eraseSection`, `eraseChip` |
20+
| Power control | `powerDown`, `powerUp` |
21+
| Suspend/resume flash operation | `suspendProg`, `resumeProg` |
22+
| Diagnose failures | `error`, `error(VERBOSE)`, `functionRunTime` |
1423

15-
- [SPIFlash function-by-function reference](spiflash-reference.md)
16-
- [SPIFram function-by-function reference](spifram-reference.md)
17-
- [Error handling and diagnostics](errors.md)
24+
## Full References
25+
26+
- [SPIFlash Function Reference](spiflash-reference.md)
27+
- [SPIFram Function Reference](spifram-reference.md)
28+
- [Errors and Diagnostics](errors.md)
29+
30+
## Function Discovery Index
31+
32+
If you're searching by function name, start here:
33+
34+
### Shared SPIFlash/SPIFram families
35+
36+
`begin`, `setClock`, `libver`, `error`, `getManID`, `getJEDECID`, `getUniqueID`, `getAddress`, `sizeofStr`, `getCapacity`, `functionRunTime`, `writeByte`, `readByte`, `writeChar`, `readChar`, `writeShort`, `readShort`, `writeWord`, `readWord`, `writeLong`, `readLong`, `writeULong`, `readULong`, `writeFloat`, `readFloat`, `writeStr`, `readStr`, `writeByteArray`, `readByteArray`, `writeCharArray`, `readCharArray`, `writeAnything`, `readAnything`, `eraseSection`, `eraseChip`, `powerDown`, `powerUp`
37+
38+
### SPIFlash-only families
39+
40+
`sfdpPresent`, `getMaxPage`, `eraseSector`, `eraseBlock32K`, `eraseBlock64K`, `suspendProg`, `resumeProg`

‎docs/guide/common-tasks.md‎

Lines changed: 45 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -2,32 +2,53 @@
22

33
## Save one number and read it back
44

5-
Use `writeULong` and `readULong`.
6-
7-
## Save a text string
8-
9-
Use `writeStr` and `readStr`.
10-
11-
## Save a custom struct
12-
13-
Use `writeAnything` and `readAnything`.
14-
15-
## Find where to write next
16-
17-
Use `getAddress(size)` before writing.
18-
19-
## Erase enough flash for a variable-sized record
20-
21-
Use `eraseSection(address, size)`.
5+
```cpp
6+
uint32_t addr = 0;
7+
flash.eraseSector(addr);
8+
flash.writeULong(addr, 42);
9+
uint32_t out = flash.readULong(addr);
10+
```
11+
12+
## Save and load a string
13+
14+
```cpp
15+
String in = "hello";
16+
String out;
17+
uint32_t addr = flash.getAddress(flash.sizeofStr(in));
18+
flash.eraseSection(addr, flash.sizeofStr(in));
19+
flash.writeStr(addr, in);
20+
flash.readStr(addr, out);
21+
```
22+
23+
## Save and load a struct
24+
25+
```cpp
26+
struct Config { uint16_t a; float b; } cfgIn{7, 3.14f}, cfgOut;
27+
uint32_t addr = flash.getAddress(sizeof(Config));
28+
flash.eraseSection(addr, sizeof(Config));
29+
flash.writeAnything(addr, cfgIn);
30+
flash.readAnything(addr, cfgOut);
31+
```
32+
33+
## Write/read byte buffers
34+
35+
```cpp
36+
uint8_t tx[8] = {1,2,3,4,5,6,7,8};
37+
uint8_t rx[8] = {0};
38+
uint32_t addr = flash.getAddress(sizeof(tx));
39+
flash.eraseSection(addr, sizeof(tx));
40+
flash.writeByteArray(addr, tx, sizeof(tx));
41+
flash.readByteArray(addr, rx, sizeof(rx));
42+
```
2243

2344
## Chip not responding
2445

25-
1. Confirm wiring and CS pin.
26-
2. Call `begin()` in `setup()`.
27-
3. Read `error(VERBOSE)`.
28-
4. Enable `RUNDIAGNOSTIC` during debug.
46+
1. Verify wiring and CS pin.
47+
2. Ensure `begin()` is called in `setup()`.
48+
3. Print `getJEDECID()` and `error(VERBOSE)`.
49+
4. Run `FlashDiagnostics` example sketch.
2950

30-
## Speed up reads/writes
51+
## Improve speed safely
3152

32-
- Reads: use `fastRead=true` where needed.
33-
- Writes: disable error check only after validation.
53+
- Read path: use `fastRead=true` selectively.
54+
- Write path: only disable error checks after full validation.

‎docs/guide/compatibility.md‎

Lines changed: 60 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,67 @@
11
# Compatibility Matrix
22

3-
Use this page as the canonical compatibility source for current releases.
3+
This page lists the compatibility data currently documented in this repository (`README.md`, `library.properties`, and headers).
44

5-
## Recommended table fields
5+
## Arduino Architectures (from `library.properties`)
66

7-
- Board / MCU
8-
- Core package version
9-
- SPI mode used (default or alternate)
10-
- Flash chips validated
11-
- FRAM chips validated
12-
- Known caveats
7+
- `avr`
8+
- `sam`
9+
- `samd`
10+
- `esp8266`
11+
- `esp32`
12+
- `Simblee`
13+
- `stm32`
14+
- `nrf52`
1315

14-
## Maintenance rule
16+
## Boards and MCUs (documented as tested)
1517

16-
Any new support claim should include:
18+
| MCU / family | Example boards tested | Notes |
19+
| --- | --- | --- |
20+
| ATmega328P | Uno, Micro, Fio, Nano | Uses default SPI constructor by default |
21+
| ATmega32u4 | Leonardo, Fio v3 | Wait for `Serial` before logging on boards that require it |
22+
| ATmega2560 | Mega | Standard SPI use |
23+
| ATSAMD21G18 | Feather M0, Feather M0 Express, ItsyBitsy M0 Express | Alternate SPI interface constructor supported |
24+
| AT91SAM3X8E | Arduino Due | Dedicated SAM path in library |
25+
| nRF52832 | Adafruit nRF52 Feather | Included in supported architectures |
26+
| ATSAMD51J19 | Adafruit Metro M4 | Included in tested list |
27+
| STM32F091RCT6 | Nucleo-F091RC | STM32 architecture macro path |
28+
| STM32L0 | Nucleo-L031K6 | Added in v3.4.0 changelog |
29+
| ESP8266 | Adafruit Feather ESP8266, Sparkfun ESP8266 Thing | Uses ESP8266 architecture branch |
30+
| ESP32 | Adafruit Feather ESP32, Sparkfun ESP32 Thing | May require explicit CS and custom SPI pins |
31+
| Simblee | Sparkfun Simblee | Listed as tested |
1732

18-
- exact board and core version tested
19-
- exact chip part number
20-
- required compile-time flags
33+
## Flash Chip Compatibility (documented as tested)
34+
35+
| Manufacturer | Parts listed in repo docs/changelog |
36+
| --- | --- |
37+
| Winbond | W25Q16BV, W25Q64FV, W25Q64JV, W25Q80BV, W25Q256FV |
38+
| Microchip | SST25VF064C, SST26VF016B, SST26VF032B, SST26VF064B |
39+
| Cypress/Spansion | S25FL032P, S25FL116K, S25FL127S |
40+
| ON Semiconductor | LE25U40CMC |
41+
| AMIC | A25L512A0 |
42+
| Micron | M25P40 |
43+
| Adesto | AT25SF041 |
44+
| Macronix | MX25L4005, MX25L8005 |
45+
| GigaDevice | GD25Q16C |
46+
47+
### SFDP note
48+
49+
The library can support more flash chips through SFDP discovery when `USES_SFDP` is enabled in `SPIMemory.h`.
50+
51+
## FRAM Compatibility (documented as tested)
52+
53+
| Manufacturer | Part |
54+
| --- | --- |
55+
| Cypress/Spansion | FM25W256 |
56+
57+
## Constructor Compatibility Notes
58+
59+
- `SPIFlash(uint8_t cs)` and `SPIFram(uint8_t cs)` are the default constructors.
60+
- `SPIFlash(uint8_t cs, SPIClass *spiinterface)` and `SPIFram(uint8_t cs, SPIClass *spiinterface)` are used on multi-SPI platforms.
61+
- `SPIFlash(int8_t *SPIPinsArray)` is intended for custom SPI pin routing (ESP32-style use cases).
62+
63+
## Before You Buy a New Chip
64+
65+
1. Check if the manufacturer is already in the tested list.
66+
2. Check if the part is SFDP-compatible (for flash).
67+
3. Plan to validate with `FlashDiagnostics` example and error codes on your target board.

‎docs/guide/configuration.md‎

Lines changed: 34 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,41 @@
11
# Build Configuration
22

3-
## Compile-Time Flags (in `SPIMemory.h`)
3+
This library is configured mainly through compile-time flags in `src/SPIMemory.h`.
44

5-
- `USES_SFDP`: enable SFDP discovery for unsupported flash chips
6-
- `RUNDIAGNOSTIC`: verbose diagnostics output
7-
- `HIGHSPEED`: skip pre-write blank checks
8-
- `DISABLEOVERFLOW`: disable address rollover
9-
- `ENABLEZERODMA`: experimental SAMD DMA mode
5+
## Compile-Time Flags
106

11-
## Runtime Configuration
7+
| Flag | Default | What it does | When to use |
8+
| --- | --- | --- | --- |
9+
| `USES_SFDP` | Off | Enables SFDP discovery logic for compatible flash chips | Using unsupported but SFDP-capable flash parts |
10+
| `RUNDIAGNOSTIC` | Off | Enables verbose diagnostics messaging and runtime tracing support | Hardware bring-up and debugging |
11+
| `HIGHSPEED` | Off | Skips pre-write blank checks (`_notPrevWritten`) | Performance tuning after you trust erase discipline |
12+
| `DISABLEOVERFLOW` | Off | Disables address wraparound at end-of-chip | Safety-critical logging where wrap is not acceptable |
13+
| `ENABLEZERODMA` | Off | Enables experimental SAMD DMA path | Advanced tuning on SAMD if validated on your board |
1214

13-
- `begin(chipSize)` optionally forces chip size
14-
- `setClock(clockSpeed)` changes SPI clock settings
15-
- platform-specific constructors enable alternate SPI interfaces
15+
## Runtime Configuration Calls
1616

17-
## Platform Notes
17+
- `begin(chipSize)` for optional explicit capacity override.
18+
- `setClock(clockSpeed)` for SPI speed tuning.
19+
- Alternate constructor variants for non-default SPI bus or custom pins.
1820

19-
When default SPI pins/bus are unsuitable, use board-specific constructor variants.
21+
## Constructor Guide
22+
23+
### Default SPI
24+
25+
- `SPIFlash flash(csPin);`
26+
- `SPIFram fram(csPin);`
27+
28+
### Alternate SPI interface (supported platforms)
29+
30+
- `SPIFlash flash(csPin, &SPI1);`
31+
- `SPIFram fram(csPin, &SPI1);`
32+
33+
### Custom SPI pins (ESP32-oriented)
34+
35+
- `SPIFlash flash(spiPinsArray);` where array order is `sck, miso, mosi, ss`.
36+
37+
## Recommended beginner defaults
38+
39+
- Keep all compile-time flags at default.
40+
- Keep write `errorCheck=true`.
41+
- Enable `RUNDIAGNOSTIC` only while debugging.

0 commit comments

Comments
 (0)