@awarns/phone-sensors

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:

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

NTP synced collection service tasks

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:

• PhoneSensor

• ProviderConfiguration

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.

• accelerometerSamplesAcquired
• gyroscopeSamplesAcquired
• magnetometerSamplesAcquired

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:

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

Records

TriAxial

TriAxialSample

License

Apache License Version 2.0