Skip to content

Latest commit

 

History

History
236 lines (178 loc) · 15.4 KB

README.md

File metadata and controls

236 lines (178 loc) · 15.4 KB
Raw

@awarns/phone-sensors

npm (scoped) npm

This module allows to collect data from the IMU sensors (i.e., accelerometer and gyroscope) and the magnetometer embedded in the mobile device.

This plugin acts as a wrapper on top of the BackgroundSensors Android library, which enables the data collection even when the application is in the background or the device is idle. This module offers tasks for starting and stopping the data collection process.

Install the plugin using the following command line instruction:

ns plugin add @awarns/phone-sensors

Usage

After installing this plugin, you'll have access to two task groups with two tasks each to start and stop the data collection process. The main difference between both tasks groups is the implementation of the underlying service that is being used for the data collection. One group uses a standard data collection service, but the other one uses a special service that syncs the system clock with an NTP server to label the collected data with the most accurate timestamp. The collected data from the sensors, will be a TriAxial record, described below.

Setup (Optional)

This plugin can be optionally registered using its loader during the framework initialization:

// ... platform imports
import { awarns } from '@awarns/core';
import { demoTasks } from '../tasks';
import { demoTaskGraph } from '../graph';
import { registerPhoneSensorsPlugin } from '@awarns/phone-sensors';

awarns
  .init(
    demoTasks,
    demoTaskGraph,
    [
      registerPhoneSensorsPlugin({ 
        enableVibrationOnStart: false
      })
    ]
  )
// ... handle initialization promise

Plugin loader parameter options:

Property Type Description
enableVibrationOnStart boolean (Optional) Enables or disables the generation of a vibration when the data collection service starts. Enabled by default.

If the plugin is not registered, the vibration will be enabled by default.

Warning: due to restrictions imposed by the OS, the plugin can only be registered once (i.e., the first time the plugin is initialized). In other words, if the plugin is first register with enableVibrationOnStart to true, and then the developer wants to disable the vibration, setting enableVibrationOnStart to false will take no effect. If you want to change the value of enableVibrationOnStart, you will have to uninstall the app.

Tasks

Standard collection service tasks

Task name Description
startDetecting{prefix}Phone{sensor}Changes Allows to start the data collection for a sensor with a specific configuration (see below). The prefix can be used to distinguish among different configurations.
stopDetectingPhone{sensor}Changes The complement to the previous task. Allows to stop collecting data from sensor.

NTP synced collection service tasks

Task name Description
startDetecting{prefix}PhoneNTPSynced{sensor}Changes Allows to start the data collection for a sensor with a specific configuration (see below). Before the collection starts, the system clock is synced with an NTP server to label the collected data with an accurate timestamp. The prefix can be used to distinguish among different configurations.
stopDetectingPhoneNTPSynced{sensor}Changes The complement to the previous task. Allows to stop collecting data from sensor.

Start data collection for a sensor with a specific configuration

To register these tasks for their use, you just need to import them and call their generator functions inside your application's task list:

import { Task } from '@awarns/core/tasks';
import {
  startDetectingPhoneSensorChangesTask,
  PhoneSensor,
  SensorDelay,
} from '@awarns/phone-sensors';

export const demoTasks: Array<Task> = [
  startDetectingPhoneSensorChangesTask(PhoneSensor.ACCELEROMETER, { sensorDelay: SensorDelay.NORMAL, batchSize: 50 }),
  // startDetectingPhoneAccelerometerChanges
  
  startDetectingPhoneSensorChangesTask(PhoneSensor.ACCELEROMETER, { sensorDelay: SensorDelay.FASTEST, batchSize: 50 }, 'Fast'),
  // startDetectingFastPhoneAccelerometerChanges

  startDetectingPhoneSensorChangesTask(PhoneSensor.GYROSCOPE, { sensorDelay: SensorDelay.NORMAL, batchSize: 50 }),
  // startDetectingPhoneGyroscopeChanges

  startDetectingPhoneNTPSyncedSensorChangesTask(PhoneSensor.GYROSCOPE, { sensorDelay: SensorDelay.NORMAL, batchSize: 50 }),
  // startDetectingPhoneNTPSyncedGyroscopeChanges

  startDetectingPhoneSensorChangesTask(PhoneSensor.MAGNETOMETER, { sensorDelay: SensorDelay.NORMAL, batchSize: 50 }),
  // startDetectingPhoneMagnetometerChanges

];

Warning: the data collection for a PhoneSensor can only be started once, if startDetectingFastPhoneAccelerometerChanges is executed after startDetectingPhoneAccelerometerChanges and while the collection is in progress, startDetectingFastPhoneAccelerometerChanges will be ignored. Therefore, if you want to dynamically change the collection's configuration while the collection is in progress, you will have to stop the collection to start it again with the new desired configuration.

