Dokumentasi Teknis v1.0

Siaga Banjir — FEWS

Flood Early Warning System — Dokumentasi Lengkap Sistem Monitoring Ketinggian Air Sungai untuk Peringatan Dini Banjir berbasis IoT.

Tentang Proyek Arsitektur Panduan

Tentang Proyek

Visi

Menjadi sistem peringatan dini banjir berbasis IoT yang andal, terjangkau, dan mudah diakses oleh masyarakat Indonesia.

Misi

Menyediakan data ketinggian air sungai secara real-time dan notifikasi peringatan dini multi-kanal (Email & Telegram) kepada warga.

SiagaBanjir adalah sistem monitoring ketinggian air sungai berbasis Internet of Things (IoT) yang dirancang untuk bekerja 24 jam non-stop, mandiri, dan siap digunakan di lingkungan nyata. Sistem ini menggunakan perangkat ESP32 yang dipasang di titik-titik rawan banjir untuk memantau ketinggian air secara real-time dan mengirimkan data melalui protokol MQTT.

Data yang terkumpul diproses secara otomatis untuk menentukan status bahaya banjir, menampilkan visualisasi di dashboard interaktif, dan mengirimkan notifikasi peringatan dini melalui Email dan Telegram Bot kepada warga yang terdaftar.

Fitur Unggulan

Monitoring Real-time

Pemantauan ketinggian air secara langsung dengan interval data setiap 30 detik dari perangkat ESP32 di lapangan.

Peta Interaktif (Leaflet)

Visualisasi lokasi perangkat monitoring pada peta interaktif dengan marker warna sesuai status banjir.

Notifikasi Multi-kanal

Peringatan dini otomatis dikirim melalui Email dan Telegram Bot kepada warga yang telah subscribe.

ESP32-CAM Integration

Dokumentasi visual kondisi sungai melalui kamera terintegrasi pada perangkat ESP32-CAM di lapangan.

Grafik & Chart

Visualisasi tren ketinggian air, suhu, kelembaban, dan data sensor lainnya dalam bentuk grafik interaktif Chart.js.

Telegram Bot

Bot Telegram interaktif untuk mendapatkan Chat ID, notifikasi otomatis, dan panduan penggunaan sistem.

Arsitektur Sistem

Sistem Siaga Banjir menggunakan arsitektur client-server berbasis event-driven dengan alur data sebagai berikut:

ESP32 Devices
Sensor + GPS
MQTT Broker
Mosquitto
MQTT Listener
Node.js Service
Database
MySQL
Web Dashboard
PHP + Bootstrap
Notifikasi
Email + Telegram
Warning Devices
Siren + Light
Alur Data Lengkap:
  1. Perangkat ESP32 membaca sensor ketinggian air, GPS, suhu, kelembaban, dan status hujan.
  2. Data dikirim melalui protokol MQTT ke topik monitoring/{device_id}/sensor dan monitoring/{device_id}/status.
  3. MQTT Listener (Node.js) menerima data, memprosesnya, dan menyimpan ke database MySQL.
  4. Sistem menghitung status banjir berdasarkan ambang batas (threshold) yang telah ditentukan per perangkat.
  5. Notifikasi dikirim secara otomatis ke warga yang subscribe melalui Email dan/atau Telegram sesuai level preferensi masing-masing.
  6. Dashboard Web (Admin & Warga) menampilkan data real-time, grafik, peta interaktif, dan riwayat notifikasi.
  7. Warning Devices (sirine/lampu) dapat dikendalikan secara manual dari dashboard admin melalui MQTT.

Stack Teknologi

