Expand beginner docs and add detailed example sketch guide

Author: Marzogh

docs/guide/common-tasks.md

@@ -1,5 +1,7 @@
 # Common Tasks (Beginner Friendly)
 
+If this is your first run on real hardware, start with [First Hour Setup](first-hour.md), then use [Example Sketches Guide](example-sketches.md) when validating behavior.
+
 ## Save one number and read it back
 
 ```cpp
@@ -47,6 +49,7 @@ flash.readByteArray(addr, rx, sizeof(rx));
 2. Ensure `begin()` is called in `setup()`.
 3. Print `getJEDECID()` and `error(VERBOSE)`.
 4. Run `FlashDiagnostics` example sketch.
+5. Compare results against [Example Sketches Guide](example-sketches.md).
 
 ## Improve speed safely
 

docs/guide/example-sketches.md

@@ -0,0 +1,110 @@
+# Example Sketches Guide (Troubleshooting + Learning)
+
+The bundled examples are one of the best parts of this library. This page explains what each one does, what success looks like, and what failures mean.
+
+## `FlashDiagnostics/FlashDiagnostics.ino`
+
+### What it tests
+
+- Chip identity (`getJEDECID`, capacity, max page, unique ID)
+- Power operations (`powerDown`, `powerUp`)
+- Erase operations (`eraseChip`, `eraseSection`, sector/block erase)
+- Data I/O for many types (byte, char, word, short, long, float, struct, array, string)
+
+### Why run it first
+
+It gives broad signal quickly: if this sketch fails, fix hardware/config before writing app logic.
+
+### Expected success signs
+
+- JEDEC ID prints non-zero.
+- Function tests report pass.
+- Read values match written values.
+
+### Common failure patterns
+
+- Fails immediately: wiring/CS/board SPI mismatch.
+- Write tests fail: region not erased, `WP/HOLD` pin state, unstable power.
+- Mixed intermittent failures: clock too fast, shared SPI bus interference.
+
+---
+
+## `TestFlash/TestFlash.ino`
+
+### What it is
+
+Interactive serial command tester for direct operation-by-operation checks.
+
+### Best use
+
+Use this when you want to isolate a single failing operation (`writeByte`, `eraseSector`, `readStr`, etc.) without full diagnostics noise.
+
+### Tips
+
+- Set Serial Monitor to expected line ending mode from sketch notes.
+- Test simple operations first (`getID`, `writeByte` + `readByte`).
+- Move to erase and string operations after basics pass.
+
+---
+
+## `getAddressEx/getAddressEx.ino`
+
+### What it teaches
+
+How to use `getAddress()` and `sizeofStr()` to allocate addresses safely without hardcoding offsets.
+
+### Troubleshooting value
+
+If this fails, you may have pre-written data conflicts or boundary behavior confusion.
+
+---
+
+## `readWriteString/readWriteString.ino`
+
+### What it teaches
+
+Simple `writeStr`/`readStr` workflow.
+
+### Troubleshooting value
+
+Great for catching string-specific issues (length metadata, readback integrity, sector erase assumptions).
+
+---
+
+## `Struct_writer/Struct_writer.ino`
+
+### What it teaches
+
+Write/read complete structs repeatedly, including nested members and arrays.
+
+### Troubleshooting value
+
+Use this for data-model persistence validation. If this fails while primitive tests pass, inspect struct layout assumptions and erase coverage.
+
+---
+
+## `FlashDiagnostics/Diagnostics_functions.ino`
+
+### What it is
+
+Helper routines used by diagnostics output (formatting, timing presentation, pass/fail display).
+
+### Why it matters
+
+Helps you understand what diagnostics output lines map to which underlying test sections.
+
+## Recommended order for beginners
+
+1. `FlashDiagnostics.ino`
+2. `TestFlash.ino` (targeted operation isolation)
+3. `readWriteString.ino`
+4. `getAddressEx.ino`
+5. `Struct_writer.ino`
+
+## What to capture when asking for help
+
+- Board and core version
+- Chip part number
+- Wiring summary (including `WP/HOLD` if flash)
+- Example sketch name
+- Error code (`error()` value) and serial output snippet

docs/guide/first-hour.md

@@ -0,0 +1,83 @@
+# First Hour Setup (Arduino Beginner Path)
+
+This walkthrough is for first-time users bringing up an external SPI memory chip.
+
+## 0-10 min: Hardware sanity check
+
+At minimum, connect:
+
+- `VCC` and `GND`
+- `SCK`, `MISO`, `MOSI`
+- `CS` (chip select)
+
+### Flash-specific pin note
+
+Many flash chips also expose `WP` (write protect) and `HOLD`. If these are floating, writes can fail or communication can be unstable. Check your chip datasheet and set valid levels.
+
+### ESP32 note
+
+Some ESP32 boards already use onboard flash on default SPI pins. Use an explicit CS pin and, if needed, the custom pin constructor.
+
+## 10-20 min: Minimal identity test
+
+Upload a minimal sketch that does:
+
+1. `begin()`
+2. `getJEDECID()`
+3. `error(VERBOSE)` on failure
+
+```cpp
+#include <SPIMemory.h>
+
+SPIFlash flash(10);
+
+void setup() {
+  Serial.begin(115200);
+  while (!Serial) {}
+
+  if (!flash.begin()) {
+    Serial.print("begin failed, err=0x");
+    Serial.println(flash.error(VERBOSE), HEX);
+    return;
+  }
+
+  Serial.print("JEDEC: 0x");
+  Serial.println(flash.getJEDECID(), HEX);
+}
+
+void loop() {}
+```
+
+If JEDEC is zero or invalid, stop and re-check wiring and CS pin.
+
+## 20-35 min: First write/read
+
+For flash:
+
+1. Erase region (`eraseSector`)
+2. Write one value (`writeULong`)
+3. Read back (`readULong`)
+
+```cpp
+uint32_t addr = 0;
+flash.eraseSector(addr);
+flash.writeULong(addr, 123456789UL);
+uint32_t out = flash.readULong(addr);
+```
+
+## 35-50 min: Run diagnostics sketch
+
+Run `examples/FlashDiagnostics/FlashDiagnostics.ino`.
+
+- This validates many read/write/erase and power operations.
+- It is the fastest way to separate hardware issues from application-code issues.
+
+## 50-60 min: Move to your real use case
+
+Pick one:
+
+- Logging numbers: use primitive write/read calls.
+- Saving settings: use `writeAnything/readAnything` with a struct.
+- Storing user text: use `writeStr/readStr`.
+
+Then use [Common Tasks](common-tasks.md) and [Example Sketches Guide](example-sketches.md).

docs/guide/quickstart.md

@@ -4,6 +4,8 @@
 
 If you are new to Arduino external memory chips, start here.
 
+For a step-by-step first session, use [First Hour Setup](first-hour.md).
+
 ## 1. Install the library
 
 ### Arduino Library Manager
@@ -70,8 +72,11 @@ Recommended beginner order:
 3. `examples/getAddressEx/getAddressEx.ino`
 4. `examples/Struct_writer/Struct_writer.ino`
 
+Use [Example Sketches Guide](example-sketches.md) for a full breakdown of what each sketch tests, what success looks like, and how to use failures for troubleshooting.
+
 ## 5. If it fails
 
 - Call `flash.error(VERBOSE)`.
 - Check [Errors and Diagnostics](../api/errors.md).
 - Run diagnostics example and capture output.
+- Follow the troubleshooting workflow in [Example Sketches Guide](example-sketches.md).

mkdocs.yml

@@ -14,7 +14,9 @@ nav:
   - Home: index.md
   - Getting Started:
       - Quick Start: guide/quickstart.md
+      - First Hour Setup: guide/first-hour.md
       - Common Tasks: guide/common-tasks.md
+      - Example Sketches Guide: guide/example-sketches.md
       - Core Concepts: guide/concepts.md
       - Build Configuration: guide/configuration.md
       - Compatibility Matrix: guide/compatibility.md