ESP32-C6 SPI Comprehensive Test Suite Documentation

Overview

The SPI Comprehensive Test Suite provides extensive validation of the EspSpi class for ESP32-C6 platforms using ESP-IDF v5.5+ SPI master driver. This comprehensive test suite demonstrates complete SPI functionality including bus management, device lifecycle, data transfer operations, DMA support, clock configuration, ESP-specific features, and advanced capabilities with a focus on embedded environments using noexcept functions.

✅ Status: Successfully tested on ESP32-C6-DevKitM-1 hardware with comprehensive validation 🎯 Focus: Full-duplex communication, DMA operations, and ESP32-C6 specific optimizations 🔧 Updated: Comprehensive SPI documentation with logic analyzer requirements

Features Tested

Core SPI Functionality

• Bus Management: Initialization, configuration, and cleanup
• Device Lifecycle: Creation, initialization, and removal
• Data Transfer: Full-duplex, half-duplex, and read-only operations
• Transfer Sizes: 1, 4, 16, 64, 256, and 1024 byte transfers
• Pattern Generation: Sequential and alternating data patterns
• Error Handling: Comprehensive error condition testing and recovery

Advanced SPI Features

• Clock Configuration: Multiple clock sources and frequency settings
• SPI Modes: CPOL/CPHA configuration (Mode 0-3)
• DMA Operations: Hardware-accelerated data transfer
• Multi-Device Support: Concurrent device management
• Thread Safety: RTOS mutex protection and concurrent access
• Performance Optimization: Timing and throughput measurement

ESP32-C6 Specific Features

• IOMUX Integration: Direct pin-to-peripheral connections
• Clock Sources: PLL_F80M, XTAL, and RC_FAST clock options
• Host Management: SPI2_HOST (only general-purpose host on ESP32-C6)
• Power Management: Sleep mode compatibility and wake-up
• Hardware Constraints: PHASE_0 sampling point limitation

Direct API Comparison

• ESP-IDF Direct API: Pure C-based SPI testing for baseline validation
• C++ Wrapper Replica: C++ wrapper comparison for wrapper validation
• Performance Comparison: Direct vs wrapper performance analysis

Hardware Requirements

ESP32-C6 DevKit-M-1 Pin Layout

The test suite uses the following safe pins on ESP32-C6 DevKit-M-1:

text Safe Test Pins: ┌─────────────────────────────────────┐ │ Function │ GPIO Pin │ ├─────────────────────┼───────────────┤ │ MOSI (Master Out) │ GPIO 7 │ │ MISO (Master In) │ GPIO 2 │ │ SCLK (Clock) │ GPIO 6 │ │ CS (Chip Select) │ GPIO 21 │ │ Test Progress LED │ GPIO 14 │ └─────────────────────┴───────────────┘ text

Optional Hardware

• Logic Analyzer: For signal analysis and timing validation
• SPI Device: For real device communication testing
• Oscilloscope: For detailed signal analysis

Test Configuration

Default Test Settings

```cpp // GPIO pin configuration static constexpr hf_pin_num_t TEST_MOSI_PIN = 7; static constexpr hf_pin_num_t TEST_MISO_PIN = 2; static constexpr hf_pin_num_t TEST_SCLK_PIN = 6; static constexpr hf_pin_num_t TEST_CS_PIN = 21;

// SPI host configuration static constexpr hf_host_id_t SPI_HOST_NUM = static_cast(1); // SPI2_HOST

// Clock configuration static constexpr uint32_t SPI_CLOCK_SPEED = 1000000; // 1MHz static constexpr hf_spi_clock_source_t CLOCK_SOURCE = hf_spi_clock_source_t::PLL_F80M_CLK;

// SPI mode configuration static constexpr hf_spi_mode_t SPI_MODE = hf_spi_mode_t::MODE_0; // CPOL=0, CPHA=0 ```text

Test Section Configuration

The test suite includes configurable test sections:

