Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions components/core/LEDPixels/ESP32RMTLedStrip.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -130,12 +130,21 @@ bool ESP32RMTLedStrip::setup(const LEDStripConfig& config, uint32_t pixelIndexSt
};
_ledStripEncoderConfig = ledStripEncoderConfig;

// How long to wait for a frame to go out: from the frame length and the strip's bit and reset timing (a 0 bit
// and a 1 bit needn't take the same time, so the longer one counts)
uint32_t bit0Ticks = (uint32_t)config.T0H_ticks + config.T0L_ticks;
uint32_t bit1Ticks = (uint32_t)config.T1H_ticks + config.T1L_ticks;
uint32_t frameSyms = LEDStripRMTPlan::frameSymbols(config.numPixels, config.bytesPerPixel);
uint32_t frameUs = LEDStripRMTPlan::frameTimeUs(frameSyms, bit0Ticks > bit1Ticks ? bit0Ticks : bit1Ticks,
config.reset_ticks, config.rmtResolutionHz);
_showWaitUs = LEDStripRMTPlan::showWaitUs(frameUs);

// Now setup
_isSetup = true;

#ifdef DEBUG_ESP32RMTLEDSTRIP_SETUP
// Debug
LOG_I(MODULE_PREFIX, "setup ok %s", config.debugStr().c_str());
LOG_I(MODULE_PREFIX, "setup ok frame %dus wait %dus %s", (int)frameUs, (int)_showWaitUs, config.debugStr().c_str());
#endif

return true;
Expand Down Expand Up @@ -563,8 +572,8 @@ void ESP32RMTLedStrip::waitUntilShowComplete()

// We're not going to use rmt_tx_wait_all_done as it errors on timeout

// Max time to wait (WS2812B: ~30us per pixel = ~10us per byte, plus reset)
uint64_t maxWaitUs = WAIT_RMT_BASE_US + WAIT_RMT_PER_PIX_US * _pixelBuffer.size();
// Max time to wait: the frame time from the strip's timing, plus a margin (set in setup())
uint64_t maxWaitUs = _showWaitUs;
uint64_t startTimeUs = micros();
while (RaftAtomicBool_get(_txInProgress) && !Raft::isTimeout(micros(), startTimeUs, maxWaitUs))
{
Expand Down
6 changes: 3 additions & 3 deletions components/core/LEDPixels/ESP32RMTLedStrip.h
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,9 @@ class ESP32RMTLedStrip
SpiramAwareUint8Vector _lastTxBuffer;
bool _lastTxBufferValid = false;

// Wait for RMT complete (WS2812B: ~1.25us/bit × 8 bits = ~10us per byte, plus ~80us reset)
static const uint32_t WAIT_RMT_BASE_US = 150;
static const uint32_t WAIT_RMT_PER_PIX_US = 10;
// Longest wait for a frame to finish going out, from the strip's bit and reset timing (set in setup() -
// LEDStripRMTPlan::showWaitUs())
uint32_t _showWaitUs = 0;

// Helpers
bool initRMTPeripheral();
Expand Down
31 changes: 31 additions & 0 deletions components/core/LEDPixels/LEDStripRMTPlan.h
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@
// A refilled frame (no DMA, or a frame longer than the DMA buffer) is helped by a higher interrupt priority (see
// intrPriority()), but a critical section on the core still holds the interrupt off.
//
// Also how long a frame takes to go out (frameTimeUs()) and how long to wait for one before giving up on it
// (showWaitUs()): from the strip's bit and reset timing, so that a frame sent while the last one is still going out
// waits for it instead of being dropped.
//
// Raft-free so it can be host-tested (linux_unit_tests/test_led_strip_rmt_plan).
//
/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
Expand Down Expand Up @@ -71,6 +75,9 @@ class LEDStripRMTPlan
// to hold a frame whole
static constexpr uint32_t DMA_MARGIN_SYMBOLS = 32;

// Least margin on the wait for a frame to go out (showWaitUs())
static constexpr uint32_t SHOW_WAIT_MARGIN_US = 200;

/// @brief Symbols in a frame
/// @param numPixels pixels in the strip
/// @param bytesPerPixel bytes per pixel (3 for RGB, 5 for RGBWW)
Expand All @@ -79,6 +86,30 @@ class LEDStripRMTPlan
return numPixels * bytesPerPixel * 8 + RESET_SYMBOLS;
}