Backend
PHP 8.x MySQL / MariaDB Node.js 18+ MQTT Protocol PHPMailer vlucas/phpdotenv
Frontend
Bootstrap 5.3 jQuery 3.7 Chart.js 4.x Leaflet.js Toastr JS DataTables
IoT & Infrastruktur
ESP32 ESP32-CAM Ultrasonic Sensor GPS Module Mosquitto MQTT PM2 Process Manager
Notifikasi
Telegram Bot API SMTP / PHP mail() node-telegram-bot-api
Package Manager
Composer npm
Keamanan
CSRF Protection Argon2id Password Hash Brute-force Protection API Key Auth

Komponen Sistem

Halaman landing page yang menjelaskan tentang proyek Siaga Banjir, masalah yang diatasi, dan solusi yang ditawarkan. Publik dapat mendaftar sebagai warga atau login ke dashboard masing-masing.

index.phpHalaman utama publik dengan informasi proyek
dokumentasi.phpDokumentasi lengkap proyek (halaman ini)

Sistem autentikasi dengan role-based access control: Admin dan Warga. Dilengkapi proteksi brute-force dan CSRF token.

users/index.phpHalaman login
users/register.phpPendaftaran akun warga baru
users/logout.phpLogout session
app/auth.phpFungsi autentikasi (require_login(), require_admin())
app/functions.phpFungsi helper (CSRF, sanitasi, URL)
app/config.phpKonfigurasi dari .env

Fitur lengkap untuk administrator dalam mengelola sistem:

users/admin/index.phpBeranda dengan peta interaktif & status perangkat
users/admin/devices.phpManajemen perangkat monitoring
users/admin/device.phpDetail perangkat, sensor, threshold, grafik, galeri kamera
users/admin/users.phpManajemen pengguna (CRUD)
users/admin/warning_devices.phpManajemen perangkat alarm (sirine/lampu) dengan kontrol MQTT
users/admin/profile.phpProfil admin

Dashboard untuk warga yang telah mendaftar dan subscribe ke perangkat monitoring:

users/warga/index.phpBeranda dengan info perangkat, grafik, peta, dan riwayat
users/warga/settings.phpPengaturan notifikasi (Email/Telegram, level notifikasi)
users/warga/subscribe.phpSubscribe ke perangkat monitoring (POST)
users/warga/unsubscribe.phpUnsubscribe dari perangkat (POST)

Layanan backend yang berjalan secara terus-menerus di server:

mqtt/listener.jsMQTT Listener — menerima data sensor/status dari ESP32, menyimpan ke DB, memicu notifikasi (Node.js + PM2)
bot/bot.jsTelegram Bot Polling — melayani perintah /start, /chatid, /help (Node.js + PM2)
mqtt/ecosystem.config.jsKonfigurasi PM2 untuk menjalankan listener

Sistem notifikasi otomatis multi-kanal yang memungkinkan warga menerima peringatan dini banjir:

  • Notifikasi Email: Dikirim melalui SMTP/PHP mail() dengan format HTML responsif yang mencakup status banjir, ketinggian air, lokasi, dan tautan ke dashboard.
  • Notifikasi Telegram: Dikirim melalui Telegram Bot API dengan format Markdown yang ringkas dan informatif.
  • Level Notifikasi: Warga dapat memilih level notifikasi (Waspada, Siaga, Awas) — hanya peringatan yang sesuai atau lebih tinggi yang akan dikirim.
  • Log Notifikasi: Semua notifikasi tercatat di tabel notification_logs untuk audit dan evaluasi.

File utama: app/notify.php, api/notify_trigger.php

Perangkat ESP32-CAM dapat mengirimkan foto kondisi sungai secara periodik ke server:

  • Autentikasi menggunakan header X-Device-ID dan X-API-Key
  • Foto disimpan di uploads/images/{tahun-bulan}/ dengan format JPEG
  • Metadata (boot count, RSSI, water level) turut disimpan
  • Galeri kamera dapat dilihat di halaman detail perangkat admin
  • Limit ukuran file: 5MB per foto

File utama: api/camera.php

