rx.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/stdint.h"
#include "fl/stl/optional.h"
#include "fl/stl/result.h"
#include "fl/stl/cstddef.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/shared_ptr.h"
#include "fl/stl/span.h"
 
namespace fl {
 
// Forward declarations
struct ChipsetTiming;

struct EdgeTime {
    u32 ns : 31;    
    u32 high : 1;   

    constexpr EdgeTime() FL_NO_EXCEPT : ns(0), high(0) {}

    constexpr EdgeTime(bool high_level, u32 ns_duration) FL_NO_EXCEPT
        : ns(ns_duration), high(high_level ? 1 : 0) {}
};

struct EdgeRange {
    size_t offset;  
    size_t count;   

    constexpr EdgeRange(size_t offsetParam, size_t countParam) FL_NO_EXCEPT
        : offset(offsetParam), count(countParam) {}
};

enum class DecodeError : u8 {
    OK = 0,                  
    HIGH_ERROR_RATE,         
    BUFFER_OVERFLOW,         
    INVALID_ARGUMENT,        
    CAPTURE_OVERRUN          
};

struct ChipsetTiming4Phase {
    // Bit 0 timing thresholds
    u32 t0h_min_ns; 
    u32 t0h_max_ns; 
    u32 t0l_min_ns; 
    u32 t0l_max_ns; 
 
    // Bit 1 timing thresholds
    u32 t1h_min_ns; 
    u32 t1h_max_ns; 
    u32 t1l_min_ns; 
    u32 t1l_max_ns; 
 
    // Reset pulse threshold
    u32 reset_min_us; 
 
    // Gap tolerance (optional, for handling transmission gaps like PARLIO DMA gaps)
    u32 gap_tolerance_ns = 0; 
};

ChipsetTiming4Phase make4PhaseTiming(const ChipsetTiming& timing_3phase,
                                      u32 tolerance_ns = 150) FL_NO_EXCEPT;

enum class RxWaitResult : u8 {
    SUCCESS = 0,             
    TIMEOUT = 1,             
    BUFFER_OVERFLOW = 2      
};

enum class RxDeviceType : u8 {
    PIO = 7,              
    PLATFORM_DEFAULT = 0,  
    ISR = 1,              
    RMT = 2,              
    FLEXPWM = 3,          
    FLEXIO = 4,           
    LPC_SCT_CAPTURE = 5,  
    PARLIO_RX = 8,        
    I2S_RX = 6            
};

inline const char* toString(RxDeviceType type) FL_NO_EXCEPT {
    switch (type) {
    case RxDeviceType::PLATFORM_DEFAULT: return "PLATFORM_DEFAULT";
    case RxDeviceType::ISR:     return "ISR";
    case RxDeviceType::RMT:     return "RMT";
    case RxDeviceType::FLEXPWM: return "FLEXPWM";
    case RxDeviceType::FLEXIO:  return "FLEXIO";
    case RxDeviceType::LPC_SCT_CAPTURE: return "LPC_SCT_CAPTURE";
    case RxDeviceType::I2S_RX: return "I2S_RX";
    case RxDeviceType::PARLIO_RX: return "PARLIO_RX";
    case RxDeviceType::PIO: return "PIO";
    }
    return "UNKNOWN";
}

struct RxConfig {
    // Hardware parameters
    size_t buffer_size = 512;               
    fl::optional<u32> hz = fl::nullopt; 
 
    // Signal detection parameters
    u32 signal_range_min_ns = 100;     
    u32 signal_range_max_ns = 100000;  
    u32 skip_signals = 0;              
    bool start_low = true;                  
 
    // Internal loopback configuration (ESP32 RMT only)
    // When true, RX receives from TX output internally (no external wire needed).
    // IMPORTANT: For RMT TX → RMT RX loopback on ESP32-S3, both TX and RX MUST be
    // configured on the SAME GPIO with io_loop_back=true. This is required because
    // ESP32-S3 has a hardware limitation where RMT TX GPIO output stops when RMT RX
    // is actively receiving on a different GPIO.
    bool io_loop_back = false;              
 
