Beacons

dk.cachet.carp.beacon is an event-based measure that runs on the phone on Android and iOS, through the dchs_flutter_beacon plugin. Add it as Measure(type: ConnectivitySamplingPackage.BEACON). Each measurement covers one region and lists the beacons in it, with their signal strength and estimated distance.

The measure detects iBeacon frames and, on Android, also AltBeacon frames. It does not detect Eddystone frames.

Add the measure to a protocol

The measure needs at least one region; without regions, it does not start. Set the regions in a BeaconRangingPeriodicSamplingConfiguration on the measure, and start it with an ImmediateTrigger. This example gives each of two beacons its own region and records beacons up to 5 meters away:

protocol.addTaskControl(
  ImmediateTrigger(),
  BackgroundTask(
    measures: [
      Measure(
        type: ConnectivitySamplingPackage.BEACON,
        samplingConfiguration: BeaconRangingPeriodicSamplingConfiguration(
          beaconDistance: 5,
          beaconRegions: [
            BeaconRegion(
              identifier: 'lab-entrance',
              uuid: 'fda50693-a4e2-4fb1-afcf-c6eb07647825',
              major: 1,
              minor: 1,
            ),
            BeaconRegion(
              identifier: 'lab-desk',
              uuid: 'fda50693-a4e2-4fb1-afcf-c6eb07647825',
              major: 1,
              minor: 2,
            ),
          ],
        ),
      ),
    ],
  ),
  phone,
);

One region per beacon keeps beacons that share a UUID apart in the data. See Data.

Configuration

BeaconRangingPeriodicSamplingConfiguration has these properties:

Despite its name, the configuration has no interval or duration: ranging runs without pauses while the measure runs.

Each region is a BeaconRegion:

Set minor only together with major. iOS ignores a minor without a major, and Android then uses the minor value as the major value.

How beacon detection works

The measure combines region monitoring and ranging:

1. When the measure starts, it monitors all configured regions.
2. When the platform reports that the phone is inside a region, the measure starts ranging all configured regions.
3. Each ranging result for a region becomes one measurement, with the beacons of that region whose estimated distance is at most beaconDistance.
4. Ranging continues until the measure pauses, also after the phone leaves the region. Measurements then have an empty scanResult.

Ranging reports every configured region at each scan cycle of the platform. The measure therefore records a steady stream of measurements while it runs, many with an empty scanResult. Plan storage and upload for this volume, and drop empty measurements in the analysis when you do not need them.

Permissions

The measure needs Bluetooth access and location access all the time, which CARP Mobile Sensing (CAMS) asks for. Bluetooth and Location Services must also be turned on:

On Android 11 and later, the participant chooses Allow all the time on the app's location settings page, not in a dialog. See Android's Request background location guide.

On Android 11 and lower, the measure also needs the legacy BLUETOOTH permission, which the plugin's Android Beacon Library adds to the merged manifest. See Installation.

Platform differences

Data

Each measurement holds a BeaconData object with the __type dk.cachet.carp.beacon, for one region:

Each entry in scanResult is a BeaconDevice:

Proximity is a type of dchs_flutter_beacon, which carp_connectivity_package does not export. To name it in Dart, add the plugin with flutter pub add dchs_flutter_beacon and import package:dchs_flutter_beacon/dchs_flutter_beacon.dart.

The measurement's sensorStartTime is the time of the ranging result. The data looks like this:

{
  "__type": "dk.cachet.carp.beacon",
  "region": "lab-entrance",
  "scanResult": [
    {
      "uuid": "FDA50693-A4E2-4FB1-AFCF-C6EB07647825",
      "rssi": -61,
      "major": 1,
      "minor": 1,
      "accuracy": 1.35,
      "proximity": "near"
    }
  ]
}

For the measurement envelope around the data, see Measurements and data.