diff --git a/esp32-s3-cliproxy-dashboard/README.md b/esp32-s3-cliproxy-dashboard/README.md new file mode 100644 index 0000000..3fb90f5 --- /dev/null +++ b/esp32-s3-cliproxy-dashboard/README.md @@ -0,0 +1,151 @@ +# 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://: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://`** để đổ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. \ No newline at end of file