    // DMA streaming mode (ESP32 RMT only). Non-DMA RMT RX caps a single receive
    // at one mem-block fill (~4096 symbols, ≈170 WS2812B LEDs). DMA mode + ESP-IDF
    // 5.3+ en_partial_rx fires the ISR multiple times per transmission — each fill
    // copies into a DRAM accumulation buffer, extending capture to the full
    // buffer_size. DMA bypasses on-chip RMT memory (uses DRAM), so it does NOT
    // consume the shared RX pool and is safe to enable alongside other RMT
    // channels. ESP32-S3 has one shared DMA slot; acquisition is coordinated via
    // RmtMemoryManager::allocateDMA(). See issue #2254.
    bool use_dma = false;                   
 
    // Streaming decode (Teensy 4.x FlexPWM). That backend decodes bits from a
    // small DMA ring inside its ISR while the frame arrives, so it needs the
    // decode thresholds before decode() is called. Pass the same timing you
    // will give decode(). Unset: WS2812B defaults. Other backends ignore it.
    fl::optional<ChipsetTiming4Phase> stream_timing;

    RxConfig() FL_NO_EXCEPT = default;
};

class RxDevice {
 
public:

    template <RxDeviceType TYPE>
    static fl::shared_ptr<RxDevice> create(int pin) FL_NO_EXCEPT;

    virtual bool begin(const RxConfig& config) FL_NO_EXCEPT = 0;

    virtual const char* lastBeginError() const FL_NO_EXCEPT { return ""; }

    virtual bool finished() const FL_NO_EXCEPT = 0;

    virtual RxWaitResult wait(u32 timeout_ms) FL_NO_EXCEPT = 0;

    virtual fl::result<u32, DecodeError> decode(const ChipsetTiming4Phase &timing,
                                                       fl::span<u8> out) FL_NO_EXCEPT = 0;

    virtual size_t getRawEdgeTimes(fl::span<EdgeTime> out, size_t offset = 0) FL_NO_EXCEPT = 0;

    virtual const char* name() const FL_NO_EXCEPT = 0;

    virtual int getPin() const FL_NO_EXCEPT = 0;

    virtual bool injectEdges(fl::span<const EdgeTime> edges) FL_NO_EXCEPT = 0;
 
protected:
    // Allow shared_ptr to access protected destructor
    friend class fl::shared_ptr<RxDevice>;
    RxDevice() FL_NO_EXCEPT = default;
    virtual ~RxDevice() FL_NO_EXCEPT = default;
 
private:
    static fl::shared_ptr<RxDevice> createDummy() FL_NO_EXCEPT;
};
 
// Explicit specialization declarations — definitions live in
// fl/channels/rx.cpp.hpp. Declaring them here prevents implicit
// instantiation of the primary template at call sites (e.g.,
// channel.cpp.hpp), which would otherwise collide with the explicit
// specializations when both live in the same translation unit.
template <> fl::shared_ptr<RxDevice> RxDevice::create<RxDeviceType::PLATFORM_DEFAULT>(int pin) FL_NO_EXCEPT;
template <> fl::shared_ptr<RxDevice> RxDevice::create<RxDeviceType::I2S_RX>(int pin) FL_NO_EXCEPT;
template <> fl::shared_ptr<RxDevice> RxDevice::create<RxDeviceType::PARLIO_RX>(int pin) FL_NO_EXCEPT;
template <> fl::shared_ptr<RxDevice> RxDevice::create<RxDeviceType::RMT>(int pin) FL_NO_EXCEPT;
template <> fl::shared_ptr<RxDevice> RxDevice::create<RxDeviceType::ISR>(int pin) FL_NO_EXCEPT;
template <> fl::shared_ptr<RxDevice> RxDevice::create<RxDeviceType::FLEXPWM>(int pin) FL_NO_EXCEPT;
template <> fl::shared_ptr<RxDevice> RxDevice::create<RxDeviceType::LPC_SCT_CAPTURE>(int pin) FL_NO_EXCEPT;
template <> fl::shared_ptr<RxDevice> RxDevice::create<RxDeviceType::PIO>(int pin) FL_NO_EXCEPT;
 
} // namespace fl