EspPio.h

Go to the documentation of this file.

 
#pragma once
 
#include "BasePio.h"
#include "EspTypes.h"
#include "PlatformMutex.h"
#include <array>
// Include ESP-IDF RMT driver headers for direct type usage
// ESP-IDF C headers must be wrapped in extern "C" for C++ compatibility
#ifdef __cplusplus
extern "C" {
#endif
 
#include "driver/rmt_encoder.h"
#include "driver/rmt_rx.h"
#include "driver/rmt_tx.h"
 
#ifdef __cplusplus
}
#endif
 
//==============================================================================
// TYPE ALIASES FOR PLATFORM COMPATIBILITY (from McuTypes.h)
//==============================================================================
 
// Forward declarations for PIO types
struct hf_pio_channel_statistics_t {
  hf_u64_t total_transmissions;
  hf_u64_t total_receptions;
  hf_u64_t failed_transmissions;
  hf_u64_t failed_receptions;
  hf_u64_t last_operation_time;
  bool is_configured;
  bool is_busy;
  hf_u32_t current_resolution_ns;
  size_t memory_blocks_allocated;
  bool dma_enabled;
};
 
class EspPio : public BasePio {
public:
  EspPio() noexcept;
 
  ~EspPio() noexcept override;
 
  // Disable copy constructor and assignment operator
  EspPio(const EspPio&) = delete;
  EspPio& operator=(const EspPio&) = delete;
 
  // Allow move operations
  EspPio(EspPio&&) noexcept = default;
  EspPio& operator=(EspPio&&) noexcept = default;
 
  //==============================================//
  // BasePio Interface Implementation
  //==============================================//
  hf_pio_err_t Initialize() noexcept override;
  hf_pio_err_t Deinitialize() noexcept override;
 
  hf_pio_err_t ConfigureChannel(hf_u8_t channel_id,
                                const hf_pio_channel_config_t& config) noexcept override;
 
  hf_pio_err_t Transmit(hf_u8_t channel_id, const hf_pio_symbol_t* symbols, size_t symbol_count,
                        bool wait_completion = false) noexcept override;
 
  hf_pio_err_t StartReceive(hf_u8_t channel_id, hf_pio_symbol_t* buffer, size_t buffer_size,
                            uint32_t timeout_us = 0) noexcept override;
  hf_pio_err_t StopReceive(hf_u8_t channel_id, size_t& symbols_received) noexcept override;
 
  bool IsChannelBusy(hf_u8_t channel_id) const noexcept override;
  hf_pio_err_t GetChannelStatus(hf_u8_t channel_id,
                                hf_pio_channel_status_t& status) const noexcept override;
  hf_pio_err_t GetCapabilities(hf_pio_capabilities_t& capabilities) const noexcept override;
 
  void SetTransmitCallback(hf_u8_t channel_id, hf_pio_transmit_callback_t callback,
                           void* user_data = nullptr) noexcept override;
  void SetReceiveCallback(hf_u8_t channel_id, hf_pio_receive_callback_t callback,
                          void* user_data = nullptr) noexcept override;
  void SetErrorCallback(hf_u8_t channel_id, hf_pio_error_callback_t callback,
                        void* user_data = nullptr) noexcept override;
  void ClearChannelCallbacks(hf_u8_t channel_id) noexcept override;
  void ClearCallbacks() noexcept override;
 
  hf_pio_err_t GetStatistics(hf_u8_t channel_id,
                             hf_pio_statistics_t& statistics) const noexcept override;
 
  hf_pio_err_t GetDiagnostics(hf_u8_t channel_id,
                              hf_pio_diagnostics_t& diagnostics) const noexcept override;
 
  //==============================================//
  // Lazy Initialization Support
  // Advanced Low-Level RMT Control Methods
  //==============================================//
 
  hf_pio_err_t TransmitRawRmtSymbols(hf_u8_t channel_id, const rmt_symbol_word_t* rmt_symbols,
                                     size_t symbol_count, bool wait_completion = false) noexcept;
 
