Add intermediate clock speeds: 18, 23, 27 MHz (#79)

Author: stuartparmenter

components/hub75/Kconfig

@@ -318,19 +318,28 @@ menu "HUB75 RGB LED Matrix Driver"
                   - ESP32-S3/P4/C6: 32 MHz
 
             config HUB75_CLK_8MHZ
-                bool "8 MHz (Very Conservative)"
+                bool "8 MHz"
 
             config HUB75_CLK_10MHZ
-                bool "10 MHz (Conservative)"
+                bool "10 MHz"
 
             config HUB75_CLK_16MHZ
-                bool "16 MHz (Good Balance)"
+                bool "16 MHz"
+
+            config HUB75_CLK_18MHZ
+                bool "18 MHz"
 
             config HUB75_CLK_20MHZ
                 bool "20 MHz (Recommended)"
 
+            config HUB75_CLK_23MHZ
+                bool "23 MHz"
+
+            config HUB75_CLK_27MHZ
+                bool "27 MHz"
+
             config HUB75_CLK_32MHZ
-                bool "32 MHz (ESP32-S3/P4/C6 only)"
+                bool "32 MHz"
         endchoice
 
         config HUB75_MIN_REFRESH_RATE

components/hub75/include/hub75_types.h

@@ -33,8 +33,9 @@ enum class Hub75ColorOrder {
 /**
  * @brief Output clock speed options
  *
- * Platform limits: ESP32 max 10MHz, ESP32-S2 max 20MHz, ESP32-S3/P4/C6 max 32MHz.
- * Unsupported speeds fall back to platform max with a warning.
+ * Requested speeds are resolved to the nearest achievable frequency based on
+ * hardware clock divider constraints. See docs/PLATFORMS.md for details on
+ * actual frequencies and platform limitations.
  *
  * Note: Panel and wiring quality are often the limiting factor. If you see
  * visual artifacts or instability, try reducing the clock speed.
@@ -43,8 +44,11 @@ enum class Hub75ClockSpeed : uint32_t {
   HZ_8M = 8000000,
   HZ_10M = 10000000,
   HZ_16M = 16000000,
+  HZ_18M = 18000000,
   HZ_20M = 20000000,  // default
-  HZ_32M = 32000000,  // ESP32-S3/P4/C6 only
+  HZ_23M = 23000000,
+  HZ_27M = 27000000,
+  HZ_32M = 32000000,
 };
 
 /**

components/hub75/src/platforms/gdma/gdma_dma.cpp

@@ -79,6 +79,7 @@ GdmaDma::GdmaDma(const Hub75Config &config)
       dma_chan_(nullptr),
       bit_depth_(HUB75_BIT_DEPTH),
       lsbMsbTransitionBit_(0),
+      actual_clock_hz_(resolve_actual_clock_speed(config.output_clock_speed)),
       panel_width_(config.panel_width),
       panel_height_(config.panel_height),
       layout_rows_(config.layout_rows),
@@ -221,7 +222,8 @@ bool GdmaDma::init() {
            is_four_scan_wiring(scan_wiring_) ? "yes" : "no");
 
   ESP_LOGI(TAG, "LCD_CAM + GDMA initialized successfully");
-  ESP_LOGI(TAG, "Clock: %u MHz", (unsigned int) (static_cast<uint32_t>(config_.output_clock_speed) / 1000000));
+  ESP_LOGI(TAG, "Clock: %.2f MHz (requested %u MHz)", actual_clock_hz_ / 1000000.0f,
+           (unsigned int) (static_cast<uint32_t>(config_.output_clock_speed) / 1000000));
 
   // Calculate BCM timing (determines lsbMsbTransitionBit for OE control)
   calculate_bcm_timings();
@@ -264,11 +266,37 @@ bool GdmaDma::init() {
   return true;
 }
 
+HUB75_CONST uint32_t GdmaDma::resolve_actual_clock_speed(Hub75ClockSpeed clock_speed) const {
+  // ESP32-S3 LCD_CAM clock derivation:
+  //   Output = PLL_F160M / lcd_clkm_div_num
+  //   Constraint: lcd_clkm_div_num >= 2
+  //
+  // We use integer dividers only - no fractional dividers. Fractional dividers
+  // cause clock jitter because the hardware alternates between two integer
+  // dividers to approximate the fractional value. With pure integer division
+  // from the stable 160 MHz PLL, every clock cycle is identical.
+  //
+  // The resulting frequencies may not be round numbers (e.g., 160/7 = 22.86 MHz),
+  // but this is fine - what matters for signal integrity is that each clock
+  // period is exactly the same, not that the frequency is a nice decimal.
+  //
+  // Available speeds: 32 MHz (div=5), 26.67 MHz (div=6), 22.86 MHz (div=7),
+  //                   20 MHz (div=8), 17.78 MHz (div=9), 16 MHz (div=10), ...
+  uint32_t requested_hz = static_cast<uint32_t>(clock_speed);
+  uint32_t divider = (160000000 + requested_hz / 2) / requested_hz;  // Round to nearest
+  return 160000000 / std::max(divider, uint32_t{2});
+}
+
 void GdmaDma::configure_lcd_clock() {
   // Configure LCD clock from PLL_F160M (160 MHz)
-  // Calculate divider: 160MHz / desired_speed
-  uint32_t div_num = 160000000 / static_cast<uint32_t>(config_.output_clock_speed);
-  div_num = std::max(div_num, uint32_t{2});  // Minimum divider
+  // actual_clock_hz_ already resolved in constructor
+  uint32_t requested_hz = static_cast<uint32_t>(config_.output_clock_speed);
+  uint32_t div_num = 160000000 / actual_clock_hz_;
+
+  if (actual_clock_hz_ != requested_hz) {
+    ESP_LOGI(TAG, "Clock speed %u Hz rounded to %u Hz (160MHz / %u)", (unsigned int) requested_hz,
+             (unsigned int) actual_clock_hz_, (unsigned int) div_num);
+  }
 
   LCD_CAM.lcd_clock.lcd_clk_sel = 3;      // PLL_F160M_CLK (value 3, not 2!)
   LCD_CAM.lcd_clock.lcd_ck_out_edge = 0;  // PCLK low in 1st half cycle
@@ -279,8 +307,7 @@ void GdmaDma::configure_lcd_clock() {
   LCD_CAM.lcd_clock.lcd_clkm_div_a = 1;  // Fractional divider (0/1)
   LCD_CAM.lcd_clock.lcd_clkm_div_b = 0;
 
-  ESP_LOGI(TAG, "LCD clock: PLL_F160M / %u = %u MHz", (unsigned int) div_num,
-           (unsigned int) (160000000 / div_num / 1000000));
+  ESP_LOGI(TAG, "LCD clock: PLL_F160M / %u = %.2f MHz", (unsigned int) div_num, actual_clock_hz_ / 1000000.0f);
 }
 
 void GdmaDma::configure_lcd_mode() {
@@ -1204,10 +1231,10 @@ void GdmaDma::calculate_bcm_timings() {
   // Buffer contains dma_width_ pixels with LAT on last pixel
   // Latch blanking is handled via OE bits, not extra pixels
   const uint16_t buffer_pixels = dma_width_;  // LAT is on last pixel, not extra
-  const float buffer_time_us = (buffer_pixels * 1000000.0f) / static_cast<uint32_t>(config_.output_clock_speed);
+  const float buffer_time_us = (buffer_pixels * 1000000.0f) / actual_clock_hz_;
 
   ESP_LOGI(TAG, "Buffer transmission time: %.2f µs (%u pixels @ %lu Hz)", buffer_time_us, (unsigned) buffer_pixels,
-           (unsigned long) static_cast<uint32_t>(config_.output_clock_speed));
+           (unsigned long) actual_clock_hz_);
 
   // Target refresh rate from config
   const uint32_t target_hz = config_.min_refresh_rate;

components/hub75/src/platforms/gdma/gdma_dma.h

@@ -66,6 +66,11 @@ class GdmaDma : public PlatformDma {
    */
   void set_rotation(Hub75Rotation rotation) override;
 
+  /**
+   * @brief Resolve clock speed to achievable frequency (160 MHz / N)
+   */
+  HUB75_CONST uint32_t resolve_actual_clock_speed(Hub75ClockSpeed clock_speed) const override;
+
   // ============================================================================
   // Pixel API (Direct DMA Buffer Writes)
   // ============================================================================
@@ -126,8 +131,9 @@ class GdmaDma : public PlatformDma {
   void calculate_bcm_timings();
 
   gdma_channel_handle_t dma_chan_;
-  const uint8_t bit_depth_;      // Bit depth from config (6, 7, 8, 10, or 12)
-  uint8_t lsbMsbTransitionBit_;  // BCM optimization threshold (calculated at init)
+  const uint8_t bit_depth_;         // Bit depth from config (6, 7, 8, 10, or 12)
+  uint8_t lsbMsbTransitionBit_;     // BCM optimization threshold (calculated at init)
+  const uint32_t actual_clock_hz_;  // Actual achieved clock frequency after rounding
 
   // Panel configuration (immutable, cached from config)
   const uint16_t panel_width_;

components/hub75/src/platforms/i2s/i2s_dma.cpp

@@ -104,7 +104,7 @@ I2sDma::I2sDma(const Hub75Config &config)
       i2s_dev_(nullptr),
       bit_depth_(HUB75_BIT_DEPTH),
       lsbMsbTransitionBit_(0),
-      actual_clock_hz_(0),
+      actual_clock_hz_(resolve_actual_clock_speed(config.output_clock_speed)),
       panel_width_(config.panel_width),
       panel_height_(config.panel_height),
       layout_rows_(config.layout_rows),
@@ -285,6 +285,50 @@ bool I2sDma::init() {
   return true;
 }
 
+HUB75_CONST uint32_t I2sDma::resolve_actual_clock_speed(Hub75ClockSpeed clock_speed) const {
+  // I2S LCD mode clock derivation:
+  //   Output = base_clock / clkm_div / (tx_bck_div_num * 2)
+  //   We use tx_bck_div_num = 2, so: Output = base_clock / clkm_div / 4
+  //
+  // TRM Constraints (ESP32 TRM v5.3, Section 12.6):
+  //   - clkm_div >= 2: "I2S_CLKM_DIV_NUM: Integral I2S clock divider value.
+  //     fI2S = fCLK / I2S_CLKM_DIV_NUM (I2S_CLKM_DIV_NUM >= 2)"
+  //   - tx_bck_div_num >= 2: Required for LCD mode stability
+  //
+  // These constraints limit max achievable frequency significantly compared
+  // to ESP32-S3's LCD_CAM peripheral which has no such divider requirements.
+  uint32_t requested_hz = static_cast<uint32_t>(clock_speed);
+
+#if defined(CONFIG_IDF_TARGET_ESP32S2)
+  // ESP32-S2: PLL_160M clock source (160 MHz base)
+  // Max output: 160 / 2 / 4 = 20 MHz (with minimum dividers)
+  // Available: 20 MHz (div=2), 13.33 MHz (div=3), 10 MHz (div=4), 8 MHz (div=5), ...
+  //
+  // Note: Higher speeds would require clkm_div < 2, which violates TRM constraints
+  // and causes unreliable operation.
+  if (requested_hz > 20000000) {
+    ESP_LOGW(TAG, "Requested %u Hz exceeds ESP32-S2 max (20 MHz), using 20 MHz", (unsigned int) requested_hz);
+    return 20000000;
+  }
+  uint32_t divider = (160000000 + requested_hz * 2) / (requested_hz * 4);  // Round to nearest
+  return 160000000 / (std::max(divider, uint32_t{2}) * 4);
+
+#else
+  // ESP32: PLL_D2_CLK clock source (80 MHz base)
+  // Max output: 80 / 2 / 4 = 10 MHz (with minimum dividers)
+  // Available: 10 MHz (div=2), 6.67 MHz (div=3), 5 MHz (div=4), 4 MHz (div=5), ...
+  //
+  // The ESP32's lower base clock (80 MHz vs 160 MHz) combined with the same
+  // divider constraints results in half the max frequency of ESP32-S2.
+  if (requested_hz > 10000000) {
+    ESP_LOGW(TAG, "Requested %u Hz exceeds ESP32 max (10 MHz), using 10 MHz", (unsigned int) requested_hz);
+    return 10000000;
+  }
+  uint32_t divider = (80000000 + requested_hz * 2) / (requested_hz * 4);  // Round to nearest
+  return 80000000 / (std::max(divider, uint32_t{2}) * 4);
+#endif
+}
+
 void I2sDma::configure_i2s_timing() {
   auto *dev = i2s_dev_;
 
@@ -293,6 +337,12 @@ void I2sDma::configure_i2s_timing() {
   dev->sample_rate_conf.rx_bits_mod = 16;  // 16-bit parallel
   dev->sample_rate_conf.tx_bits_mod = 16;
 
+  // Clock already resolved in constructor
+  uint32_t requested_hz = static_cast<uint32_t>(config_.output_clock_speed);
+  if (actual_clock_hz_ != requested_hz) {
+    ESP_LOGI(TAG, "Clock speed %u Hz resolved to %u Hz", (unsigned int) requested_hz, (unsigned int) actual_clock_hz_);
+  }
+
 #if defined(CONFIG_IDF_TARGET_ESP32S2)
   // ESP32-S2: PLL_160M clock source
   // Output Frequency = 160MHz / clkm_div_num / (tx_bck_div_num * 2)
@@ -302,32 +352,8 @@ void I2sDma::configure_i2s_timing() {
   dev->clkm_conf.clkm_div_a = 1;
   dev->clkm_conf.clkm_div_b = 0;
 
-  unsigned int clkm_div;
-  unsigned int actual_freq;
-  switch (config_.output_clock_speed) {
-    case Hub75ClockSpeed::HZ_32M:
-      // 32MHz not achievable on ESP32-S2 (max 20MHz), falling back
-      ESP_LOGW(TAG, "32MHz not achievable on ESP32-S2 (max 20MHz), falling back to 20MHz");
-      [[fallthrough]];
-    case Hub75ClockSpeed::HZ_20M:
-      clkm_div = 2;  // 160/2/4 = 20MHz
-      actual_freq = 20;
-      break;
-    case Hub75ClockSpeed::HZ_16M:
-      // 16MHz not achievable exactly with integer dividers, falling back to 10MHz
-      ESP_LOGW(TAG, "16MHz not achievable on ESP32-S2, falling back to 10MHz");
-      [[fallthrough]];
-    case Hub75ClockSpeed::HZ_10M:
-      clkm_div = 4;  // 160/4/4 = 10MHz
-      actual_freq = 10;
-      break;
-    case Hub75ClockSpeed::HZ_8M:
-      clkm_div = 5;  // 160/5/4 = 8MHz
-      actual_freq = 8;
-      break;
-    default:
-      __builtin_unreachable();
-  }
+  // Calculate divider from actual frequency: actual = 160M / (div * 4)
+  unsigned int clkm_div = 160000000 / (actual_clock_hz_ * 4);
 
   dev->clkm_conf.clkm_div_num = clkm_div;
   dev->clkm_conf.clk_en = 1;
@@ -336,67 +362,29 @@ void I2sDma::configure_i2s_timing() {
   dev->sample_rate_conf.rx_bck_div_num = 2;
   dev->sample_rate_conf.tx_bck_div_num = 2;
 
-  // Store actual clock frequency for BCM timing calculations
-  actual_clock_hz_ = actual_freq * 1000000;
-
-  ESP_LOGI(TAG, "ESP32-S2 I2S clock: 160MHz / %u / 4 = %u MHz", clkm_div, actual_freq);
+  ESP_LOGI(TAG, "ESP32-S2 I2S clock: 160MHz / %u / 4 = %.2f MHz (requested %u MHz)", clkm_div,
+           actual_clock_hz_ / 1000000.0f, (unsigned int) (requested_hz / 1000000));
 
 #else
   // ESP32: PLL_D2_CLK clock source (80MHz)
   // Output Frequency = 80MHz / clkm_div_num / (tx_bck_div_num * 2)
   // Reference: ESP32 TRM v5.3, Section 12.5 (I2S Clock)
   // Constraints: clkm_div_num >= 2, tx_bck_div_num >= 2 (TRM Section 12.6)
-  //
-  // NOTE: Maximum achievable frequency is 10MHz with minimum dividers (2, 2).
-  // Higher frequencies (16/20MHz) would require clkm_div_num < 2 which violates
-  // TRM constraints. The TRM states: "I2S_CLKM_DIV_NUM: Integral I2S clock
-  // divider value. fI2S = fCLK / I2S_CLKM_DIV_NUM (I2S_CLKM_DIV_NUM >= 2)"
   dev->clkm_conf.clka_en = 0;  // PLL_D2_CLK (80MHz)
   dev->clkm_conf.clkm_div_a = 1;
   dev->clkm_conf.clkm_div_b = 0;
 
-  unsigned int clkm_div;
-  unsigned int actual_freq;
-  switch (config_.output_clock_speed) {
-    case Hub75ClockSpeed::HZ_32M:
-      ESP_LOGW(TAG, "32MHz not achievable on ESP32 (max 10MHz), falling back to 10MHz");
-      clkm_div = 2;  // 80/2/4 = 10MHz
-      actual_freq = 10;
-      break;
-    case Hub75ClockSpeed::HZ_20M:
-      ESP_LOGW(TAG, "20MHz not achievable on ESP32 (max 10MHz), falling back to 10MHz");
-      clkm_div = 2;  // 80/2/4 = 10MHz
-      actual_freq = 10;
-      break;
-    case Hub75ClockSpeed::HZ_16M:
-      ESP_LOGW(TAG, "16MHz not achievable on ESP32 (max 10MHz), falling back to 10MHz");
-      clkm_div = 2;  // 80/2/4 = 10MHz
-      actual_freq = 10;
-      break;
-    case Hub75ClockSpeed::HZ_10M:
-      clkm_div = 2;  // 80/2/4 = 10MHz
-      actual_freq = 10;
-      break;
-    case Hub75ClockSpeed::HZ_8M:
-      // 8MHz not achievable exactly, closest is 5MHz
-      ESP_LOGW(TAG, "8MHz not achievable on ESP32, falling back to 5MHz");
-      clkm_div = 4;  // 80/4/4 = 5MHz
-      actual_freq = 5;
-      break;
-    default:
-      __builtin_unreachable();
-  }
+  // Calculate divider from actual frequency: actual = 80M / (div * 4)
+  unsigned int clkm_div = 80000000 / (actual_clock_hz_ * 4);
 
   dev->clkm_conf.clkm_div_num = clkm_div;
 
   // BCK divider (must be >= 2 per TRM Section 12.6)
   dev->sample_rate_conf.tx_bck_div_num = 2;
   dev->sample_rate_conf.rx_bck_div_num = 2;
 
-  // Store actual clock frequency for BCM timing calculations
-  actual_clock_hz_ = actual_freq * 1000000;
-
-  ESP_LOGI(TAG, "ESP32 I2S clock: 80MHz / %u / 4 = %u MHz", clkm_div, actual_freq);
+  ESP_LOGI(TAG, "ESP32 I2S clock: 80MHz / %u / 4 = %.2f MHz (requested %u MHz)", clkm_div,
+           actual_clock_hz_ / 1000000.0f, (unsigned int) (requested_hz / 1000000));
 #endif
 }
 

components/hub75/src/platforms/i2s/i2s_dma.h

@@ -65,6 +65,14 @@ class I2sDma : public PlatformDma {
    */
   void set_rotation(Hub75Rotation rotation) override;
 
+  /**
+   * @brief Resolve clock speed to achievable frequency (I2S constraints)
+   *
+   * ESP32: max 10 MHz (80 MHz / 2 / 4)
+   * ESP32-S2: max 20 MHz (160 MHz / 2 / 4)
+   */
+  HUB75_CONST uint32_t resolve_actual_clock_speed(Hub75ClockSpeed clock_speed) const override;
+
   // ============================================================================
   // Pixel API (Direct DMA Buffer Writes)
   // ============================================================================
@@ -122,9 +130,9 @@ class I2sDma : public PlatformDma {
   void calculate_bcm_timings();
 
   volatile i2s_dev_t *i2s_dev_;
-  const uint8_t bit_depth_;      // Bit depth from config (6, 7, 8, 10, or 12)
-  uint8_t lsbMsbTransitionBit_;  // BCM optimization threshold (calculated at init)
-  uint32_t actual_clock_hz_;     // Actual I2S clock frequency (may differ from config due to fallbacks)
+  const uint8_t bit_depth_;         // Bit depth from config (6, 7, 8, 10, or 12)
+  uint8_t lsbMsbTransitionBit_;     // BCM optimization threshold (calculated at init)
+  const uint32_t actual_clock_hz_;  // Actual I2S clock frequency (may differ from config due to fallbacks)
 
   // Panel configuration (immutable, cached from config)
   const uint16_t panel_width_;