165 lines
5.4 KiB
Markdown
165 lines
5.4 KiB
Markdown
# SPI Module
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2017-05-04 | [Arnim Läuger](https://github.com/devsaurus) | [Arnim Läuger](https://github.com/devsaurus) | [spi.c](../../../components/modules/spi.c)|
|
|
|
|
# SPI Bus
|
|
The ESP32 contains 4 SPI bus hosts called `SPI`, `SPI1`, `HSPI`, and `VSPI`. `SPI` is locked to flash communication and is not available for the application. `SPI1` is currently also tied to flash support, but might be available in the future. Applications can currently only use the `HSPI` and `VSPI` hosts.
|
|
|
|
The host signals can be mapped to any suitable GPIO pins.
|
|
|
|
!!! note
|
|
|
|
The API on ESP32 differs from the API on ESP8266. For backwards compatibility please refer to [`lua_compat/spi_compat.lua`](../../../lua_compat/spi_compat.lua).
|
|
|
|
|
|
## spi.master()
|
|
Initializes a bus in master mode and returns a bus master object.
|
|
|
|
#### Syntax
|
|
`spi.master(host, config[, dma])`
|
|
|
|
#### Parameters
|
|
- `host` id, one of
|
|
- `spi.SPI1`. not supported yet
|
|
- `spi.HSPI`
|
|
- `spi.VSPI`
|
|
- `config` table listing the assigned GPIOs. All signal assignment are optional.
|
|
- `sclk`
|
|
- `mosi`
|
|
- `miso`
|
|
- `quadwp`
|
|
- `quadhd`
|
|
- `dma` set DMA channel (1 or 2) or disable DMA (0), defaults to 1 if omitted.
|
|
Enabling DMA allows sending and receiving an unlimited amount of bytes but has restrictions in halfduplex mode (see [`spi.master:device()`](#spimasterdevice)).
|
|
Disabling DMA limits a transaction to 32 bytes max.
|
|
|
|
#### Returns
|
|
SPI bus master object
|
|
|
|
#### Example
|
|
```lua
|
|
busmaster_config = {sclk = 19, mosi = 23, miso = 25}
|
|
busmaster = spi.master(spi.HSPI, busmaster_config)
|
|
```
|
|
|
|
# Bus Master Object
|
|
|
|
## spi.master:close()
|
|
Close the bus host. This fails if there are still devices registered on this bus.
|
|
|
|
!!! caution
|
|
|
|
The bus is also closed when the bus master object is automatically destroyed during garbage collection. Registered devices inherently prevent garbage collection of the bus master object.
|
|
|
|
#### Syntax
|
|
`busmaster:close()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
## spi.master:device()
|
|
Adds a device on the given master bus. Up to three devices per bus are supported.
|
|
|
|
!!! note
|
|
|
|
Due to restrictions of the ESP IDF, halfduplex mode does not support DMA with both MOSI and MISO phases. Disable DMA during the call to [`spi.master()`](#spimaster) in this case and ensure that transaction data is not larger than 32 bytes.
|
|
|
|
#### Syntax
|
|
`busmaster:device(config)`
|
|
|
|
#### Parameters
|
|
`config` table describing the device parameters:
|
|
|
|
- `cs` GPIO connected to device's chip-select pin, optional
|
|
- `mode` SPI mode used for this device (0-3), mandatory
|
|
- `freq` clock frequency used for this device [Hz], mandatory
|
|
- `command_bits` amount of bits in command phase (0-16), defaults to 0 if omitted
|
|
- `address_bits` amount of bits in address phase (0-64), defaults to 0 if omitted
|
|
- `dummy_bits` amount of dummy bits to insert address and data phase, defaults to 0 if omitted
|
|
- `cs_ena_pretrans`, optional
|
|
- `cs_ena_posttrans`, optional
|
|
- `duty_cycle_pos`, optional
|
|
- `tx_lsb_first` transmit command/address/data LSB first if `true`, MSB first otherwise (or if omitted)
|
|
- `rx_lsb_first` receive data LSB first if `true`, MSB first otherwise (or if omitted)
|
|
- `wire3` use spiq for both transmit and receive if `true`, use mosi and miso otherwise (or if omitted)
|
|
- `positive_cs` chip-select is active high during a transaction if `true`, cs is active low otherwise (or if omitted)
|
|
- `halfduplex` transmit data before receiving data if `true`, transmit and receive simultaneously otherwise (or if omitted)
|
|
- `clk_as_cs` output clock on cs line when cs is active if `true`, defaults to `false` if omitted
|
|
|
|
#### Returns
|
|
SPI device object
|
|
|
|
#### Example
|
|
```lua
|
|
device_config = {mode = 0, freq = 1000000}
|
|
device_config.cs = 22
|
|
dev1 = busmaster:device(device_config)
|
|
|
|
device_config.cs = 4
|
|
dev2 = busmaster:device(device_config)
|
|
```
|
|
|
|
# Device Object
|
|
|
|
## spi.master:device:remove()
|
|
Removes a device from the related bus master.
|
|
|
|
!!! caution
|
|
|
|
The device is also removed when the device object is automatically destroyed during garbage collection.
|
|
|
|
#### Syntax
|
|
`device:remove()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
## spi.master:device:transfer()
|
|
Initiate an SPI transaction consisting of
|
|
|
|
1. assertion of cs signal
|
|
2. optional sending of command bits
|
|
3. optional sending of address bits
|
|
4. optional sending of dummy bits
|
|
5. sending of tx data
|
|
6. concurrent or appended reception of rx data, optional
|
|
7. de-assertion of cs signal
|
|
|
|
The function returns after the transaction is completed.
|
|
|
|
#### Syntax
|
|
```lua
|
|
device:transfer(trans)
|
|
device:transfer(txdata)
|
|
```
|
|
|
|
#### Parameters
|
|
`trans` table containing the elements of the transaction:
|
|
|
|
- `command` data for command phase, amount of bits was defined during device creation, optional
|
|
- `address` data for address phase, amount of bits was defined during device creation, optional
|
|
- `txdata` string of data to be sent to the device, optional
|
|
- `rxlen` number of bytes to be received, optional
|
|
- `mode` optional, one of
|
|
- `sio` transmit in SIO mode, default if omitted
|
|
- `dio` transmit in DIO mode
|
|
- `qio` transmit in QIO mode
|
|
- `addr_mode` transmit address also in selected `mode` if `true`, transmit address in SIO otherwise.
|
|
|
|
`txdata` string of data to be sent to the device
|
|
|
|
#### Returns
|
|
String of `rxlen` length, or `#txdata` length if `rxlen` is omitted.
|
|
|
|
|
|
## spi.slave()
|
|
Initializes a bus in slave mode and returns a slave object.
|
|
Not yet supported.
|