dumon-geolocation/README.md

# dumon-geolocation

Capacitor Plugin untuk Android yang menyediakan **real-time high-accuracy positioning** menggunakan kombinasi:
- 📡 **GNSS multi-konstelasi** (GPS, GLONASS, BeiDou, Galileo)
- 📶 **Wi-Fi RTT / RSSI**
- 🎯 **IMU Sensor** (Accelerometer, Gyroscope, Rotation)
- ⏩ **Forward Prediction (opsional)**
- 🛡️ **Deteksi Lokasi Palsu (Mock Location Detection)**

---

## 📦 Instalasi

```bash
npm install git+https://git.jayacita.com/wengki/dumon-geolocation.git
```

Jika terjadi konflik dependency:
```bash
npm install git+https://git.jayacita.com/wengki/dumon-geolocation.git --legacy-peer-deps
```

Kemudian:
```bash
npx cap sync
```

---

## Permissions

Plugin ini memerlukan izin berikut:
- ACCESS_FINE_LOCATION
- ACCESS_COARSE_LOCATION
- ACCESS_WIFI_STATE
- CHANGE_WIFI_STATE
- NEARBY_WIFI_DEVICES (untuk Android 13+)

Gunakan API checkAndRequestPermissions() sebelum memulai positioning.

---

## API

### startPositioning()

```typescript
startPositioning(): Promise<void>
```

Memulai pengambilan data lokasi dari GNSS, Wi-Fi, dan IMU secara simultan.

### stopPositioning()

```typescript
stopPositioning(): Promise<void>
```

Menghentikan semua sensor dan proses positioning.

### getLatestPosition()

```typescript
getLatestPosition(): Promise<PositioningData>
```

 Mengembalikan posisi terkini. Jika opsi prediksi diaktifkan (lihat setOptions), nilai dapat diproyeksikan pendek dan ditandai `predicted: true`.

### addListener(‘onPositionUpdate’, …)

```typescript
addListener('onPositionUpdate', (data: PositioningData) => void): PluginListenerHandle
```

Menerima update posisi secara real-time (dengan debounce + threshold perubahan posisi/speed/direction).

### checkAndRequestPermissions()

```typescript
checkAndRequestPermissions(): Promise<PermissionStatus>
```

Memeriksa dan meminta semua permission yang dibutuhkan oleh plugin.

### configureEdgeToEdge()

```typescript
configureEdgeToEdge(options: {
  bgColor: string;
  style: 'DARK' | 'LIGHT';
  overlay?: boolean;
}): Promise<void>
```

Mengatur status bar dan navigasi bar agar transparan, dengan warna dan icon style sesuai UI.

### setGpsMode()

```typescript
setGpsMode(options: { mode: 'normal' | 'driving' }): Promise<void>
```

Mengganti mode GPS:
- `normal`: polling adaptif (hemat baterai)
- `driving`: continuous updates + loop emisi periodik

### setOptions()

```typescript
setOptions(options: {
  distanceThresholdMeters?: number;
  speedChangeThreshold?: number;
  directionChangeThreshold?: number;
  emitDebounceMs?: number;
  drivingEmitIntervalMs?: number;
  wifiScanIntervalMs?: number;
  enableWifiRtt?: boolean;
  enableLogging?: boolean;
  enableForwardPrediction?: boolean;
  maxPredictionSeconds?: number;
  emitGnssStatus?: boolean;
  suppressMockedUpdates?: boolean;
  keepScreenOn?: boolean;
}): Promise<void>
```

Mengubah parameter runtime tanpa rebuild. Semua default menjaga perilaku saat ini.

### getGnssStatus()

```typescript
getGnssStatus(): Promise<SatelliteStatus | null>
```

Mengambil status GNSS terakhir untuk debugging.

### getLocationServicesStatus()

```typescript
getLocationServicesStatus(): Promise<{ gpsEnabled: boolean; networkEnabled: boolean }>
```

Memeriksa apakah provider lokasi aktif.

### addListener('onGnssStatus', …)

