14 KiB
Bug Analysis and Logical Errors - ESP32-S3 Touch UI Project
Executive Summary
This document outlines all identified bugs, gaps, logical errors, and design issues found during a comprehensive code review of the ESP32-S3 Touch UI project. The project is a home IoT controller with a 4.3" touchscreen display (NV3041A QSPI) showing weather, boiler/heating control, and statistics.
🔴 CRITICAL BUGS
1. Clock Seconds Not Updating ⏰
Location: src/ui/page_home.cpp - drawClockPanel()
Severity: HIGH
Issue:
- The clock displays seconds (HH:MM:SS format) but they NEVER update
drawPageHome()is only called when navigating to a page or whenuiRequestRedraw()is triggered- Once the home page is drawn, there is NO continuous refresh mechanism
- The seconds display is static and frozen
Root Cause:
- The UI framework lacks a real-time update loop for the home page
uiLoop()inui_framework.cpponly handles auto-rotation and does NOT refresh the home page display- No timer mechanism exists to redraw the clock panel every second
Impact: User sees static time that appears broken
Proposed Fix: Add a per-frame clock update mechanism:
- Add a timestamp variable to track last update
- In
uiLoop(), check if HOME page is active and time has advanced by 1 second - Redraw only the clock panel (partial update) instead of full screen redraw
- This avoids full-screen flicker while keeping time updated
2. Overlapping Text in Multiple Panels 📝
Locations:
src/ui/page_home.cpp- Weather panel, Status bardata/js/app.js- Web UI dashboarddata/css/style.css- Layout issues
Severity: HIGH Issues:
A. Weather Panel Text Overlap:
- Weather description and details badges can overlap with boiler temperature sensor box
- No proper spacing calculation between right-side boiler sensor and detail badges
- When weather description is long, it overlaps with the sensor box
Root Cause:
computeHomeWeatherLayout()doesn't account for text width overflow- Boiler sensor box position is fixed, not accounting for text content
- No overflow handling or dynamic text truncation
Example Problem:
[Weather Icon] Ext Temp [←Long desc overlaps→] [Boiler Box]
↓ No margin calculation
B. Status Bar Text Crowding:
- Timestamp, Memory, Sensor, WiFi RSSI, and Mode all crammed on one line
- No text width validation before positioning next element
- Elements can overflow screen width
- Text can overlap when combined with long status strings
C. Web UI CSS Issues:
- Navbar links can overflow on small screens
- Card headers don't handle long titles properly
- Weather details grid cells can misalign
Impact: UI looks broken, hard to read, unprofessional
Proposed Fix:
- Add text bounding box calculations before drawing
- Implement dynamic spacing based on text width
- Add overflow truncation with ellipsis for long strings
- Use
getTextWidth()function to calculate required space - Implement responsive grid layout in web UI
3. No Continuous Sensor Data Updates 📊
Location: src/main.cpp, src/ui/page_home.cpp
Severity: MEDIUM
Issue:
- Weather data and boiler temperature are updated via API endpoints
- BUT the home page doesn't auto-refresh when data arrives
- User sees stale data until they navigate away and back to home page
updateWeatherOnly()andupdateBoilerData()calluiRequestRedraw()but this only works if navigation is not locked
Root Cause:
- Navigation lock cooldown (UI_NAV_COOLDOWN = 500ms) prevents rapid redraws
uiRequestRedraw()callsnavigateToPage()which respects the navigation lock- Real-time updates are blocked if user recently navigated
Impact: Data feels stale, system appears unresponsive
Proposed Fix:
- Create a separate
uiPartialRedraw()function for data updates - Bypass navigation lock for home page updates
- Implement partial screen updates (only update changed elements)
- Add update queue system for multiple rapid updates
4. WiFi Strength Indicator Calculation Missing 📡
Location: src/ui/page_home.cpp - drawStatusBar()
Severity: MEDIUM
Issue:
int rssi = NetworkManager::getWiFiRSSI();
snprintf(rssiStr, sizeof(rssiStr), "WiFi:%ddBm", rssi);
- Uses raw dBm values without range validation
- Negative dBm values might display incorrectly (e.g., "WiFi:-100dBm")
- No visual indicator of signal strength (bars/percentage)
- Threshold values seem hardcoded but never explained
Root Cause:
- No proper RSSI-to-percentage conversion
- No bounds checking
Proposed Fix:
- Add RSSI-to-percentage conversion function
- Validate range (-120 to 0 dBm)
- Add visual strength indicator (bars or percentage)
- Define signal strength thresholds as constants
🟡 LOGICAL ERRORS
5. Memory Display Format Inconsistency 💾
Location: src/ui/page_home.cpp - drawStatusBar()
Severity: LOW
Issue:
snprintf(memStr, sizeof(memStr), "RAM:%dk", freeHeap / 1024);
- Shows RAM in KB but other sensors show full units (hPa, km/h, °C)
- Inconsistent with rest of UI styling
- Very large memory values can overflow display area
- No indication of total RAM for context
Impact: Minor, but affects professional appearance
Proposed Fix:
- Convert to MB when > 1024 KB
- Add total RAM reference for percentage
- Use consistent unit formatting
6. Temperature Sensor Status Always Shows ✓ or ✗ 🌡️
Location: src/ui/page_home.cpp - drawStatusBar()
Severity: LOW
Issue:
snprintf(sensorStr, sizeof(sensorStr), "TEMP:%s",
!isnan(globalWeather.currentTemp) ? "✓" : "✗");
- Only shows if value exists, not actual value or status
- Doesn't distinguish between "not reading" vs "stale data"
- User can't see the actual boiler temperature at a glance from status bar
Impact: Reduced visibility of critical sensor
Proposed Fix:
- Show abbreviated temperature value instead of just checkmark
- e.g., "TEMP:45°" instead of "TEMP:✓"
- Use color coding for warning states
7. Heater Mode Display Incomplete 🔥
Location: src/ui/page_home.cpp - drawStatusBar()
Severity: MEDIUM
Issue:
const char* mode = "";
switch (globalWeather.heaterControlMode) {
case 0: mode = "OFF"; break;
case 1: mode = "MAN"; break;
case 2: mode = "AUTO"; break;
case 3: mode = "AI"; break;
default: mode = "---"; break;
}
- Only shows mode acronym (3 chars), not state
- Doesn't show if heater is actively heating (on/off state separately)
- "MAN" could mean Manual but unclear if manually ON or OFF
- No "Schedule" mode (mode=1 might be schedule but labeled "MAN")
Impact: User confusion about heater state
Proposed Fix:
- Add heater on/off indicator
- Use full words or better abbreviations
- Add icon or color to indicate heating state
- Clarify mode 1 - is it Manual or Schedule?
8. Web API Status Polling Low Frequency ⏱️
Location: data/js/app.js - startStatusPolling()
Severity: LOW
Issue:
statusInterval = setInterval(fetchStatus, 3000); // Every 3 seconds
- 3-second polling interval might miss fast changes
- No adaptive polling (faster when changing, slower when idle)
- If fetch takes time, next poll doesn't wait for completion
- No timeout on fetch requests
Impact: Web UI feels sluggish
Proposed Fix:
- Reduce to 1-2 second interval for real-time feel
- Implement adaptive polling
- Add fetch timeout (5s)
- Add error retry logic with backoff
9. Missing Error Handling in Navigation ❌
Location: src/ui/ui_framework.cpp - navigateToPage()
Severity: LOW
Issue:
- No validation that page drawing functions exist
- If a page ID is invalid, function silently does nothing
- No error messaging to user
- Navigation lock might prevent recovery
Impact: Silent failures, difficult to debug
Proposed Fix:
- Add bounds checking on page IDs
- Add debug logging
- Fallback to home page on invalid navigation
- Add error indicator to UI
🟠 DESIGN GAPS
10. No Partial Screen Update System 📐
Location: Entire project Severity: MEDIUM Issue:
- Every data change redraws the entire home page
- Causes visual flicker
- Inefficient use of display bandwidth
- Partial updates could be 100x faster
Proposed Fix:
- Implement dirty rect system (track changed regions)
- Create
drawClockPanelPartial(),drawWeatherPanelPartial() - Only redraw changed elements
- Cache previous values to detect changes
11. UI Theme System Incomplete 🎨
Location: src/ui/ui_framework.cpp
Severity: LOW
Issue:
- Only DARK and LIGHT themes
- Theme switch requires full page redraw
- No runtime theme change capability
- Hard-coded color values scattered across files
Proposed Fix:
- Implement theme switching without full redraw
- Store theme in config
- Add more theme options (High Contrast, etc.)
- Centralize all colors to theme definitions
12. Font Scaling Not Applied to All Text 📝
Location: src/ui/page_home.cpp
Severity: LOW
Issue:
FONT_SCALEexists but not consistently used- Some text uses hard-coded font sizes via
getFont(level) - User's font preference setting might be ignored
Proposed Fix:
- Apply font scale to all text rendering
- Test with font scale 0.85, 1.0, 1.15, 1.30
- Ensure no text overflow at extreme scales
13. No Timezone Auto-Detection 🌍
Location: src/main.cpp, src/utils/time_manager.h
Severity: LOW
Issue:
- Timezone is hardcoded or requires manual config
- No IP-based timezone detection
- NTP sync works but timezone must be set manually
Proposed Fix:
- Add geolocation API integration (IP-based)
- Auto-detect and set timezone on first boot
- Allow manual override in settings
14. Weather Update Frequency Not Configurable 🌦️
Location: src/network/weather_service.cpp (not shown but implied)
Severity: LOW
Issue:
- Weather API update interval appears hard-coded
- No user configuration for update frequency
- Could hit API rate limits
Proposed Fix:
- Make update frequency configurable
- Add update interval to settings page
- Log API call counts for debugging
15. Status Bar Elements Can Overflow Screen 📊
Location: src/ui/page_home.cpp - drawStatusBar()
Severity: MEDIUM
Issue:
- No screen width validation for status bar elements
- Multiple text elements positioned without checking total width
- Example: "Updated HH:MM:SS" + "RAM:999k" + "TEMP:✓" + "WiFi:-100dBm" + "MAN" mode chip
- Combined width can exceed 480 pixels
Proposed Fix:
- Pre-calculate total width needed
- Implement responsive layout (hide less important items if space is tight)
- Add text truncation with ellipsis
- Use abbreviated units for space saving
🔵 MINOR ISSUES & INCONSISTENCIES
16. Time Format Hardcoded ⏰
Location: src/ui/page_home.cpp
Issue: Time always shows 24-hour format, no 12-hour option
17. Date Format Not User Configurable 📅
Location: src/ui/page_home.cpp
Issue: Date format hardcoded to "%a, %d %b %Y"
18. Weather Description String Might Be Uninitialized ⚠️
Location: src/ui/page_home.cpp - drawWeatherPanel()
Issue:
const char* desc = globalWeather.weatherDesc.c_str();
if (!desc || strlen(desc) == 0) desc = "Clear";
String might be empty but never set to a default. Should initialize in initWeatherData().
19. WebUI Not Synced With LCD Display 🔄
Location: Web UI and LCD UI are independent Issue:
- Changes made in web UI don't update LCD display in real-time
- LCD changes don't update web UI automatically
- Potential for state desynchronization
20. No Debouncing on Touch Events 👆
Location: src/ui/touch_handler.h (implied)
Issue:
- No mention of debounce delays
- Could register multiple touches for single touch event
📋 SUMMARY TABLE
| # | Issue | Severity | Category | Quick Fix Time |
|---|---|---|---|---|
| 1 | Clock seconds not updating | 🔴 HIGH | Bug | 1 hour |
| 2 | Overlapping text in panels | 🔴 HIGH | Bug | 2 hours |
| 3 | No continuous sensor updates | 🟡 MEDIUM | Bug | 1.5 hours |
| 4 | WiFi strength calculation missing | 🟡 MEDIUM | Bug | 30 min |
| 5 | Memory display format | 🟡 MEDIUM | Logic | 30 min |
| 6 | Temp sensor status limited | 🟡 MEDIUM | Logic | 30 min |
| 7 | Heater mode display incomplete | 🟡 MEDIUM | Logic | 45 min |
| 8 | Web API polling frequency | 🟡 MEDIUM | Logic | 30 min |
| 9 | Missing error handling | 🟠 LOW | Logic | 1 hour |
| 10 | No partial screen updates | 🟠 LOW | Gap | 2-3 hours |
| 11 | Theme system incomplete | 🟠 LOW | Gap | 1 hour |
| 12 | Font scaling not applied | 🟠 LOW | Gap | 1 hour |
| 13 | No timezone auto-detect | 🟠 LOW | Gap | 45 min |
| 14 | Weather update not configurable | 🟠 LOW | Gap | 30 min |
| 15 | Status bar overflow possible | 🟠 LOW | Gap | 1 hour |
| 16-20 | Minor formatting issues | 🔵 TRIVIAL | Minor | < 30 min |
✅ RECOMMENDED FIXES BY PRIORITY
Phase 1: Critical (Start Immediately)
- Fix clock seconds update - Add real-time refresh in
uiLoop() - Fix text overlaps - Add proper spacing calculations
- Fix sensor data updates - Bypass navigation lock for updates
Phase 2: Important (Next Week)
- Fix WiFi strength display
- Fix heater mode clarity
- Fix status bar overflow
- Add partial screen update system
Phase 3: Enhancement (Future)
- Add timezone auto-detection
- Improve theme system
- Make weather update frequency configurable
🛠️ IMPLEMENTATION NOTES
Architecture Improvements Needed:
- Data Update System: Decouple data updates from page navigation
- Dirty Region Tracking: For efficient partial updates
- Event System: Pub/sub for data changes
- Configuration System: More user-configurable options
- Error Recovery: Better error handling and recovery
Code Quality:
- Add unit tests for text layout calculations
- Add integration tests for data flow
- Add performance metrics for render time
- Add debug overlay showing render stats