Sistem terintegrasi dengan perangkat alarm fisik (sirine dan/atau lampu rotator) yang dapat dikendalikan dari dashboard admin:

  • Dua tipe perangkat: Siren (sirine suara) dan Light (lampu rotator)
  • Dikendalikan melalui MQTT publish ke topik warning/{device_id}/control
  • Status perangkat (ON/OFF) dipantau melalui topik warning/{device_id}/status
  • Tombol kontrol: ON, OFF, dan Test (5 detik) di dashboard admin
  • Semua aktivitas tercatat di log sistem

File utama: users/admin/warning_devices.php

Level Status Banjir

Sistem mendefinisikan 4 level status banjir berdasarkan ketinggian air yang terukur. Setiap perangkat dapat memiliki ambang batas (threshold) yang berbeda-beda:

Level Kode Warna Keterangan Tindakan
✅ Normal normal   Hijau Ketinggian air dalam batas aman Tidak ada notifikasi
⚠️ Waspada waspada   Kuning Ketinggian air mulai meningkat, perlu kewaspadaan Notifikasi dikirim ke warga yang memilih level Waspada
🟠 Siaga siaga   Oranye Ketinggian air mendekati level berbahaya Notifikasi dikirim ke warga level Siaga ke atas
🚨 Awas / Bahaya awas   Merah Ketinggian air mencapai level berbahaya, potensi banjir Notifikasi dikirim ke semua warga, aktivasi warning devices

Ambang batas (threshold) untuk setiap level dapat dikonfigurasi per perangkat melalui dashboard admin pada halaman detail perangkat.

Struktur Database

Sistem menggunakan database MySQL/MariaDB dengan tabel-tabel utama sebagai berikut:

Nama Tabel Fungsi
usersData pengguna (admin & warga) — nama, email, password (Argon2id), role, status, notifikasi, subscribed device
monitoring_devicesData perangkat ESP32 — device_id, nama_lokasi, API key, GPS, status aktif, mode operasi, send_interval, last_trx
device_sensorsMapping sensor per perangkat — menghubungkan device dengan sensor types
sensor_typesJenis sensor yang tersedia — water_level, temperature, humidity, rain, dll.
sensor_readingsData pembacaan sensor individual — nilai numerik, boolean, atau teks per session
reading_sessionsSesi pembacaan data — status banjir, water level, raw payload JSON
device_statusStatus terkini perangkat — online/offline, water level terakhir, last_session_id
device_imagesFoto dari ESP32-CAM — path file, ukuran, water level, captured_at
thresholdsAmbang batas banjir per perangkat — water_level_min, water_level_max, status_level
device_shutdown_eventsLog mati/peristiwa shutdown perangkat — reason, vbat, acknowledged
warning_devicesData perangkat alarm (sirine/lampu) — device_id, tipe, lokasi, status, MQTT topic
notification_logsLog pengiriman notifikasi — channel (email/telegram), status, error_msg
login_attemptsProteksi brute-force — IP, email, jumlah percobaan, waktu
system_logsLog aktivitas sistem umum — aksi, deskripsi, IP, user-agent

API & Endpoint

Endpoint Method Fungsi Autentikasi
/api/camera.php POST Upload foto dari ESP32-CAM X-Device-ID + X-API-Key (headers)
/api/notify_trigger.php GET Trigger notifikasi (dipanggil internal oleh MQTT listener) Internal (parameter query)
Topik MQTT
Topik Direction Payload Keterangan
monitoring/{id}/sensorESP32 → ServerJSONData sensor (water_level, suhu, dll.)
monitoring/{id}/statusESP32 → ServerJSONStatus hidup/mati, mode, vbat
warning/{id}/controlServer → AlarmON / OFF / TESTKontrol perangkat alarm
warning/{id}/statusAlarm → ServerON / OFFStatus perangkat alarm

Panduan Pengguna

