Refactor README: enhance project details, clarify features, and improve installation instructions

README.md

@@ -2,25 +2,23 @@
 
 A customizable LED matrix display project using ESP32 and MAX7219 LED matrix modules. This project creates a "Matrix"-style rain effect combined with a functional digital clock that synchronizes time via WiFi/NTP.
 
-![LED Matrix Monitor 2](https://via.placeholder.com/800x400?text=LED+Matrix+Monitor+2)
-
 ## Features
 
-- Matrix-style falling characters rain effect with realistic brightness simulation
+- Matrix-style falling characters rain effect
-- Real-time clock display with seconds progress bar
 - WiFi connectivity for automatic time synchronization with NTP servers
-- Configurable LED brightness levels
+- Digital clock display with seconds progress bar
-- Multiple text display modes (scrolling, centered)
+- Customizable text display (scrolling and centered)
-- Modular code architecture for easy customization
+- Configurable LED brightness
+- Modular code architecture for easy expansion
 
 ## Hardware Requirements
 
 - ESP-WROOM-32 development board
-- 4 MAX7219 LED matrix modules (8x8 each, cascaded)
+- MAX7219 LED matrix modules (4 units in cascade, 8x8 each)
-- Micro USB cable for programming and power
+- Power supply for the ESP32 and LED matrices
-- Jumper wires for connections
+- Connecting wires
 
-## Wiring Diagram
+## Wiring
 
 | ESP32 Pin | MAX7219 Pin |
 |-----------|-------------|
@@ -32,12 +30,68 @@ A customizable LED matrix display project using ESP32 and MAX7219 LED matrix mod
 
 ## Software Dependencies
 
-- PlatformIO IDE
 - Arduino framework for ESP32
-- [MD_MAX72XX](https://github.com/MajicDesigns/MD_MAX72XX) library for controlling MAX7219 LED matrices
+- MD_MAX72XX library for controlling MAX7219 LED matrices
-- ESP32 Arduino Core (includes WiFi and Time libraries)
+- WiFi library for connectivity
+- Time library for handling time functions
 
-## Project Structure
+## Installation
+
+1. Clone this repository or download the source code
+2. Open the project in PlatformIO IDE
+3. Create a `credentials.h` file in the `/src` directory with your WiFi credentials:
+
+```cpp
+#ifndef CREDENTIALS_H
+#define CREDENTIALS_H
+
+#define WIFI_SSID "your_wifi_ssid"
+#define WIFI_PASSWORD "your_wifi_password"
+#define NTP_SERVER "pool.ntp.org"
+#define GMT_OFFSET_SEC 3600  // Change based on your timezone (3600 = +1 GMT)
+#define DAYLIGHT_OFFSET_SEC 3600  // Change if daylight saving time is in effect
+
+#endif
+```
+
+4. Build and upload the project to your ESP32
+
+## Usage
+
+Once powered up, the device will:
+
+1. Connect to WiFi and sync time with NTP servers
+2. Display a "MATRIX" welcome message
+3. Show the matrix rain effect
+4. Periodically display the current time with a seconds progress bar on the bottom row
+
+## Configuration Options
+
+Customize the project by adjusting these parameters in `main.cpp`:
+
+- `MAX_DEVICES`: Number of connected 8x8 LED matrices (default: 4)
+- `MAX_BRIGHTNESS`: Maximum LED brightness level (0-15)
+- Pins for connecting MAX7219 modules to the ESP32:
+  - `CS_PIN`: 5
+  - `DIN_PIN`: 23
+  - `CLK_PIN`: 18
+
+## Code Organization
 
 The code is organized into modules to improve maintainability:
 
+- `/src/main.cpp`: Main program entry point
+- `/src/effects/matrix_rain.*`: Matrix rain effect implementation
+- `/src/display/text_display.*`: Text display functions
+- `/src/utils/wifi_manager.*`: WiFi and NTP connectivity
+- `/src/utils/time_utils.*`: Time formatting and utilities
+- `/src/fonts/font5x7.h`: Font definition for the display
+
+## License
+
+This project is provided as an open-source example for educational purposes.
+
+## Acknowledgments
+
+- Inspired by the digital rain effect from "The Matrix" movie
+- Built with PlatformIO IDE for seamless development