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

Cài Arduino IDE ≥ 2.x
Boards Manager → tìm "esp32" → cài esp32 by Espressif Systems ≥ 3.0.0
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
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:

// ── 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

Kết nối ESP32-S3 với PC qua USB-C.
Chọn đúng Port (COMx / /dev/ttyUSBx).
Nhấn Upload (mũi tên phải) trong Arduino IDE.
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):

ESP32 phát Access Point ESP32-S3-Setup (không mật khẩu).
Kết nối điện thoại / laptop vào WiFi này.
Mở trình duyệt truy cập http://192.168.4.1.
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).
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")
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

No part of this software or its source code may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of the copyright holder.

README.md Unescape Escape