```cpp // Core SPI functionality tests static constexpr bool ENABLE_CORE_TESTS = true; // Bus management, device lifecycle static constexpr bool ENABLE_TRANSFER_TESTS = true; // Data transfer operations static constexpr bool ENABLE_PERFORMANCE_TESTS = true; // Clock speeds, performance static constexpr bool ENABLE_ADVANCED_TESTS = true; // ESP-specific features static constexpr bool ENABLE_STRESS_TESTS = true; // Error handling, edge cases

// Direct API comparison tests static constexpr bool ENABLE_ESPIDF_DIRECT_TEST = true; // Pure ESP-IDF API testing static constexpr bool ENABLE_ESPIDF_WRAPPER_REPLICA = true; // C++ wrapper comparison ```text

Test Categories

Core Functionality (8 tests)

1. Bus initialization - Basic setup and configuration validation
2. Bus deinitialization - Cleanup and state management verification
3. Configuration validation - Clock sources and settings verification
4. Device creation - Device lifecycle management
5. Device management - Multi-device operations and cleanup
6. Write operations - Data transmission validation
7. Read operations - Data reception validation
8. Write-read operations - Full-duplex communication testing

Advanced Features (8 tests)

1. Error handling - Fault conditions and recovery mechanisms
2. Timeout handling - Timing validation and error recovery
3. Multi-device operations - Concurrent device access testing
4. Clock speeds - Various frequency configuration testing
5. SPI modes - CPOL/CPHA configuration validation
6. ESP-specific features - Clock sources, power management
7. Thread safety - Concurrent access verification
8. Performance - Timing and throughput measurement

Transfer Size Testing (4 tests)

1. Small transfers - 1, 4, 16 byte transfer validation
2. Medium transfers - 64, 256 byte transfer validation
3. Large transfers - 1024 byte transfer validation
4. Pattern generation - Sequential and alternating pattern validation

Direct API Comparison (2 tests)

1. ESP-IDF direct API - Pure C-based SPI testing for baseline
2. C++ wrapper replica - C++ wrapper comparison for validation

Expected Output

Test Suite Header

```text ╔══════════════════════════════════════════════════════════════════════════════╗ ║ ESP32-C6 SPI COMPREHENSIVE TEST SUITE ║ ║ HardFOC Internal Interface ║ ╚══════════════════════════════════════════════════════════════════════════════╝

═══════════════════════════════════════════════════════════════════ ESP-IDF Direct API Test ═══════════════════════════════════════════════════════════════════ [SUCCESS] ESP-IDF direct API test passed

═══════════════════════════════════════════════════════════════════ C++ Wrapper Replica Test ═══════════════════════════════════════════════════════════════════ [SUCCESS] C++ wrapper replica test passed

═══════════════════════════════════════════════════════════════════ SPI Core Functionality Tests ═══════════════════════════════════════════════════════════════════ [SUCCESS] Bus initialization tests passed [SUCCESS] Bus deinitialization tests passed [SUCCESS] Configuration validation tests passed [SUCCESS] Device creation tests passed [SUCCESS] Device management tests passed [SUCCESS] Write operations tests passed [SUCCESS] Read operations tests passed [SUCCESS] Write-read operations tests passed

═══════════════════════════════════════════════════════════════════ SPI Advanced Features Tests ═══════════════════════════════════════════════════════════════════ [SUCCESS] Error handling tests passed [SUCCESS] Timeout handling tests passed [SUCCESS] Multi-device operations tests passed [SUCCESS] Clock speeds tests passed [SUCCESS] SPI modes tests passed [SUCCESS] ESP-specific features tests passed [SUCCESS] Thread safety tests passed [SUCCESS] Performance tests passed

═══════════════════════════════════════════════════════════════════ SPI Transfer Size Tests ═══════════════════════════════════════════════════════════════════ [SUCCESS] Small transfers tests passed [SUCCESS] Medium transfers tests passed [SUCCESS] Large transfers tests passed [SUCCESS] Pattern generation tests passed

Test Summary: SPI

Tests Run: 22 Passed: 22
Failed: 0 Success Rate: 100.00% ```text

Logic Analyzer Requirements

Sampling Rate Requirements

For proper SPI signal analysis, ensure your logic analyzer meets these specifications:

Minimum Requirements

• Sampling Rate: 4x SPI clock frequency
• Example: For 1MHz SPI clock → 4MS/s minimum

Recommended Requirements

• Sampling Rate: 10x SPI clock frequency
• Example: For 1MHz SPI clock → 10MS/s minimum, 40MS/s recommended

Mathematical Justification

Based on Nyquist-Shannon theorem and digital signal analysis:

