More doc cleanup

stuartparmenter · stuartparmenter · commit 9c7816d5b504 · 2025-10-30T20:34:45.000-07:00
diff --git a/README.md b/README.md
@@ -1,5 +1,8 @@
 # ESP32 HUB75 DMA Driver
 
+[![ESP Component Registry](https://components.espressif.com/components/stuartparmenter/esp-hub75/badge.svg)](https://components.espressif.com/components/stuartparmenter/esp-hub75)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/stuartparmenter/library/esp-hub75.svg)](https://registry.platformio.org/libraries/stuartparmenter/esp-hub75)
+
 High-performance DMA-based driver for HUB75 RGB LED matrix panels, supporting ESP32, ESP32-S2, ESP32-S3, ESP32-C6, and ESP32-P4.
 
 ## Features
@@ -24,7 +27,19 @@ High-performance DMA-based driver for HUB75 RGB LED matrix panels, supporting ES
 
 ## Installation
 
-Add to your project via Component Manager (`idf_component.yml`):
+### ESP-IDF Component Manager
+
+Add to your project's `idf_component.yml`:
+
+```yaml
+dependencies:
+  hub75:
+    version: "^0.1.0"
+```
+
+Browse on the [ESP Component Registry](https://components.espressif.com/components/stuartparmenter/esp-hub75).
+
+Or install from git:
 
 ```yaml
 dependencies:
@@ -33,13 +48,57 @@ dependencies:
     path: components/hub75  # Important: point to the component subdirectory!
 ```
 
+### PlatformIO
+
+Add to `platformio.ini`:
+
+```ini
+lib_deps =
+    stuartparmenter/esp-hub75@^0.1.0
+```
+
+Browse on the [PlatformIO Registry](https://registry.platformio.org/libraries/stuartparmenter/esp-hub75).
+
+### Manual Installation
+
 See [Component Documentation](components/hub75/README.md) for manual installation options.
 
 ## Quick Start
 
-Configure your panel hardware, set GPIO pins, call `begin()`, and start drawing pixels. The driver handles continuous DMA refresh automatically - no CPU intervention needed after initialization. Supports single pixels (`set_pixel`), bulk writes (`draw_pixels`), and double buffering for tear-free animation.
+```cpp
+#include "hub75.h"
+
+void app_main() {
+    // Configure your panel
+    Hub75Config config{};
+    config.panel_width = 64;
+    config.panel_height = 64;
+    config.scan_pattern = Hub75ScanPattern::SCAN_1_32;
+    config.shift_driver = ShiftDriver::FM6126A;  // Try this if GENERIC doesn't work
+
+    // Set GPIO pins (example for ESP32-S3)
+    config.pins.r1 = 42; config.pins.g1 = 41; config.pins.b1 = 40;
+    config.pins.r2 = 38; config.pins.g2 = 39; config.pins.b2 = 37;
+    config.pins.a = 45; config.pins.b = 36; config.pins.c = 48;
+    config.pins.d = 35; config.pins.e = 21;
+    config.pins.lat = 47; config.pins.oe = 14; config.pins.clk = 2;
+
+    // Initialize and draw
+    Hub75Driver driver(config);
+    driver.begin();
+    driver.set_pixel(10, 10, 255, 0, 0);  // Red pixel at (10,10)
+}
+```
+
+See [examples/01_basic/simple_colors](examples/01_basic/simple_colors) for complete working example and [examples/common/](examples/common/) for board-specific pin configurations.
+
+## Getting Started Paths
 
-See [examples/](examples/) for working code and [Component Documentation](components/hub75/README.md) for complete API reference.
+- **First time with HUB75 panels?** → See [Quick Start](#quick-start) above, then try [examples/01_basic/](examples/)
+- **Setting up multiple panels?** → See [Multi-Panel Guide](docs/MULTI_PANEL.md)
+- **Display not working?** → See [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
+- **Want to understand the internals?** → See [Architecture Overview](docs/ARCHITECTURE.md)
+- **Need complete API reference?** → See [Component Documentation](components/hub75/README.md)
 
 ## Building & Testing Standalone
 
diff --git a/components/hub75/README.md b/components/hub75/README.md
@@ -17,7 +17,17 @@ ESP-IDF component for driving HUB75 RGB LED matrix panels via DMA. Supports ESP3
 
 ### Option 1: Component Manager (Recommended)
 
-In your project's `idf_component.yml`:
+**From ESP Component Registry:**
+
+```yaml
+dependencies:
+  hub75:
+    version: "^1.0.0"
+```
+
+Browse versions on the [ESP Component Registry](https://components.espressif.com/components/stuartparmenter/esp-hub75).
+
+**From Git:**
 
 ```yaml
 dependencies:
@@ -26,7 +36,7 @@ dependencies:
     path: components/hub75  # Important: point to subdirectory!
 ```
 
-For local development:
+**For local development:**
 
 ```yaml
 dependencies:
@@ -149,197 +159,69 @@ Double buffering doubles memory usage but enables tear-free animation. PARLIO us
 
 ## Configuration Options
 
-### Hardware Specifications
-
-```cpp
-Hub75Config config{};  // Start with defaults
-
-// Single Panel Hardware
-config.panel_width = 64;                               // Single panel width in pixels
-config.panel_height = 64;                              // Single panel height in pixels
-config.scan_pattern = Hub75ScanPattern::SCAN_1_32;     // Hardware scan pattern
-config.scan_wiring = ScanPattern::STANDARD_TWO_SCAN;   // Coordinate remapping
-config.shift_driver = ShiftDriver::GENERIC;            // LED driver chip type
-```
-
-**Scan Pattern Options:**
-- `SCAN_1_2` - 2-row pairs (4px high panels)
-- `SCAN_1_4` - 4-row pairs (8px high panels)
-- `SCAN_1_8` - 8-row pairs (16px high panels)
-- `SCAN_1_16` - 16-row pairs (32px high panels)
-- `SCAN_1_32` - 32-row pairs (64px high panels)
-
-Must match panel hardware. Formula: `num_rows = height / scan_pattern_value`
-
-**Scan Wiring Options:**
-- `STANDARD_TWO_SCAN` - Most panels (default, no coordinate remapping)
-- `FOUR_SCAN_16PX_HIGH` - Four-scan 1/4 scan, 16-pixel high panels
-- `FOUR_SCAN_32PX_HIGH` - Four-scan 1/8 scan, 32-pixel high panels
-- `FOUR_SCAN_64PX_HIGH` - Four-scan 1/8 scan, 64-pixel high panels
-
-For panels with non-standard internal wiring that require coordinate remapping.
-
-**Shift Driver Options:**
-- `GENERIC` - Standard panels with no special initialization (default)
-- `FM6126A` - Very common in modern panels (also works for ICN2038S)
-- `ICN2038S` - Alias for FM6126A (same initialization sequence)
-- `FM6124` - FM6124 family panels
-- `MBI5124` - MBI5124 panels (requires `clk_phase_inverted = true`)
-- `DP3246` - DP3246 panels (special timing requirements)
-
-**Tip:** If panel shows incorrect colors or doesn't light up with `GENERIC`, try `FM6126A` first - it's the most common driver chip in modern panels.
-
-### Multi-Panel Physical Layout
+### Quick Examples
 
+**Single 64×64 panel:**
 ```cpp
-// Multi-panel configuration (optional, defaults to single panel)
-config.layout_rows = 1;                                // Number of panels vertically
-config.layout_cols = 1;                                // Number of panels horizontally
-config.layout = PanelLayout::HORIZONTAL;               // Chaining pattern
+Hub75Config config{};
+config.panel_width = 64;
+config.panel_height = 64;
+config.scan_pattern = Hub75ScanPattern::SCAN_1_32;
+config.shift_driver = ShiftDriver::FM6126A;  // Try this if GENERIC doesn't work
 ```
 
-**Layout Options:**
-- `HORIZONTAL` - Simple left-to-right chain (single row only)
-- `TOP_LEFT_DOWN` - Serpentine, start top-left corner
-- `TOP_RIGHT_DOWN` - Serpentine, start top-right corner
-- `BOTTOM_LEFT_UP` - Serpentine, start bottom-left corner
-- `BOTTOM_RIGHT_UP` - Serpentine, start bottom-right corner
-- `TOP_LEFT_DOWN_ZIGZAG` - Zigzag, start top-left (all panels upright)
-- `TOP_RIGHT_DOWN_ZIGZAG` - Zigzag, start top-right (all panels upright)
-- `BOTTOM_LEFT_UP_ZIGZAG` - Zigzag, start bottom-left (all panels upright)
-- `BOTTOM_RIGHT_UP_ZIGZAG` - Zigzag, start bottom-right (all panels upright)
-
-**Serpentine vs Zigzag:**
-- **Serpentine**: Alternate rows are physically mounted upside down (saves cable length)
-- **Zigzag**: All panels mounted upright, cables route back between rows (longer cables)
-
-**Row-Major Chaining:** Panels chain HORIZONTALLY across rows (not vertically down columns). This matches the ESP32-HUB75-MatrixPanel-DMA reference library.
-
-### Performance & Timing
-
+**Two panels side-by-side:**
 ```cpp
-// Performance
-config.output_clock_speed = Hub75ClockSpeed::HZ_20M;   // Clock speed
-config.bit_depth = 8;                                   // BCM bit depth: 6-12
-config.min_refresh_rate = 60;                           // Minimum refresh rate in Hz
-
-// Timing
-config.latch_blanking = 1;                              // OE blanking cycles during LAT
-config.clk_phase_inverted = false;                      // Invert clock phase (MBI5124)
-
-// Features
-config.double_buffer = false;                           // Enable double buffering
-config.temporal_dither = false;                         // Enable temporal dithering (NYI)
-
-// Color
-config.gamma_mode = Hub75GammaMode::CIE1931;            // Gamma correction mode
-config.brightness = 128;                                // Initial brightness (0-255)
+config.layout_cols = 2;  // Two panels horizontally
+config.layout = PanelLayout::HORIZONTAL;
+// Virtual display: 128×64
 ```
 
-**Clock Speed Options:**
-- `HZ_8M` - 8 MHz (most compatible)
-- `HZ_10M` - 10 MHz
-- `HZ_16M` - 16 MHz
-- `HZ_20M` - 20 MHz (default, works with most panels)
-
-Higher speeds may cause signal integrity issues with long cables or poor-quality panels.
-
-**Bit Depth:**
-- 6-bit: Fast refresh, basic color depth
-- 8-bit: Good balance (default)
-- 10-bit: Better gradients, recommended for smooth animations
-- 12-bit: Best quality, slower refresh
-
-Higher bit depth = more descriptors + slower refresh rate.
-
-### Pin Configuration
-
+**Higher quality display:**
 ```cpp
-// GPIO pin assignments (example for ESP32-S3)
-config.pins.r1 = 25;   // Red data (top half)
-config.pins.g1 = 26;   // Green data (top half)
-config.pins.b1 = 27;   // Blue data (top half)
-config.pins.r2 = 14;   // Red data (bottom half)
-config.pins.g2 = 12;   // Green data (bottom half)
-config.pins.b2 = 13;   // Blue data (bottom half)
-config.pins.a = 23;    // Row address bit A
-config.pins.b = 19;    // Row address bit B
-config.pins.c = 5;     // Row address bit C
-config.pins.d = 17;    // Row address bit D
-config.pins.e = -1;    // Row address bit E (-1 if unused)
-config.pins.lat = 4;   // Latch
-config.pins.oe = 15;   // Output enable
-config.pins.clk = 16;  // Clock
+config.bit_depth = 10;         // Better gradients
+config.double_buffer = true;   // Tear-free updates
+config.min_refresh_rate = 90;  // Smoother for cameras
 ```
 
-**GPIO Restrictions:**
-- Avoid strapping pins (GPIO0, GPIO46, etc.)
-- ESP32-S3: GPIO19/20 unavailable if USB CDC enabled
-- Check ESP32 variant datasheets for input-only pins
-- Some platforms have restrictions on which peripherals can use which pins
-
-**Pre-configured Examples:** See repository [examples/common/pins_example.h](https://github.com/stuartparmenter/esp-hub75/blob/main/examples/common/pins_example.h) for tested pin configurations for different boards.
+**For complete configuration reference** (all scan patterns, layouts, clock speeds, bit depth options, pin configuration, etc.), see **[MENUCONFIG.md](../../docs/MENUCONFIG.md)**.
 
 ## Multi-Panel Layouts
 
-Chain multiple panels for larger displays. Panels connect **horizontally across rows** (row-major traversal).
+Chain multiple panels for larger displays:
 
-**Simple Example** (2 panels side-by-side):
 ```cpp
 config.panel_width = 64;
 config.panel_height = 64;
-config.layout_rows = 1;          // Single row
-config.layout_cols = 2;          // Two panels
-config.layout = PanelLayout::HORIZONTAL;
-// Virtual display: 128×64 pixels
+config.layout_rows = 2;    // Two rows vertically
+config.layout_cols = 3;    // Three panels per row
+config.layout = PanelLayout::TOP_LEFT_DOWN;  // Serpentine wiring
+// Virtual display: 192×128 pixels
 ```
 
-**Layout Types:**
-- `HORIZONTAL` - Simple left-to-right chain (single row)
-- `TOP_LEFT_DOWN` - Serpentine wiring (alternate rows upside down, saves cable)
-- `TOP_LEFT_DOWN_ZIGZAG` - Zigzag wiring (all panels upright, longer cables)
+Panels chain **horizontally across rows** (row-major). Serpentine layouts have alternate rows mounted upside down to save cable length.
 
-**For complete guide** including layout patterns, wiring diagrams, serpentine vs zigzag, coordinate remapping, and troubleshooting, see **[Multi-Panel Guide](../../docs/MULTI_PANEL.md)**.
+**For complete multi-panel guide** (layout patterns, wiring diagrams, coordinate remapping), see **[Multi-Panel Guide](../../docs/MULTI_PANEL.md)**.
 
-## Platform-Specific Notes
+## Platform Support
 
-| Platform | Status | Memory Pool | BCM Method | 64×64 Buffer |
-|----------|--------|-------------|------------|--------------|
-| **ESP32-S3** (GDMA) | ✅ Tested | Internal SRAM | Descriptor duplication | ~57 KB |
-| **ESP32/S2** (I2S) | ⏳ Not tested | Internal SRAM | Descriptor duplication | ~57 KB |
-| **ESP32-P4** (PARLIO) | ✅ Tested | **PSRAM** | Buffer padding + clock gating | ~284 KB |
-| **ESP32-C6** (PARLIO) | ⏳ Not tested | PSRAM | Buffer padding (no clock gating) | ~284 KB |
+Supports ESP32, ESP32-S2, ESP32-S3, and ESP32-P4 with platform-specific optimizations:
 
-**Key Differences:**
-- **GDMA/I2S**: Fast internal SRAM, uses descriptor chains for BCM timing
-- **PARLIO (P4/C6)**: Uses PSRAM (frees ~500 KB internal SRAM for your app), buffer padding for BCM timing
-- **ESP32-P4 specific**: Hardware clock gating via MSB for precise display timing
+- **ESP32/ESP32-S2** (I2S): ~57 KB SRAM, proven stability
+- **ESP32-S3** (GDMA): ~57 KB SRAM, faster clock (40 MHz), ghosting fix
+- **ESP32-P4** (PARLIO): ~284 KB PSRAM + ~16 KB SRAM, frees internal memory for apps
+- **ESP32-C6** (PARLIO): Planned, same as P4 but no clock gating
 
-**For detailed platform comparison**, implementation specifics, memory calculations, and when to choose each platform, see **[Platform Details](../../docs/PLATFORMS.md)** and **[Memory Usage](../../docs/MEMORY_USAGE.md)**.
+**For detailed platform comparison, memory calculations, and implementation specifics**, see **[Platform Details](../../docs/PLATFORMS.md)**.
 
 ## Troubleshooting
 
-### Common Issues
-
-**Black Screen:**
-- Try `shift_driver = ShiftDriver::FM6126A` (most modern panels)
-- Verify power supply adequate (3-5A per 64×64 panel)
-- Check pin mapping matches board layout
-
-**Wrong Colors:**
-- Try `FM6126A` shift driver
-- Verify R1/G1/B1/R2/G2/B2 pin connections
-- Check scan pattern matches panel height
-
-**Scrambled Display:**
-- Verify `scan_pattern` matches panel height (64px = SCAN_1_32)
-- Try `FOUR_SCAN_*` scan wiring variants for non-standard panels
-
-**MBI5124 Panels:**
-- Must set `shift_driver = ShiftDriver::MBI5124`
-- Must set `clk_phase_inverted = true`
+**Common quick fixes:**
+- **Black screen** → Try `shift_driver = ShiftDriver::FM6126A` (most modern panels)
+- **Wrong colors** → Check R1/G1/B1/R2/G2/B2 pin mapping
+- **Scrambled display** → Verify `scan_pattern` matches panel height (64px = SCAN_1_32)
 
-**For complete debugging guide** including ghosting, flickering, multi-panel issues, platform-specific problems, and error messages, see **[Troubleshooting Guide](../../docs/TROUBLESHOOTING.md)**.
+**For complete debugging guide** (ghosting, flickering, multi-panel issues, platform-specific problems, error messages), see **[Troubleshooting Guide](../../docs/TROUBLESHOOTING.md)**.
 
 ## Advanced Documentation
 
diff --git a/docs/MULTI_PANEL.md b/docs/MULTI_PANEL.md
@@ -108,6 +108,22 @@ Applications draw in virtual coordinates (0,0) to (width-1, height-1):
 - ✅ Cleaner physical installation
 - ⚠️ Must physically rotate alternate rows
 
+### Serpentine vs Zigzag Comparison
+
+| Factor | Serpentine | Zigzag |
+|--------|-----------|--------|
+| **Cable length** | ✅ Shorter (~50% savings) | ⚠️ Longer cables needed |
+| **Physical install** | ⚠️ Must rotate alternate rows 180° | ✅ All panels same orientation |
+| **Troubleshooting** | ⚠️ Harder (mixed orientations) | ✅ Easier (uniform) |
+| **Visual confirmation** | ⚠️ Text on alternate panels upside down | ✅ All labels readable |
+| **Best for** | Permanent installations, wall mounts | Prototyping, testing, temporary setups |
+
+**Choose Serpentine when:** Cable management and clean install matter more than convenience
+
+**Choose Zigzag when:** Ease of assembly/troubleshooting matters more than cable length
+
+---
+
 #### TOP_LEFT_DOWN (Serpentine)
 
 **Start**: Top-left corner
diff --git a/examples/README.md b/examples/README.md
