# 📡 Panduan Integrasi Hardware Real-Time Gempa

## 🎯 Ringkasan Sistem

Sistem ini dirancang untuk menampilkan data real-time dari hardware deteksi getaran gempa. Setiap sensor/gateway hardware dapat mengirimkan data melalui API REST yang akan langsung ditampilkan di web dashboard.

---

## 🔧 Cara Kerja Real-Time Data

### Alur Data:

```
Hardware Sensor
      ↓
API Endpoint (/api/v1/devices/data)
      ↓
Database (device_data, gempa tables)
      ↓
JavaScript Real-Time Handler (public/js/realtime.js)
      ↓
Browser UI Updates (Live Display)
```

---

## 📝 Setup Hardware

### 1. Registrasi Device

Sebelum hardware dapat mengirim data, device harus terdaftar di sistem.

**Opsi A: Via Dashboard Admin**
```
Buka: Admin → Devices → Create New Device
- Device ID: Nomor unik hardware (mis: SENSOR-001)
- Name: Nama sensor (mis: Sensor Gempa Jakarta)
- Type: sensor / gateway / actuator
- Dapatkan API Key yang akan digunakan untuk autentikasi
```

**Opsi B: Via API (Untuk Automation)**
```bash
POST /api/v1/devices/register
Content-Type: application/json

{
  "device_id": "SENSOR-001",
  "name": "Seismic Sensor Jakarta",
  "type": "sensor",
  "capabilities": ["vibration", "magnitude"],
  "metadata": {
    "location": "Jakarta",
    "latitude": -6.2088,
    "longitude": 106.8456
  },
  "firmware_version": "1.0.0"
}

Response:
{
  "success": true,
  "message": "Device registered successfully",
  "data": {
    "device": { ... },
    "api_key": "xxx_api_key_xxx"
  }
}
```

---

## 📤 Mengirim Data dari Hardware

### Endpoint: `POST /api/v1/devices/data`

**Authentication:**
```
Header: X-API-Key: [api_key_dari_registrasi]
```

### Format Request:

```json
{
  "data": [
    {
      "type": "gempa",
      "value": 150,
      "timestamp": "2026-05-19T10:30:45Z"
    },
    {
      "type": "vibration",
      "value": {"x": 5.2, "y": 3.1, "z": 2.8},
      "timestamp": "2026-05-19T10:30:46Z"
    }
  ]
}
```

### Parameter Data:

| Parameter | Type | Wajib | Deskripsi |
|-----------|------|-------|-----------|
| type | string | Ya | Tipe data: `gempa`, `vibration`, `acceleration`, dll |
| value | number/object | Ya | Nilai sensor (bisa angka atau object) |
| timestamp | ISO8601 | Tidak | Waktu pengukuran (default: sekarang) |

### Contoh Request dengan cURL:

```bash
curl -X POST http://localhost:8000/api/v1/devices/data \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "type": "gempa",
        "value": 250,
        "timestamp": "2026-05-19T10:30:45Z"
      }
    ]
  }'
```

### Contoh Request dengan Python:

```python
import requests
import json
from datetime import datetime

API_KEY = "your_api_key_here"
BASE_URL = "http://localhost:8000/api/v1"

def send_earthquake_data(intensity, magnitude, depth=None):
    """Kirim data gempa ke server"""
    
    headers = {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    }
    
    payload = {
        "data": [
            {
                "type": "gempa",
                "value": {
                    "intensitas": intensity,
                    "magnitude": magnitude,
                    "kedalaman": depth or 0
                },
                "timestamp": datetime.utcnow().isoformat() + "Z"
            }
        ]
    }
    
    response = requests.post(
        f"{BASE_URL}/devices/data",
        headers=headers,
        json=payload
    )
    
    return response.json()

# Contoh penggunaan
result = send_earthquake_data(
    intensity=250,
    magnitude=5.5,
    depth=10
)

print(result)
```

### Contoh Request dengan Arduino/ESP32:

