Using BeaconFence

Go Up to BeaconFence

• Platform Support
• BeaconFence Settings
• Map Settings
• Proximity Events
• Computing Position
• Calculating Routes

Platform Support

Platform	Supported?
Windows	10+
Mac OS X
iOS
iOS Simulator
Android

BeaconFence Settings

In order to start using BeaconFence you must have installed the BeaconFence package.

Then you can include:

• A TBeaconMapFencing component.
• A TBeaconZonesFencing component.
• A combination of both.

Note: The TBeaconZonesFencing component does not contain the visual BeaconFence Map Editor. This component is intended for managing proximity events.

Then you must enable the component so that the fencing process starts:

BeaconMapFencing.Enabled := True;

BeaconZonesFencing.Enabled := True;

Next, you can set specific values for the TBeaconManagerOptions properties associated with the beacons of your map project. We recommend that you use the Object Inspector. See TBeaconManager properties and Using Beacons for further info.

Adding Location Services

TBeaconMapFencing and TBeaconZonesFencing require that you enable location services in order to access location-based information from your device. To enable this service you must follow the same procedure explained for Beacons in Adding Location Services.

Note: Optionally, you may allow your iOS application to run in background so that the BLE device wakes up to handle bluetooth events associated with either Beacons in Standard Mode or Alternative Mode. To do that you have to add support for Core Bluetooth background execution modes by including the required value to the UIBackgroundModes key in the Info.plist file of your project:

1. In the IDE: File > Project > Options > Version Info.
2. Select the key UIBackgroundModes.
3. Introduce the value bluetooth-central.

Map Settings

In order to set a map project in your application you must:

• Set the PainControl property to the control that is going to display the map in your application.

Then you can choose between two alternatives:

1. Use the visual BeaconFence Map Editor.
2. Use data from a XMLMap in XML format to manually:

• Load a map project with LoadProjectFromXML.
• Save a map project with SaveProjectToXML.
• Set a map project with SetXmlData.

Once you have a map project, if you wish to monitor its information and manage possible changes, you can use:

• The OnBeforeMapChange event to manage custom actions before a map changes.
• The ProjectInformation property: Use it to access all the information available regarding with current elements in the XMLMap. This property contains information about:
  • The regions to monitorize (BeaconMapFencing1.ProjectInformation.RegionsToMonitorize).
  • The list of points of interest (BeaconMapFencing1.ProjectInformation.PoiList).
  • The maps (BeaconMapFencing1.ProjectInformation.Maps).
    • The zones in each map (BeaconMapFencing1.ProjectInformation.Maps[I].Zones[J]).
    • The position of each zone in a map:
      • BeaconMapFencing1.ProjectInformation.Maps[I].Zones[J].GetGlobalRect.Left.
      • BeaconMapFencing1.ProjectInformation.Maps[I].Zones[J].GetGlobalRect.Top.
      • BeaconMapFencing1.ProjectInformation.Maps[I].Zones[J].GetGlobalRect.Right.
      • BeaconMapFencing1.ProjectInformation.Maps[I].Zones[J].GetGlobalRect.Bottom.
    • The beacons list in each map (BeaconMapFencing1.ProjectInformation.Maps[I].BeaconList[J]).
  • The paths and its nodes (BeaconMapFencing1.ProjectInformation.GlobalPath[I].Node).

For example, to obtain a beacon list of each map and some information of each beacon use the following code snippet:

Delphi:

var
  LInformation: TFencingProject;
  I: Integer;
  J: Integer;
  LMapCount: Integer;
  LLine: string;
  MmMapsInformation: TMemo;