Untuk Warga (Masyarakat Umum)
  1. Klik "Daftar" di halaman utama (atau langsung ke /users/register.php)
  2. Isi nama lengkap, email, dan password
  3. Setelah registrasi, login ke akun Anda
  4. Di dashboard warga, cari perangkat monitoring terdekat dan klik Subscribe
  5. Buka menu Notifikasi untuk mengatur preferensi notifikasi
  6. Untuk notifikasi Telegram: chat ke @SiagaBanjirBot, ketik /chatid, copy Chat ID, tempel di menu Notifikasi
Untuk Admin
  1. Login dengan akun administrator
  2. Perangkat: Tambah/kelola perangkat ESP32, atur threshold banjir
  3. Detail Perangkat: Lihat data real-time, grafik sensor, galeri kamera, atur mode operasi
  4. Pengguna: Kelola akun warga dan admin
  5. Perangkat Alarm: Tambah/kelola sirine/lampu, kontrol ON/OFF/Test via MQTT
Panduan Telegram Bot

Bot Telegram Siaga Banjir merespon perintah berikut:

/startMemulai bot dan mendapat sambutan
/chatidMendapatkan Chat ID untuk notifikasi
/helpMenampilkan bantuan perintah yang tersedia
Panduan Instalasi Perangkat

Untuk pengembang atau teknisi lapangan yang memasang perangkat ESP32:

  1. Flash firmware ESP32 dengan konfigurasi WiFi, MQTT broker, dan device ID
  2. Daftarkan device ID dan API Key di dashboard admin
  3. Atur threshold ketinggian air sesuai kondisi lapangan
  4. Pasang sensor ultrasonik di lokasi pemantauan sungai
  5. Uji koneksi dengan melihat status "online" di dashboard admin

Informasi Pengembangan

Persyaratan Sistem
  • Web Server: Apache / Nginx dengan PHP 8.0+
  • Database: MySQL 5.7+ / MariaDB 10.3+
  • Node.js 18+ (untuk MQTT Listener & Telegram Bot)
  • MQTT Broker: Mosquitto atau sejenisnya
  • Composer (dependency manager PHP)
  • npm (dependency manager Node.js)
  • PM2 (process manager untuk Node.js services)
Instalasi
# 1. Clone repositori ke server web
git clone https://github.com/username/siagabanjir.git

# 2. Install dependensi PHP
cd siagabanjir
composer install

# 3. Copy .env dan sesuaikan konfigurasi
cp .env.example .env
# Edit .env: DB_HOST, DB_USER, DB_PASS, DB_NAME, MQTT_*, TELEGRAM_*, dsb.

# 4. Install dependensi Node.js untuk MQTT Listener
cd mqtt
npm install

# 5. Install dependensi Node.js untuk Telegram Bot
cd ../bot
npm install

# 6. Import database dari file SQL yang disediakan

# 7. Jalankan services dengan PM2
pm2 start mqtt/ecosystem.config.js
pm2 start bot/bot.js --name telegram-bot

# 8. Simpan PM2 config
pm2 save
pm2 startup
Konfigurasi Lingkungan (.env)
# Database
DB_HOST=localhost
DB_USER=root
DB_PASS=secret
DB_NAME=siagabanjir

# Aplikasi
BASE_URL=https://fews.kakaadebasodara.com
LOGIN_MAX_ATTEMPTS=5
LOGIN_BLOCK_MINUTES=60

# MQTT Broker
MQTT_HOST=localhost
MQTT_PORT=1883
MQTT_USER=mqtt_user
MQTT_PASS=mqtt_pass

# Email / SMTP
MAIL_FROM=noreply@siagabanjir.com
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password
SMTP_ENCRYPTION=tls

# Telegram Bot
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_BOT_USERNAME=SiagaBanjirBot

Tim Pengembang

Proyek Siaga Banjir dikembangkan oleh tim yang terdiri dari:

Tim Pengembang
Developer & System Architect
Teknisi Lapangan
Instalasi & Pemeliharaan Perangkat

Repositori: github.com/username/siagabanjir