@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:

Method	Return type	Description
insert(aois: Array<AreaOfInterest>)	Promise<void>	Inserts the given list of areas of interest into the local database. More details on the AreaOfInterest interface right after this table
getById(id: string)	Promise<AreaOfInterest>	Allows to retrieve a stored area of interest by its id
getAll()	Promise<Array<AreaOfInterest>>	Allows to retrieve all the stored areas of interest at once
list()	Observable<Array<AreaOfInterest>>	Allows to observe changes in all the stored areas of interest. It is recommended to install the RxJS package too, to operate with the output of this method
deleteAll()	Promise<void>	Allows to clear all the stored areas of interest at once

AreaOfInterest

Property	Type	Description
id	string	The unique identifier of the area
name	string	A display name for the area
longitude	number	The longitude of the center of the area
latitude	number	The latitude of the center of the area
radius	number	The radius of the area, from its center's longitude and latitude
category	string	(Optional) Free text field, can be used to classify the area in an arbitrary category
level	number	(Optional) Can be used to rank areas

Tasks

Task name	Description
checkAreaOfInterestProximity	Given one or more locations included in the payload of the event invoking the task, this task checks their proximity towards a set of registered areas of interest
filterGeolocationByAoIProximity	Given one or more locations included in the payload of the event invoking the task, this task checks their proximity towards a set of registered areas of interest and only outputs those that fall nearby or inside their radii

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

Name	Payload	Description
movedCloseToAreaOfInterest	Array<AoIProximityChange>	Detected that one or more of the given locations represent an approximation towards the surroundings of one or more registered areas of interest. The approximation radius can be configured in the application workflow. See an example below this table
movedInsideAreaOfInterest	Array<AoIProximityChange>	Detected that one or more of the given locations have just fallen between the center of one or more registered areas and their radii
movedOutsideAreaOfInterest	Array<AoIProximityChange>	Detected that one or more of the given locations have just fallen outside one or more area radii, but are still within their approximation radii. This event won't fire while there's still a location that falls inside an area
movedAwayFromAreaOfInterest	Array<AoIProximityChange>	Detected that one or more of the given locations have just fallen completely outside one or more area approximation radii. This event won't fire while there's still a location that falls inside the approximation radius of an area
geolocationCloseToAoIAcquired	'Geolocation' | 'Array'	A location or a list of locations which have passed the area of interest filter (fall nearby or inside the known areas)

Records

AoIProximityChange

Property	Type	Description
id	string	Record's unique id
type	string	Always aoi-proximity-change
change	Change	Can be either start or end. The former indicates a transition to the proximity indicated by the the record, whereas the later indicates no longer being in the reported level of proximity
timestamp	Date	The local time when the proximity change was detected
aoi	AreaOfInterest	The area of interest towards which the proximity change has been detected
proximity	GeofencingProximity	Indicates the relative proximity towards the area. Look at the change property to identify if the change is towards the proximity or contrary to it. See all the proximity options below

GeofencingProximity

Option	Description
INSIDE	One or more locations fall within the center and the radius of an area
NEARBY	One or more locations fall outside the center and the radius of an area, but they fall within its approximation radius
OUTSIDE	One or more locations fall completely outside an area and its approximation radius. This option will never be used in an AoIProximityChange record

License

Apache License Version 2.0