begin
  LInformation := BeaconMapFencing1.ProjectInformation;
  LMapCount := Length(LInformation.Maps);
  for I := 0 to LMapCount - 1 do
    begin
      LLine := 'Map: ' + LInformation.Maps[I].Map.Name + ' Size: ' + FormatFloat('0.00', LInformation.Maps[I].Map.GetGlobalRect.Width) + '-' +
        FormatFloat('0.00', LInformation.Maps[I].Map.GetGlobalRect.Height);
      MmMapsInformation.Lines.Add(LLine);
      MmMapsInformation.Lines.Add('  Beacon List: ');
      for J := 0 to Length(LInformation.Maps[I].BeaconList) - 1 do
      begin
        LLine := '     ' + LInformation.Maps[I].BeaconList[J].DesignBeacon.Name;
        LLine := LLine  + ' Position : (' + FormatFloat('0.00', LInformation.Maps[I].BeaconList[J].DesignBeacon.CenterInGlobalSpace.X) + '-' +
          FormatFloat('0.00', LInformation.Maps[I].BeaconList[J].DesignBeacon.CenterInGlobalSpace.Y) + ')';
        MmMapsInformation.Lines.Add(LLine);
        LLine := '      BeaconType' + Integer(LInformation.Maps[I].BeaconList[J].DesignBeacon.KindofBeacon).ToString
          + 'GUID' + LInformation.Maps[I].BeaconList[J].DesignBeacon.GUID.ToString
          + ' Major: ' + LInformation.Maps[I].BeaconList[J].DesignBeacon.Major.ToString
          + ' Minor: ' + LInformation.Maps[I].BeaconList[J].DesignBeacon.Minor.ToString
          + ' EddyNamespace: ' + LInformation.Maps[I].BeaconList[J].DesignBeacon.EddyNamespace
          + ' EddyInstance: ' + LInformation.Maps[I].BeaconList[J].DesignBeacon.EddyInstance;
        MmMapsInformation.Lines.Add(LLine);
      end;
    end;
end

C++:

TFencingProject LInformation;
Integer I;
Integer J;
Integer LMapCount;
String LLine;
TMemo *MmMapsInformation;

LInformation = BeaconMapFencing1->ProjectInformation;
LMapCount = LInformation.Maps.Length;
for (I = 0; I < LMapCount; I++) {
  LLine = "Map: " + LInformation.Maps[I].Map->Name + " Size: " + FormatFloat("0.00", LInformation.Maps[I].Map->GetGlobalRect().Width()) + "-" +
    FormatFloat("0.00", LInformation.Maps[I].Map->GetGlobalRect().Height());
  MmMapsInformation->Lines->Add(LLine);
  MmMapsInformation->Lines->Add("  Beacon List: ");
  for (J = 0; J < LInformation.Maps[I].BeaconList.Length; J++) {
    LLine = "     " + LInformation.Maps[I].BeaconList[J].DesignBeacon->Name;
    LLine = LLine  + " Position : (" + FormatFloat("0.00", LInformation.Maps[I].BeaconList[J].DesignBeacon->CenterInGlobalSpace.X) + "-" +
      FormatFloat("0.00", LInformation.Maps[I].BeaconList[J].DesignBeacon->CenterInGlobalSpace.Y) + ")";
    MmMapsInformation->Lines->Add(LLine);
    LLine = "      BeaconType" + IntToStr(Integer(LInformation.Maps[I].BeaconList[J].DesignBeacon->KindofBeacon))
      + "GUID" + GUIDToString(LInformation.Maps[I].BeaconList[J].DesignBeacon->GUID)
      + " Major: " + IntToStr(LInformation.Maps[I].BeaconList[J].DesignBeacon->Major)
      + " Minor: " + IntToStr(LInformation.Maps[I].BeaconList[J].DesignBeacon->Minor)
      + " EddyNamespace: " + LInformation.Maps[I].BeaconList[J].DesignBeacon->EddyNamespace
      + " EddyInstance: " + LInformation.Maps[I].BeaconList[J].DesignBeacon->EddyInstance;
    MmMapsInformation->Lines->Add(LLine);
  };
};

For more information about the ProjectInformation property, see the function called ShowProjectInformation in the FencingGeneric sample of the BeaconFence Demos.

Map Options

Now you can use BeaconManagerOptions to change the following TFencingMapOption visual options of the current map at run time:

• ColorBeacon: Displays beacons with different colors depending on the proximity value.

Level	Color
Intermediate	Green
Near	Yellow
Far	Orange
Away	Red

