Troubleshooting & FAQ

Troubleshooting & FAQ

This document addresses common questions, troubleshooting steps, and diagnostic procedures for ESP-MeteoPlaneRadar.

---

❓ Frequently Asked Questions (FAQ)

Q: Does the device support 5 GHz Wi-Fi networks?

A: No. Like all ESP32 chips, the ESP32-S3 only operates on 2.4 GHz (802.11 b/g/n). If your router uses a combined single SSID for both 2.4 GHz and 5 GHz (band steering), ensure the 2.4 GHz band is enabled and permits legacy connections.

Q: Why do I see fewer aircraft when zoomed in?

A: When zoomed into 10 km or 25 km, only flights within that immediate radius will be rendered. If your location is far from a major airport or busy terminal control area, low-altitude traffic may be sparse. Tap the range indicator to zoom out to 100 km or 250 km (Tactical mode) to view high-altitude transcontinental traffic.

Q: Do I need an API key for ADS-B tracking?

A: No! The tracking engine uses the community open data endpoint from adsb.fi, which does not require registration, personal API keys, or subscriptions.

Q: Why did eastern aircraft disappear at maximum zoom in older versions?

A: Upstream adsb.fi API queries return flights ordered strictly by longitude (west to east). In firmware versions prior to v1.5.8, the buffer was capped at 100 aircraft, causing the parser to stop around 19.4°E longitude. Starting with v1.5.8, the buffer was increased to 250 aircraft and equipped with distance-based dynamic sorting, ensuring full 360° coverage across all of Slovakia and Central Europe.

---

🔍 Troubleshooting Guide

1. The Screen is Blank / Black, but the Backlight is Lit

• Cause: The display driver or I2C I/O expander (TCA9554) did not complete initialization or experienced an I2C bus collision.
• Solution:
  1. Unplug the USB-C cable, wait 3 seconds, and reconnect.
  2. Ensure the pixel clock in Display_ST7701.h is set to 8 MHz (higher frequencies such as 16 MHz cause PSRAM DMA contention during network traffic).
  3. The firmware includes an automatic display watchdog (LCD_VsyncCount() and TCA9554_Verify()) that automatically restarts the RGB panel if DMA frame output ever stalls.

2. Random Restarts or Brownout Detection

• Cause: Inadequate power supply. The ESP32-S3 transmitter draws transient peaks up to 400 mA during Wi-Fi packet transmission.
• Solution:
  • Connect the device directly to a dedicated 5V / 1A or 2A USB wall adapter.
  • Avoid unpowered USB hubs, low-current front PC ports, or extra-long thin USB cables with high voltage drop.

3. Touchscreen Does Not Respond to Taps

• Cause: CST820 capacitive touch sensor needs proper electrical grounding or calibration at power-up.
• Solution:
  • Ensure the screen surface is clean and free of water drops or conductive moisture.
  • Make sure the device is grounded (touching the USB chassis or connecting to a grounded PC port often resolves touch sensitivity issues).
  • Reboot the board; the CST820 recalibrates its baseline capacitance during initial startup.

4. Weather Radar Shows a Blank Grid or Fails to Load

• Cause: The selected national provider (SHMÚ or ČHMÚ) might be undergoing scheduled maintenance or experiencing network issues.
• Solution:
  • Tap the radar badge to cycle to RainViewer, which provides a globally resilient composite.
  • Check your internet connection: open the Web Dashboard and verify that Wi-Fi status is Connected with an RSSI better than -75 dBm.

5. YouTube Screen Shows Error or Does Not Update

• Cause 1 - Invalid API Key: Ensure you copied the full key starting with AIzaSy... from Google Cloud Console.
• Cause 2 - API Not Enabled: Verify that YouTube Data API v3 is enabled in your Google Cloud project.
• Cause 3 - Invalid Channel Handle: If using a handle (e.g. @CuriousCatFPV), ensure the @ prefix is included. If the handle fails to resolve, use the explicit 24-character Channel ID (UC...).
• Cause 4 - Quota Exceeded: The free Google tier provides 10,000 quota units/day. The device polls efficiently (1 unit per check), so one device consumes <500 units/day.

6. Physical Screen Shift / Image Offset

• Cause: In early firmware versions, NVS flash writes during auto-rotation stalled the PSRAM bus.
• Solution:
  • Starting with v1.9.8, flash writes during screen cycling are eliminated, and factory timing porches (VBP 8, HBP 10, HFP 50) are calibrated.
  • If a transient shift ever occurs, the driver automatically resynchronizes on the next VSYNC (CONFIG_LCD_RGB_RESTART_IN_VSYNC), or you can call POST /api/display/resync from the web portal to instantly restore perfect alignment without a reboot.

7. SSL / HTTPS Connection Errors ((-32512) Memory allocation failed)

• Cause: TLS handshakes in mbedTLS require 45–50 KB of contiguous internal SRAM (MALLOC_CAP_INTERNAL).
• Solution: Keep DMA bounce buffers balanced at 30 lines ($30 \times 480\text{ px}$) to leave 95+ KB free internal SRAM for network cryptography.

---

🛠️ Viewing Diagnostics via Serial Monitor

To view live diagnostic output, connect the device to your PC via USB-C and open a serial terminal at 115200 baud:

Using PlatformIO:

pio device monitor -b 115200

Typical Healthy Boot Log:

[   120][I][Display]: ST7701 panel initialized successfully (480x480 RGB565)
[   180][I][Touch]: CST820 initialized on I2C addr 0x15
[   210][I][TCA9554]: I/O expander OK
[   450][I][WiFi]: Connected to MyHomeNetwork, IP: 192.168.1.145, RSSI: -54 dBm
[   510][I][mDNS]: Hostname http://meteoplaneradar.local advertised
[  1200][I][ADSB]: Fetched 138 aircraft in range (closest: OM-XYZ 4.2 km)
[  2400][I][Weather]: Provider SHMU loaded (composite frame OK)

If you encounter persistent issues not covered here, please open an issue on GitHub and attach your serial monitor log.