@awarns/wifi

npm (scoped) npm

This module includes tasks to obtain information regarding nearby Wi-Fi access points (APs). This is useful to assess the existence of concrete access points nearby. Also, to build custom indoor localization and positioning systems based on Wi-Fi.

This plugin acts as a wrapper on top of the nativescript-context-apis plugin (from the same authors), offering Wi-Fi scanning tasks. Scan for nearby Wi-Fi APs even in background.

Install the plugin using the following command line instruction:

ns plugin add @awarns/wifi

Usage

After installing and setting up this plugin, you'll have access to two different tasks to scan for Wi-Fi APs seen nearby. The result, will be a WifiScan record, described below.

Tasks

Task name	Description
`acquirePhoneWifiScan`	Allows to perform a single Wi-Fi scan for a given amount of time
`acquireMultiplePhoneWifiScan`	Allows to repeatedly perform Wi-Fi scans. Scans will happen for as long as there is execution time remaining (3 minutes max. or shortly before the next time-scheduled task execution, whatever occurs earlier)

Note: All the tasks require fine location permission and active Wi-Fi radio for their execution. Each task will automatically request what is missing during framework's initialization

Acquire a single Wi-Fi scan

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 { acquirePhoneWifiScanTask } from '@awarns/wifi';

export const demoTasks: Array<Task> = [
    acquirePhoneWifiScanTask(/* optional */ { ensureIsNew: true, timeout: 15000 }),
];

Task generator parameters:

Name	Type	Description
`ensureIsNew`	`boolean`	Make sure that the resulting Wi-Fi scan is up-to-date. A value of `true` ensures Android Wi-Fi scanning restrictions are met, thus the reported value is always new. The default value is `true`
`timeout`	`number`	The maximum time, in milliseconds, to be spent scanning for nearby Wi-Fi APs. The default value is `15000` (15s)

Task output events:

wifiScanAcquired

Example usage in the application task graph:
on(
  'startEvent',
  run('acquirePhoneWifiScan')
    .every(1, 'minutes')
    .cancelOn('stopEvent')
);

on('wifiScanAcquired', run('writeRecords'));
Note: To use the writeRecords task, the persistence package must be installed and configured. See persistence package docs.

Acquire Wi-Fi scans in batch

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 { acquireMultiplePhoneWifiScanTask } from '@awarns/wifi';

export const demoTasks: Array<Task> = [
  acquireMultiplePhoneWifiScanTask(/* optional */ { ensureIsNew: true, timeout: 15000 }),
];

Task generator parameters:

Name	Type	Description
`ensureIsNew`	`boolean`	Make sure that the resulting Wi-Fi scans are up-to-date. A value of `true` ensures Android Wi-Fi scanning restrictions are met, thus the reported values are always new. The default value is `true`
`timeout`	`number`	The maximum time to be spent performing each individual Wi-Fi scan. The default value is `15000` (15s)

Task output events:

wifiScanAcquired

Example usage in the application task graph:

on(
  'startEvent',
  run('acquireMultiplePhoneWifiScan', { 
     maxInterval: 25000 
     /* 
        (Optional, mandatory if ensureIsNew=true) Maximun interval between scans, unlimited by default. 
        
        If ensureIsNew=true, the value must ensure that a maximum of 2 scans are being collectd every minute. 
        
        For example, here the task will be executed every 1 minute, which means it will have ~55s to run. 
        With 25s between scans we meet the OS restrictions and have enought time to collect 2 Wi-Fi fingerprints. 
     */ 
  })
    .every(1, 'minutes')
    .cancelOn('stopEvent')
);

on('wifiScanAcquired', run('writeRecords'));

Note: To use the writeRecords task, the persistence package must be installed and configured. See persistence package docs.

Events

Name	Payload	Description
`wifiScanAcquired`	`WifiScan \| Array<WifiScan>`	Indicates that one or more new Wi-Fi scan results have been acquired

Records

WifiScan

Property	Type	Description
`id`	`string`	Record's unique id
`type`	`string`	Always `wifi-scan`
`change`	`Change`	Always `none`. Scan results are returned as a whole. Intermediate results are not reported
`timestamp`	`Date`	The local time when the scan was completed
`isNew`	`boolean`	Indicates if the results of the scan are cached. This can only be `false` when using `ensureIsNew=false` option during the scans
`seen`	`Array<WifiApInfo>`	The Wi-Fi APs seen during the scan. The list can be empty. For details on the properties of the WifiApInfo object, see context-apis API docs section on Wi-Fi

License

Apache License Version 2.0