OVMS3-idf/examples/peripherals/sdio/README.md

### SDIO Example

## Introduction

These two projects illustrate the SDIO driver (host and slave). The host
example shows how to initialize a SDIO card, respond to a slave interrupt, as
well as reading and writing registers and buffers. The slave is a dedicated
peripheral, providing 8 interrupts, 52 8-bit R/W registers, an input FIFO and
an output FIFO. The example shows how to configure the driver and use these
feature.

The host first tell the slave to write the registers to a specified value,
then reads and prints the value from the slave. Then tell the slave to send 8
interrupts to the host. Then the host start sending data to the slave FIFO
and then reads from the slave FIFO in loops.

## Wiring

The SDIO protocol requires at least 4 lines (one more line than SD memory
protocol): CMD, CLK, DAT0 and DAT1. DAT1 is mandatory for the interrupt. DAT2
is required if 4-bit mode is used. DAT3 is required in 4-bit mode (connected
to host), or required by the slave as mode detect in 1-bit mode (pull up). It
is okay in 1-bit mode to leave DAT3 of host disconnected.

Please run wires between the slave and master to make the example function
(pins are the same for the host and the slave):

| Signal | GPIO NUM |
|--------|----------|
| CLK    | GPIO-14  |
| CMD    | GPIO-15  |
| DAT0   | GPIO-2   |
| DAT1   | GPIO-4   |
| DAT2   | GPIO-12  |
| DAT3   | GPIO-13  |
| Ground | GND      |

CMD and DAT0-3 lines require to be pulled up by 50KOhm resistors even in
1-bit mode. See *Board Compability* below for details. In 1-bit mode, the
host can make use of DAT2 and DAT3, however the slave should leave them alone
but pulled up.

Be aware that the example uses lines normally reserved for JTAG. If you're
using a board with JTAG functions, please remember to remove jumpers
connecting to the JTAG adapter. The SD peripheral works at a high frequency
and uses native pins, there's no way to configure it to other pins through
the GPIO matrix.

Please make sure CMD and DATA lines are pulled up by 50KOhm resistors even in
1-bit mode or SPI mode, which is required by the SD specification.

The 4-bit mode can be configured in the menuconfig. If the 4-bit mode is not
used, the host will not control the DAT3 line, the slave hardware is
responsible to pull-up the line (or the slave may run into the SPI mode and
cause a crash).

The host uses HS mode by default. If the example does not work properly,
please try connecting two boards by short wires, grounding between two boards
better or disabling the HS mode in menuconfig.

## Board compatibility

1. If you're using a board (e.g. WroverKit v2 and before, PICO, DevKitC)
    which is not able to drive GPIO2 low on downloading, please remember to
    disconnect GPIO2 between two boards when downloading the application.

2. It is suggested to use the official Wrover Kit as the slave. This is
    because Wrover Kits have pullups on CMD, DAT0 and DAT1. Otherwise you'll have
    to connect the pullups manually (or use the Wrover Kit as the host). However,
    due to a PCB issue, Wrover Kits v3 and earlier have pullup v.s. pulldown
    conflicts on DAT3 line. You'll have to:

        1. Pull up GPIO13 by resistor of 5KOhm or smaller (2KOhm suggested)
           in 4-bit mode.
        2. Pull up, or tie GPIO13 to VDD3.3 in 1-bit mode.

    To help you faster evaluate the SDIO example on devkits without pullups,
    you can uncomment the pullup enable flags in the initialization code of
    the app_main of host or slave. This enables internal weak pullups on CMD,
    DAT0 and DAT1 and DAT3 lines. However please don't rely on internal weak
    pullups in your own design.

3. Moreover, if your slave devkit is using code flash of 3.3V, it is required
    to pull down DAT2 line to set proper flash voltage. This conflicts with SDIO
    pullup requirements. Currently devkits using PICO-D4 and Wroom-32 series
    modules have this problem. You can either:
    
        - Use Wrover Kit v3 which integrates a Wrover module
        - Still use PICO-D4 or Wroom-32 Series modules as the slave, however:
            - Don't connect the DAT2 pin and leave it floating. This means
                you have to use 1-bit mode in the host. ``SDIO_DAT2_DISABLED``
                option should be enabled in the menuconfig to avoid using of
                DAT2. Or:
            - Burn the EFUSE to force the module using 3.3V as the flash
                voltage. In this way the voltage of flash doesn't depend on MTDI
                any more, connect DAT2 to the host and make sure it is pulled up
                correctly. See document below.

See docs in the programming guide ``api_reference/peripherals/sdio_slave``
and ``api_reference/peripherals/sd_pullup_requirements`` to see more
descriptions about pullups and MTDI requirements and solutions of official
modules and devkits.

## About esp_slave component in this example

The component in this example shows how to communicate with esp32 sdio slave
correctly. However, currently it is for example purpose only.

The example shows how to talk with the slave, but doesn't show how to handle
exceptions. Assertion fails if any of the preconditions (connections,
grounding, slave data preparation, etc.) is not met.

Please do check and handle the return value in your real product.