Skip to content

Latest commit

 

History

History
88 lines (51 loc) · 6.84 KB

WT32-SC01-PLUS_DOCUMENTATION_EN.md

File metadata and controls

88 lines (51 loc) · 6.84 KB

WT32-SC01 PLUS – Comprehensive Documentation

1. Project goal and core capabilities

The WT32-SC01 PLUS firmware targets Espressif's ESP32-S3 touch display module, presenting a desktop companion that displays the current time, weather information, and an online radio stream while persisting user preferences in EEPROM and optionally logging to a microSD card. The application is built with PlatformIO and relies on LVGL and LovyanGFX for the UI. The graphical layout is also available as a SquareLine Studio project so designers can tweak the interface visually.

2. Repository structure overview

  • WT32-SC01-PLUS/src/main.cpp: entry point that configures the display, network stack, FreeRTOS tasks, and high-level features.
  • WT32-SC01-PLUS/src/Managers/…: modular managers for time (TimeManager), Wi-Fi (WiFiManager), EEPROM (EEPROMManager), and SD card access (SDManager).
  • WT32-SC01-PLUS/src/Features/…: feature implementations for the weather client and online radio.
  • WT32-SC01-PLUS/src/ui.* and screens/: LVGL files generated by SquareLine Studio.

3. Hardware requirements and peripherals

  • Display and touch: The LovyanGFX configuration drives the WT32-SC01 PLUS 480×320 IPS panel over an 8-bit parallel bus that maps WR (GPIO 47), RS (GPIO 0), and D0–D7 (GPIO 9, 46, 3, 8, 18, 17, 16, 15). Reset (GPIO 4), backlight PWM (GPIO 45), and the FT5x06 touch controller on I²C (SDA GPIO 6, SCL GPIO 5) are also set up.
  • Audio (I2S): The online radio feature streams audio using the ESP32-AudioI2S library over BCLK (GPIO 36), LRC (GPIO 35), and DOUT (GPIO 37) to an external amplifier.
  • SD card: A microSD card can be connected in SPI mode using CS GPIO 41, CLK GPIO 39, CMD GPIO 40, and D0 GPIO 38. Toggle the SDCARD_INSERTED flag to enable or disable logging.
  • Additional hardware: A Wake-on-LAN packet is sent to a configured MAC address when the Wi-Fi icon is tapped on the UI.

4. Development environment and toolchain

All configuration lives in platformio.ini, which targets esp32-s3-devkitc-1, lists library dependencies, and enables PSRAM-specific build flags. The default serial monitor speed is 115200 baud.

Build and upload steps

  1. Clone the repository and open it in VS Code with the PlatformIO IDE extension installed.
  2. Confirm that the monitor_port entry in platformio.ini matches the serial device assigned to the board.
  3. Run PlatformIO: Upload from the command palette or execute pio run --target upload in the terminal.
  4. Use PlatformIO: Monitor to view logs during boot and runtime.

5. Startup sequence and main loop

setup() initializes the display, LVGL drivers, Wi-Fi management task, EEPROM-backed settings, and timers that refresh weather information and supervise connectivity. The loop() function keeps LVGL responsive, reacts to touch events (including Wake-on-LAN), and cycles through services such as time updates, on-screen keyboard handling, brightness control, location management, weather refresh, dimming logic, and radio stream stabilization.

6. Networking and Wake-on-LAN

WiFiManager handles user-entered credentials, stores them in EEPROM, and reconnects automatically on boot. The InitWifi() routine processes LVGL text area input, persists credentials, and updates UI status indicators, while StartWifiFromEEPROM() retries connections with a configurable counter. A dedicated FreeRTOS task (WiFiErrorHandling) pings an external host every five seconds and reboots the ESP32 after repeated failures to keep the device responsive. The Wake-on-LAN feature sends a magic packet to a predefined MAC address when triggered from the UI.

7. Time management

TimeManager synchronizes with pool.ntp.org, automatically applies daylight-saving time rules, and provides formatted hour, minute, and date strings for the UI. DisplayTime() runs each loop iteration to refresh the LVGL labels with the latest values.

8. Weather feature

InitWeather() communicates with the OpenWeatherMap API using the selected city ID. It updates temperature, humidity, textual descriptions, and weather icons. Errors trigger short retries and optionally log to the SD card. A SimpleTimer schedules updates every five minutes, and location changes prompt immediate refreshes.

9. Online radio player

The radio module maintains arrays of stream URLs and display names. It stores the last played station and volume in EEPROM so playback resumes after reboot. A dedicated FreeRTOS task listens for LVGL events and runs audio.loop() to keep streaming stable.

10. Screen brightness and automatic dimming

Users control brightness with a slider; the value is applied instantly and persisted in EEPROM. Two time pickers define an automatic dimming window, correctly handling intervals that cross midnight and restoring brightness afterward.

11. Location selection and EEPROM persistence

City selection, Wi-Fi credentials, brightness, and radio settings are written to EEPROM. The address layout is documented in EEPROMManager. RestoreFromEEPROM() runs at boot to reapply saved preferences and reinitialize dependent modules.

12. SD card logging

When SDCARD_INSERTED is true, the system creates log.txt at startup. The helper function SD_LOG duplicates critical messages (Wi-Fi status, weather updates, errors) to both the serial console and the SD card, providing a persistent audit trail.

13. User interface and SquareLine Studio integration

ui_init() loads the LVGL scene designed in SquareLine Studio. The .spj project inside the repository enables designers to edit widgets visually and regenerate the LVGL source files included under src.

14. Error handling and maintenance

  • Wi-Fi dropouts: The background task pings a remote host and restarts the ESP32 if connectivity cannot be restored.
  • Weather API failures: Empty or invalid responses trigger immediate retries with short delays.
  • Boot loop recovery: If necessary, erase flash contents with esptool.py --chip esp32-s3 erase_flash before reflashing.

15. Customization options

  • Add new locations: Append OpenWeatherMap city IDs and matching LVGL dropdown options in weather.cpp and the UI project.
  • Expand radio stations: Extend the stations and stations_name arrays, keeping EEPROM indices aligned.
  • Disable SD logging: Leave SDCARD_INSERTED set to false to bypass SD operations when no card is present.
  • Localization: Translate UI labels in SquareLine Studio and adjust the OPEN_WEATHER_MAP_LANGUAGE value in weather.cpp to request different API languages.

16. Future ideas

Potential enhancements include leveraging unused GPIO pins for sensors or actuators, and adding hourly weather forecasts alongside the existing current-conditions view.

This document summarizes the hardware setup, software architecture, customization points, and maintenance procedures for the WT32-SC01 PLUS project.