add esp32 dashboard

2026-07-06 10:16:18 +07:00
parent a3b3f417af
commit 790c3c3053
1 changed files with 151 additions and 0 deletions
@@ -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://<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.