204 lines
5.9 KiB
Markdown
204 lines
5.9 KiB
Markdown
# Ringkasan WebServer & API — Smart UPS V1.1
|
|
|
|
## Struktur Kode WebServer
|
|
|
|
### `upsSvr.h` — Backend (C++ ESP8266)
|
|
```cpp
|
|
AsyncWebServer server(80); // Server HTTP port 80
|
|
```
|
|
|
|
**Route handlers** (daftar endpoint):
|
|
```cpp
|
|
server.on("/login", HTTP_GET, handler); // Validasi login
|
|
server.on("/logout", HTTP_GET, handler); // Logout
|
|
server.on("/state", HTTP_GET, handleGetState); // REST API utama
|
|
server.on("/", onRootRequest); // Dashboard HTML
|
|
server.on("/*", onRootRequest); // Catch-all → dashboard
|
|
```
|
|
|
|
**Auth checking** — manual Base64 decode:
|
|
```cpp
|
|
const char* http_username = "admin";
|
|
const char* http_password = "admin123";
|
|
|
|
bool checkAuth(request) {
|
|
// 1. Ambil header "Authorization"
|
|
// 2. Cek apakah diawali "Basic "
|
|
// 3. Base64 decode bagian setelah "Basic "
|
|
// 4. Split jadi "username:password"
|
|
// 5. Bandingkan dengan http_username / http_password
|
|
}
|
|
```
|
|
|
|
Setiap request ke `/state` dicek dulu:
|
|
```cpp
|
|
void handleGetState(request) {
|
|
if (!checkAuth(request)) {
|
|
request->send(401, "application/json", "{\"success\":0}"); // JSON, bukan popup browser
|
|
return;
|
|
}
|
|
// ... baca/tulis parameter dan kirim response JSON ...
|
|
}
|
|
```
|
|
|
|
**Fungsi utama `handleGetState()`**:
|
|
1. Baca parameter URL (`on`, `auto`, `shutdown`, `cm`, dll)
|
|
2. Jika ada parameter → eksekusi perintah (misal: nyalakan power)
|
|
3. Jika tidak ada parameter → kirim status lengkap sebagai JSON
|
|
|
|
### `webUI.h` — Frontend (HTML+JS embedded)
|
|
HTML ini disimpan di PROGMEM (flash), fallback jika file LittleFS tidak ada.
|
|
|
|
```cpp
|
|
const char index_html[] PROGMEM = R"rawliteral(
|
|
<!DOCTYPE html>
|
|
<html>... semua HTML, CSS, JavaScript ...</html>
|
|
)rawliteral";
|
|
```
|
|
|
|
### `data/index.html` — Frontend (HTML+JS di LittleFS)
|
|
File fisik di LittleFS, sama persis dengan `webUI.h`. Server prioritaskan ini.
|
|
|
|
### `upsCfg.h` — Konfigurasi
|
|
Simpan & baca pengaturan dari `/cfg.json` di LittleFS.
|
|
```cpp
|
|
void saveCfg(); // Simpan: auto, shut, chgMode, chgILTC, chgOVP, chgAR
|
|
void loadCfg(); // Baca kembali
|
|
```
|
|
|
|
---
|
|
|
|
## Alur Request
|
|
|
|
### Request tanpa parameter → Refresh status
|
|
```
|
|
Browser → GET /state (Authorization: Basic ...)
|
|
← 200 {"success":2, "on":1, "v":"12.5", ...}
|
|
```
|
|
|
|
### Request dengan parameter → Eksekusi perintah
|
|
```
|
|
Browser → GET /state?on=1 (Authorization: Basic ...)
|
|
← 200 {"success":1, "on":1, ...}
|
|
```
|
|
|
|
### Request tanpa auth → Ditolak
|
|
```
|
|
Browser → GET /state (tanpa Authorization)
|
|
← 401 {"success":0}
|
|
```
|
|
|
|
---
|
|
|
|
## Cara Menggunakan API
|
|
|
|
### 1. Baca Status UPS
|
|
```bash
|
|
curl -u admin:admin123 http://192.168.1.100/state
|
|
```
|
|
Response:
|
|
```json
|
|
{"success":2, "on":1, "state":1, "v":"13.20", "batt":4, "battP":100, "line":1, ...}
|
|
```
|
|
|
|
### 2. Nyalakan Power Output
|
|
```bash
|
|
curl -u admin:admin123 "http://192.168.1.100/state?on=1"
|
|
```
|
|
|
|
### 3. Matikan Power Output
|
|
```bash
|
|
curl -u admin:admin123 "http://192.168.1.100/state?on=0"
|
|
```
|
|
|
|
### 4. Shutdown Timer (120 detik)
|
|
```bash
|
|
curl -u admin:admin123 "http://192.168.1.100/state?shutdown=120"
|
|
```
|
|
|
|
### 5. Set Mode Auto ON
|
|
```bash
|
|
curl -u admin:admin123 "http://192.168.1.100/state?auto=0" # Disabled
|
|
curl -u admin:admin123 "http://192.168.1.100/state?auto=1" # Line Powered
|
|
curl -u admin:admin123 "http://192.168.1.100/state?auto=2" # Persistent on Line
|
|
```
|
|
|
|
### 6. Set Charge Mode (0=Always, 1=90-100%, ..., 9=80-85%)
|
|
```bash
|
|
curl -u admin:admin123 "http://192.168.1.100/state?cm=1"
|
|
```
|
|
|
|
### 7. Set FCoPL (Full Charge on Power Lost)
|
|
```bash
|
|
curl -u admin:admin123 "http://192.168.1.100/state?coil=0" # Disabled
|
|
curl -u admin:admin123 "http://192.168.1.100/state?coil=1" # Always
|
|
curl -u admin:admin123 "http://192.168.1.100/state?coil=3" # At battery ≤90%
|
|
```
|
|
|
|
### 8. AVR / OVP
|
|
```bash
|
|
curl -u admin:admin123 "http://192.168.1.100/state?car=1" # AVR ON
|
|
curl -u admin:admin123 "http://192.168.1.100/state?car=0" # AVR OFF
|
|
curl -u admin:admin123 "http://192.168.1.100/state?covp=1" # OVP ON
|
|
```
|
|
|
|
### 9. Set Shutdown Suggestion Level
|
|
```bash
|
|
curl -u admin:admin123 "http://192.168.1.100/state?shutlv=0" # Disabled
|
|
curl -u admin:admin123 "http://192.168.1.100/state?shutlv=1" # On Battery
|
|
curl -u admin:admin123 "http://192.168.1.100/state?shutlv=3" # ≤50% Battery
|
|
```
|
|
|
|
### 10. Login (untuk testing)
|
|
```bash
|
|
curl -u admin:admin123 http://192.168.1.100/login
|
|
# 200 → {"success":1}
|
|
```
|
|
|
|
### 11. Buka Dashboard via Browser
|
|
```
|
|
http://192.168.1.100/
|
|
→ Login overlay (isi admin / admin123)
|
|
→ Dashboard muncul
|
|
→ Klik "Logout" untuk keluar
|
|
```
|
|
|
|
---
|
|
|
|
## Respon JSON — Penjelasan Field
|
|
|
|
```json
|
|
{
|
|
"success": 2, // 1=ada perubahan, 2=refresh biasa
|
|
"on": 1, // target power (yg diminta ON/OFF)
|
|
"state": 1, // real power (aktual ON/OFF)
|
|
"v": "13.20", // tegangan baterai (volt)
|
|
"batt": 4, // level baterai (0-4)
|
|
"battP": 100, // persentase baterai (0-100)
|
|
"line": 1, // 0=OFF, 1=Line/AC, 2=Battery
|
|
"auto": 1, // mode auto ON (0/1/2)
|
|
"battBlink": 0, // indicator charging blink
|
|
"battCritical": 0, // baterai kritis
|
|
"timedShutdown": 0, // shutdown timer aktif?
|
|
"shutdownRemain": 0, // sisa detik shutdown
|
|
"chgError": 0, // 0=normal, 1=batt not detected, 2=short, 4=overvoltage
|
|
"charging": 2, // 0=tidak charge, 1=reduced, 2=full charging
|
|
"chgMode": 1, // mode charge (0..9)
|
|
"chgOVP": 1, // overvoltage protection ON/OFF
|
|
"chgReducer": 0, // AVR ON/OFF
|
|
"chgFullTrig": 3, // FCoPL mode (0..5)
|
|
"chgOFC": 0 // ongoing full charge flag
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Catatan Penting
|
|
|
|
| Hal | Keterangan |
|
|
|-----|-----------|
|
|
| **Auth** | Basic Auth, username/password hardcoded di `upsSvr.h:16-17` |
|
|
| **Login gagal** | Server return `401` → JS tampilkan overlay login (bukan popup browser) |
|
|
| **Kompresi** | Ganti username/password dengan mengedit `upsSvr.h` |
|
|
| **Rename** | `upsSvr.h` → file backend, `webUI.h` → frontend embedded, `upsCfg.h` → config |
|