Nyquist Rate

• Fundamental: 2x clock frequency (minimum required)
• Digital signals: Contain harmonics up to 5x-10x fundamental frequency
• Jitter tolerance: Higher sampling rates reduce timing uncertainty

Oversampling Benefits

• Signal reconstruction: 4x oversampling provides reliable digital signal capture
• Noise immunity: Higher sampling rates improve signal-to-noise ratio
• Timing accuracy: Better resolution for edge detection and timing analysis

Key Considerations

Hardware Requirements

• Memory depth: Ensure sufficient capture length for complete transfers
• Probe quality: High-quality probes reduce signal degradation
• Ground connection: Proper grounding essential for signal integrity
• Bandwidth: Logic analyzer bandwidth should exceed sampling rate

Signal Analysis

• Clock signal: Verify clean clock edges and proper frequency
• Data signals: Check for proper data timing and levels
• CS signal: Validate chip select timing and behavior
• Timing relationships: Ensure proper setup and hold times

Running the Tests

Build and Flash

```bash

From project root

cd examples/esp32

Build the SPI test suite

./scripts/build_example.sh main Release

Flash and monitor

./scripts/flash_example.sh main Release flash_monitor ```text

Test Execution

The test suite runs automatically with the following sequence:

1. ESP-IDF Direct API Test - Pure C-based validation
2. C++ Wrapper Replica Test - C++ wrapper comparison
3. Core Functionality Tests - Basic SPI operations
4. Advanced Features Tests - ESP-specific capabilities
5. Transfer Size Tests - Various data transfer sizes
6. Test Summary - Complete results and statistics

Monitoring Output

```bash

Monitor test execution

./scripts/flash_example.sh main Release monitor

View detailed logs

./scripts/flash_example.sh main Release monitor –log ```text

Troubleshooting

Common Issues

Build Errors

• ESP-IDF not sourced: Ensure export.sh is sourced
• Missing dependencies: Check component requirements
• Version mismatch: Verify ESP-IDF v5.5+ compatibility

Runtime Errors

• GPIO conflicts: Verify pin assignments don’t conflict
• Memory issues: Check available heap and stack sizes
• Clock configuration: Validate clock source and frequency settings

Logic Analyzer Issues

• Sampling rate too low: Increase to 4x-10x clock frequency
• Signal quality: Check probe connections and grounding
• Memory depth: Ensure sufficient capture length

Debug Information

The test suite provides comprehensive debug output:

• Test section headers: Clear separation between test categories
• Individual test results: Success/failure status for each test
• Performance metrics: Timing and throughput measurements
• Error details: Specific error codes and descriptions

Performance Characteristics

Transfer Performance

Transfer Size

Expected Performance

Notes

|——————-|————————–|———–|

1-16 bytes

< 100 μs

Small transfer optimization

64-256 bytes

< 500 μs

Medium transfer with DMA

1024 bytes

< 2 ms

Large transfer with DMA

Clock Performance

Clock Source

Maximum Frequency

Notes

|——————|———————-|———–|

PLL_F80M

80 MHz

Maximum performance

XTAL

40 MHz

Stable, crystal-based

RC_FAST

~17.5 MHz

Low-power, approximate

For Complete Documentation

📖 See EspSpi.md for:

• Complete API reference and implementation details
• Detailed test descriptions and validation procedures
• Usage examples and best practices
• Clock configuration and optimization details
• SPI mode explanations and timing requirements
• Performance characteristics and benchmarking
• Advanced features and ESP-specific capabilities
• Troubleshooting guide and common solutions

Navigation

Documentation Structure

• 🏠 Main Documentation - Complete system overview
• 📋 API Interfaces - Base classes and interfaces
• 🔧 ESP32 Implementations - Hardware-specific implementations
• 🧪 Test Suites - Testing and validation overview

Related Documentation

• EspSpi Implementation - ESP32-C6 SPI implementation
• BaseSpi API Reference - Abstract SPI interface
• Hardware Types - Type definitions
• ESP-IDF SPI Master Driver - Official ESP-IDF documentation

Navigation Links

• ⬅️ Previous: I2C Tests - I2C functionality testing
• ➡️ Next: UART Tests - Serial communication testing
• 🔙 Back to Test Suites - Test suites overview