Merge branch 'stage'

Author: effelle

components/cfx_effect/CFXRunner.cpp

@@ -646,13 +646,20 @@ static const uint32_t PaletteTwilight[16] CFX_PROGMEM = {
     0xFF00FF, 0xDD33FF, 0xBB66FF, 0x9999FF  // Magenta -> Lighter
 };
 
-// Palette 255: Solid Color - filled dynamically from segment.colors[0]
-static uint32_t PaletteSolid[16] = {0}; // Will be filled at runtime
+// Palette 255: Solid Color - filled dynamically from segment.colors[0].
+// Runners can be serviced on both ESP32 cores at the same time, so keep the
+// mutable solid palette per-core instead of sharing one write-heavy buffer.
+static uint32_t PaletteSolidPerCore[2][16] = {};
+
+static uint32_t *activeSolidPalette() {
+  return PaletteSolidPerCore[xPortGetCoreID()];
+}
 
 // Fill PaletteSolid with current color
 static void fillSolidPalette(uint32_t color) {
+  uint32_t *palette = activeSolidPalette();
   for (int i = 0; i < 16; i++) {
-    PaletteSolid[i] = color;
+    palette[i] = color;
   }
 }
 
@@ -704,7 +711,7 @@ static const uint32_t *getPaletteByIndex(uint8_t palette_index) {
   case 20:
     return PaletteSunnyGold;
   case 21:
-    return PaletteSolid;
+    return activeSolidPalette();
   case 22:
     return PaletteFairy;
   case 23:
@@ -718,7 +725,7 @@ static const uint32_t *getPaletteByIndex(uint8_t palette_index) {
   case 255:
     // Solid color mode - caller must call fillSolidPalette first
     // 21 = selector position, 255 = internal constant
-    return PaletteSolid;
+    return activeSolidPalette();
   default:
     return PaletteRainbow; // Fallback to Rainbow (most generic)
   }
@@ -2234,7 +2241,7 @@ uint16_t mode_dissolve(void) {
   if (!use_rainbow) {
     if (instance->_segment.palette == 255) {
       fillSolidPalette(instance->_segment.colors[0]);
-      active_palette = PaletteSolid;
+      active_palette = activeSolidPalette();
     } else {
       active_palette = getPaletteByIndex(instance->_segment.palette);
     }
@@ -3229,7 +3236,7 @@ uint16_t mode_percent(void) {
 
   const uint32_t *active_palette =
       (instance->_segment.palette == 0)
-          ? PaletteSolid // Default to Solid
+          ? activeSolidPalette() // Default to Solid
           : getPaletteByIndex(instance->_segment.palette);
 
   // Behavior:
@@ -3238,7 +3245,7 @@ uint16_t mode_percent(void) {
 
   if (instance->_segment.palette == 0 || instance->_segment.palette == 255) {
     fillSolidPalette(instance->_segment.colors[0]);
-    active_palette = PaletteSolid;
+    active_palette = activeSolidPalette();
   }
 
   for (int i = 0; i < len; i++) {
@@ -3285,12 +3292,12 @@ uint16_t mode_percent_center(void) {
 
   const uint32_t *active_palette =
       (instance->_segment.palette == 0)
-          ? PaletteSolid
+          ? activeSolidPalette()
           : getPaletteByIndex(instance->_segment.palette);
 
   if (instance->_segment.palette == 0 || instance->_segment.palette == 255) {
     fillSolidPalette(instance->_segment.colors[0]);
-    active_palette = PaletteSolid;
+    active_palette = activeSolidPalette();
   }
 
   for (int i = 0; i < len; i++) {
@@ -5811,7 +5818,7 @@ uint16_t mode_bouncing_balls(void) {
     if (instance->_segment.palette == 255 || instance->_segment.palette == 0) {
       // Default (0) or Explicit Solid (255) -> Use Primary Color
       fillSolidPalette(instance->_segment.colors[0]);
-      active_palette = PaletteSolid;
+      active_palette = activeSolidPalette();
     } else {
       active_palette = getPaletteByIndex(instance->_segment.palette);
     }
@@ -6245,7 +6252,7 @@ uint16_t color_wipe(bool rev, bool useRandomColors) {
   if (useRandomColors) {
     active_palette = PaletteRainbow;
   } else if (instance->_segment.palette == 255) {
-    active_palette = PaletteSolid;
+    active_palette = activeSolidPalette();
   } else {
     active_palette = getPaletteByIndex(instance->_segment.palette);
   }

components/cfx_effect/cfx_addressable_light_effect.cpp

@@ -2645,6 +2645,12 @@ bool CFXAddressableLightEffect::try_batch_steady_virtual_segments_(
     return false;
   }
   auto *parent = my_seg->get_parent();
+  if (parent->is_spi_transport()) {
+    // SPI parents already use the CFXLightOutput segment coordinator/coalesced
+    // flush path. The legacy steady batcher can be entered once per virtual
+    // segment apply and queue duplicate full-strip SPI frames.
+    return false;
+  }
 
   CFXAddressableLightEffect *effects[MAX_CFX_SEGMENTS]{};
   CFXRunner *runners[MAX_CFX_SEGMENTS]{};

components/cfx_effect/cfx_scheduler.cpp

@@ -126,7 +126,7 @@ bool CFXScheduler::service_runners(std::vector<CFXRunner *> &runners,
       if (this->last_batch_diag_ms_ == 0 ||
           (now_ms - this->last_batch_diag_ms_) >= 2000) {
         this->last_batch_diag_ms_ = now_ms;
-        ESP_LOGD(TAG,
+        ESP_LOGV(TAG,
                  "CFX sched_batch total=%u mode=sequential force=%u global=%u "
                  "core1=%u core0=0 cost1=0 cost0=0 dispatch_us=%u ok=1",
                  static_cast<unsigned>(total),
@@ -226,7 +226,7 @@ bool CFXScheduler::service_runners(std::vector<CFXRunner *> &runners,
       if (this->last_batch_diag_ms_ == 0 ||
           (now_ms - this->last_batch_diag_ms_) >= 2000) {
         this->last_batch_diag_ms_ = now_ms;
-        ESP_LOGD(TAG,
+        ESP_LOGV(TAG,
                  "CFX sched_batch total=%u mode=dual force=0 global=%u "
                  "core1=%u core0=%u cost1=%u cost0=%u dispatch_us=%u "
                  "ok=%u timeout_ms=%u",
@@ -259,7 +259,7 @@ bool CFXScheduler::service_runners(std::vector<CFXRunner *> &runners,
     if (this->last_batch_diag_ms_ == 0 ||
         (now_ms - this->last_batch_diag_ms_) >= 2000) {
       this->last_batch_diag_ms_ = now_ms;
-      ESP_LOGD(TAG,
+      ESP_LOGV(TAG,
                "CFX sched_batch total=%u mode=fallthrough force=%u global=%u "
                "core1=%u core0=0 cost1=0 cost0=0 dispatch_us=%u ok=1",
                static_cast<unsigned>(total),

components/cfx_light/cfx_light.cpp

@@ -664,6 +664,11 @@ void CFXLightOutput::release_outro_callback_storage_() {
   }
 }
 
+void CFXLightOutput::add_outro_callback(OutroCallback cb) {
+  this->outro_cbs_.push_back(cb);
+  this->update_high_frequency_loop_request_();
+}
+
 void CFXLightOutput::drain_outro_callbacks() {
   if (this->outro_cbs_.empty()) {
     return;
@@ -2473,6 +2478,7 @@ void CFXLightOutput::flush_parent_owned_segment_epoch_direct_(uint8_t mask,
 // all subsequent socket() calls to fail. close() is available via
 // lwip/sockets.h.
 CFXLightOutput::~CFXLightOutput() {
+  this->high_freq_loop_requester_.stop();
   if (this->socket_fd_ >= 0) {
     ::close(this->socket_fd_);
     this->socket_fd_ = -1;
@@ -2502,6 +2508,7 @@ void CFXLightOutput::on_shutdown() {
   if (this->transport_ == TRANSPORT_PARALLEL) {
     this->force_parallel_shutdown_blackout_();
   }
+  this->high_freq_loop_requester_.stop();
 }
 
 // --- Timing Configuration ---
@@ -5460,6 +5467,51 @@ static uint8_t active_parallel_group_mask_() {
   return active_mask;
 }
 
+bool CFXLightOutput::should_request_high_frequency_loop_() {
+  if (!this->setup_completed_ || this->is_failed()) {
+    return false;
+  }
+
+  // Governor: request high-frequency loop only while transport/service work is
+  // pending. Active effects alone can monopolize the main loop on dense nodes.
+  if (this->has_outro() || this->rmt_flush_pending_ ||
+      this->seg_flush_pending_) {
+    return true;
+  }
+
+  // SPI and Classic RMT need active-effect cadence restoration under ESPHome
+  // 2026.5+. Parallel remains governed by pending group work to preserve the
+  // validated S3 behavior and avoid monopolizing dense parallel nodes.
+  if ((this->is_spi_transport() || this->is_rmt_transport()) &&
+      has_active_rendering_cfx_effect(this)) {
+    return true;
+  }
+
+  if (this->is_parallel_transport()) {
+    auto &group = *parallel_group_for_output_(this);
+    if (group.pending_mask != 0 || group.pending_first_ms != 0) {
+      return true;
+    }
+#ifdef CFX_PARALLEL_I80_ENABLED
+    const uint8_t group_bit =
+        static_cast<uint8_t>(1u << group.group_index);
+    if ((g_parallel_i80.pending_group_mask & group_bit) != 0) {
+      return true;
+    }
+#endif
+  }
+
+  return false;
+}
+
+void CFXLightOutput::update_high_frequency_loop_request_() {
+  if (this->should_request_high_frequency_loop_()) {
+    this->high_freq_loop_requester_.start();
+  } else {
+    this->high_freq_loop_requester_.stop();
+  }
+}
+
 static bool parallel_shared_whole_group_mode_enabled_() {
 #if !defined(CONFIG_IDF_TARGET_ESP32) && defined(CFX_PARALLEL_I80_ENABLED)
   if (!g_parallel_i80.ready || parallel_configured_group_count_() < 2) {
@@ -5537,6 +5589,7 @@ bool CFXLightOutput::request_parallel_group_flush_() {
       active_parallel_lanes_mask_(g_parallel_group, lane_bit);
 
   if ((g_parallel_group.pending_mask & active_lanes_mask) != active_lanes_mask) {
+    this->update_high_frequency_loop_request_();
     return false;
   }
 
@@ -5623,6 +5676,7 @@ bool CFXLightOutput::request_parallel_shared_group_flush_() {
     }
     this->flush_parallel_shared_groups_(flush_mask);
   }
+  this->update_high_frequency_loop_request_();
   return false;
 #else
   return true;
@@ -6034,6 +6088,7 @@ void CFXLightOutput::on_segment_update() {
 // --- Component Loop (Intercepts Outro Playback) ---
 
 void CFXLightOutput::loop() {
+  this->update_high_frequency_loop_request_();
   this->record_parallel_completed_led_frames_();
 
   if (runtime_debug_enabled_for_output(this)) {
@@ -6173,6 +6228,7 @@ void CFXLightOutput::loop() {
   }
 
 segment_flush_done:
+  this->update_high_frequency_loop_request_();
 #ifdef USE_CFX_EVENTS
   chimera_fx::CFXEventManager::get().flush_pending();
 #endif
@@ -6403,6 +6459,10 @@ void CFXLightOutput::request_segment_flush(light::LightState *state) {
     this->log_segment_coordinator_diag_();
     return;
   }
+  if (state != nullptr && this->segment_coordinator_owns(state)) {
+    this->note_segment_coord_write_skip();
+    return;
+  }
 
   if (state != nullptr) {
     for (size_t i = 0; i < this->segment_light_states_.size() && i < 8; i++) {
@@ -6425,6 +6485,7 @@ void CFXLightOutput::request_segment_flush(light::LightState *state) {
   if (!this->seg_flush_pending_) {
     this->seg_flush_pending_ = true;
     this->seg_flush_first_ms_ = esphome::millis();
+    this->update_high_frequency_loop_request_();
   }
 
   const size_t segment_count = this->segment_light_states_.size();
@@ -6511,6 +6572,7 @@ void CFXLightOutput::write_state(light::LightState *state) {
   const bool rmt_cadence_diag_enabled =
       this->is_rmt_transport() && runtime_debug_enabled_for_output(this);
   const uint32_t write_start_us = micros();
+  this->update_high_frequency_loop_request_();
   this->perf_diag_last_flush_valid_ = false;
   this->perf_diag_last_flush_total_us_ = 0;
   this->perf_diag_last_flush_tx_us_ = 0;
@@ -6545,6 +6607,15 @@ void CFXLightOutput::write_state(light::LightState *state) {
   if (state != nullptr && !this->outro_cbs_.empty()) {
     return; // Block Master during outro on non-segmented lights
   }
+  if (state == nullptr && this->is_spi_transport() &&
+      this->has_active_parent_owned_segments_() && !this->has_outro()) {
+    // Parent-coordinated SPI segments flush through
+    // flush_parent_owned_segment_epoch_direct_(). A generic nullptr write can
+    // still be queued by ESPHome/legacy segment paths in the same visual frame,
+    // causing a second identical SPI DMA frame and inflated LedFPS.
+    this->note_segment_coord_write_skip();
+    return;
+  }
 
   // 1.2 Prevent Master paint from bleeding into OFF segments.
   // Skip during outro — the outro renders into the OFF segment's range;
@@ -6774,6 +6845,7 @@ void CFXLightOutput::write_state(light::LightState *state) {
       this->perf_diag_last_log_ms_ = now_ms;
     }
   }
+  this->update_high_frequency_loop_request_();
 }
 
 // --- RMT Transport Flush ---
@@ -6814,6 +6886,7 @@ void CFXLightOutput::flush_rmt_() {
       this->rmt_flush_pending_ = true;
       this->perf_diag_total_rmt_coalesced_flushes_++;
       this->perf_diag_last_flush_valid_ = false;
+      this->update_high_frequency_loop_request_();
       return;
     }
   }

components/cfx_light/cfx_light.h

@@ -206,7 +206,7 @@ class CFXLightOutput : public light::AddressableLight {
   int32_t size() const override { return this->num_leds_; }
   std::unique_ptr<light::LightTransformer> create_default_transition() override;
 
-  void add_outro_callback(OutroCallback cb) { this->outro_cbs_.push_back(cb); }
+  void add_outro_callback(OutroCallback cb);
   void drain_outro_callbacks();
   bool has_outro() const { return !this->outro_cbs_.empty(); }
   void note_show_request();
@@ -498,6 +498,8 @@ class CFXLightOutput : public light::AddressableLight {
       bool include_reset);
   bool flush_parallel_shared_groups_(uint8_t group_mask);
   void bind_force_white_switch_();
+  bool should_request_high_frequency_loop_();
+  void update_high_frequency_loop_request_();
   void maybe_apply_turn_on_defaults_(light::LightState *state, bool &prev_on_state);
   void repaint_force_white_solid_(bool state);
   void release_outro_callback_storage_();
@@ -562,6 +564,7 @@ class CFXLightOutput : public light::AddressableLight {
   // Pixel data buffer (written by effects via ESPColorView)
   uint8_t *buf_{nullptr};
   bool setup_completed_{false};
+  HighFrequencyLoopRequester high_freq_loop_requester_{};
 
   // Callbacks used to execute Outro animations after ESPHome turns the light
   // off

docs/Troubleshooting.md

@@ -64,6 +64,8 @@ ESP-IDF doesn't always play well with RGB lights. `ChimeraFX` tries to set the b
 - **ESP32-S3**: 192 total symbols, 48-symbol blocks.
 - **ESP32-C3**: 96 total symbols, 48-symbol blocks.
 
+On ESP32 Classic, automatic allocation is intentionally conservative and caps each RMT light at `128` symbols. This avoids the higher completion latency seen with larger automatic blocks on long strips. If you have a tested layout that benefits from larger buffers, set `rmt_symbols` manually: for example `512` for one RMT light, `256` each for two RMT lights, or `128` each for four RMT lights.
+
 For platform-specific output limits, see [`cfx_light`](cfx_light.md#hardware-architecture--performance-limits).
 
 Example configuration:

docs/cfx_light.md

@@ -62,7 +62,7 @@ light:
 * **is_wrgb** (*boolean*, default: `false`): Sets the white byte position to the front of the data packet. Required for some rare SK6812 variant clones.
 * **sacrificial_pixel** (*boolean*, default: `false`): RMT-only option. Transmits one extra black pixel before logical LED `0` to boost data signals on long wire runs.
 * **spi_speed** (*Frequency*): SPI clock speed for 2-wire strips.
-* **rmt_symbols** (*int*, default: `0`): Manual RMT symbol allocation. Leave at `0` for dynamic safe allocation.
+* **rmt_symbols** (*int*, default: `0`): Manual RMT symbol allocation. Leave at `0` for dynamic safe allocation. On ESP32 Classic, auto mode intentionally caps each RMT light at `128` symbols for the lowest-latency stable path; set this manually if a tested install should use more of the 512-symbol hardware pool.
 * **default_transition_length** (*Time*, default: `0s`): Standard ESPHome transition duration for solid-color mode and eligible effects.
 * **controls** (*boolean*, default: `true`): Automatically generate ChimeraFX control entities for this light.
 * **ctrl_exclude** (*list[int]*): Exclude specific auto-generated control groups by ID. See [Controls](Controls.md).
@@ -191,6 +191,7 @@ Rules of thumb:
     * **Stress Tests, Not Averages:** The numbers below represent the suggested maximum limits of the hardware. A device is intentionally pushed to find the maximum number of LEDs you can run while maintaining a *minimum* of ~30 FPS and keeping the device stable.
     * **Higher FPS:** These are not the best performances you can get! By simply reducing the number of LEDs to normal room-scale amounts, performance will scale up smoothly to **~60 FPS**.
     * **Benchmark Details:** Every test ran for at least 20 minutes using the `Energy` effect, chosen because it represents one of the heaviest mathematical loads in the library. This guarantees real-world stability for even the most demanding setups.
+    * **Strip Type:** The matrix was measured with SK-class RGBW strips. Simpler 3-byte WS-class RGB strips can reduce heap pressure and may run roughly **10-15% faster** because each frame carries less pixel data.
     * **Segment Sizing:** In the tables below, segmented lights were tested using equal-sized segments (e.g., 4x200 or 8x175). Please note that **this is not a limitation**. You can customize your segments to any size; equal sizes were used purely to establish a consistent testing baseline.
     !!! note "Result labels"
         `PASS` means Heap WiFi >= 75kB.