iBeacon scanning measure

carp_mobile_sensing/analysis_options.yaml

@@ -4,6 +4,8 @@
 include: package:flutter_lints/flutter.yaml
 
 analyzer:
+  errors:
+    deprecated_member_use_from_same_package: ignore
   exclude: [build/**]
   language:
     strict-casts: true
@@ -17,3 +19,5 @@ linter:
     depend_on_referenced_packages: true
     avoid_print: false
     use_string_in_part_of_directives: true
+    deprecated_member_use_from_same_package: false
+

carp_mobile_sensing/example/lib/example.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: unused_local_variable
+
 /*
  * Copyright 2018-2024 the Technical University of Denmark (DTU).
  * Use of this source code is governed by a MIT-style license that can be

packages/carp_connectivity_package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.9.0
+
+* added support for scanning iBeacons using the [dchs_flutter_beacon](https://pub.dev/packages/dchs_flutter_beacon) plugin
+* use the `BEACON` measure type for collecting `BeaconData` within a set of specific regions as specified in a `BeaconRangingPeriodicSamplingConfiguration`
+
 ## 1.8.1+1
 
 * added `BluetoothScanPeriodicSamplingConfiguration`

packages/carp_connectivity_package/README.md

@@ -12,6 +12,7 @@ This packages supports sampling of the following [`Measure`](https://github.com/
 * `dk.cachet.carp.wifi`
 * `dk.cachet.carp.connectivity`
 * `dk.cachet.carp.bluetooth`
+* `dk.cachet.carp.beacon`
 
 See the [wiki](https://github.com/cph-cachet/carp.sensing-flutter/wiki) for further documentation, particularly on available [measure types](https://github.com/cph-cachet/carp.sensing-flutter/wiki/A.-Measure-Types).
 See the [CARP Mobile Sensing App](https://github.com/cph-cachet/carp.sensing-flutter/tree/master/apps/carp_mobile_sensing_app) for an example of how to build a mobile sensing app in Flutter.
@@ -55,7 +56,7 @@ Add the following to your app's `AndroidManifest.xml` file located in `android/a
     <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
-
+    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
 </manifest>
 ````
 
@@ -70,8 +71,10 @@ and here for the [iOS](https://developer.apple.com/documentation/systemconfigura
 To enable bluetooth tracking, add these permissions in the `Info.plist` file located in `ios/Runner`:
 
 ````xml
+<!-- Bluetooth Privacy -->
+<!-- for iOS 13 + -->
 <key>NSBluetoothAlwaysUsageDescription</key>
-<string>Bluetooth needed</string>
+<string>Reason why app needs bluetooth</string>
 <key>UIBackgroundModes</key>
   <array>
   <string>bluetooth-central</string>
@@ -81,7 +84,23 @@ To enable bluetooth tracking, add these permissions in the `Info.plist` file loc
 </array>
 ````
 
-> Note that on iOS, it is [impossible to do a general Bluetooth scan when the screen is off or the app is in background](https://developer.apple.com/forums/thread/652592). This will simply result in an empty scan. Hence, bluetooth devices are only collected when the app is in the foreground.
+> [!NOTE]
+> On iOS, it is [impossible to do a general Bluetooth scan when the screen is off or the app is in background](https://developer.apple.com/forums/thread/652592). This will simply result in an empty scan. Hence, bluetooth devices are only collected when the app is in the foreground.
+
+To collect iBeacon measurements, please follow the setup described in the [dchs_flutter_beacon](https://pub.dev/packages/dchs_flutter_beacon) plugin. Especially, for iOS you need permissions to access location information in the `Info.plist` file:
+
+````xml
+<!-- When in use -->
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>Reason why app needs location</string>
+<!-- Always -->
+<!-- for iOS 11 + -->
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>Reason why app needs location</string>
+<!-- for iOS 9/10 -->
+<key>NSLocationAlwaysUsageDescription</key>
+<string>Reason why app needs location</string>
+````
 
 ## Using it
 
@@ -116,13 +135,13 @@ Smartphone phone = Smartphone();
 protocol.addPrimaryDevice(phone);
 
 // Add an automatic task that immediately starts collecting connectivity,
-// nearby bluetooth devices, and wifi information.
+// wifi information, and nearby bluetooth devices.
 protocol.addTaskControl(
     ImmediateTrigger(),
     BackgroundTask(measures: [
       Measure(type: ConnectivitySamplingPackage.CONNECTIVITY),
-      Measure(type: ConnectivitySamplingPackage.BLUETOOTH),
       Measure(type: ConnectivitySamplingPackage.WIFI),
+      Measure(type: ConnectivitySamplingPackage.BLUETOOTH),
     ]),
     phone);
 ```
@@ -136,11 +155,42 @@ protocol.addTaskControl(
       Measure(
           type: ConnectivitySamplingPackage.BLUETOOTH,
           samplingConfiguration: BluetoothScanPeriodicSamplingConfiguration(
-            interval: const Duration(minutes: 10),
-            duration: const Duration(seconds: 10),
+            interval: const Duration(minutes: 20),
+            duration: const Duration(seconds: 15),
             withRemoteIds: ['123', '456'],
             withServices: ['service1', 'service2'],
           ))
     ]),
     phone);
 ```
+
+The default configuration scans every 10 minutes for 10 seconds, and does not specify any remote IDs or services.
+
+If you want to collect iBeacon measurements, you need to configure the scanning by setting a [`BeaconRangingPeriodicSamplingConfiguration`](https://pub.dev/documentation/carp_connectivity_package/latest/connectivity/BeaconRangingPeriodicSamplingConfiguration-class.html).
+The following example will scan for iBeacons in the specified regions which are closer than 2 meters. The regions are specified by their identifier and UUID. See the [dchs_flutter_beacon](https://pub.dev/packages/dchs_flutter_beacon) plugin for more information on how to set up iBeacon regions.
+
+> [!NOTE]
+> There is no default sampling configuration for iBeacons. You need to specify at least one region to scan for.
+
+```dart
+  protocol.addTaskControl(
+      ImmediateTrigger(),
+      BackgroundTask(measures: [
+        Measure(
+            type: ConnectivitySamplingPackage.BEACON,
+            samplingConfiguration: BeaconRangingPeriodicSamplingConfiguration(
+              beaconDistance: 2, 
+              beaconRegions: [
+                BeaconRegion(
+                  identifier: 'region1',
+                  uuid: '12345678-1234-1234-1234-123456789012',
+                ),
+                BeaconRegion(
+                  identifier: 'region2',
+                  uuid: '12345678-1234-1234-1234-123456789012',
+                ),
+              ],
+            ))
+      ]),
+      phone);
+```

packages/carp_connectivity_package/example/lib/example.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: unused_local_variable
+
 import 'package:carp_core/carp_core.dart';
 import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
 import 'package:carp_connectivity_package/connectivity.dart';
@@ -22,13 +24,59 @@ void main() async {
   protocol.addPrimaryDevice(phone);
 
   // Add an automatic task that immediately starts collecting connectivity,
-  // nearby bluetooth devices, and wifi information.
+  // wifi information, and nearby bluetooth devices.
   protocol.addTaskControl(
       ImmediateTrigger(),
       BackgroundTask(measures: [
         Measure(type: ConnectivitySamplingPackage.CONNECTIVITY),
-        Measure(type: ConnectivitySamplingPackage.BLUETOOTH),
         Measure(type: ConnectivitySamplingPackage.WIFI),
+        Measure(type: ConnectivitySamplingPackage.BLUETOOTH),
+      ]),
+      phone);
+
+  // If you want to scan for nearby bluetooth devices, you can use a
+  // [BluetoothScanPeriodicSamplingConfiguration] to configure the scan.
+  // This will scan for bluetooth devices every 10 minutes for 10 seconds.
+  // You can also filter by remoteIds and services.
+  protocol.addTaskControl(
+      ImmediateTrigger(),
+      BackgroundTask(measures: [
+        Measure(
+            type: ConnectivitySamplingPackage.BLUETOOTH,
+            samplingConfiguration: BluetoothScanPeriodicSamplingConfiguration(
+              interval: const Duration(minutes: 20),
+              duration: const Duration(seconds: 15),
+              withRemoteIds: ['123', '456'],
+              withServices: ['service1', 'service2'],
+            ))
+      ]),
+      phone);
+
+  // If you want to collect iBeacon measurements, you can use a
+  // [BeaconRangingPeriodicSamplingConfiguration] to configure the scan.
+  // This will scan for iBeacons in the specified regions which are closer than
+  // 2 meters. The regions are specified by their identifier and UUID.
+  //
+  // See the dchs_flutter_beacon plugin for more information on how to set up
+  // iBeacon regions.
+  protocol.addTaskControl(
+      ImmediateTrigger(),
+      BackgroundTask(measures: [
+        Measure(
+            type: ConnectivitySamplingPackage.BEACON,
+            samplingConfiguration: BeaconRangingPeriodicSamplingConfiguration(
+              beaconDistance: 2,
+              beaconRegions: [
+                BeaconRegion(
+                  identifier: 'region1',
+                  uuid: '12345678-1234-1234-1234-123456789012',
+                ),
+                BeaconRegion(
+                  identifier: 'region2',
+                  uuid: '12345678-1234-1234-1234-123456789012',
+                ),
+              ],
+            ))
       ]),
       phone);
 }

packages/carp_connectivity_package/lib/connectivity.dart

@@ -7,6 +7,7 @@ library;
 import 'dart:async';
 import 'dart:convert';
 
+import 'package:dchs_flutter_beacon/dchs_flutter_beacon.dart';
 import 'package:flutter_blue_plus/flutter_blue_plus.dart';
 import 'package:json_annotation/json_annotation.dart';
 import 'package:connectivity_plus/connectivity_plus.dart' as connectivity;