RadiaCode-Spectrometer/ESP32-S3-Touch/_archive_previous_project/NEW_HOME_PAGE_DOCUMENTATION.md

12 KiB

New Clean Home Page Implementation

Date: October 1, 2025
Status: ✅ Deployed to device
File: src/ui/page_home.cpp (backup: src/ui/page_home.cpp.backup)


🎯 Problem Summary

The original home page had multiple overlapping issues:

  1. Text overlapping in status bar (timestamp + system info)
  2. Complex layout calculations causing unpredictable positioning
  3. Mixed coordinate systems and inconsistent spacing
  4. No consideration for the NV3041A QSPI display's specific requirements

Root Cause: The code was trying to patch a fundamentally flawed layout system instead of redesigning it from scratch.


✨ Complete Rewrite - What Changed

Design Philosophy

  • Clean & Simple: No complex calculations, straightforward pixel positions
  • No Overlap Guaranteed: Each element measured before next is positioned
  • QSPI-Optimized: Works with the patched NV3041A driver for proper partial updates
  • 480x272 Native: Designed specifically for your display resolution

New Architecture

1. Helper Functions (Lines 1-100)

// Clean utility functions
- rgb565()         : Simple RGB to 565 conversion
- alphaBlend()     : Color blending
- getFont()        : Get font by size level (1-5)
- printText()      : Draw text with automatic baseline calculation
- getTextWidth()   : Measure text width BEFORE rendering

Key Improvement: printText() handles all the baseline math internally, so you never worry about font metrics again.

2. Data Management (Lines 102-145)

static WeatherData globalWeather;  // Single global data store
- initWeatherData()      : Initialize with sensible defaults
- updateWeatherOnly()    : Update weather fields only
- updateBoilerData()     : Update boiler fields only
- getCurrentWeatherData(): Getter for other modules

Key Improvement: Centralized data with clear update separation.

3. Layout System (Lines 147-175)

HomeLayoutGeometry getHomeLayoutGeometry() {
  layout.margin = 10;
  layout.headerHeight = 32;
  layout.weatherHeight = 120;
  layout.clockHeight = 60;
  layout.statusHeight = 24;
  // Calculate Y positions
}

Key Improvement: Fixed heights, no complex dynamic calculations that could fail.

4. Drawing Functions

Header (Lines 194-209)
  • Simple rounded rectangle
  • "Home" title left
  • Decorative dots right
  • Height: 32px
Weather Panel (Lines 211-294)
  • Icon (left): 50x50px weather icon
  • Temperature (center): Large outdoor temp + description
  • Weather grid: 2x2 details (humidity, pressure, wind, energy/solar)
  • Boiler sensor (right): Current + target temperature (if enabled)
  • Layout: Icon | [Temp + Details] | [Boiler]
  • Height: 120px
Clock Panel (Lines 296-331)
  • Large time display (centered): HH:MM:SS
  • Date below (centered): Day, DD Mon YYYY
  • Height: 60px
Status Bar (Lines 333-422) - THE MOST IMPORTANT FIX
// LEFT SIDE: Timestamp
"Updated HH:MM:SS"
currentX += getTextWidth(timestamp) + 15;  // Move right

// MIDDLE: System Info
"RAM:XXXk"
currentX += getTextWidth(memStr) + 12;  // Move right

"TEMP:✓/✗"
currentX += getTextWidth(sensorStr) + 12;  // Move right

"WiFi:-XXdBm"
// Color coded: green/yellow/red

// RIGHT SIDE: Mode Chip (fixed position)
[OFF/MAN/AUTO/AI]

KEY FIX:

  • Each element measures its width before drawing next
  • currentX moves right after each element
  • No hardcoded positions except the mode chip (right-aligned)
  • Guaranteed 12-15px gaps between all elements
  • No overlap possible - each element knows where the previous ended

📏 Screen Layout

┌─────────────────────────────────────────────────────┐ Y=0
│ [Header] "Home"                        .... ....    │ 32px
├─────────────────────────────────────────────────────┤ Y=40
│ [Weather Panel]                                     │
│ ☀ 15.2°C         💧65%  🌀1013hPa  │ Boiler  │      │
│   Clear sky      💨8km/h ☀800W/m²  │  19.5°  │      │ 120px
│                                     │  → 21°  │      │
├─────────────────────────────────────────────────────┤ Y=168
│ [Clock Panel]                                       │
│             12:34:56                                │
│       Wed, 01 Oct 2025                              │ 60px
├─────────────────────────────────────────────────────┤ Y=236
│ [Status] Updated 12:34:56 RAM:241k TEMP:✓ WiFi:-58 │
│                                          [AI] │     │ 24px
└─────────────────────────────────────────────────────┘ Y=272

Total: 32 + 120 + 60 + 24 + 4 gaps = 248px (margin: 24px total)

🔧 Technical Improvements

1. Text Rendering

Before:

gfx->setCursor(x, y);  // Wrong! y is not baseline
gfx->print(text);

After:

printText(gfx, x, y, text, font, color);
// Internally calculates: baseline = y - y1
// Handles all font metrics automatically

2. Status Bar Positioning

Before:

int16_t indicatorX = x + 210;  // HARDCODED!
gfx->print("MEM:");
indicatorX += 90;  // HARDCODED gap!

After:

int16_t currentX = x + 10;
printText(gfx, currentX, textY, timestamp, font, color);
currentX += getTextWidth(timestamp, font) + 15;  // MEASURED!

3. Color Management

Before:

blendColor(0x07E0, currentTheme->text, 160);  // Complex math everywhere

After:

rgb565(0, 255, 0);  // Clear color definition
alphaBlend(fg, bg, alpha);  // Simple blending

