Make clock speed calculations more explicit (#59)

Author: stuartparmenter

components/hub75/Kconfig

@@ -282,10 +282,10 @@ menu "HUB75 RGB LED Matrix Driver"
                 Higher speeds = faster refresh, but may cause signal integrity
                 issues on long cables or with some panels.
 
-                  - 8 MHz: Very conservative
-                  - 10 MHz: Conservative, works with all panels
-                  - 16 MHz: Good balance
-                  - 20 MHz: Recommended default
+                Platform limits (falls back with warning if exceeded):
+                  - ESP32: 10 MHz max
+                  - ESP32-S2: 20 MHz max
+                  - ESP32-S3/P4/C6: 32 MHz
 
             config HUB75_CLK_8MHZ
                 bool "8 MHz (Very Conservative)"
@@ -298,6 +298,9 @@ menu "HUB75 RGB LED Matrix Driver"
 
             config HUB75_CLK_20MHZ
                 bool "20 MHz (Recommended)"
+
+            config HUB75_CLK_32MHZ
+                bool "32 MHz (ESP32-S3/P4/C6 only)"
         endchoice
 
         config HUB75_MIN_REFRESH_RATE

components/hub75/include/hub75_types.h

@@ -33,13 +33,18 @@ enum class Hub75ColorOrder {
 /**
  * @brief Output clock speed options
  *
- * Valid speeds that divide evenly from 160MHz base clock.
+ * 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.
+ *
+ * Note: Panel and wiring quality are often the limiting factor. If you see
+ * visual artifacts or instability, try reducing the clock speed.
  */
 enum class Hub75ClockSpeed : uint32_t {
-  HZ_8M = 8000000,    // 8 MHz
-  HZ_10M = 10000000,  // 10 MHz
-  HZ_16M = 16000000,  // 16 MHz
-  HZ_20M = 20000000,  // 20 MHz (default)
+  HZ_8M = 8000000,
+  HZ_10M = 10000000,
+  HZ_16M = 16000000,
+  HZ_20M = 20000000,  // default
+  HZ_32M = 32000000,  // ESP32-S3/P4/C6 only
 };
 
 /**

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

@@ -266,44 +266,110 @@ bool I2sDma::init() {
 
 void I2sDma::configure_i2s_timing() {
   auto *dev = i2s_dev_;
-  uint32_t freq = static_cast<uint32_t>(config_.output_clock_speed);
 
   // Sample rate configuration
   dev->sample_rate_conf.val = 0;
   dev->sample_rate_conf.rx_bits_mod = 16;  // 16-bit parallel
   dev->sample_rate_conf.tx_bits_mod = 16;
 
 #if defined(CONFIG_IDF_TARGET_ESP32S2)
-  // ESP32-S2: Use PLL_160M
+  // ESP32-S2: PLL_160M clock source
+  // Output Frequency = 160MHz / clkm_div_num / (tx_bck_div_num * 2)
+  // Reference: ESP32-S2 TRM v1.5, Section 12.5 (I2S Clock)
+  // Constraints: clkm_div_num >= 2, tx_bck_div_num >= 2 (TRM Section 12.6)
   dev->clkm_conf.clk_sel = 2;  // PLL_160M_CLK
   dev->clkm_conf.clkm_div_a = 1;
   dev->clkm_conf.clkm_div_b = 0;
 
-  // Output Frequency = (160MHz / clkm_div_num) / (tx_bck_div_num*2)
-  unsigned int div_num = (freq > 8000000) ? 2 : 4;  // 20MHz or 10MHz
-  dev->clkm_conf.clkm_div_num = div_num;
+  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();
+  }
+
+  dev->clkm_conf.clkm_div_num = clkm_div;
   dev->clkm_conf.clk_en = 1;
 
-  // BCK divider (must be >= 2 per TRM)
+  // BCK divider (must be >= 2 per TRM Section 12.6)
   dev->sample_rate_conf.rx_bck_div_num = 2;
   dev->sample_rate_conf.tx_bck_div_num = 2;
 
-  ESP_LOGI(TAG, "ESP32-S2 I2S clock: 160MHz / %d / 4 = %d MHz", div_num, 160 / div_num / 4);
+  ESP_LOGI(TAG, "ESP32-S2 I2S clock: 160MHz / %u / 4 = %u MHz", clkm_div, actual_freq);
+
 #else
-  // ESP32: Use PLL_D2 (80MHz)
-  dev->clkm_conf.clka_en = 0;     // Use PLL_D2_CLK (80MHz)
-  dev->clkm_conf.clkm_div_a = 1;  // Denominator
-  dev->clkm_conf.clkm_div_b = 0;  // Numerator
+  // 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: 80MHz / clkm_div_num / tx_bck_div_num
-  unsigned int div_num = (freq > 8000000) ? 2 : 4;  // 20MHz or 10MHz
-  dev->clkm_conf.clkm_div_num = div_num;
+  dev->clkm_conf.clkm_div_num = clkm_div;
 
-  // BCK divider (must be >= 2 per TRM)
+  // 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;
 
-  ESP_LOGI(TAG, "ESP32 I2S clock: 80MHz / %d / 4 = %d MHz", div_num, 80 / div_num / 4);
+  ESP_LOGI(TAG, "ESP32 I2S clock: 80MHz / %u / 4 = %u MHz", clkm_div, actual_freq);
 #endif
 }
 

docs/PLATFORMS.md

@@ -4,16 +4,87 @@ Detailed comparison and implementation notes for ESP32 platform variants.
 
 ## Platform Comparison Table
 
-| Feature | ESP32 / ESP32-S2 | ESP32-S3 | ESP32-P4 | ESP32-C6 |
-|---------|------------------|----------|----------|----------|
-| **Peripheral** | I2S (LCD mode) | LCD_CAM | PARLIO | PARLIO |
-| **DMA Engine** | I2S DMA | GDMA (AHB) | EDMA | EDMA |
-| **Memory** | Internal SRAM | Internal SRAM | **PSRAM** | Internal SRAM |
-| **Buffer Size** (64×64) | ~57 KB | ~57 KB | ~284 KB | ~284 KB |
-| **BCM Method** | Descriptor dup | Descriptor dup | Buffer padding | Buffer padding |
-| **Clock Gating** | No | No | **Yes** (MSB) | **No** |
-| **Max Clock** | 20 MHz | 40 MHz | 40 MHz+ | 40 MHz+ |
-| **Status** | ✅ Tested | ✅ Tested | ✅ Tested | ⏳ Planned |
+| Feature | ESP32 | ESP32-S2 | ESP32-S3 | ESP32-P4 | ESP32-C6 |
+|---------|-------|----------|----------|----------|----------|
+| **Peripheral** | I2S (LCD mode) | I2S (LCD mode) | LCD_CAM | PARLIO | PARLIO |
+| **DMA Engine** | I2S DMA | I2S DMA | GDMA (AHB) | EDMA | EDMA |
+| **Memory** | Internal SRAM | Internal SRAM | Internal SRAM | **PSRAM** | Internal SRAM |
+| **Buffer Size** (64×64) | ~57 KB | ~57 KB | ~57 KB | ~284 KB | ~284 KB |
+| **BCM Method** | Descriptor dup | Descriptor dup | Descriptor dup | Buffer padding | Buffer padding |
+| **Clock Gating** | No | No | No | **Yes** (MSB) | **No** |
+| **Max Clock** | 10 MHz | 20 MHz | 40 MHz | 40 MHz+ | 40 MHz+ |
+| **Status** | ✅ Tested | ✅ Tested | ✅ Tested | ✅ Tested | ⏳ Planned |
+
+---
+
+## Clock Speed Reference
+
+The achievable clock speeds depend on platform hardware constraints. The I2S peripheral
+on ESP32/ESP32-S2 has different clock divider limitations than the LCD_CAM and PARLIO
+peripherals on newer chips.
+
+### Clock Speed by Platform
+
+| Requested | ESP32 | ESP32-S2 | ESP32-S3 | ESP32-P4/C6 |
+|-----------|-------|----------|----------|-------------|
+| **32 MHz** | ⚠️ 10 MHz | ⚠️ 20 MHz | ✅ 32 MHz | ✅ 32 MHz |
+| **20 MHz** | ⚠️ 10 MHz | ✅ 20 MHz | ✅ 20 MHz | ✅ 20 MHz |
+| **16 MHz** | ⚠️ 10 MHz | ⚠️ 10 MHz | ✅ 16 MHz | ✅ 16 MHz |
+| **10 MHz** | ✅ 10 MHz | ✅ 10 MHz | ✅ 10 MHz | ✅ 10 MHz |
+| **8 MHz** | ⚠️ 5 MHz | ✅ 8 MHz | ✅ 8 MHz | ✅ 8 MHz |
+
+⚠️ = Falls back to nearest achievable frequency (warning logged at runtime)
+
+### ESP32 Clock Limitations
+
+The ESP32 uses PLL_D2_CLK (80 MHz) as the I2S clock source. The output frequency is:
+
+```
+Output = 80 MHz / clkm_div_num / (tx_bck_div_num × 2)
+```
+
+Per the ESP32 TRM (Section 12.6), both `clkm_div_num` and `tx_bck_div_num` must be ≥ 2.
+With minimum dividers (2, 2), the maximum achievable frequency is:
+
+```
+80 MHz / 2 / 4 = 10 MHz (maximum)
+```
+
+Higher frequencies (16/20 MHz) would require `clkm_div_num < 2`, which violates TRM
+constraints and produces undefined behavior.
+
+### ESP32-S2 Clock Configuration
+
+The ESP32-S2 uses PLL_160M (160 MHz) as the I2S clock source:
+
+```
+Output = 160 MHz / clkm_div_num / (tx_bck_div_num × 2)
+```
+
+With the same divider constraints, more frequencies are achievable:
+
+| Speed | clkm_div | Formula | Result |
+|-------|----------|---------|--------|
+| 20 MHz | 2 | 160/2/4 | 20 MHz ✓ |
+| 16 MHz | — | Not achievable with integer dividers | Falls back to 10 MHz |
+| 10 MHz | 4 | 160/4/4 | 10 MHz ✓ |
+| 8 MHz | 5 | 160/5/4 | 8 MHz ✓ |
+
+### ESP32-S3 / ESP32-P4 / ESP32-C6
+
+These platforms use LCD_CAM or PARLIO peripherals with simpler clock dividers:
+
+```
+Output = 160 MHz / div_num
+```
+
+All standard frequencies (8/10/16/20/32 MHz) are achievable with integer dividers.
+
+### References
+
+- ESP32 TRM v5.3, Section 12.5-12.6 (I2S Clock)
+- ESP32-S2 TRM v1.5, Section 12.5-12.6 (I2S Clock)
+- ESP32-S3 TRM, Chapter 26 (LCD_CAM)
 
 ---
 
@@ -66,7 +137,7 @@ Detailed comparison and implementation notes for ESP32 platform variants.
 ### Limitations
 
 - **I2S peripheral misuse**: Designed for audio, not parallel data
-- **20 MHz max clock**: Higher speeds may be unstable
+- **Clock speed limits**: ESP32 max 10 MHz, ESP32-S2 max 20 MHz (see [Clock Speed Reference](#clock-speed-reference))
 - **No PSRAM support**: All buffers must be internal SRAM
 
 ### Advantages

examples/common/board_config.h

@@ -205,6 +205,8 @@ static inline Hub75Config getMenuConfigSettings() {
   config.output_clock_speed = Hub75ClockSpeed::HZ_16M;
 #elif defined(CONFIG_HUB75_CLK_20MHZ)
   config.output_clock_speed = Hub75ClockSpeed::HZ_20M;
+#elif defined(CONFIG_HUB75_CLK_32MHZ)
+  config.output_clock_speed = Hub75ClockSpeed::HZ_32M;
 #endif
 
   // Performance settings