• HighlightZones: Changes the opacity value of the active zone.
• ShowPosition: Draws the estimated position of the BLE device in the map.
• ShowPositionInPath: Draws a refined estimated position that fits on the closest path.
• ShowBeacons: Displays the beacons you set in the map.
• ShowBeaconSignal: Draws circles centered on the beacons that indicate the current distance to the BLE device. The distance is computed from rssi values.
• ShowZones: Displays the zones you set in the map.
• ShowPaths: Displays the paths you set in the map.

Proximity Events

• OnBeaconEnter: Triggered when a new beacon is detected within a reachable distance.
• OnBeaconExit: Triggered when a beacon is no longer detected within a reachable distance.
• OnBeaconProximity: Triggered every time the proximity value changes.

Zone Events

• OnZoneEnter: Triggered when the calculated position is inside a defined zone.
• OnZoneExit: Triggered when the calculated position leaves a defined zone.
• OnZoneBeaconEnter: Triggered when a beacon that was previously defined in a zone, enters such zone.
• OnZoneBeaconExit: Triggered when a beacon that was previously defined in a zone, exits such zone.
• OnZoneOnBeaconProximity: Triggered every time the proximity value of a beacon defined in a zone changes.

Note: Besides these events based on position, you can still register regions to be monitored by UUID, Major and Minor. Use the BeaconFence Map Editor to add and configure beacons to be monitorized. See Using Beacons for more info.

Computing Position

The API for BeaconFence provides the System.Beacon.Fencing.PositionCalculator unit, where you can find the necessary classes used to estimate the current position of your BLE device in a specific map.

The default implementation of TPositionCalculator embeds the main functionalities of a particle filter algorithm optimized for localization tasks. In particular, this particle filter corresponds to a Monte Carlo Localization algorithm.

Monte Carlo Localization

The Monte Carlo Localization algorithm is implemented in TTrilateration and it extracts distance measures from your BLE device to several beacons in the map. Then it uses these distances to compute the estimated position of the BLE device by means of a Trilateration technique.

Use the following properties to tune the option parameters of the Particle Filter:

• ParticlesNumber: Number of particles that represent a gaussian distribution for statistical calculations. A large number of particles produces accurate estimates at a cost of computation. Find a tradeoff based on the resources of your device.
• UpdateInterval: Time interval in milliseconds used to estimate consecutive positions.
• MovementStDeviation: Standard deviation used to randomize the distribution of the particles.
• SignalRelativeStdDev: Standard deviation used to represent the signal to error ratio when dealing with distance calculations.
• BeaconsToUse: Number of beacons used to calculate distance measures. Then TTrilateration performs trilateration with these distances in order to provide the final estimated position.
• OwnsCalcDistance: Set to true to enable the default implementation of TPositionCalculator to calculate the distance to the beacons.
• AutomaticCalibration: Set to true to enable the default implementation of TPositionCalculator to perform automatic calibration for the beacons.
• MotionThreshold: Threshold value that determines when the BLE device is moving.

Getting Position Estimate

You can use the following events in order to retreive the estimated position of your BLE device:

• OnEstimatingPosition: Triggered when the position is estimated.
• OnCalcPosition: Triggered before the position is calculated.
• OnPositionEstimated: Triggered when the calculated position changes.

Custome Implementation

System.Beacon.Fencing.PositionCalculator includes abstract classes that you can override in order to implement your custom design for the position calculator. To that end, you have to override the methods in an object of type TPositionCalculatorClass.

Note: Use the OnEstimatingPosition property to retreive the estimate of the current position at run time.

Calculating Routes

The API for BeaconFence provides the System.Beacon.Fencing.PathFinder unit, where you can find an implementation of the Dijkstra's algorithm for calculating the shortest route from the current estimated position of your BLE device (initial point) to a desired point of interest (destination point) in your map.

In order to exploit this feature for navigating purposes you must:

1. Add and configure paths and nodes so that your map contains predefined paths that connect all the available points of interest.
2. Call TCustomBeaconMapFencing.ShowPathToNodeIndex to get the shortest route to the destination point. It selects and shows the shortest path available in your map.

See Also

• IoT
• BeaconFence Map Editor
• Installing BeaconFence
• Using Beacons