/// @brief Time a frame takes to go out
/// @param frameSyms symbols in the frame (frameSymbols()): one per bit, then the reset
/// @param bitTicks the longer bit period in RMT ticks (T0H + T0L or T1H + T1L)
/// @param resetTicks the reset period in RMT ticks
/// @param rmtResolutionHz RMT tick rate
/// @return microseconds, rounded up
static uint32_t frameTimeUs(uint32_t frameSyms, uint32_t bitTicks, uint32_t resetTicks, uint32_t rmtResolutionHz)
{
if (rmtResolutionHz == 0)
return 0;
uint32_t bits = frameSyms > RESET_SYMBOLS ? frameSyms - RESET_SYMBOLS : 0;
uint64_t ticks = (uint64_t)bits * bitTicks + resetTicks;
return (uint32_t)((ticks * 1000000 + rmtResolutionHz - 1) / rmtResolutionHz);
}

/// @brief Time to wait for a frame to finish going out before giving up on it (the frame time plus a margin for
/// the interrupt and the task that waits being late: a quarter of the frame time, at least SHOW_WAIT_MARGIN_US)
/// @param frameUs frame time (frameTimeUs())
static uint32_t showWaitUs(uint32_t frameUs)
{
uint32_t margin = frameUs / 4;
return frameUs + (margin > SHOW_WAIT_MARGIN_US ? margin : SHOW_WAIT_MARGIN_US);
}

/// @brief DMA buffer for a frame (the whole frame if it fits in DMA_MAX_SYMBOLS)
static uint32_t dmaSymbols(uint32_t frameSyms)
{
Expand Down
2 changes: 1 addition & 1 deletion linux_unit_tests/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ make -C linux_unit_tests check DEV_TYPE_CATALOGUES="../../RaftI2C/linux_unit_tes
| `test_device_poll_timing` | `DevicePollTimingStats` (interval statistics, histogram, percentiles) and its recording at full poll starts in `DeviceStatus` |
| `test_protocol_exchange` | `ProtocolExchange`: a real-time stream session from start to final block, the file stream activity hook, and refusal of a stream to an unknown endpoint |
| `test_file_upload_okto` | `FileUploadOKTOProtocol`: when it acks - the first block, each batch, the last block, at once for the first block out of sequence (a lost block or one sent again), and on its timer - and that its acks stay in step with the host's batches after a loss or a timer ack |
| `test_led_strip_rmt_plan` | `LEDStripRMTPlan`: the RMT memory (or DMA buffer) an LED strip's channel asks for - the whole frame in RMT memory when it fits in the strip's share, DMA where the chip has it when it doesn't, then smaller sizes; shares between strips, a configured size, DMA modes and when a frame is refilled |
| `test_led_strip_rmt_plan` | `LEDStripRMTPlan`: the RMT memory (or DMA buffer) an LED strip's channel asks for - the whole frame in RMT memory when it fits in the strip's share, DMA where the chip has it when it doesn't, then smaller sizes; shares between strips, a configured size, DMA modes and when a frame is refilled; the time a frame takes from the strip's bit and reset timing, and the wait for it to go out |
| `test_mini_hdlc` | `MiniHDLC`: frames encoded and decoded again up to 70000 bytes (past 64 KB), the frame length limit, and a 200000-byte limit (as ProtocolRICSerial sets with PSRAM) kept rather than truncated to 16 bits |
| `test_rest_api_params` | `RestAPIEndpointManager`: `unencodeHTTPChars` decodes any `%XX` escape once (control characters, `'`, UTF-8, either hex case) and leaves non-escapes alone; query values are decoded and trimmed, path segments decoded after splitting |
| `test_comms_framing_vectors` | Makes the shared vectors `scripts/tests/hdlc_vectors.json` and `overascii_vectors.json` from `MiniHDLC` and `ProtocolOverAscii` and fails if the files differ (the RICRESTProtocol wiki examples are checked too). Client libraries (raftjs, raftpy) test their framing against these files. After an intended change to the framing, run `./test_comms_framing_vectors --write` and copy the files to the clients |
Expand Down
27 changes: 27 additions & 0 deletions linux_unit_tests/test_led_strip_rmt_plan.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
// - A longer frame gets DMA where the chip has it (the whole frame up to DMA_MAX_SYMBOLS), then the most RMT memory.
// - The share of TX memory is split between strips; a configured memBlockSymbols is used as given.
// - DMA modes; refill detection; interrupt priority.
// - Frame time from the strip's bit and reset timing, and the wait for a frame to go out.
//
/////////////////////////////////////////////////////////////////////////////////////////////////////////////////

Expand Down Expand Up @@ -34,6 +35,31 @@ static void testFrameSymbols()
TEST_ASSERT(Plan::frameSymbols(0, 3) == 1, "no pixels: reset only");
}

