diff options
Diffstat (limited to 'docs/spi_driver.md')
-rw-r--r-- | docs/spi_driver.md | 44 |
1 files changed, 22 insertions, 22 deletions
diff --git a/docs/spi_driver.md b/docs/spi_driver.md index 569a19f1db..b77e2dbb46 100644 --- a/docs/spi_driver.md +++ b/docs/spi_driver.md @@ -1,10 +1,10 @@ -# SPI Master Driver :id=spi-master-driver +# SPI Master Driver {#spi-master-driver} The SPI Master drivers used in QMK have a set of common functions to allow portability between MCUs. -## Usage :id=usage +## Usage {#usage} -In most cases, the SPI Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](feature_oled_driver.md). +In most cases, the SPI Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](feature_oled_driver). However, if you need to use the driver standalone, add the following to your `rules.mk`: @@ -14,7 +14,7 @@ SPI_DRIVER_REQUIRED = yes You can then call the SPI API by including `spi_master.h` in your code. -## AVR Configuration :id=avr-configuration +## AVR Configuration {#avr-configuration} No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` pins of your SPI devices to the matching pins on the MCU: @@ -28,7 +28,7 @@ No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` p You may use more than one slave select pin, not just the `SS` pin. This is useful when you have multiple devices connected and need to communicate with them individually. `SPI_SS_PIN` can be passed to `spi_start()` to refer to `SS`. -## ChibiOS/ARM Configuration :id=arm-configuration +## ChibiOS/ARM Configuration {#arm-configuration} You'll need to determine which pins can be used for SPI -- as an example, STM32 parts generally have multiple SPI peripherals, labeled SPI1, SPI2, SPI3 etc. @@ -66,19 +66,19 @@ If a complete SPI interface is not required, then the following can be done to d - in `config.h`: `#define SPI_MOSI_PIN NO_PIN` - in `mcuconf.h`: `#define SPI_SELECT_MODE SPI_SELECT_MODE_NONE`, in this case the `slavePin` argument passed to `spi_start()` may be `NO_PIN` if the slave select pin is not used. -## API :id=api +## API {#api} -### `void spi_init(void)` :id=api-spi-init +### `void spi_init(void)` {#api-spi-init} Initialize the SPI driver. This function must be called only once, before any of the below functions can be called. --- -### `bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)` :id=api-spi-start +### `bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)` {#api-spi-start} Start an SPI transaction. -#### Arguments :id=api-spi-start-arguments +#### Arguments {#api-spi-start-arguments} - `pin_t slavePin` The QMK pin to assert as the slave select pin, eg. `B4`. @@ -97,71 +97,71 @@ Start an SPI transaction. - `uint16_t divisor` The SPI clock divisor, will be rounded up to the nearest power of two. This number can be calculated by dividing the MCU's clock speed by the desired SPI clock speed. For example, an MCU running at 8 MHz wanting to talk to an SPI device at 4 MHz would set the divisor to `2`. -#### Return Value :id=api-spi-start-return +#### Return Value {#api-spi-start-return} `false` if the supplied parameters are invalid or the SPI peripheral is already in use, or `true`. --- -### `spi_status_t spi_write(uint8_t data)` :id=api-spi-write +### `spi_status_t spi_write(uint8_t data)` {#api-spi-write} Write a byte to the selected SPI device. -#### Arguments :id=api-spi-write-arguments +#### Arguments {#api-spi-write-arguments} - `uint8_t data` The byte to write. -#### Return Value :id=api-spi-write-return +#### Return Value {#api-spi-write-return} `SPI_STATUS_TIMEOUT` if the timeout period elapses, or `SPI_STATUS_SUCCESS`. --- -### `spi_status_t spi_read(void)` :id=api-spi-read +### `spi_status_t spi_read(void)` {#api-spi-read} Read a byte from the selected SPI device. -#### Return Value :id=api-spi-read-return +#### Return Value {#api-spi-read-return} `SPI_STATUS_TIMEOUT` if the timeout period elapses, or the byte read from the device. --- -### `spi_status_t spi_transmit(const uint8_t *data, uint16_t length)` :id=api-spi-transmit +### `spi_status_t spi_transmit(const uint8_t *data, uint16_t length)` {#api-spi-transmit} Send multiple bytes to the selected SPI device. -#### Arguments :id=api-spi-transmit-arguments +#### Arguments {#api-spi-transmit-arguments} - `const uint8_t *data` A pointer to the data to write from. - `uint16_t length` The number of bytes to write. Take care not to overrun the length of `data`. -#### Return Value :id=api-spi-transmit-return +#### Return Value {#api-spi-transmit-return} `SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`. --- -### `spi_status_t spi_receive(uint8_t *data, uint16_t length)` :id=api-spi-receive +### `spi_status_t spi_receive(uint8_t *data, uint16_t length)` {#api-spi-receive} Receive multiple bytes from the selected SPI device. -#### Arguments :id=api-spi-receive-arguments +#### Arguments {#api-spi-receive-arguments} - `uint8_t *data` A pointer to the buffer to read into. - `uint16_t length` The number of bytes to read. Take care not to overrun the length of `data`. -#### Return Value :id=api-spi-receive-return +#### Return Value {#api-spi-receive-return} `SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`. --- -### `void spi_stop(void)` :id=api-spi-stop +### `void spi_stop(void)` {#api-spi-stop} End the current SPI transaction. This will deassert the slave select pin and reset the endianness, mode and divisor configured by `spi_start()`. |