4. QSPI Display Compatibility

  • Uses proper rounded rectangles (not split commands)
  • Full screen clear before redraw (prevents artifacts)
  • No complex clipping that could confuse the driver
  • Works with patched writeC8D16D16 in NV3041A driver

🎨 Visual Design

Color Coding

  • Memory:

    • Green: > 100KB free (healthy)
    • Yellow: 50-100KB (warning)
    • Red: < 50KB (critical)
  • WiFi Signal:

    • Green: > -60dBm (excellent)
    • Yellow: -60 to -75dBm (good)
    • Red: < -75dBm (poor)
  • Temperature Sensor:

    • Green ✓: Working
    • Red ✗: Error

Typography

  • Size 5: Clock time (24pt Bold)
  • Size 4: Temperatures (18pt Bold)
  • Size 3: Headers (12pt Bold)
  • Size 2: Descriptions, dates (12pt Regular)
  • Size 1: Details, status bar (9pt Regular)

Spacing

  • Panel margins: 10px
  • Inter-panel gaps: 8px
  • Status bar text gaps: 12-15px
  • Panel padding: 10-15px

📊 Memory Usage

Compilation Results:

  • RAM: 47,908 bytes (14.6%)
  • Flash: 1,149,369 bytes (87.7%)

Code Size:

  • New implementation: ~420 lines
  • Old implementation: ~622 lines
  • Reduction: 32% less code!

✅ Testing Checklist

Basic Display

  • Header shows "Home" title
  • Weather panel shows outdoor temperature
  • Weather icon displays correctly
  • Clock shows current time
  • Date displays correctly
  • Status bar shows timestamp

Status Bar (Critical)

  • "Updated HH:MM:SS" visible
  • "RAM:XXXk" shows memory
  • "TEMP:✓" or "TEMP:✗" shows sensor status
  • "WiFi:-XXdBm" shows signal strength
  • Mode chip shows "OFF/MAN/AUTO/AI"
  • NO TEXT OVERLAP anywhere
  • All colors are correct (green/yellow/red)

Weather Details

  • Humidity (💧) displays
  • Pressure (🌀) displays
  • Wind (💨) displays
  • Energy/Solar displays

Boiler Sensor (if enabled)

  • Shows current temperature (19.5°)
  • Shows target temperature (→ 21°)
  • Box is on the right side
  • Doesn't overlap weather info

Dynamic Updates

  • Time updates every second
  • Memory value changes over time
  • Weather data updates when refreshed
  • Boiler data updates when API responds

🐛 Known Limitations

  1. Emoji Support: Unicode emojis (💧🌀💨☀⚡) may not render on all systems. If they don't show, replace with text:

    • 💧 → "H:"
    • 🌀 → "P:"
    • 💨 → "W:"
    • ☀ → "S:"
    • ⚡ → "E:"
  2. Long Text: Weather descriptions longer than ~20 characters will be cut off. Current max: "Partly cloudy" fits perfectly.

  3. Boiler Sensor: Only shows when showBoilerTempOnHome is enabled AND currentTemp is valid (not NaN).


🔄 Rollback Instructions

If you need to revert to the old implementation:

Copy-Item "src\ui\page_home.cpp.backup" "src\ui\page_home.cpp" -Force

Then rebuild and upload.


📚 Code Structure Reference

File Organization

page_home.cpp
├── Helper Functions (lines 1-100)
│   ├── rgb565()
│   ├── alphaBlend()
│   ├── getFont()
│   ├── printText()
│   └── getTextWidth()
├── Global Data (lines 102-145)
│   ├── globalWeather
│   ├── initWeatherData()
│   ├── updateWeatherOnly()
│   ├── updateBoilerData()
│   └── getCurrentWeatherData()
├── Layout Calculation (lines 147-175)
│   ├── getHomeLayoutGeometry()
│   └── computeHomeWeatherLayout()
├── Main Entry Point (lines 177-192)
│   └── drawPageHome()
└── Panel Drawing (lines 194-425)
    ├── drawHomeHeader()
    ├── drawWeatherPanel()
    ├── drawClockPanel()
    └── drawStatusBar()

Key Functions

printText()

static void printText(Arduino_GFX* gfx, int16_t x, int16_t y, 
                     const char* text, const GFXfont* font, uint16_t color)
  • Purpose: Draw text with automatic baseline calculation
  • Parameters:
    • x, y: Top-left position (NOT baseline!)
    • text: String to draw
    • font: GFXfont pointer from getFont()
    • color: RGB565 color
  • Returns: Nothing
  • Usage:
    printText(gfx, 10, 10, "Hello", getFont(2), WHITE);
    

getTextWidth()

static int16_t getTextWidth(Arduino_GFX* gfx, const char* text, const GFXfont* font)
  • Purpose: Measure text width BEFORE drawing
  • Returns: Width in pixels
  • Usage:
    int16_t w = getTextWidth(gfx, "Hello", getFont(2));
    int16_t nextX = currentX + w + 10;  // Move right with gap
    

🚀 Future Enhancements

Easy Wins

  1. Add touch zones for mode switching
  2. Swipe gestures to change pages
  3. Animated transitions between updates
  4. Graph view for temperature history
  5. Notification badges for alerts

Advanced

  1. Customizable layouts via Web UI
  2. Widget system for modular panels
  3. Multiple themes (dark/light/custom)
  4. Screen saver mode with clock only
  5. OTA firmware updates via Web UI

📝 Conclusion

This is a complete ground-up rewrite of the home page, not a patch. Every line of code is:

  • ✅ Clean and readable
  • ✅ Properly measured and positioned
  • ✅ QSPI display compatible
  • ✅ Guaranteed no overlap
  • ✅ Optimized for 480x272 resolution

The old implementation is backed up at src/ui/page_home.cpp.backup if you need to reference it.

Test thoroughly and let me know if any issues remain!