capture()

size_t capture	(	fl::shared_ptr< fl::RxChannel >	rx_channel,
		fl::span< uint8_t >	rx_buffer,
		const fl::ChipsetTimingConfig &	timing,
		const char *	driver_name )

Definition at line 317 of file AutoResearchTest.cpp.

                                                                                                                                              {
    if (!rx_channel) {
        FL_ERROR("RX channel is null");
        return 0;
    }
 
    // Clear RX buffer
    fl::memset(rx_buffer.data(), 0, rx_buffer.size());
 
    // Prepare RX config (but don't arm yet to avoid locking TX resources)
    fl::RxChannelConfig rx_config(rx_channel->getPin());
    rx_config.hz = 40000000; // 40MHz for high-precision LED timing capture
 
    // Buffer size: 1 LED byte = 8 bits = 8 RMT symbols
    // UART with TX inversion produces standard WS2812 waveform, same symbol count
    bool is_uart_driver = (fl::strcmp(driver_name, "UART") == 0);
    rx_config.edge_capacity = rx_buffer.size() * 8;
 
    // Internal loopback configuration: Enable ONLY for RMT TX -> RMT RX scenarios
    // When driver_name == "RMT", enable io_loop_back to route RMT TX output to RMT RX internally
    // This is REQUIRED for ESP32-S3 because TX GPIO output stops when RX is active on different GPIO
    // For other drivers (PARLIO, SPI, UART, I2S), disable io_loop_back (use external GPIO wire)
    bool is_rmt_driver = (fl::strcmp(driver_name, "RMT") == 0);
    rx_config.io_loop_back = is_rmt_driver;
    // RX DMA streaming: extends capture past the non-DMA cap by sizing
    // mem_block_symbols = 14336 so ESP-IDF allocates ~14 DMA descriptor
    // nodes (each 4092 bytes), yielding a 57 KB user-buffer cap — enough to
    // capture ~583 WS2812B LEDs in a single rmt_receive() call. Safe for
    // non-RMT TX paths (SPI, PARLIO, I2S, UART, LCD_*) that don't contend
    // for the shared ESP32-S3 DMA slot. RMT loopback stays non-DMA.
    // See issue #2254.
    rx_config.use_dma = !is_rmt_driver;
    if (is_rmt_driver) {
        FL_WARN("[CAPTURE] RMT TX -> RMT RX: Internal loopback enabled (io_loop_back=true)");
    } else {
        // The RX peripheral is platform-dependent (RMT on ESP32, FlexPWM on
        // Teensy 4, LPC_SCT on LPC845, …). Don't claim "RMT RX" on platforms
        // that have no RMT — that label burned an hour of Teensy-4 debug
        // (FastLED#3059). Just say "external RX" so the label stays correct
        // regardless of backend.
        FL_WARN("[CAPTURE] " << driver_name << " TX -> external RX: External GPIO wire (io_loop_back=false, use_dma=true)");
    }
 
    // Driver-aware capture strategy:
    // - RMT: Two-TX approach (ESP32-S3 workaround - TX GPIO blocked when RX active)
    // - PARLIO/SPI/other: Single-TX approach (arm RX first, then TX)
 
    // TX wait timeout: 1 second max per frame - prevents infinite hang if driver stalls
    // Even a 10000-LED strip at 800kbps takes only ~300ms, so 1s is very safe
    const uint32_t TX_WAIT_TIMEOUT_MS = 1000;
 
    if (is_rmt_driver) {
        // RMT: Two-TX approach for ESP32-S3 compatibility
        // First TX without RX armed (diagnostics), then arm RX, then second TX
        FL_WARN("[CAPTURE] RMT: Two-TX approach (ESP32-S3 workaround)");
        FastLED.show();
        if (!FastLED.wait(TX_WAIT_TIMEOUT_MS)) {
            FL_ERROR("[CAPTURE] TX wait timeout (pre-arm) - driver may be stalled");
            return 0;
        }
 
        // Arm RX for capture
        if (!rx_channel->begin(rx_config)) {
            FL_ERROR("Failed to arm RX receiver");
            return 0;
        }
        // Second TX with RX armed
        FastLED.show();
        if (!FastLED.wait(TX_WAIT_TIMEOUT_MS)) {
            FL_ERROR("[CAPTURE] TX wait timeout (capture) - driver may be stalled");
            return 0;
        }
    } else {
        // Non-RMT (PARLIO, SPI, etc.): Single-TX approach
        if (!rx_channel->begin(rx_config)) {
            FL_WARN("[CAPTURE] RX begin() failed for pin " << rx_channel->getPin());
            return 0;
        }
        FL_WARN("[CAPTURE] RX armed, calling FastLED.show()...");
 
        FastLED.show();
        FL_WARN("[CAPTURE] FastLED.show() returned, calling wait...");
        if (!FastLED.wait(TX_WAIT_TIMEOUT_MS)) {
            FL_WARN("[CAPTURE] FastLED.wait() timed out");
            return 0;
        }
        FL_WARN("[CAPTURE] FastLED.wait() done");
    }
 
 
 
 
    // Wait for RX completion
    // WS2812B: ~30μs per LED → 3000 LEDs = 90ms, use 150ms
    // UART with inverted TX produces same waveform timing as WS2812
    const uint32_t rx_wait_ms = is_uart_driver ? 500 : 150;
    FL_WARN("[CAPTURE] Waiting for RX completion (" << rx_wait_ms << "ms timeout)...");
    auto wait_result = rx_channel->wait(rx_wait_ms);
    FL_WARN("[CAPTURE] RX wait returned: " << static_cast<int>(wait_result));
 
    if (wait_result != fl::RxWaitResult::SUCCESS) {
        FL_WARN("RX wait failed (timeout or no data received)");
        fl::sstream ss;
        ss << "\n⚠️  TROUBLESHOOTING:\n";
        ss << "   1. Connect physical jumper wire from TX GPIO to RX GPIO " << rx_channel->getPin() << "\n";
        ss << "   2. Check that both TX and RX pins are correctly configured\n";
        ss << "   3. Verify the GPIO connection is working (GPIO baseline test should pass)\n";
        ss << "   4. For RMT TX → RMT RX: Ensure io_loop_back=true in RxConfig";
        FL_WARN(ss.str());
        if (!is_uart_driver) {
            return 0;
        }
        // UART: still attempt decode with captured edges (timeout may be expected)
        FL_WARN("[CAPTURE] UART: attempting decode with captured edges despite timeout");
    }
 
    // UART with TX inversion at 4 Mbps produces a standard WS2812-compatible
    // waveform on the wire. Each 10-bit UART frame (2500ns) encodes exactly 2
    // LED bits with correct WS2812 timing:
    //   T0H=250ns, T0L=1000ns (LED bit "0")
    //   T1H=750ns, T1L=500ns  (LED bit "1")
    // Use the standard WS2812 decoder with UART-specific timing thresholds.
    if (is_uart_driver) {
        FL_WARN("[CAPTURE] UART (inverted TX): using standard WS2812 decoder with UART timing...");
        // UART timing at 4 Mbps: T0H=250ns, T1H-T0H=500ns, T0L=1000ns
        fl::ChipsetTiming uart_timing{
            250,   // T1 = T0H (1 UART bit = 250ns)
            500,   // T2 = T1H - T0H (3 bits - 1 bit = 2 bits = 500ns)
            500,   // T3 = T1L (2 UART bits = 500ns, stop + next start)
            50,    // reset_us (WS2812 minimum)
            "UART_4Mbps"
        };
        // Use wider tolerance (250ns) for UART because the UART clock and RMT
        // sample clock are asynchronous, and GPIO matrix adds ~10-20ns jitter
        auto rx_timing = fl::make4PhaseTiming(uart_timing, 250);
        rx_timing.gap_tolerance_ns = 100000; // 100µs for UART inter-frame gaps
 
        FL_WARN("[CAPTURE] UART RX timing: T0H=" << uart_timing.T1
                << " T1H=" << (uart_timing.T1 + uart_timing.T2)
                << " T0L=" << (uart_timing.T2 + uart_timing.T3)
                << " T1L=" << uart_timing.T3);
 
        auto decode_result = rx_channel->decode(rx_timing, rx_buffer);
        if (!decode_result.ok()) {
            FL_WARN("[CAPTURE] UART decode failed (error: " << static_cast<int>(decode_result.error()) << ")");
            dumpRawEdgeTiming(rx_channel, timing, fl::EdgeRange(0, 256));
            return 0;
        }
        FL_WARN("[CAPTURE] UART decoded " << decode_result.value() << " LED bytes");
        return decode_result.value();
    }
 
    // SPI chipset drivers (LCD_SPI, I2S_SPI): decode raw SPI bit stream
    // These drivers use LCD_CAM I80 bus or I2S to output APA102 data.
    // RMT RX captures edges on the data pin; clock pin is ignored.
    bool is_lcd_spi_driver = (fl::strcmp(driver_name, "LCD_SPI") == 0);
    bool is_i2s_spi_driver = (fl::strcmp(driver_name, "I2S_SPI") == 0);
    if (is_lcd_spi_driver || is_i2s_spi_driver) {
        // SPI clock used for validation: 2.4MHz (matches ValidationRemote.cpp)
        const uint32_t spi_clock_hz = 2400000;
        FL_WARN("[CAPTURE] SPI chipset decode: clock=" << spi_clock_hz << " Hz");
        size_t decoded = decodeSpiEdges(rx_channel, rx_buffer, spi_clock_hz);
        if (decoded == 0) {
            FL_WARN("[CAPTURE] SPI decode failed");
            dumpRawEdgeTiming(rx_channel, timing, fl::EdgeRange(0, 256));
        }
        return decoded;
    }
 
    // Decode received data directly into rx_buffer
    // Create 4-phase RX timing from the TX timing
    //
    // Wave8 drivers (SPI, PARLIO, I2S) use 8-bit expansion encoding:
    //   Bit 0: round(T1/(T1+T2+T3)*8) HIGH pulses, rest LOW
    //   Bit 1: round((T1+T2)/(T1+T2+T3)*8) HIGH pulses, rest LOW
    // The actual pulse widths are quantized to tick boundaries, so we must
    // compute the exact wave8 timing for RX decode thresholds.
    // Without this correction, the RX decoder may reject valid waveforms when
    // the nominal timing period differs from the quantized 8-tick period.
    // Example: WS2812_800KHZ has T0L=1000ns nominal but PARLIO wave8 produces 750ns.
    //
    // Clock sources differ by driver:
    //   SPI/I2S: clock = 8/(T1+T2+T3) Hz, tick = (T1+T2+T3)/8 ns (variable)
    //   PARLIO:  clock = 8 MHz fixed, tick = 125 ns (fixed)
    bool is_spi_driver = (fl::strcmp(driver_name, "SPI") == 0);
    bool is_parlio_driver = (fl::strcmp(driver_name, "PARLIO") == 0);
    bool is_i2s_driver = (fl::strcmp(driver_name, "I2S") == 0);
    // LCD_CLOCKLESS auto-selects wave3 vs wave8 based on canUseWave3() of the
    // chipset timing. Compute the same eligibility check on the host side so
    // the RX decoder reconstructs the correct quantized waveform.
    bool is_lcd_clockless_driver = (fl::strcmp(driver_name, "LCD_CLOCKLESS") == 0);
    bool lcd_clockless_uses_wave3 = false;
    if (is_lcd_clockless_driver) {
        fl::ChipsetTiming probe{timing.t1_ns, timing.t2_ns, timing.t3_ns, timing.reset_us, timing.name};
        lcd_clockless_uses_wave3 = fl::canUseWave3(probe);
    }
    bool uses_wave8 = is_spi_driver || is_parlio_driver || is_i2s_driver
                      || (is_lcd_clockless_driver && !lcd_clockless_uses_wave3);
    bool uses_wave3 = is_lcd_clockless_driver && lcd_clockless_uses_wave3;
    fl::ChipsetTiming tx_timing;
    if (uses_wave8) {
        // Compute actual wave8 timing from chipset timing
        const uint32_t period = timing.t1_ns + timing.t2_ns + timing.t3_ns;
        // PARLIO uses fixed 8MHz clock (125ns/tick), not derived from period
        // SPI/I2S/LCD_CLOCKLESS derive clock from period: tick = period/8
        const uint32_t tick_ns = is_parlio_driver ? 125 : (period / 8);
        // Wave8 LUT computes: pulses = round(fraction * 8)
        const uint32_t pulses_bit0 = static_cast<uint32_t>(
            static_cast<float>(timing.t1_ns) / period * 8.0f + 0.5f);
        const uint32_t pulses_bit1 = static_cast<uint32_t>(
            static_cast<float>(timing.t1_ns + timing.t2_ns) / period * 8.0f + 0.5f);
        // Convert back to 3-phase timing (T1=T0H, T2=T1H-T0H, T3=actual_period-T1H)
        const uint32_t actual_t0h = pulses_bit0 * tick_ns;
        const uint32_t actual_t1h = pulses_bit1 * tick_ns;
        const uint32_t actual_period = 8 * tick_ns;
        const char* wave8_name = is_spi_driver ? "SPI_wave8" :
                                 is_parlio_driver ? "PARLIO_wave8" :
                                 is_lcd_clockless_driver ? "LCD_CLOCKLESS_wave8" : "I2S_wave8";
        tx_timing = fl::ChipsetTiming{
            actual_t0h,                    // T1 = T0H
            actual_t1h - actual_t0h,       // T2 = T1H - T0H
            actual_period - actual_t1h,    // T3 = actual_period - T1H
            timing.reset_us,
            wave8_name
        };
        FL_WARN("[RX TIMING] " << wave8_name << ": pulses_bit0=" << pulses_bit0
                << " pulses_bit1=" << pulses_bit1
                << " tick_ns=" << tick_ns
                << " -> T1=" << tx_timing.T1 << " T2=" << tx_timing.T2
                << " T3=" << tx_timing.T3);
    } else if (uses_wave3) {
        // Wave3 encoding: 3 ticks per LED bit, clock = 3/(T1+T2+T3) Hz
        const uint32_t period = timing.t1_ns + timing.t2_ns + timing.t3_ns;
        const uint32_t tick_ns = period / 3;
        const uint32_t ticks_bit0 = static_cast<uint32_t>(
            static_cast<float>(timing.t1_ns) / period * 3.0f + 0.5f);
        const uint32_t ticks_bit1 = static_cast<uint32_t>(
            static_cast<float>(timing.t1_ns + timing.t2_ns) / period * 3.0f + 0.5f);
        const uint32_t actual_t0h = ticks_bit0 * tick_ns;
        const uint32_t actual_t1h = ticks_bit1 * tick_ns;
        const uint32_t actual_period = 3 * tick_ns;
        tx_timing = fl::ChipsetTiming{
            actual_t0h,
            actual_t1h - actual_t0h,
            actual_period - actual_t1h,
            timing.reset_us,
            "LCD_CLOCKLESS_wave3"
        };
        FL_WARN("[RX TIMING] LCD_CLOCKLESS_wave3: ticks_bit0=" << ticks_bit0
                << " ticks_bit1=" << ticks_bit1
                << " tick_ns=" << tick_ns
                << " -> T1=" << tx_timing.T1 << " T2=" << tx_timing.T2
                << " T3=" << tx_timing.T3);
    } else {
        tx_timing = fl::ChipsetTiming{timing.t1_ns, timing.t2_ns, timing.t3_ns, timing.reset_us, timing.name};
    }
    // Wave8/wave3 encoding has timing jitter due to clock quantization and GPIO matrix latency
    // Use wider tolerance (200ns) to accommodate clock rounding
    const uint32_t tolerance = (uses_wave8 || uses_wave3) ? 200 : 170;
    auto rx_timing = fl::make4PhaseTiming(tx_timing, tolerance);
 
    // Enable gap tolerance for PARLIO/SPI DMA gaps
    // PARLIO: ~20µs typical gaps during buffer transitions
    // SPI: Can have longer inter-frame gaps due to software encoding timing
    // Increased to 100µs to accommodate SPI driver timing variations
    rx_timing.gap_tolerance_ns = 100000; // 100µs (was 30µs)
 
    FL_WARN("[CAPTURE] Decoding...");
    auto decode_result = rx_channel->decode(rx_timing, rx_buffer);
 
    if (!decode_result.ok()) {
        // Use FL_WARN instead of FL_ERROR to avoid triggering bash autoresearch exit
        // This can happen during warmup/setup and is not fatal
        FL_WARN("Decode failed (error code: " << static_cast<int>(decode_result.error()) << ")");
        // Print raw edge timing on decode failure to diagnose the issue
        dumpRawEdgeTiming(rx_channel, timing, fl::EdgeRange(0, 256));
        return 0;
    }
 
    FL_WARN("[CAPTURE] Decoded " << decode_result.value() << " bytes");
    return decode_result.value();
}

References fl::canUseWave3(), fl::span< T, Extent >::data(), decodeSpiEdges(), dumpRawEdgeTiming(), fl::RxChannelConfig::edge_capacity, FastLED, FL_ERROR, FL_WARN, fl::RxChannelConfig::hz, fl::RxChannelConfig::io_loop_back, fl::make4PhaseTiming(), fl::memset(), fl::ChipsetTimingConfig::name, fl::ChipsetTimingConfig::reset_us, fl::span< T, Extent >::size(), fl::sstream::str(), fl::strcmp(), fl::SUCCESS, fl::ChipsetTiming::T1, fl::ChipsetTimingConfig::t1_ns, fl::ChipsetTiming::T2, fl::ChipsetTimingConfig::t2_ns, fl::ChipsetTiming::T3, fl::ChipsetTimingConfig::t3_ns, and fl::RxChannelConfig::use_dma.

Referenced by runMultiTest(), and runTest().

Here is the call graph for this function:

Here is the caller graph for this function: