# 🇨🇮 Côte d'Ivoire District Clock & UNDP Projects Tracker

This project is an intelligent embedded system based on an **ESP32** that serves as a premium desk clock and an interactive tracking board for UNDP (United Nations Development Programme) projects by district in Côte d'Ivoire.

It includes a TFT LCD screen powered by **LVGL (v8 & v9)**, a 3D-printed map of Côte d'Ivoire equipped with **14 addressable WS2812B LEDs** (one for each district), a **DS1302** Real-Time Clock (RTC), two physical push buttons, and an active buzzer for alarms.

---

## 🔌 Hardware Connections

### 1. TFT LCD Screen (ILI9341 / ILI9488) - SPI2 (VSPI)
*   **MOSI** ➡️ `GPIO23`
*   **MISO** ➡️ `GPIO19`
*   **SCK**  ➡️ `GPIO18`
*   **CS**   ➡️ `GPIO5`
*   **DC/RS**➡️ `GPIO21`
*   **RESET**➡️ `GPIO22`
*   **LED / Backlight** ➡️ Tied directly to 3.3V/VCC (or driven by a GPIO)

### 2. DS1302 RTC Module
*   **CE / RST** ➡️ `GPIO27`
*   **I/O / DAT**➡️ `GPIO26`
*   **SCLK / CLK**➡️ `GPIO25`

### 3. District Map (14 x WS2812B NeoPixel LEDs)
*   **DIN** of the first LED ➡️ `GPIO13`
*   *The sequence of the addressable LEDs (0 to 13) maps to the following districts:*
    1.  LED 0: `U1` ➡️ **Bas-Sassandra** (Bottom-Left)
    2.  LED 1: `U2` ➡️ **Montagnes** (Mid-Left Bottom)
    3.  LED 2: `U3` ➡️ **Woroba** (Mid-Left Top)
    4.  LED 3: `U4` ➡️ **Sassandra-Marahoue** (Center-Left)
    5.  LED 4: `U5` ➡️ **Denguele** (Top-Left)
    6.  LED 5: `U6` ➡️ **Savanes** (Top-Center)
    7.  LED 6: `U7` ➡️ **Vallee du Bandama** (Center-Mid Top)
    8.  LED 7: `U10`➡️ **Zanzan** (Top-Right)
    9.  LED 8: `U11`➡️ **Lacs** (Center-Right)
    10. LED 9: `U12`➡️ **Yamoussoukro** (Center-Dot)
    11. LED 10: `U13`➡️ **Lagunes** (Mid-South-East)
    12. LED 11: `U14`➡️ **Comoe** (Bottom-Right)
    13. LED 12: `U15`➡️ **Abidjan** (Bottom-Mid-South)
    14. LED 13: `U16`➡️ **Goh-Djiboua** (Bottom-Mid-Left)

### 4. Push Buttons and Buzzer
*   **Button 1 (BP1 - Green button)** ➡️ `GPIO17` (Connected to GND, internal pull-up active)
*   **Button 2 (BP2 - Yellow button)**➡️ `GPIO4` (Connected to GND, internal pull-up active)
*   **Buzzer (Active)**               ➡️ `GPIO16`

---

## 📚 Required Libraries (Arduino IDE)

Install these libraries via the Arduino IDE Library Manager:
1.  **lvgl** (v8.x or v9.x)
2.  **TFT_eSPI** (by Bodmer)
3.  **Adafruit NeoPixel** (by Adafruit)
4.  **RtcByMakuna** (by Makuna)
5.  **ElegantOTA** (v3.x)
6.  **ESPAsyncWebServer** (Install via GitHub Zip, required for async web server)
7.  **AsyncTCP** (Install via GitHub Zip, ESPAsyncWebServer dependency)

---

## ⚙️ Initial Configuration Guide

