192 lines
3.9 KiB
Markdown
192 lines
3.9 KiB
Markdown
# 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.
|
||
|
||
---
|
||
|
||
## Interfaces
|
||
|
||
PositioningData
|
||
|
||
```typescript
|
||
interface PositioningData {
|
||
source: 'GNSS' | 'WIFI' | 'FUSED' | 'MOCK' | 'PREDICTED';
|
||
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 🇮🇩 |