# 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( ... semua HTML, CSS, JavaScript ... )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 |