```cpp
#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

const char* WIFI_SSID = "Your_WiFi_SSID";
const char* WIFI_PASSWORD = "Your_WiFi_Password";
const char* API_URL = "http://192.168.1.100:8000/api/v1/devices/data";
const char* API_KEY = "your_api_key_here";

void sendSensorData(float intensity, float magnitude) {
  if(WiFi.status() == WL_CONNECTED) {
    HTTPClient http;
    
    // Buat JSON payload
    StaticJsonDocument<256> doc;
    JsonArray dataArray = doc.createNestedArray("data");
    JsonObject dataObj = dataArray.createNestedObject();
    
    dataObj["type"] = "gempa";
    dataObj["value"] = intensity;
    dataObj["timestamp"] = getTimeString(); // ISO8601 format
    
    String jsonString;
    serializeJson(doc, jsonString);
    
    // Kirim request
    http.begin(API_URL);
    http.addHeader("X-API-Key", API_KEY);
    http.addHeader("Content-Type", "application/json");
    
    int httpCode = http.POST(jsonString);
    
    if(httpCode == 200) {
      Serial.println("✅ Data sent successfully");
    } else {
      Serial.printf("❌ Error: %d\n", httpCode);
    }
    
    http.end();
  }
}

void setup() {
  Serial.begin(115200);
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("\n✅ WiFi Connected");
}

void loop() {
  // Baca sensor
  float intensity = readIntensitySensor();
  float magnitude = calculateMagnitude(intensity);
  
  sendSensorData(intensity, magnitude);
  
  delay(5000); // Kirim setiap 5 detik
}
```

---

## 💓 Heartbeat (Keep-Alive)

Untuk memastikan device dianggap "online", kirim heartbeat secara berkala:

### Endpoint: `POST /api/v1/devices/heartbeat`

```bash
curl -X POST http://localhost:8000/api/v1/devices/heartbeat \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "uptime": 12345,
      "cpu_temp": 45.2
    }
  }'
```

**Rekomendasi:** Kirim heartbeat setiap 5 menit agar device tetap "online".

---

## 📊 Monitoring Real-Time di Dashboard

### Data akan ditampilkan di:

1. **Admin Dashboard**
   - Device Details Page: `/admin/devices/{device_id}`
   - Menampilkan:
     - Real-time statistics (total readings, last 24h, avg value)
     - Recent data history (Last 50 readings)

2. **User Dashboard**
   - Device Details: `/devices/{device_id}`
   - API Key display dengan real-time update

3. **Public API**
   - Active Stations: `/api/v1/public/stations`
   - Station Details: `/api/v1/public/stations/{station_id}`

---

## 🔍 Testing API Endpoints

### 1. Test with cURL

```bash
# Get device statistics
curl http://localhost:8000/api/v1/devices/4444/statistics \
  -H "Authorization: Bearer your_token"

# Get device data history
curl http://localhost:8000/api/v1/devices/4444/data \
  -H "Authorization: Bearer your_token"

# Send test data
curl -X POST http://localhost:8000/api/v1/devices/data \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{
      "type": "gempa",
      "value": 300,
      "timestamp": "2026-05-19T10:30:45Z"
    }]
  }'
```

### 2. Test dengan Postman

1. Import endpoints ke Postman
2. Set environment variables:
   - `api_key`: Device API key
   - `device_id`: Device ID
   - `base_url`: http://localhost:8000
3. Jalankan requests

---

## 🔄 Data Flow Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                    HARDWARE SENSOR                           │
│              (Deteksi getaran gempa)                         │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       │ POST /api/v1/devices/data
                       │ Header: X-API-Key
                       │ JSON: {"data": [...]}
                       ↓
┌─────────────────────────────────────────────────────────────┐
│              API SERVER (Laravel)                            │
│  - Validasi API Key                                          │
│  - Simpan ke device_data table                               │
│  - Process earthquake data                                   │
│  - Update last_heartbeat & status                            │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       │ Save to DB
                       ↓