  hf_pio_err_t ReceiveRawRmtSymbols(hf_u8_t channel_id, rmt_symbol_word_t* rmt_buffer,
                                    size_t buffer_size, size_t& symbols_received,
                                    uint32_t timeout_us = 10000) noexcept;
  hf_pio_err_t ConfigureAdvancedRmt(hf_u8_t channel_id, size_t memory_blocks = 64,
                                    bool enable_dma = false, uint32_t queue_depth = 4) noexcept;
 
  //==============================================//
  // ESP32-Specific Methods (continued)
  //==============================================//
 
  hf_pio_err_t ConfigureCarrier(hf_u8_t channel_id, uint32_t carrier_freq_hz,
                                float duty_cycle) noexcept;
 
  hf_pio_err_t EnableLoopback(hf_u8_t channel_id, bool enable) noexcept;
 
  size_t GetMaxSymbolCount() const noexcept;
 
  bool ValidatePioSystem() noexcept;
 
  hf_pio_err_t ConfigureEncoder(hf_u8_t channel_id, const hf_pio_symbol_t& bit0_config,
                                const hf_pio_symbol_t& bit1_config) noexcept;
 
  hf_pio_err_t SetIdleLevel(hf_u8_t channel_id, bool idle_level) noexcept;
 
  hf_pio_err_t GetChannelStatistics(hf_u8_t channel_id,
                                    hf_pio_channel_statistics_t& stats) const noexcept;
 
  hf_pio_err_t ResetChannelStatistics(hf_u8_t channel_id) noexcept;
 
  hf_pio_err_t GetActualResolution(hf_u8_t channel_id,
                                   hf_u32_t& achieved_resolution_ns) const noexcept;
 
  hf_pio_err_t SetClockSource(hf_u8_t channel_id, rmt_clock_source_t clk_src) noexcept;
 
  hf_pio_err_t GetClockSource(hf_u8_t channel_id, rmt_clock_source_t& clk_src) const noexcept;
 
  hf_pio_err_t GetSourceClockHz(hf_u8_t channel_id, hf_u32_t& clock_hz) const noexcept;
 
private:
  //==============================================//
  // Internal Structures
  //==============================================//
 
  struct ChannelState {
    bool configured;
    bool busy;
    hf_pio_channel_config_t config;
    hf_pio_channel_status_t status;
 
    // Use original ESP-IDF RMT types directly
    rmt_channel_handle_t tx_channel;
    rmt_channel_handle_t rx_channel;
    rmt_encoder_handle_t encoder;
    rmt_encoder_handle_t bytes_encoder; // For byte-level protocols
 
    // Buffers
    hf_pio_symbol_t* rx_buffer;
    size_t rx_buffer_size;
    size_t rx_symbols_received;
    rmt_symbol_word_t* rmt_rx_buffer; // Allocated RMT buffer for reception
 
    // Timing
    uint64_t last_operation_time;
    hf_u32_t actual_resolution_ns;       // Actual achieved resolution due to divider constraints
    rmt_clock_source_t selected_clk_src; // Selected clock source for this channel
    hf_u32_t source_clock_hz;            // Source clock frequency in Hz for calculations
 
    // Idle level configuration
    bool idle_level;
 
    // Callbacks
    hf_pio_transmit_callback_t transmit_callback;
    void* transmit_user_data;
    hf_pio_receive_callback_t receive_callback;
    void* receive_user_data;
    hf_pio_error_callback_t error_callback;
    void* error_user_data;
 
    ChannelState() noexcept
        : configured(false), busy(false), config(), status(), tx_channel(nullptr),
          rx_channel(nullptr), encoder(nullptr), bytes_encoder(nullptr), rx_buffer(nullptr),
          rx_buffer_size(0), rx_symbols_received(0), rmt_rx_buffer(nullptr), last_operation_time(0),
          actual_resolution_ns(0), selected_clk_src(RMT_CLK_SRC_DEFAULT), source_clock_hz(80000000),
          idle_level(false), transmit_callback(nullptr), transmit_user_data(nullptr),
          receive_callback(nullptr), receive_user_data(nullptr), error_callback(nullptr),
          error_user_data(nullptr) {}
  };
 
