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

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

README.md Unescape Escape