GeofencingSDK-Android

The AirMap Geofencing SDK enables your application to receive real-time alerts as your aircraft approaches, enters or intersects any airspace during its flight. You simply provide the service an airspace source (the AirMap map tile service, the AirMap Airspace Api, or your own custom GeoJSON formatted geometries), the aircraft position and velocity, and we will provide you with real-time geofence notification updates.

Integration

Add the library to your module-level build.gradle file:

implementation 'com.airmap.geofencingsdk:geofencingsdk:0.9.0-beta.1'

Add jitpack to your application-level build.gradle file in the allprojects.repositories block

maven { url "https://dl.bintray.com/airmapio/maven" }

Running the Geofencing Service

Create an Airspace Source to provide geometries to geofence your flight to. Or use one of the sources from the example app. We recommend the AirspaceMapSource. If you're not familiar with ReactiveX, use the examples for a template or extend the SimpleAirspaceSource.

AirspaceSource airspaceSource = new AirspaceMapSource(mapView, map);

Construct the GeofencingService with the airspace source and add a listener to receive status updates.

GeofencingService geofencingService = new GeofencingService(airspaceSource, bounds);
geofencingService.addListener(new GeofencingService.Listener() {
    @Override
    public void onStatusChanged(List<GeofencingStatus> statuses) {
        /*
         *  Each airspace will have a respective status returned by the Geofencing Service
         *
         *  The status will include the level such as SAFE, APPROACHING, ENTERING, INTERSECTING, etc
         *  If the aircraft is entering or approaching airspace, the status will include the proximity
         *  The distanceTo and timeTo are calculated based on the aircraft's telemetry and the airspace's geometry
         */
    }
});

Provide telemetry updates of the aircraft to the Geofencing Service by calling onPositionChanged & onSpeedChanged, which can be made independent of each other. The more frequent these methods are called, the more accurate the geofencing alerts will be. We suggest calling them 5-10 times a second if possible.

The GeofencingSDK uses the N-E-D (North-East-Down) coordinate system, i.e. a positive velocityX means movement towards the north, negative velocityX meaning movement towards the south. Make sure you telemetry updates adhere to this.

Position aircraftPosition = Position.fromCoordinates(latLng.getLongitude(), latLng.getLatitude());
geofencingService.onPositionChanged(aircraftPosition, altitudeMSL, altitudeAGL);

geofencingService.onSpeedChanged(velocityX, velocityY, velocityZ);

When your app/activity closes, shutdown the Geofencing Service so it doesn't continue to run.

@Override
protected void onDestroy() {
    super.onDestroy();
    mapView.onDestroy();

    // shutdown service
    if (geofencingService != null) {
        geofencingService.destroy();
    }
}

GeofencingStatus

Each time the Geofencing Service runs, it will return a list of statuses. One for each respective airspace returned by the AirspaceSource. The GeofencingStatus levels are as follows:

    SAFE,           // The aircraft is not approaching, entering or intersecting the airspace 
    APPROACHING,    // The aircraft is approaching (within 30 seconds of intersecting) the airspace 
    ENTERING,       // The aircraft is entering (within 10 seconds of intersecting) the airspace
    INTERSECTING,   // The aircraft is intersecting the airspace
    LEAVING,        // The aircraft is leaving (within 10 seconds) the airspace (Geocage)
    DEVIATED,       // The aircraft has left the airspace (Geocage)
    UNAVAILABLE     // The Geofencing service was unable to calculate a status due to lack of information (missing aircraft's telemetry or airspace info)

If the status level is approaching or entering, the status will include proximity data. The proximity data includes a timeTo (seconds) & distanceTo (meters), which indicates when the aircraft will intersect the airspace given its current course and speed.

Running the SDK Sample App

Clone this repo
Add your AirMap API Key to the airmap.config.json file located in the assets folder
Add your Mapbox access token to the airmap.config.json file located in the assets folder
Run sample app

API Keys

An API Key can be obtained from our Developer Portal.

Terms of Service

By using this SDK, you are agreeing to the AirMap Developer Terms & Conditions

License

The Geofencing SDK is linked with unmodified libraries of Mapbox Java SDK licensed under the MIT License. As well as Reactive X licensed under the Apache License

Support

You can get support from AirMap with the following methods:

Join our developer workspace on Slack
https://developers.airmap.com/

isabella232 / geofencingsdk-android-example Goto Github PK