SPI Examples (Blocking API)
===========================

Overview
~~~~~~~~

The blocking SPI examples are available for both C and C++:

- C: ``examples/blocking_api/spi/c/``
- C++: ``examples/blocking_api/spi/cpp/``

These examples are intended for both **Supernova** and **Pulsar** USB host adapters.

Hardware Setup
~~~~~~~~~~~~~~

Required hardware:

1. One Binho **Supernova** or **Pulsar**
2. One **Binho mikroBUS Adapter Board**
3. One MikroE **Flash 6 Click** board (Winbond **W25Q128JV**, 128 M-bit NOR Flash)

Useful references:

- Binho mikroBUS Adapter Board:
  `binho.io/test-measurement/products/usb-host-adapters/accessories/mikrobus-adapter-board/ <https://binho.io/test-measurement/products/usb-host-adapters/accessories/mikrobus-adapter-board/>`__
- Flash 6 Click:
  `mikroe.com/flash-6-click <https://www.mikroe.com/flash-6-click>`__
- W25Q128JV datasheet:
  `download.mikroe.com/documents/datasheets/w25q128jv.pdf <https://download.mikroe.com/documents/datasheets/w25q128jv.pdf>`__

What The SPI Examples Do
~~~~~~~~~~~~~~~~~~~~~~~~

1. Connect to the Binho adapter and read device information.
2. Set target voltage to ``3300 mV`` using the SPI voltage API:
    - C: ``CosmicSDK_SpiSetBusVoltage``
    - C++: ``spiSetBusVoltage``
3. Initialize the SPI controller on ``CS0``:
    - Mode: ``SPI_MODE_0``
    - Data width: ``8 bits``
    - Bit order: ``MSB first``
    - Frequency: ``10 MHz``
4. Read JEDEC ID with opcode ``0x9F`` and validate ``0xEF 0x40 0x18``.
5. Enable writes (``0x06``), then erase sector at address ``0x00 0x20 0x00`` (``0x20``).
6. Poll Status Register-1 (``0x05``) until WIP bit clears.
7. Enable writes again (``0x06``), then page program random data (1..256 bytes) with ``0x02``.
8. Poll Status Register-1 again until ready.
9. Read back memory (``0x03``) and verify read data matches written data.

Expected JEDEC ID Response
~~~~~~~~~~~~~~~~~~~~~~~~~~

The command ``0x9F`` requests manufacturer and device identification from the flash.
For W25Q128JV, the validated JEDEC bytes are:

- Manufacturer: ``0xEF`` (Winbond)
- Memory type: ``0x40``
- Capacity: ``0x18`` (128 M-bit)

Build and Run (SPI C/C++)
~~~~~~~~~~~~~~~~~~~~~~~~~

SPI example directories build binaries with different names:

- C (``examples/blocking_api/spi/c/``):
    - ``example_c_dynamic``
    - ``example_c_static``
- C++ (``examples/blocking_api/spi/cpp/``):
    - ``example_cpp_dynamic``
    - ``example_cpp_static``

See also:

- C API SPI reference: :doc:`../../api/c/spi`
- C++ blocking SPI reference: :doc:`../../api/cpp_blocking/spi`