  //==============================================//
  // Member Variables
  //==============================================//
 
  static constexpr hf_u8_t MAX_CHANNELS = HF_RMT_MAX_CHANNELS; // Use centralized constant
  static constexpr size_t MAX_SYMBOLS_PER_TRANSMISSION = 256;
  static constexpr uint32_t DEFAULT_RESOLUTION_NS = 1000; // 1 microsecond
// ESP32-C6 specific clock frequency configuration
#if defined(CONFIG_IDF_TARGET_ESP32C6)
  static constexpr uint32_t RMT_CLK_SRC_FREQ = 80000000; // ESP32-C6 APB clock (80 MHz)
#else
  static constexpr uint32_t RMT_CLK_SRC_FREQ = 80000000; // 80 MHz APB clock
#endif
 
  std::array<ChannelState, MAX_CHANNELS> channels_;
  mutable PlatformMutex state_mutex_;
 
  // Global statistics and diagnostics
  hf_pio_statistics_t global_statistics_;
  hf_pio_diagnostics_t global_diagnostics_;
 
  //==============================================//
  // Internal Helper Methods
  //==============================================//
 
  bool IsValidChannelId(hf_u8_t channel_id) const noexcept;
  hf_pio_err_t ConvertToRmtSymbols(const hf_pio_symbol_t* symbols, size_t symbol_count,
                                   rmt_symbol_word_t* rmt_symbols,
                                   size_t& rmt_symbol_count) noexcept;
 
  hf_pio_err_t ConvertFromRmtSymbols(const rmt_symbol_word_t* rmt_symbols, size_t rmt_symbol_count,
                                     hf_pio_symbol_t* symbols, size_t max_symbols,
                                     size_t& symbols_converted) noexcept;
 
#ifdef HF_MCU_FAMILY_ESP32
  // Update callback signatures to match ESP-IDF v5.5 API
  static bool OnTransmitComplete(rmt_channel_handle_t channel,
                                 const rmt_tx_done_event_data_t* edata, void* user_ctx);
  static bool OnReceiveComplete(rmt_channel_handle_t channel, const rmt_rx_done_event_data_t* edata,
                                void* user_ctx);
#endif
 
  hf_pio_err_t InitializeChannel(hf_u8_t channel_id) noexcept;
 
  hf_pio_err_t DeinitializeChannel(hf_u8_t channel_id) noexcept;
 
  hf_pio_err_t ValidateSymbols(const hf_pio_symbol_t* symbols, size_t symbol_count) const noexcept;
 
  hf_u32_t CalculateResolutionHz(hf_u32_t resolution_ns, hf_u32_t& actual_resolution_ns,
                                 hf_u32_t source_clock_hz) const noexcept;
 
  uint32_t CalculateClockDivider(uint32_t resolution_ns, uint32_t& actual_resolution_ns,
                                 uint32_t source_clock_hz) const noexcept;
 
  uint32_t GetEffectiveClockFrequency(uint32_t clock_divider,
                                      uint32_t source_clock_hz) const noexcept;
 
  hf_pio_err_t GetResolutionConstraints(hf_u32_t& min_resolution_ns, hf_u32_t& max_resolution_ns,
                                        hf_u32_t& clock_freq_hz) const noexcept;
 
  hf_pio_err_t GetResolutionConstraints(hf_u8_t channel_id, hf_u32_t& min_resolution_ns,
                                        hf_u32_t& max_resolution_ns,
                                        hf_u32_t& clock_freq_hz) const noexcept;
 
  static inline hf_u32_t GetClockSourceFrequency(rmt_clock_source_t clk_src) noexcept;
  static inline hf_u32_t ResolveClockSourceHz(rmt_clock_source_t clk_src) noexcept;
 
  hf_pio_err_t ValidateChannelConfiguration(hf_u8_t channel_id,
                                            const hf_pio_channel_config_t& config) const noexcept;
 
  void InvokeChannelErrorCallback(hf_u8_t channel_id, hf_pio_err_t error) noexcept;
 
  static constexpr const char* TAG = "EspPio"; 
};