static void testFrameTimeUs()
{
printf("Running testFrameTimeUs...\n");
// 10 MHz ticks. WS2812B defaults (T0H 0.4 T0L 0.85 T1H 0.8 T1L 0.45, reset 100us): the longer bit is 1.2us (12
// ticks; 0.85us is 8 ticks)
uint32_t frame14 = Plan::frameSymbols(14, 3); // 336 bits
TEST_ASSERT(Plan::frameTimeUs(frame14, 12, 1000, 10000000) == 504, "14 WS2812B pixels: 403.2 + 100 us, rounded up");
// CogPro: T0H 0.3 T0L 0.9 T1H 0.7 T1L 0.6 (1.3us bits), 300us reset: 336 x 1.3 + 300 = 736.8us. The old fixed
// budget (150us + 10us per byte = 570us) gave up on this frame and dropped the next one
TEST_ASSERT(Plan::frameTimeUs(frame14, 13, 3000, 10000000) == 737, "14 CogPro pixels: 436.8 + 300 us");
TEST_ASSERT(Plan::frameTimeUs(Plan::frameSymbols(0, 3), 12, 1000, 10000000) == 100, "no pixels: the reset");
TEST_ASSERT(Plan::frameTimeUs(frame14, 12, 1000, 0) == 0, "no tick rate: 0");
// 20 MHz ticks: the same timing in twice the ticks gives the same time
TEST_ASSERT(Plan::frameTimeUs(frame14, 24, 2000, 20000000) == 504, "20 MHz ticks");
// A long strip: 300 RGBWW pixels, 12000 bits at 1.25us + 280us = 15.28ms (no 32-bit overflow in the ticks)
TEST_ASSERT(Plan::frameTimeUs(Plan::frameSymbols(300, 5), 25, 5600, 20000000) == 15280, "300 RGBWW pixels");

// Wait: the frame plus a quarter, at least 200us
TEST_ASSERT(Plan::showWaitUs(737) == 937, "737us frame: + 200us");
TEST_ASSERT(Plan::showWaitUs(800) == 1000, "800us frame: + 200us");
TEST_ASSERT(Plan::showWaitUs(804) == 1005, "804us frame: + a quarter");
TEST_ASSERT(Plan::showWaitUs(15280) == 19100, "15.28ms frame: + a quarter");
TEST_ASSERT(Plan::showWaitUs(0) == 200, "no frame: the margin");
}

static void testFitsInRMTMemory()
{
printf("Running testFitsInRMTMemory...\n");
Expand Down Expand Up @@ -154,6 +180,7 @@ static void testIntrPriority()
int main()
{
testFrameSymbols();
testFrameTimeUs();
testFitsInRMTMemory();
testDma();
testShares();
Expand Down
Loading