====== SPI ======

Different variants exist. Usually SPI refers to the Motorola Serial Peripheral Interface. Other variants are the Texas Instruments Serial protocol (SSP) and the National Instruments Microwire.


===== Protocol =====

Most significant bit first


===== Modes =====
There are 4 Modes. Defied by the two settings "clock polarity" CPOL and "clock phase" CPHA.

"clock polarity" CPOL = 0:
  - Clock line is low when idle.

"clock polarity" CPOL = 1:
  - Clock line is high when idle.

"clock phase" CPHA = 0:
  - first data bit is output on /CS activating (going low).
  - data bits change when clock goes to idle level.
  - data bits are read when clock comes from idle level.

"clock phase" CPHA = 1:
  - first data bit starts on first edge after /CS activates.
  - data bits change when clock comes from idle level.
  - data bits are read when clock goes to idle level.
  
^ mode ^ CPOL ^ CPHA ^ write bit                               ^ read bit        ^
| 0    | 0    | 0    | clock goes low, and when /CS activates  | clock goes high |
| 1    | 0    | 1    | clock goes high                         | clock goes low  |
| 2    | 1    | 0    | clock goes high, and when /CS activates | clock goes low  |
| 3    | 1    | 1    | clock goes low                          | clock goes high |


===== SPI group =====

This group defines all used  Serial Peripheral Interface (SPI) interfaces.

Each SPI interface is a sub group with the SPI name as the group name.

<code>
    "SPI": {
        "encoder_spi": {
            "pad_sck": "PA5",
            "pad_miso": "PA6",
            "pad_mosi": "PA7",
            "pad_ncs": "PA15",
            "peripheral" : "SPI0",
            "role": "master",
            "communication_mode": "duplex",
            "frame_format": "motorola",
            "clock_polarity": "idle_low",
            "clock_phase": "sample_on_leading_edge",
            "bit_order": "msb_first",
            "baud_rate": "10 MHz",
        }
    }
</code>


=== pad_sck ===

Serial Clock.

**type**: String

=== pad_mosi ===

"Master Out Slave In" data signal.

**type**: String

=== pad_miso ===

"Master In Slave Out" data signal.

**type**: String

=== pad_ncs ===

Chip Select signal (Low active).

**type**: String

==== peripheral ====

name of the SPI peripheral to use.

**type**: String

=== role ===

Is either master(host) or slave(device).

**type**: enum

**default**: master

=== communication_mode ===

Describes the communication. Possible values are:
  * duplex : the traditional mode using MISO and MOSI to transmit and receive at the same time.
  * half-duplex : meaning the same wire between master and slave is used for both directions.
  * receive-only : send line is not used
  * send-only : receive Line is not used.

**type**: enum

**default**: duplex

=== frame_format ===

Describes the communication. Possible values are:
  * motorola : the "normal" SPI.
  * ti : 

**type**: enum

**default**: motorola

=== clock_polarity ===
Also often called CPOL. Describes the communication. Possible values are:
  * idle_low
  * idle_high

**type**: enum

**default**: idle_low

=== clock_phase ===
Also often called CPHA. Describes the communication. Possible values are:
  * sample_on_leading_edge : samples the data on the edge from idle value to non-idle value.
  * sample_on_trailinging_edge : samples the data on the edge from non-idle value to idle value.

**type**: enum

**default**: sample_on_leading_edge


=== SPI Mode ===
Sometimes the documentation talks about a SPI Mode with the value of 0 to 3. This mode maps to the phase and polarity as described in the following table:

^ Mode ^ CPOL ^ CPHA ^ description^
| 0 | 0 | 0 | clock: idle_low, phase: sample_on_leading_edge |
| 1 | 0 | 1 | clock: idle_low, phase: sample_on_trailing_edge |
| 2 | 1 | 0 | clock: idle_high, phase: sample_on_leading_edge |
| 3 | 1 | 1 | clock: idle_high, phase: sample_on_trailing_edge |



=== bit_order ===
Describes the communication. Possible values are:
  * msb_first : most significant bit first (bits on the line :  76543210 )
  * lsb_first : least significant bit first (bits on the line:  01234567 )

**type**: enum

**default**: msb_first

=== baud_rate ===

Is the number of bits per second exchanged on the data lines. Expressed as frequency of the clock line.

**type**: int (Hz)


===== API =====
The part "signal_name" in the described functions will be replaced by the name of the signal. E.g. if your signal is called "audio" then the API function "signal_name_transfer" will become "audio_transfer".

<code>
void signal_name_transfer(const uint8_t *data_send, 
                          const uint8_t *data_receive, 
                          const uint32_t length )</code>
Will send "length" bytes from the buffer "data_send" out on MOSI and will receive the same amount of bytes from MISO into the buffer "data_receive".