```typescript
addListener('onGnssStatus', (data: SatelliteStatus) => void): PluginListenerHandle
```

Menerima update status GNSS jika `emitGnssStatus: true` di setOptions.

---

## Interfaces

PositioningData

```typescript
interface PositioningData {
  source: 'GNSS' | 'WIFI' | 'FUSED' | 'MOCK';
  timestamp: number;
  latitude: number;
  longitude: number;
  accuracy: number;
  speed: number;
  acceleration: number;
  directionRad: number;
  isMocked: boolean;
  mode: 'normal' | 'driving';
  predicted?: boolean;
  // opsional: detail asal speed
  speedSource?: 'GNSS' | 'IMU' | 'DELTA' | 'NONE';
  speedGnss?: number;     // m/s dari Location.getSpeed bila tersedia & segar
  speedImu?: number;      // m/s dari IMU (heuristik internal)
  speedDerived?: number;  // m/s hasil Δpos/Δt (kasar)
}
```

PermissionStatus

```typescript
interface PermissionStatus {
  location: 'granted' | 'denied';
  wifi: 'granted' | 'denied';
}
```

---

## Fusion dan Prediksi

- Tidak ada Kalman/Fusion saat ini. Data yang dipancarkan berasal dari GNSS, dilengkapi IMU untuk heuristik interval dan estimasi arah/kecepatan.
- Prediksi maju (dead‑reckoning) bersifat opsional dan nonaktif secara default. Aktifkan dengan `setOptions({ enableForwardPrediction: true, maxPredictionSeconds?: number })`.
- Saat prediksi aktif, posisi dapat diproyeksikan pendek (<= `maxPredictionSeconds`) berdasarkan `speed` dan `directionRad` dari IMU, serta ditandai `predicted: true`. Nilai `source` tidak berubah.

### Kebijakan `speed`

- Field `speed` kini dipilih dengan prioritas: GNSS > IMU > Δpos/Δt > 0.
  - GNSS: dipakai jika `Location.hasSpeed()` dan usia fix ≤ ~3000 ms.
  - IMU: fallback dari integrasi percepatan IMU (dibatasi ke 0..30 m/s, dengan smoothing & idle handling).
  - Δpos/Δt: fallback terakhir, hanya bila selang waktu antar fix ≥ 3 s.
- Field tambahan opsional: `speedSource`, `speedGnss`, `speedImu`, `speedDerived` untuk transparansi asal nilai.

---

## Detail Sensor (untuk pengembangan lanjutan)

> gnssData, imuData, dan wifiData tersedia dalam payload internal dan bisa diaktifkan untuk debug.

```typescript
// Dapat disertakan di masa depan:
interface SatelliteStatus {
  satellitesInView: number;
  usedInFix: number;
  constellationCounts: { [key: string]: number };
}

interface ImuData {
  accelX: number;
  accelY: number;
  accelZ: number;
  gyroX: number;
  gyroY: number;
  gyroZ: number;
  speed: number;
  acceleration: number;
  directionRad: number;
}

interface WifiAp {
  ssid: string;
  bssid: string;
  rssi: number;
  distance?: number;
}
```

---

## Catatan

- Hanya mendukung platform Android.
- Gunakan bersama @capacitor/geolocation jika ingin membandingkan hasil native vs Dumon.
- Posisi dipancarkan setiap 1000ms atau saat terjadi perubahan signifikan (jarak, kecepatan, arah).
- directionRad dalam radian relatif terhadap utara.
- Fitur Mock Location Detection aktif secara default.

---

## Testing (example-app)

Contoh implementasi tersedia di folder `/example-app` dengan kontrol:

- Start/Stop Positioning, Get Latest Position
- Request Permissions, Clear Log
- Mode: Driving / Normal
- Apply Options (semua opsi runtime, termasuk keepScreenOn, emitGnssStatus, enableForwardPrediction, interval)
- Diagnostics: Get GNSS Status, Get Location Services Status

---

- Lisensi: MIT
- Dibuat oleh: Tim Dumon 🇮🇩