@awarns/wifi v1.0.0
@awarns/wifi
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:
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:
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\ | 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
2 years ago
2 years ago