151 lines
6.0 KiB
Markdown
151 lines
6.0 KiB
Markdown
# 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. |