How miladhalabi/led-matrix-dashboard works
1. Project type and runtime
- This is an ESP32 firmware project, built with PlatformIO for an Arduino-style runtime.
- The code is organized as a set of hardware- and feature-focused modules under src/, with main.cpp acting as the central orchestrator.
2. System-level role of main.cpp
- src/main.cpp is the integration point that ties together startup, periodic updates, input handling, display rotation, network services, and scheduled actions.
- It likely coordinates the “always-on” control loop typical of embedded dashboards: read inputs, refresh data, update the matrix, and service network/telemetry features.
3. Display subsystem
- src/display/ contains the LED matrix rendering layer for the MAX7219 8x32 display.
- Based on the README and PlatformIO dependencies, this layer likely uses MD_Parola / MD_MAX72XX for text animation, scrolling messages, icons/glyphs, and the dashboard’s rotating views.
- This is the user-facing output boundary for time, weather, prayer status, Telegram messages, and system notifications like OTA updates.
4. Time, RTC, and alarm subsystem
- src/time/ manages the DS3231 RTC and the current time source used by the dashboard.
- This module is the core authority for clock display, alarm triggering, and keeping time stable when network access is unavailable.
- The alarm behavior is probably coupled to audio playback through the DFPlayer and to display notifications.
5. Prayer-time subsystem
- src/prayerTime/ handles fetching and scheduling daily prayer times, using the Aladhan API as described in the README.
- This subsystem likely computes or stores the day’s prayer schedule and determines when to trigger the Azan/alarm behavior.
- It is a separate scheduling concern from the general clock/alarm logic, but both feed the same UI and audio outputs.
6. Weather subsystem
- src/weather/ integrates with the Open-Meteo API for current weather and temperature.
- Weather data is an external input that feeds the display rotation, especially the date/weather screen mentioned in the README.
- The architecture likely treats weather as periodically refreshed network data with local caching/fallback behavior when offline.
7. Telegram control plane
- src/telegram/ is the remote management surface, built on AsyncTelegram2.
- It supports interactive control via inline keyboards, message handling, and OTA update acceptance from a .bin file sent to the bot.
- This is the main remote “control plane” for changing settings, pushing messages to the matrix, toggling alarm/prayer features, and triggering firmware updates.
8. Local input and offline control
- src/encoder/ implements the rotary encoder and button-driven local menu.
- This is the offline fallback/control path when the device is not using Telegram, and it exposes key configuration functions such as time, alarm, brightness, volume, and prayer toggles.
- The encoder subsystem is important because it provides a fully local management boundary independent of the network stack.
9. Connectivity and provisioning
- src/wifi/ handles WiFi connection management and the initial captive portal configuration flow via IotWebConf.
- The README describes a provisioning hotspot and recovery behavior, so this module likely manages first boot setup, reconnection, and internet availability checks.
- This subsystem is the bridge between the device and all remote dependencies: Telegram, weather, prayer-time APIs, and OTA.
10. Persistence, settings, and flash handling
- src/flashUtils/, src/setters/, src/usersManagement/, and src/utils/ form the non-volatile configuration and support layer.
- These modules likely store and update device preferences such as WiFi credentials, alarm state, brightness, volume, selected music, Telegram identity, and other user settings.
- usersManagement is probably the authorization boundary for Telegram chat access, while setters encapsulates state changes driven by either Telegram or the encoder menu.
11. Parsing, formatting, and conversion helpers
- src/parsers/, src/formaters/, and src/converters/ are shared utility layers used to move data between external formats and display-ready/internal representations.
- Typical responsibilities here would include JSON parsing, string shaping for the matrix display, time/date formatting, and unit/value conversion for weather or clock fields.
- These modules reduce coupling between network data sources and presentation logic.
12. Audio and media control
- While there is no dedicated top-level audio folder, the README shows the device uses a DFPlayer Mini and SD card for Azan/alarm playback.
- Audio control is likely coordinated across the alarm/prayer-time logic and whichever module handles sound selection and volume settings.
- The src/backups/ directory suggests prior iterations or experimental state for some of this behavior, but the active architecture is centered on the current modules above.
13. Testing and build artifacts
- test/prayTimeTest.cpp indicates at least one focused test target around prayer-time behavior.
- firmware/firmware.bin is the build artifact used for deployment and also the OTA payload accepted over Telegram.
- The platformio.ini file is the build/dependency boundary that defines the embedded toolchain and third-party libraries.
14. End-to-end data flow
- Inputs enter the system from four places: RTC/local encoder, WiFi + APIs, Telegram, and SD/audio media.
- Those inputs are normalized by parsers/setters/converters, persisted through flash utilities where needed, and then consumed by the display, alarm, and audio subsystems.
- The main architectural pattern is an event-driven embedded controller with two interaction surfaces: a local physical UI and a remote Telegram UI, both feeding the same device state.
Main entry points: main.cpp Main loop · setters.h Setters · telegram.h Telegram · prayerTime.h Prayer time
Components 17
Core runtime
Embedded control loop and shared device state
User interfaces
Local and remote control surfaces
External services
Networked data sources and provisioning
- WiFi · Connection management and captive portal provisioning
src/wifi/wifi.h - Weather · Open-Meteo weather retrieval and refresh logic
src/weather/weather.h - Prayer time · Daily prayer schedule and Azan timing
src/prayerTime/prayerTime.h
Support layers
Persistence, parsing, and formatting helpers
- Flash utils · Non-volatile storage helpers for device settings
src/flashUtils/flashUtils.h - Setters · Centralized device state mutations from UI and services
src/setters/setters.h - Users · Telegram chat authorization and user management
src/usersManagement/usersManagement.h - Parsers · Input parsing for API and message payloads
src/parsers/parsers.h - Formaters · String and payload formatting for display and messages
src/formaters/formaters.h - Converters · Value and unit conversion helpers
src/converters/converters.h - Utils · Common utility functions used across modules
src/utils/utils.h - Firmware bin · Built binary used for deployment and Telegram OTA
firmware/firmware.bin - Prayer test · Focused test target for prayer-time behavior
test/prayTimeTest.cpp
Connections 25
- Main loop → RTC time: reads clock · Uses RTC time for display, alarms, and scheduling
- Main loop → Display: drives UI · Refreshes dashboard screens and notifications
- Main loop → Encoder: reads input · Polls local controls and menu actions
- Main loop → Telegram: handles remote · Services bot commands and interactive control
- Main loop → WiFi: connects · Depends on network availability for remote services
- Main loop → Weather: refreshes data · Pulls weather updates into the dashboard
- Main loop → Prayer time: schedules · Evaluates prayer times and Azan triggers
- Main loop → Setters: applies changes · Routes configuration changes into shared device state
- Main loop → Flash utils: persists · Stores and restores settings across reboots
- Telegram → Users: authenticates · Restricts control to allowed chats/users
- Telegram → Firmware bin: ota payload · Accepts firmware updates as uploaded binary
- Telegram → Setters: remote config · Updates brightness, volume, alarm, and feature toggles
- Encoder → Setters: local config · Changes settings through physical controls
- WiFi → Weather: fetches · Provides connectivity for weather API access
- WiFi → Prayer time: fetches · Provides connectivity for prayer-time API access
- Weather → Parsers: parses response · Converts API payloads into internal data
- Prayer time → Parsers: parses response · Processes prayer schedule payloads
- Display → Formaters: formats text · Turns data into matrix-friendly strings
- Display → Converters: converts values · Adapts units and time fields for presentation
- Setters → Flash utils: stores state · Writes persistent preferences and identity data
- Setters → Utils: uses helpers · Shares common logic for state handling
- Formaters → Utils: uses helpers · Relies on shared formatting utilities
- Parsers → Utils: uses helpers · Shares common parsing helpers
- Converters → Utils: uses helpers · Shares common conversion helpers
- Prayer test → Prayer time: verifies · Exercises prayer-time calculations and scheduling