Task generator parameters:

Parameter name Type Description
sensor PhoneSensor Sensor to collect data from. See below.
providerConfiguration ProviderConfiguration Collection's configuration of the task. See below.
prefix (Optional) string Adds the prefix to the name of the task. Useful to create multiple tasks for the same sensor but with multiple configurations.
  • PhoneSensor
Value Description
ACCELEROMETER Represents the phone's accelerometer sensor.
GYROSCOPE Represents the phone's gyroscope sensor.
MAGNETOMETER Represents the phone's magnetometer sensor.
  • ProviderConfiguration
Property Type Description
sensorDelay SensorDelay | number Indicates the time between two consecutive samples. It can be a SensorDelay (i.e., UI, NORMAL, GAME or FASTEST) or a value in milliseconds.
batchSize number Indicates the amount of samples to be delivered in each record.

Note: the sensorDelay is taken as a suggestion by the Android OS. Samples could be delivered at a smaller or higher rate.

Task output events:

These tasks don't produce significant events after they complete their execution aside from the regular {task-name}Finished events.

However, once the start task has finished running, relevant events will be emitted by the internal listeners while the data collection is active. These are listed below.

Example usage in the application task graph:

on('startEvent', run('startDetectingPhoneAccelerometerChanges'));
on('startEvent', run('startDetectingPhoneGyroscopeChanges'));
on('startEvent', run('startDetectingPhoneMagnetometerChanges'));

on('accelerometerSamplesAcquired', run('writeRecords'));
on('gyroscopeSamplesAcquired', run('writeRecords'));
on('magnetometerSamplesAcquired', run('writeRecords'));

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

Stop data collection for a sensor

To register these tasks for their use, you just need to import them and call their generator functions inside your application's task list:

import { Task } from '@awarns/core/tasks';
import {
  stopDetectingPhoneSensorChangesTask,
  PhoneSensor,
} from '@awarns/phone-sensors';

export const demoTasks: Array<Task> = [
  stopDetectingPhoneSensorChangesTask(PhoneSensor.ACCELEROMETER),        // stopDetectingPhoneAccelerometerChanges
  stopDetectingPhoneNTPSyncedSensorChangesTask(PhoneSensor.GYROSCOPE),   // stopDetectingPhoneNTPSyncedGyroscopeChanges
  stopDetectingPhoneSensorChangesTask(PhoneSensor.MAGNETOMETER),         // stopDetectingPhoneMagnetometerChanges
];

Note: a stop task of a specific PhoneSensor can be used to stop the collection started by any start task for that PhoneSensor no matter the specific configuration.

Task generator parameters:

Parameter name Type Description
sensor WatchSensor Sensor to stop the data collection from.

Task output events:

These tasks don't produce significant events after they complete their execution aside from the regular {task-name}Finished events.

Example usage in the application task graph:

on('startEvent', run('startDetectingPhoneAccelerometerChanges').every(1, 'minute'));
on('startEvent', run('startDetectingPhoneNTPSyncedGyroscopeChanges').every(1, 'minute'));
on('startEvent', run('startDetectingPhoneMagnetometerChanges').every(1, 'minute'));

on('accelerometerSamplesAcquired', run('stopDetectingPhoneAccelerometerChanges'));
on('gyroscopeSamplesAcquired', run('stopDetectingPhoneNTPSyncedGyroscopeChanges'));
on('magnetometerSamplesAcquired', run('stopDetectingPhoneMagnetometerChanges'));

Note: it makes no sense to use these tasks without using before their complementary tasks to start the data collection.

Events

Name Payload Description
accelerometerSamplesAcquired TriAxial Contains a list of samples with the x, y, and z values of an accelerometer sensor.
gyroscopeSamplesAcquired TriAxial Contains a list of samples with the x, y, and z values of a gyroscope sensor.
magnetometerSamplesAcquired TriAxial Contains a list of samples with the x, y, and z values of a magnetometer sensor.

Records

TriAxial

Property Type Description
id string Record's unique id.
type string One of the following values: accelerometer, gyroscope, or magnetometer.
change Change Always NONE.
timestamp Date The local time when the data was collected. It is equal to the time of the first sample in the record.
samples TriAxialSample[] List with the collected samples.
TriAxialSample
Property Type Description
x number Value x of the sensor.
y number Value y of the sensor.
z number Value z of the sensor.
timestamp number The local time (UNIX timestamp) when the sample was collected.

License

Apache License Version 2.0