### 🛠️ Configure `TFT_eSPI`
1.  Navigate to your Arduino libraries directory (e.g. `Documents/Arduino/libraries/TFT_eSPI/`).
2.  Open the file `User_Setup.h` in a text editor.
3.  Define the driver corresponding to your screen (e.g. `#define ILI9341_DRIVER` or `#define ILI9488_DRIVER`).
4.  Uncomment/define the following SPI mapping:
    ```cpp
    #define TFT_MISO 19
    #define TFT_MOSI 23
    #define TFT_SCLK 18
    #define TFT_CS    5  // Chip select
    #define TFT_DC    21 // Data/Command
    #define TFT_RST   22 // Reset
    ```
5.  Save and close the file.

### 🎨 Configure `LVGL` (v8 & v9)
1.  Navigate to `Documents/Arduino/libraries/`.
2.  Copy the file `lv_conf_template.h` from the `lvgl` directory to the parent `libraries/` directory.
3.  Rename it to `lv_conf.h`.
4.  Open `lv_conf.h` and change `#if 0` at the top to `#if 1` to enable it.
5.  Ensure color depth matches: `#define LV_COLOR_DEPTH 16`.
6.  Enable Montserrat fonts (`12`, `14`, `16`, `40`) by setting their definitions to `1`:
    ```cpp
    #define LV_FONT_MONTSERRAT_12 1
    #define LV_FONT_MONTSERRAT_14 1
    #define LV_FONT_MONTSERRAT_16 1
    #define LV_FONT_MONTSERRAT_40 1
    ```
7.  Save and close the file.

---

## 🚀 How It Works

### 1. LCD Interface (LVGL)
The display transitions through several modern views:
*   **Clock Mode (Default):** Displays the time in a large `HH:MM:SS` format, the calendar date in English, the Wi-Fi AP name, and the state of the 3 alarms.
*   **District Mode:** Displays a clean overlay containing the selected district name, project status ("UNDP Project Completed", "UNDP Project In Progress", "No UNDP Project"), a color pastille, and a 5-second progress bar countdown.
*   **Auto Mode:** Displays global stats summarizing project counts across the country.
*   **Alarm Alert:** A red modal box pops up with an "OK" touch button when an alarm triggers.

### 2. Physical Controls (Buttons BP1 & BP2)
*   **BP1 (Green Button - Short Press):**
    *   Mutes the alarm if it is currently ringing.
    *   Cycles to the **next district** (resets the 5s timer).
*   **BP2 (Yellow Button - Short Press):**
    *   Shows the current **active district card** and lights up its LED for 5 seconds.
    *   Resets the 5-second timer if pressed while already viewing a card.
*   **BP1 (Hold for 6 seconds) ➡️ AUTO Mode:**
    *   All 14 LEDs light up simultaneously on the map showing their project statuses (Green/Blue/Red). The screen displays statistics for 6 seconds before returning to clock mode.
*   **BP2 (Hold for 6 seconds) ➡️ Shuffled Walkthrough Mode:**
    *   The system shuffles all 14 districts in a random order and shows them one by one for 5 seconds each. The corresponding LED lights up. Once done, it returns to clock mode.

### 3. Alarms and Buzzer
Three independent alarms can be configured. When an alarm triggers:
*   The active buzzer beeps at 1Hz (500ms ON / 500ms OFF).
*   The red alert box appears on the screen.
*   The alarm can be stopped by pressing the physical **BP1** button or clicking **OK** on the screen.
*   A safety timer turns off the buzzer automatically after 60 seconds if no button is pressed.

### 4. Web Portal (Asynchronous Wi-Fi)
The ESP32 starts its own Wi-Fi Access Point:
*   **SSID:** `PNUD_District_Clock`
*   **Password:** `pnud1234`
*   **IP Address:** `192.168.4.1`

Connect to this network and open `http://192.168.4.1` in your browser to access the Ivory Coast Flag-themed dashboard:
*   **Clock Settings:** Synchronize the RTC time with your device or save a manual date/time.
*   **Alarm Configuration:** Toggle alarms on/off and edit schedules.
*   **District Projects:** Modify the project status (Completed, In Progress, Non-existent) for all 14 districts. Changes instantly update the map LEDs and LCD screen and persist inside the ESP32 `Preferences` storage.
*   **OTA Update (ElegantOTA):** Accessible at `http://192.168.4.1/update` to flash new firmware binaries wirelessly.
