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

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

Jika terjadi konflik dependency:

npm install git+https://git.jayacita.com/wengki/dumon-geolocation.git --legacy-peer-deps

Kemudian:

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()

startPositioning(): Promise<void>

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

stopPositioning()

stopPositioning(): Promise<void>

Menghentikan semua sensor dan proses positioning.

getLatestPosition()

getLatestPosition(): Promise<PositioningData>

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

addListener(‘onPositionUpdate’, …)

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

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

checkAndRequestPermissions()

checkAndRequestPermissions(): Promise<PermissionStatus>

Memeriksa dan meminta semua permission yang dibutuhkan oleh plugin.

configureEdgeToEdge()

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()

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

Mengganti mode GPS:

• normal: polling adaptif (hemat baterai)
• driving: continuous updates + loop emisi periodik

setOptions()

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()

getGnssStatus(): Promise<SatelliteStatus | null>

Mengambil status GNSS terakhir untuk debugging.

getLocationServicesStatus()

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

Memeriksa apakah provider lokasi aktif.

addListener('onGnssStatus', …)

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

Menerima update status GNSS jika emitGnssStatus: true di setOptions.

---

Interfaces

PositioningData

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

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.

// 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 🇮🇩