15 KiB
PROJECT INVESTIGATION SUMMARY
Overview
Comprehensive investigation of ESP32-S3 Touch UI project (Home IoT Controller) identified 20 bugs/issues ranging from critical to minor. The system displays weather, boiler heating control, and statistics on a 4.3" touchscreen.
🎯 KEY FINDINGS
System Architecture
┌─────────────────────────────────────────────────────────┐
│ ESP32-S3 DevKit │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────┐ │
│ │ Arduino_GFX Library (NV3041A QSPI) │ │
│ │ Display: 480x272 pixels, 16-bit color │ │
│ └──────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ UI Framework (ui_framework.cpp) │ │
│ │ - Page management (HOME, DASHBOARD, etc) │ │
│ │ - Theme system (DARK/LIGHT) │ │
│ │ - Navigation with 500ms lock │ │
│ └──────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Page Rendering (page_home.cpp, etc) │ │
│ │ - Home: Clock, Weather, Boiler, Status │ │
│ │ - Dashboard, Stats, Controls, Settings │ │
│ └──────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Data Sources │ │
│ │ - Weather API updates │ │
│ │ - Boiler sensor data │ │
│ │ - WiFi status │ │
│ └──────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Web Interface (data/*) │ │
│ │ - Dashboard.html with status polling │ │
│ │ - Builder for custom UI elements │ │
│ │ - Settings management │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
🔴 CRITICAL ISSUES (Fix Immediately)
1. Clock Seconds Frozen ⏰
Current Behavior:
┌─────────────────────────────┐
│ Clock Panel │
│ 14:32:45 │ ← Frozen! Never updates
│ Wed, 20 Oct 2024 │
└─────────────────────────────┘
Root Cause Flow:
drawPageHome() called on navigation
↓
drawClockPanel() draws "14:32:45"
↓
No refresh loop for HOME page
↓
Time remains static until user navigates away/back
↓
Clock appears BROKEN to user
Impact: ❌ Time display is useless; appears as broken feature
Solution: Add per-second refresh in uiLoop() that detects second change and triggers redraw
2. Text Overlaps in Multiple Panels 📝
Current Problem:
Weather Panel (Too Crowded):
┌─────────────────────────────────────────┐
│ ☀ Ext Temp: 15.2°C │
│ Mostly Cloudy (overlaps→) │ Boiler │ ← Overlap!
│ 💧 65% 🌀 1013hPa │
│ 💨 8.5km/h ⚡ 45.5kWh │ 19.5° │ ← Overlap!
│ │ → 21° │
└─────────────────────────────────────────┘
↑
No margin calculation
Status Bar (Text Overflow):
┌──────────────────────────────────────────────┐
│ Updated 14:32 RAM:128k TEMP:✓ WiFi:-50dBm MAN │
└──────────────────────────────────────────────┘
↑
May exceed 480px width
Root Causes:
- No pre-calculation of text width
- Fixed element positions don't account for content size
- No overflow detection or truncation
Impact: ❌ UI looks broken; text unreadable; unprofessional appearance
Solution: Calculate text width before drawing; implement truncation with ellipsis
3. Data Updates Don't Auto-Refresh Home Page 📊
Current Problem:
Timeline:
14:00:00 Weather API returns: 22.5°C (UPDATE)
↓
updateWeatherOnly() called
↓
Calls uiRequestRedraw()
↓
navigateToPage() respects 500ms navigation lock
↓
Lock is active from recent navigation
↓
UPDATE BLOCKED! ❌
↓
User doesn't see update until they navigate away/back
Impact: ❌ Data feels stale; system appears unresponsive; real-time features don't work
Solution: Create uiRequestHomeUpdate() that bypasses navigation lock
🟡 IMPORTANT ISSUES
4. WiFi Strength as Raw dBm 📡
Problem:
Status Bar shows: "WiFi:-65dBm"
User confusion:
- Is -65 good or bad?
- What's the range (-120 to 0)?
- Need context!
Better:
Status Bar shows: "📡 73%" (color-coded)
- Green (▓▓▓▓) 80-100%: Excellent
- Yellow (▓▓▓░) 60-80%: Good
- Orange (▓▓░░) 40-60%: Fair
- Red (▓░░░) 0-40%: Weak
Solution: Add RSSI-to-percentage conversion function
5. Heater Mode Unclear 🔥
Problem:
Status Bar shows: "MAN"
User confusion:
- MAN = Manual ON or Manual OFF?
- Is heater actually running?
- Need both mode AND state!
Better:
Status Bar shows: "🔥 MAN" (heater ON, Manual mode)
or
"❌ OFF" (heater OFF, Manual mode)
or
"⚙️ AUTO" (Auto mode)
Solution: Show both state (on/off) and mode, with icons
6. Status Bar Can Overflow 📊
Problem:
480px screen width:
[Time] [Memory] [Sensor] [WiFi] [Heater]
↑ ↑ ↑ ↑ ↑
8px - - - (MODE CHIP at right)
If WiFi string is "WiFi:-120dBm" instead of "WiFi:-50dBm"
and memory is "RAM:999k" instead of "RAM:128k"
then total width might exceed 480px!
Result: Text gets cut off or overlaps
Solution: Add bounds checking; hide less important items if not enough space
🟠 DESIGN GAPS
7. No Partial Screen Update System 📐
Current Implementation:
Data changes (weather, boiler)
↓
uiRequestRedraw() called
↓
navigateToPage(PAGE_HOME) called
↓
display->fillScreen() (entire 480x272 black out)
↓
drawPageHome() redraws EVERYTHING
↓
User sees flicker! ENTIRE screen refreshes
↓
Takes ~500-1000ms
Proposed Implementation:
Data changes (weather, boiler)
↓
uiRequestHomeUpdate() called
↓
Check what changed (temp, humidity, time, mode)
↓
Only redraw affected panel(s)
↓
Example: Only redraw Clock Panel (not full screen)
↓
Takes ~50-100ms (10-100x faster!)
↓
No flicker! Smooth update
Impact: Performance (10-100x faster), smooth user experience
📊 ISSUES SUMMARY TABLE
| # | Category | Severity | Issue | Time to Fix | Impact |
|---|---|---|---|---|---|
| 1 | Display | 🔴 Critical | Clock not updating | 1h | HIGH |
| 2 | Display | 🔴 Critical | Text overlaps | 2-3h | HIGH |
| 3 | Real-time | 🔴 Critical | Data not auto-updating | 1.5h | HIGH |
| 4 | Display | 🟡 Important | WiFi display incomplete | 30m | MED |
| 5 | Display | 🟡 Important | Heater mode unclear | 30m | MED |
| 6 | Display | 🟡 Important | Status bar overflow | 1h | MED |
| 7 | Display | 🟡 Important | Temp sensor minimal | 15m | LOW |
| 8 | Performance | 🟠 Enhancement | No partial updates | 2-3h | PERF |
| 9 | User Config | 🟠 Enhancement | No theme switching | 1h | UX |
| 10 | Fonts | 🟠 Enhancement | Font scaling incomplete | 1h | UX |
| 11-20 | Minor | 🔵 Trivial | Format issues, etc | <30m | LOW |
🔧 QUICK FIX PRIORITY
Phase 1: Critical (3-4 hours)
Implement these for immediate visual/functional improvements:
Day 1 Focus:
✓ Fix #1: Clock seconds update (1h) → Time displays live
✓ Fix #3: Data auto-update home page (1.5h)→ Real-time updates
✓ Fix #2: Text overlaps (2h) → Professional appearance
────
4.5h total → MAJOR improvement
Phase 2: Polish (2-3 hours)
Day 2 Focus:
✓ Fix #4: WiFi as percentage (30m) → Better UX
✓ Fix #5: Heater mode clarity (30m) → Clearer state
✓ Fix #6: Status bar boundaries (1h) → No overflow
────
2h total → PROFESSIONAL appearance
Phase 3: Performance (3-4 hours)
Day 3 Focus:
✓ Fix #7: Partial screen updates (3h) → Smooth, flicker-free
────
3h total → PREMIUM feel
📈 Expected Impact Timeline
BEFORE FIXES:
- Clock: FROZEN (broken appearance)
- Data: Stale (updates not visible)
- Text: OVERLAPPING (unprofessional)
- Status: UNCLEAR (confusing heater state)
- Performance: STUTTERY (full screen redraws)
↓
User Opinion: "This app is broken"
AFTER PHASE 1 (4.5 hours):
- Clock: Live every second ✓
- Data: Updates in real-time ✓
- Text: Properly spaced ✓
↓
User Opinion: "Looks much better"
AFTER PHASE 2 (2 more hours):
- WiFi: Shows percentage with color ✓
- Heater: Shows mode AND state ✓
- Status: No overflow issues ✓
↓
User Opinion: "Professional quality"
AFTER PHASE 3 (3 more hours):
- Performance: Smooth, no flicker ✓
- Updates: Instant, sub-100ms ✓
- Responsiveness: Premium feel ✓
↓
User Opinion: "Production-ready!"
🎓 CODE STRUCTURE INSIGHTS
Current Update Flow
API Response (weather/boiler)
↓
updateWeatherOnly() / updateBoilerData()
↓
Modify globalWeather struct
↓
uiRequestRedraw()
↓
navigateToPage() [respects 500ms lock]
↓
drawPageHome() [full screen redraw if not locked]
↓
Display updates or BLOCKS
Problem: Blocking on navigation lock delays real-time updates
Proposed Update Flow
API Response
↓
updateWeatherOnly() / updateBoilerData()
↓
Modify globalWeather struct
↓
uiRequestHomeUpdate() [new function]
↓
Direct redraw (bypass nav lock)
↓
Only changed panels redraw [with dirty tracking]
↓
Fast, smooth update
Benefit: Real-time, efficient, responsive
📋 FILES REQUIRING CHANGES
Priority 1 (Must Change)
src/ui/ui_framework.cpp
├─ Add clock refresh variables
├─ Add per-second refresh in uiLoop()
└─ Add uiRequestHomeUpdate() function
src/ui/page_home.cpp
├─ Fix drawWeatherPanel() (text layout)
├─ Fix drawStatusBar() (overflow/clarity)
└─ Update data callbacks
Priority 2 (Should Change)
src/ui/ui_framework.h
├─ Add function declarations
└─ Add partial redraw prototypes
src/ui/page_home.h
└─ Update export declarations
Priority 3 (Nice to Have)
data/js/app.js
└─ Update polling interval
src/utils/time_manager.h
└─ Add timezone detection
✅ VALIDATION CHECKLIST
After implementing fixes, verify:
- Clock updates every second (no frozen time)
- Weather panel displays without text overlap
- Long weather descriptions are truncated with "..."
- Boiler sensor box doesn't overlap details
- Status bar fits within 480px (no overflow)
- WiFi shows as percentage with color coding
- Heater shows both state (on/off) and mode with icon
- Data updates appear on home page instantly
- No flicker when updating (after partial update impl)
- All text is readable at all font scales (0.85x to 1.30x)
- Both Dark and Light themes work correctly
- Test with extreme values (long strings, unusual numbers)
📚 DOCUMENTATION FILES CREATED
- BUG_ANALYSIS_AND_FIXES.md - Comprehensive analysis of all 20 issues with detailed descriptions
- DETAILED_FIXES_GUIDE.md - Step-by-step implementation guides with code examples
- QUICK_FIXES_CHECKLIST.md - Actionable checklist for each fix with file locations
- THIS FILE - High-level overview and visualization of issues
🚀 RECOMMENDATIONS
Immediate Actions (Start Now)
- Implement Fix #1 (Clock) - Quick confidence booster
- Implement Fix #3 (Data updates) - Critical for real-time feel
- Implement Fix #2 (Text overlaps) - Visible quality improvement
This Week
- Implement Fix #4, #5, #6 (Display clarity)
- Implement Fix #8 (Partial updates) - Performance jump
This Month
- Implement remaining fixes for polish and robustness
- Add unit tests for text layout calculations
- Performance profiling and optimization
💡 KEY TAKEAWAYS
-
Clock not updating - Critical user-facing bug. Needs immediate per-second refresh loop.
-
Text overlaps - Professional appearance problem. Requires proper layout calculation.
-
Data not auto-updating - Real-time expectation broken. Needs bypass for nav lock.
-
Partial updates missing - Performance/UX issue. Should implement for smooth experience.
-
UI Clarity issues - WiFi, heater mode need better visualization.
-
Overall quality - Good architecture but needs these refinements for production.