# ESP32-S3 CLIProxyAPI Dashboard

Hiển thị thống kê sử dụng CLIProxyAPI trên màn hình ST7789 320x240 gắn với ESP32-S3 (N16R8).

## 📦 Phần cứng cần thiết

| Thành phần | Mô tả |
|------------|-------|
| **ESP32-S3** | Board có PSRAM (N16R8 khuyến nghị) – ví dụ: ESP32-S3-DevKitC-1, ESP32-S3-N16R8 |
| **Màn hình ST7789** | 320×240 SPI, driver ST7789, không touch (hoặc có touch nhưng không dùng) |
| **Dây nối** | 6–7 dây jumper (mẹ-đực hoặc hàn trực tiếp) |
| **Nguồn** | USB-C (5 V) cấp cho ESP32-S3 |

> ⚠️ ESP32-S3 chỉ chịu 3.3 V trên GPIO. Màn hình ST7789 thông thường hoạt động 3.3 V logic – **không cần level-shifter** nếu màn hình đã có LDO 3.3 V onboard (phần lớn module ST7789 bán sẵn đều có).

---

## 🔌 Sơ đồ đấu nối (theo code hiện tại)

| Màn hình ST7789 | ESP32-S3 (GPIO) | Chú thích |
|----------------|----------------|----------|
| **VCC** | 3V3 | Cấp 3.3 V (hoặc 5V nếu module có LDO) |
| **GND** | GND | |
| **SCL / SCK** | **GPIO 5** | SPI Clock |
| **SDA / MOSI** | **GPIO 6** | SPI MOSI |
| **RST** | **GPIO 7** | Reset (active low) |
| **DC / RS** | **GPIO 15** | Data/Command select |
| **CS** | **GPIO 16** | Chip Select |
| **BLK / BL** | 3V3 (hoặc GPIO tùy chỉnh) | Backlight – nối 3V3 để luôn bật, hoặc gắn GPIO để PWM dimming |

> Nếu màn hình của bạn có chân **MISO** – **không cần nối** (driver Adafruit_ST7789 chỉ dùng chế độ write-only).

---

## 🛠 Chuẩn bị môi trường Arduino IDE

1. **Cài Arduino IDE** ≥ 2.x
2. **Boards Manager** → tìm **"esp32"** → cài **esp32 by Espressif Systems** ≥ 3.0.0
3. **Tools → Board** → **ESP32S3 Dev Module** (hoặc board ESP32-S3 cụ thể bạn dùng)
   - **USB CDC On Boot**: Enabled
   - **Flash Mode**: QIO 80MHz
   - **Flash Size**: 16 MB (128 Mb)
   - **Partition Scheme**: 16M Flash (3M APP / 9.9M FATFS) hoặc tuỳ chọn
   - **PSRAM**: OPI PSRAM
4. **Library Manager** cài các thư viện sau:
   - `Adafruit GFX Library` (by Adafruit)
   - `Adafruit ST7735 and ST7789 Library` (by Adafruit)
   - `Adafruit NeoPixel` (by Adafruit)
   - `ArduinoJson` ≥ 7.x (by Benoit Blanchon)

---

## ⚙️ Cấu hình code trước khi nạp

Mở file `esp32-s3-cliproxy-dashboard.ino`, sửa các dòng sau nếu cần:

```cpp
// ── Cấu hình chân TFT ── (đổi nếu bạn đấu nối khác)
#define TFT_CS    16
#define TFT_DC    15
#define TFT_RST    7
#define TFT_MOSI   6   // SDA
#define TFT_SCLK   5   // SCL

// Màn hình ngang 320x240
#define SCREEN_WIDTH  320
#define SCREEN_HEIGHT 240
#define TFT_ROTATION  3   // 0,1,2,3 – xoay cho đúng hướng

// ── WiFi mặc định (sẽ ghi đè qua giao diện web sau khi nạp) ──
char g_ssid[64]     = "TEN_WIFI_CUA_BAN";
char g_password[64] = "MAT_KHAU_WIFI";

// ── API URL trỏ về dashboard server (máy chạy usage-dashboard.py) ──
// Mặc định: http://<IP_MAY_CHU>:8320/api/summary?range=today
char g_api_url[160] = "http://192.168.1.3:8320/api/summary?range=today";
```

