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

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 when uiRequestRedraw() 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() in ui_framework.cpp only 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:

  1. Add a timestamp variable to track last update
  2. In uiLoop(), check if HOME page is active and time has advanced by 1 second
  3. Redraw only the clock panel (partial update) instead of full screen redraw
  4. This avoids full-screen flicker while keeping time updated

2. Overlapping Text in Multiple Panels 📝

Locations:

  • src/ui/page_home.cpp - Weather panel, Status bar
  • data/js/app.js - Web UI dashboard
  • data/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:

  1. Add text bounding box calculations before drawing
  2. Implement dynamic spacing based on text width
  3. Add overflow truncation with ellipsis for long strings
  4. Use getTextWidth() function to calculate required space
  5. 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() and updateBoilerData() call uiRequestRedraw() but this only works if navigation is not locked

Root Cause:

  • Navigation lock cooldown (UI_NAV_COOLDOWN = 500ms) prevents rapid redraws
  • uiRequestRedraw() calls navigateToPage() which respects the navigation lock
  • Real-time updates are blocked if user recently navigated

Impact: Data feels stale, system appears unresponsive

Proposed Fix:

  1. Create a separate uiPartialRedraw() function for data updates
  2. Bypass navigation lock for home page updates
  3. Implement partial screen updates (only update changed elements)
  4. 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:

  1. Add RSSI-to-percentage conversion function
  2. Validate range (-120 to 0 dBm)
  3. Add visual strength indicator (bars or percentage)
  4. 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:

  1. Convert to MB when > 1024 KB
  2. Add total RAM reference for percentage
  3. 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:

  1. Show abbreviated temperature value instead of just checkmark
  2. e.g., "TEMP:45°" instead of "TEMP:✓"
  3. 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:

  1. Add heater on/off indicator
  2. Use full words or better abbreviations
  3. Add icon or color to indicate heating state
  4. 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:

  1. Reduce to 1-2 second interval for real-time feel
  2. Implement adaptive polling
  3. Add fetch timeout (5s)
  4. 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:

  1. Add bounds checking on page IDs
  2. Add debug logging
  3. Fallback to home page on invalid navigation
  4. 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:

  1. Implement dirty rect system (track changed regions)
  2. Create drawClockPanelPartial(), drawWeatherPanelPartial()
  3. Only redraw changed elements
  4. 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:

  1. Implement theme switching without full redraw
  2. Store theme in config
  3. Add more theme options (High Contrast, etc.)
  4. Centralize all colors to theme definitions

12. Font Scaling Not Applied to All Text 📝

Location: src/ui/page_home.cpp Severity: LOW Issue:

  • FONT_SCALE exists but not consistently used
  • Some text uses hard-coded font sizes via getFont(level)
  • User's font preference setting might be ignored

Proposed Fix:

  1. Apply font scale to all text rendering
  2. Test with font scale 0.85, 1.0, 1.15, 1.30
  3. 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:

  1. Add geolocation API integration (IP-based)
  2. Auto-detect and set timezone on first boot
  3. 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:

  1. Make update frequency configurable
  2. Add update interval to settings page
  3. 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:

  1. Pre-calculate total width needed
  2. Implement responsive layout (hide less important items if space is tight)
  3. Add text truncation with ellipsis
  4. 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

Phase 1: Critical (Start Immediately)

  1. Fix clock seconds update - Add real-time refresh in uiLoop()
  2. Fix text overlaps - Add proper spacing calculations
  3. Fix sensor data updates - Bypass navigation lock for updates

Phase 2: Important (Next Week)

  1. Fix WiFi strength display
  2. Fix heater mode clarity
  3. Fix status bar overflow
  4. Add partial screen update system

Phase 3: Enhancement (Future)

  1. Add timezone auto-detection
  2. Improve theme system
  3. Make weather update frequency configurable

🛠️ IMPLEMENTATION NOTES

Architecture Improvements Needed:

  1. Data Update System: Decouple data updates from page navigation
  2. Dirty Region Tracking: For efficient partial updates
  3. Event System: Pub/sub for data changes
  4. Configuration System: More user-configurable options
  5. 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