feat(spi): Add espp::Spi SPI component

.github/workflows/build.yml

@@ -185,6 +185,8 @@ jobs:
           target: esp32s3
         - path: 'components/socket/example'
           target: esp32
+        - path: 'components/spi/example'
+          target: esp32s3
         - path: 'components/st25dv/example'
           target: esp32s3
         - path: 'components/state_machine/example'

.github/workflows/upload_components.yml

@@ -113,6 +113,7 @@ jobs:
             components/serialization
             components/smartpanlee-sc01-plus
             components/socket
+            components/spi
             components/st25dv
             components/state_machine
             components/t_keyboard

components/spi/CMakeLists.txt

@@ -0,0 +1,5 @@
+idf_component_register(
+  INCLUDE_DIRS "include"
+  SRC_DIRS "src"
+  REQUIRES "base_component" "esp_driver_gpio" "esp_driver_spi" "task"
+  )

components/spi/README.md

@@ -0,0 +1,13 @@
+# SPI Component
+
+[![Badge](https://components.espressif.com/components/espp/spi/badge.svg)](https://components.espressif.com/components/espp/spi)
+
+The `Spi` class provides a simple C++ wrapper around the ESP-IDF SPI master
+driver. It manages SPI bus initialization, per-device registration, blocking
+transfers, queued transactions, and bus acquisition.
+
+## Example
+
+The [example](./example) shows how to create an SPI bus, attach a device, and
+perform a simple addressed read transaction, with the address phase driven on
+MOSI and the response read back on MISO.

components/spi/example/CMakeLists.txt

@@ -0,0 +1,21 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.20)
+
+set(ENV{IDF_COMPONENT_MANAGER} "0")
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+set(EXTRA_COMPONENT_DIRS
+  "../../../components/"
+)
+
+set(
+  COMPONENTS
+  "main esptool_py driver task spi"
+  CACHE STRING
+  "List of components to include"
+  )
+
+project(spi_example)
+
+set(CMAKE_CXX_STANDARD 20)

components/spi/example/README.md

@@ -0,0 +1,10 @@
+# SPI Example
+
+This example shows the use of the `Spi` component to create an SPI bus, attach a
+device, and perform a simple addressed read transaction.
+
+## How to use example
+
+The example is intended primarily as a compile-time reference for the `Spi`
+API. Update the GPIO assignments to match your hardware before flashing; the
+address phase is driven on MOSI and the response is read on MISO.

components/spi/example/main/CMakeLists.txt

@@ -0,0 +1,3 @@
+idf_component_register(SRC_DIRS "."
+                       INCLUDE_DIRS "."
+                       REQUIRES spi)

components/spi/example/main/spi_example.cpp

@@ -0,0 +1,46 @@
+#include <array>
+#include <cstdio>
+
+#include "spi.hpp"
+
+extern "C" void app_main(void) {
+  //! [spi example]
+  constexpr spi_host_device_t spi_host = SPI2_HOST;
+  constexpr auto sclk_gpio = GPIO_NUM_36;
+  constexpr auto mosi_gpio = GPIO_NUM_38;
+  constexpr auto miso_gpio = GPIO_NUM_35;
+  constexpr auto cs_gpio = GPIO_NUM_37;
+  constexpr uint8_t read_address = 0x80;
+
+  espp::Spi spi({
+      .host = spi_host,
+      .sclk_io_num = sclk_gpio,
+      .mosi_io_num = mosi_gpio,
+      .miso_io_num = miso_gpio,
+      .max_transfer_sz = 16,
+  });
+
+  std::error_code ec;
+  auto device = spi.add_device(
+      {
+          .address_bits = 8,
+          .mode = 0,
+          .clock_speed_hz = 1 * 1000 * 1000,
+          .cs_io_num = cs_gpio,
+          .queue_size = 1,
+      },
+      ec);
+  if (ec || !device) {
+    std::printf("Failed to create SPI device: %s\n", ec.message().c_str());
+    return;
+  }
+
+  std::array<uint8_t, 2> rx_data{};
+  if (!device->read(rx_data, {.address = read_address}, ec)) {
+    std::printf("SPI read failed: %s\n", ec.message().c_str());
+    return;
+  }
+
+  std::printf("Read bytes: 0x%02x 0x%02x\n", rx_data[0], rx_data[1]);
+  //! [spi example]
+}

components/spi/example/sdkconfig.defaults

@@ -0,0 +1,4 @@
+# Common ESP-related
+#
+CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=4096
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192

components/spi/idf_component.yml

@@ -0,0 +1,20 @@
+## IDF Component Manager Manifest File
+license: "MIT"
+description: "SPI component for ESP-IDF"
+url: "https://github.com/esp-cpp/espp/tree/main/components/spi"
+repository: "git://github.com/esp-cpp/espp.git"
+maintainers:
+  - William Emfinger <waemfinger@gmail.com>
+documentation: "https://esp-cpp.github.io/espp/spi.html"
+examples:
+  - path: example
+tags:
+  - cpp
+  - Component
+  - SPI
+  - DMA
+dependencies:
+  idf:
+    version: '>=5.0'
+  espp/base_component: '>=1.0'
+  espp/task: '>=1.0'