@awarns/geofencing

This module allows to perform basic geofencing analysis based on the locations obtained by the tasks declared in the @awarns/geolocation package. It is also compatible with any other custom entity matching the GeolocationLike interface (for example, an entity produced by a custom indoor positioning system).

The geofencing mechanism inside this package allows to detect multiple degrees of nearness towards the registered areas of interest.

Install the plugin using the following command line instruction:

ns plugin add @awarns/geofencing

Usage

After installing and configuring this plugin, you'll be granted with two interaction mechanisms to work with it:

1. The plugin API. Through it, you'll be able to configure and update the areas of interest which are relevant to your application.
2. The geofencing task, which allows to detect if one or more locations which have just been acquired are close to one or more registered areas of interest. When a change in the proximity is detected, this task emits an AoIProximityChange record, described below.

API

areasOfInterest

The areasOfInterest singleton object is the main plugin entrypoint. Through it, you can set up and manage areas of interest. This is the complete API:

AreaOfInterest

Tasks

Check area of interest proximity

To register this task for its use, you just need to import it and call its generator function inside your application's task list:

import { Task } from '@awarns/core/tasks';
import { checkAreaOfInterestProximityTask } from '@awarns/geofencing';

export const demoTasks: Array<Task> = [
    checkAreaOfInterestProximityTask(),
];

Task generator parameters:

The task generator takes no parameters.

Task output events:

• checkAreaOfInterestProximityFinished (default, no content)
• movedCloseToAreaOfInterest
• movedInsideAreaOfInterest
• movedOutsideAreaOfInterest
• movedAwayFromAreaOfInterest

Example usage in the application task graph:

on(
  'startEvent',
  run('acquirePhoneGeolocation')
    .every(1, 'minutes')
    .cancelOn('stopEvent')
);

on(
  'geolocationAcquired',
  run('checkAreaOfInterestProximity', {
    nearbyRange: 100, // Area approximation radius, in meters (defaults to 100)
    offset: 15, // Optional distance calculation offset, in meters. Can help mitigating location error (defaults to 0)
  })
);

on('movedCloseToAreaOfInterest', run('writeRecords'));
on('movedInsideAreaOfInterest', run('writeRecords'));
on('movedOutsideAreaOfInterest', run('writeRecords'));
on('movedAwayFromAreaOfInterest', run('writeRecords'));

Note: To use the acquirePhoneGeolocation and writeRecords tasks, the geolocation and persistence packages must be installed and configured. See geolocation package and persistence package docs.

Filter geolocations based on area of interest proximity

To register this task for its use, you just need to import it and call its generator function inside your application's task list:

import { Task } from '@awarns/core/tasks';
import { filterGeolocationByAoIProximityTask } from '@awarns/geofencing';

export const demoTasks: Array<Task> = [
  filterGeolocationByAoIProximityTask(),
];

Task generator parameters:

The task generator takes no parameters.

Task output events:

• filterGeolocationByAoIProximityFinished (default, no content)
• geolocationCloseToAoIAcquired

Example usage in the application task graph:

on(
  'startEvent',
  run('acquirePhoneGeolocation')
    .every(1, 'minutes')
    .cancelOn('stopEvent')
);

on(
  'geolocationAcquired',
  run('filterGeolocationByAoIProximity', {
    nearbyRange: 100, // Area approximation radius, in meters (defaults to 100)
    offset: 15, // Optional distance calculation offset, in meters. Can help mitigating location error (defaults to 0)
    includeNearby: true // Optional indicate if points nearby an area should be taken into consideration (defaults to false)
  })
);

on('geolocationCloseToAoIAcquired', run('writeRecords')); // Just write the locations captured nearby an area of interest

Note: To use the acquirePhoneGeolocation and writeRecords tasks, the geolocation and persistence packages must be installed and configured. See geolocation package and persistence package docs.

Events

Records

AoIProximityChange

GeofencingProximity

License

Apache License Version 2.0