> **Lưu ý**: `g_api_url` phải trỏ đến endpoint `/api/summary` của `usage-dashboard.py` đang chạy trên máy chủ (PC/Server) cùng mạng LAN.

---

## 🚀 Nạp firmware

1. Kết nối ESP32-S3 với PC qua USB-C.
2. Chọn đúng **Port** (COMx / /dev/ttyUSBx).
3. Nhấn **Upload** (mũi tên phải) trong Arduino IDE.
4. Mở **Serial Monitor** (115200 baud) để theo dõi log.

---

## 🌐 Cấu hình WiFi & API qua giao diện Web (AP Mode)

Lần đầu nạp (hoặc khi reset cấu hình):

1. ESP32 phát Access Point **`ESP32-S3-Setup`** (không mật khẩu).
2. Kết nối điện thoại / laptop vào WiFi này.
3. Mở trình duyệt truy cập **`http://192.168.4.1`**.
4. Trang web sẽ hiện:
   - Nút **"Quét WiFi"** → chọn mạng nhà bạn.
   - Nhập **Mật khẩu WiFi**.
   - Kiểm tra/sửa **API URL** (IP máy chạy dashboard server + port 8320).
5. Nhấn **"Lưu và Kết nối"** → ESP32 restart, kết nối WiFi nhà bạn.

Sau khi đã có cấu hình:
- Truy cập **`http://<IP_ESP32_TRONG_MANG_LAN>`** để đổi API URL, đổi WiFi, hoặc Reset về AP Mode.

---

## 📊 Giao diện màn hình (4 trang tự xoay 10s/lần)

| Trang | Nội dung |
|-------|----------|
| **0 – Total** | Tổng Requests, Failed, Total Tokens, Input / Output / Reasoning / Cached |
| **1 – Account** | Top 5 tài khoản: requests, tokens, failed |
| **2 – Model** | Top 6 model: requests, tokens, failed |
| **3 – Hourly** | 6 giờ gần nhất: requests, tokens |

- **Đèn RGB onboard (GPIO 48)**:
  - 🔵 **Xanh dương** = fetch dữ liệu thành công
  - 🟢 **Xanh lá** = chuyển trang hiển thị
- Nút **BOOT** (GPIO 0) trên board: *chưa gán chức năng trong code, dự trữ cho tương lai*.

---

## 🔧 Troubleshooting

| Vấn đề | Nguyên nhân / Khắc phục |
|--------|------------------------|
| Màn hình trắng / không sáng | Kiểm tra dây **BLK** (nối 3V3), kiểm tra `TFT_ROTATION` (thử 0–3), kiểm tra `init(240, 320)` vs `init(320, 240)`. |
| Kết nối WiFi thất bại -> rơi về AP | SSID/Pass sai, hoặc router chặn ESP32 (MAC filter, band 5 GHz – ESP32 chỉ 2.4 GHz). |
| Fetch lỗi ("Fetch loi! Kiem tra API URL") | API URL sai IP") | Kiểm tra IP server, port 8320, firewall, và `usage-dashboard.py` đang chạy (`start` hoặc `serve`). |
| JSON parse error | Đảm bảo server trả về đúng format `summary`, `accounts[]`, `models[]`, `hours[]` như code mong đợi. |
| Guru Meditation / Crash | Tăng stack size task `fetch_task` (hiện 8192) hoặc giảm `DynamicJsonDocument` size. |

---

## 📁 Cấu trúc thư mục

```
esp32-s3-cliproxy-dashboard/
├── esp32-s3-cliproxy-dashboard.ino   # Firmware chính
├── README.md                          # File này
└── (các file build tự động)
```

---

## 📄 License

MIT – tự do sử dụng, sửa đổi, phân phối.