-
Notifications
You must be signed in to change notification settings - Fork 0
/
02.1_collection-tools.qmd
262 lines (197 loc) · 13.9 KB
/
02.1_collection-tools.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
---
description: Describes the reliable data collection libraries for Android smartphones and Wear OS smartwatches.
highlight-style: github
code-annotations: select
format:
html:
code-links:
- text: Background Sensors
icon: github
href: https://github.com/GeoTecINIT/BackgroundSensors/tree/v1.3.0
target: blank
- text: WearOS Sensors
icon: github
href: https://github.com/GeoTecINIT/WearOSSensors/tree/v1.2.1
target: blank
- text: NativeScript WearOS Sensors
icon: github
href: https://github.com/GeoTecINIT/nativescript-wearos-sensors/tree/v1.3.0
target: blank
- text: AwarNS Phone Sensors
icon: github
href: https://github.com/GeoTecINIT/awarns-framework/blob/v1.0.0.210922/packages/phone-sensors
target: blank
- text: AwarNS Wear OS
icon: github
href: https://github.com/GeoTecINIT/awarns-framework/blob/v1.0.0.210922/packages/wear-os
target: blank
---
# Data collection libraries {#sec-collection_tools}
The data collection from IMU sensors built-in Android smartphones or Wear OS smartwatches for HAR (and other applications) should be reliable, i.e., reduce the presence of missing data.
However, as indicated previously, it has been documented that a broad amount of passive sensing applications used in published research suffer up to 50% of missing data [@boonstra2018]. As pointed out by @gonzalez2022using, the cause of this missingness comes from the energy consumption restrictions imposed by the OS, which tends to reduce resources and even kill long-running processes (e.g., data collection).
To mitigate these energy restrictions, @gonzalez2022using propose a set of development guidelines that must be applied to reduce the amount of missing data, showing only a 1% of data missingness in long-running executions.
This section describes the developed libraries implementing these guidelines for data collection in Android smartphones and WearOS smartwatches, addressing research objective **RO1**.
## Background Sensors
The _Background Sensors_ library is an Android library developed in Java that implements a reliable passive collection of IMU sensors (i.e., accelerometer, gyroscope and magnetometer), and, therefore, it can be used to develop native Android applications that require to collect samples from such sensors. The library has been developed to support devices running from Andriod 5.0 (API level 21) to Android 13 (API level 33).
::: {.callout-note}
## Availability
The version of the library at the moment of writing this thesis is **v1.3.0**. The library is available in:
- [Maven Central Repository](https://mvnrepository.com/artifact/io.github.geotecinit/background-sensors/1.3.0)
- [GitHub](https://github.com/GeoTecINIT/BackgroundSensors/tree/v1.3.0)
- Zenodo [@matey2024bs]
:::
@fig-bs_arch includes the simplified architecture of the _Background Sensors_ library.
{#fig-bs_arch .lightbox}
::: {.callout-tip}
## Library documentation
The full documentation of the library and its components can be found in [GitHub](https://github.com/GeoTecINIT/BackgroundSensors/tree/v1.3.0).
:::
### Sample usage
::: {.callout-tip}
Tap on the numbers at the end of the lines to obtain insights about the code.
:::
```{.java}
public class ExampleActivity extends Activity {
private SensorManager sensorManager;
private ServiceManager serviceManager;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
sensorManager = new SensorManager(this); // <1>
List<Sensor> sensors = sensorManager.availableSensors(BaseSensor.values()); // <1>
serviceManager = new ServiceManager(this, BaseSensorRecordingService.class); // <2>
}
public void start() {
Sensor sensor = BaseSensor.ACCELEROMETER;
CollectionConfiguration config = new CollectionConfiguration( // <3>
sensor, // <3>
10000, // sensorDelay (microseconds) // <3>
100 // batchSize // <3>
); // <3>
RecordCallback callback = new RecordCallback { // <4>
public void onRecordsCollected(List<Record> records) { // <4>
// Accelerometer samples received here // <4>
} // <4>
}; // <4>
serviceManager.startCollection(config, callback); // <5>
}
public void stop() {
serviceManager.stopCollection(BaseSensor.ACCELEROMETER); // <6>
}
}
```
1. Create an instance of `SensorManager` and call `availableSensors(...)` to determine which sensors are available in the device.
2. Create a `ServiceManager` instance with a `SensorRecordingService`.
3. Create a `CollectionConfiguration` indicating the `sensor`, the `sensorDelay`(microseconds) and the `batchSize`.
4. Implement the `RecordCallback`. The samples will be received here.
5. Start the data collection calling `ServiceManager#startCollection(...)`.
6. Stop the data collection calling `ServiceManager#stopCollection(...)`.
## WearOS Sensors & NativeScript WearOS Sensors
The _WearOS Sensors_ library is a Wear OS library written in Java that can be used to develop native Wear OS applications and, like _Background Sensors_, implements a reliable passive collection of IMU sensors (i.e., accelerometer, gyroscope and magnetometer). In addition, it supports collecting data from the heart rate sensor and the location services (i.e., GNSS).
On the other hand, _NativeScript WearOS Sensors_ is a library written in TypeScript that can be used to build smartphone applications complementary to _WearOS Sensors_ developed applications. Unlike the other libraries, this one cannot be used to develop native applications but applications built with the [NativeScript development framework](https://nativescript.org), which uses web technologies (e.g., JavaScript, TypeScript) to build Android and iOS applications.
The following features are available when using applications developed with these libraries:
- _WearOS Sensors_:
- Start and stop from the smartwatch the data collection of the available sensors in the device.
- Store collected data in the smartwatch.
- _WearOS Sensors_ + _Nativescript WearOS Sensors_:
- Start and stop from the smartwatch the data collection of the available sensors in the device.
- Start and stop from the paired smartphone the data collection of the available sensors in the smartwatch.
- Store the collected data in the smartwatch or in the smartphone.
The _WearOS Sensors_ and _NativeScript WearOS Senosrs_ libraries have been developed to support devices running from Wear OS 1.0 (\gls{api} level 23) to Wear OS 4 (\gls{api} level 33) and from Android 6 (\gls{api} level 23) to Android 13 (\gls{api} level 33), respectively.
::: {.callout-note}
## Availability
The version of _WearOS Sensors_ and _NativeScript WearOS Sensors_ at the moment of writing this thesis are **v1.2.1** and **v1.3.0**. The libraries are available in:
- WearOS Sensors:
- [Maven Central Repository](https://mvnrepository.com/artifact/io.github.geotecinit/wear-os-sensors/1.2.1)
- [GitHub](https://github.com/GeoTecINIT/WearOSSensors/tree/v1.2.1)
- Zenodo [@matey2024ws]
- NativeScript WearOS Sensors:
- [Node Package Manager](https://www.npmjs.com/package/nativescript-wearos-sensors/v/1.3.0)
- [GitHub](https://github.com/GeoTecINIT/nativescript-wearos-sensors/tree/v1.3.0)
- Zenodo [@matey2024nws]
:::
@fig-ws_arch includes the simplified architecture of the _WearOS Sensors_ and _NativeScript WearOS Sensors_ libraries.
{#fig-ws_arch .lightbox}
::: {.callout-tip}
## Library documentation
The full documentation of the libraries and their components can be found in their respective repositories: [WearOS Sensors](https://github.com/GeoTecINIT/WearOSSensors/tree/v1.2.1) and [NativeScript WearOS Sensors](https://github.com/GeoTecINIT/nativescript-wearos-sensors/tree/v1.3.0).
:::
### Sample usage
#### Managing collection process and storing data in smartwatch.
Since _WearOS Sensors_ is built on top of _Background Sensors_ the same code as the one presented previously can be employed for this purpose.
#### Managing collection process in smartwatch, storing data in smartphone.
```{.java}
public class ExampleActivity extends Activity {
private CommandClient commandClient;
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
commandClient = new CommandClient(this); // <1>
}
public void start() {
Sensor sensor = WearSensor.ACCELEROMETER;
CollectionConfiguration config = new CollectionConfiguration( // <2>
sensor, // <2>
10000, // sensorDelay (microseconds) // <2>
100 // batchSize // <2>
); // <2>
commandClient.sendStartCommand(config); // <3>
}
public void stop() {
commandClient.sendStopCommand(WearSensor.ACCELEROMETER); // <4>
}
}
```
1. Create a `CommandClient` instance.
2. Create a `CollectionConfiguration` including the `sensor`, `sensorDelay` (microseconds) and `batchSize`.
3. Start the data collection using the `CommandClient#sendStartCommand(...)`.
4. Stop the data collection using the `CommandClient#sendStopCommand(...)`.
```{.typescript}
function registerListener() {
const collectorManager = getCollectorManager(); // <5>
collectorManager.addSensorListener((sensorRecord: SensorRecord<any>) => { // <6>
// Accelerometer samples received here. // <6>
}); // <6>
}
```
5. Obtain a `CollectorManager` instance using the `getCollectorManager()` function.
6. Register a listener with the `CollectorManager#addSensorListener(...)`.
#### Managing collection process and storing data in smartphone.
```{.typescript}
let collectorManager;
function registerListener() {
const collectorManager = getCollectorManager(); // <1>
collectorManager.addSensorListener((sensorRecord: SensorRecord<any>) => { // <2>
// Accelerometer samples received here. // <2>
}); // <2>
}
let smartwatch;
async function getConnectedSmartwatch() {
const nodesDiscovered = await getNodeDiscoverer().getConnectedNodes(); // <3>
smartwatch = nodesDiscovered[0]; // <3>
}
function start() {
const config: CollectionConfiguration = {sensorInterval: 10000, batchSize: 100}; // <4>
collectorManager.startCollecting(smartwatch, SensorType.ACCELEROMETER, config); // <5>
}
function stop() {
collectorManager.stopCollecting(smartwatch, SensorType.ACCELEROMETER); // <6>
}
```
1. Obtain a `CollectorManager` instance using the `getCollectorManager()` function.
2. Register a listener with the `CollectorManager#addSensorListener(...)`.
3. Use `NodeDiscoverer#getConnectedNodes()` to get a reference to the connected smartwatches.
4. Create a `CollectionConfiguration` including the `sensorInterval` (microseconds) and `batchSize`.
5. Start the data collection on the selected smartwatch calling `CollectorManager#startCollecting(...)`.
6. Stop the data collection on the selected smartwatch calling `CollectorManager#stopCollecting(...)`.
## Integration in the AwarNS Framework
The AwarNS Framework, implemented by a colleague researcher, is an Android-based development framework aimed to facilitate the development of context-aware smartphone applications which require systematic data acquisition, on-device analyses and perform actions based on these analyses [@gonzalez2023awarns]. The framework is built on top of the NativeScript Task Dispatcher, which allows the definition and execution of reactive workflows using its building blocks: `Tasks` (code units), `Events` (execution drivers) and `TaskGraphs` (allow the definition of reactive workflows, i.e., `Tasks` triggered by `Events`) [@gonzalez2022using].
This dissertation contributes to the AwarNS Framework by wrapping the previously described data collection tools in it. This integration would allow the combination of already existing features in the framework (e.g., geolocation) with the features of the developed libraries (e.g., IMU data for HAR) to implement context-aware applications (e.g., recognition of activities in specific contexts).
In particular, two new packages are developed and added into the framework: the _Phone Sensors_ and the _Wear OS_ packages. These packages wrap up the _Background Sensors_ and _NativeScript WearOS Sensors_ libraries to integrate their functionality into the AwarNS Framework.
::: {.callout-note}
For a more detailed description of the AwarNS Framework, check its [GitHub repository](https://github.com/GeoTecINIT/awarns-framework/tree/v1.0.0.210922) and the research paper [@gonzalez2023awarns]
:::
{.lightbox}
::: {.callout-tip}
## Library documentation
The full documentation of the libraries and their components can be found in the AwarNS Framework repository: [Phone Sensors](https://github.com/GeoTecINIT/awarns-framework/tree/v1.0.0.210922/packages/phone-sensors) and [WearOS Sensors](https://github.com/GeoTecINIT/awarns-framework/blob/v1.0.0.210922/packages/wear-os).
:::