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)
- ⚙️ **Kalman Filter Fusion** dan **Forward Prediction**
- 🛡️ **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 yang telah melalui proses fusion/prediksi.

### 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.

### 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;
  predicted?: boolean;
}
```

PermissionStatus

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

---

## Fusion dan Prediksi

- Fusion posisi dilakukan menggunakan Kalman Filter sederhana untuk latitude & longitude.
- Saat GNSS tidak tersedia (signal hilang), plugin akan melakukan forward prediction berbasis speed + heading dari IMU selama 1 detik ke depan.

---

## 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 tombol:

- Start Positioning
- Stop Positioning
- Get Latest Position
- Realtime log via onPositionUpdate

---

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