┌─────────────────────────────────────────────────────────────┐
│              DATABASE                                        │
│  - device_data (all sensor readings)                         │
│  - gempa (earthquake events)                                 │
│  - devices (hardware registration)                           │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       │ GET /api/v1/devices/{id}/statistics
                       │ GET /api/v1/devices/{id}/data
                       ↓
┌─────────────────────────────────────────────────────────────┐
│           WEB BROWSER (JavaScript)                           │
│  - public/js/realtime.js                                     │
│  - Poll API setiap interval (default: 5 detik)              │
│  - Update DOM elements dengan data terbaru                   │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ↓
┌─────────────────────────────────────────────────────────────┐
│       LIVE DASHBOARD (Real-Time Display)                     │
│  - Statistics update                                         │
│  - Data history table refresh                                │
│  - Device status indicator                                   │
└─────────────────────────────────────────────────────────────┘
```

---

## ⚙️ Konfigurasi Real-Time

### Mengubah Polling Interval

Edit `resources/views/admin/devices/show.blade.php`:

```html
<!-- Default: 5000ms (5 detik) -->
<span data-realtime-url="/api/v1/devices/..." 
      data-realtime-interval="5000">
  Loading...
</span>

<!-- Ubah ke 10 detik -->
<span data-realtime-url="/api/v1/devices/..." 
      data-realtime-interval="10000">
  Loading...
</span>
```

### Mengubah Format Tampilan

Edit `public/js/realtime.js` untuk custom rendering.

---

## 🐛 Troubleshooting

### Problem: Data tidak tampil di dashboard

**Solusi:**
1. Pastikan API key sudah benar
2. Check browser console untuk error (F12)
3. Pastikan endpoint mengembalikan status 200
4. Verify database memiliki data dengan `SELECT * FROM device_data;`

### Problem: Device offline

**Solusi:**
1. Pastikan hardware mengirim heartbeat minimal setiap 5 menit
2. Check logs di `storage/logs/laravel.log`
3. Verify API key masih valid

### Problem: CORS Error

**Solusi:**
Jika hardware di domain berbeda, pastikan CORS sudah dikonfigurasi di `config/cors.php`

---

## 📚 Referensi API Lengkap

### Device Endpoints

| Method | Endpoint | Auth | Deskripsi |
|--------|----------|------|-----------|
| POST | `/api/v1/devices/data` | API Key | Kirim sensor data |
| POST | `/api/v1/devices/heartbeat` | API Key | Keep-alive signal |
| GET | `/api/v1/devices/{id}` | Bearer | Detail device |
| GET | `/api/v1/devices/{id}/statistics` | Bearer | Statistics |
| GET | `/api/v1/devices/{id}/data` | Bearer | Data history |
| POST | `/api/v1/devices/{id}/command` | Bearer | Send command |

### Public Endpoints

| Method | Endpoint | Auth | Deskripsi |
|--------|----------|------|-----------|
| GET | `/api/v1/public/stations` | - | List active stations |
| GET | `/api/v1/public/stations/{id}` | - | Station details |
| GET | `/api/v1/public/earthquakes/latest` | - | Latest earthquake |
| GET | `/api/v1/public/earthquakes/statistics` | - | Earthquake stats |

---

## ✅ Checklist Implementasi

- [ ] Device sudah terdaftar di sistem
- [ ] API Key didapatkan dari registrasi
- [ ] Hardware dapat terhubung ke network
- [ ] Test API endpoint dengan cURL/Postman
- [ ] Kirim sample data untuk testing
- [ ] Verifikasi data muncul di database
- [ ] Check real-time update di dashboard
- [ ] Konfigurasi polling interval sesuai kebutuhan
- [ ] Setup heartbeat untuk keep-alive
- [ ] Monitor logs untuk troubleshooting

---

## 📞 Support

Jika ada pertanyaan atau masalah, silakan:
1. Check `/storage/logs/laravel.log` untuk error messages
2. Test API endpoint dengan Postman
3. Verifikasi database connectivity

**Last Updated:** 2026-05-19