BeaconManager (Estimote SDK for Android)

java.lang.Object
- com.estimote.coresdk.service.BeaconManager

```
public class BeaconManager
extends java.lang.Object
```
This is a class that clients should use to scan for Estimote devices. It allows for:
- Ranging regions (FOREGROUND scan for beacons in given region. It might be an BeaconRegion (or SecureBeaconRegion) or any other abstract region, like MirrorRegion)
- Monitoring regions (low-power BACKGROUND mode for tracking enter/exit events in given Region)
- Discovery (Constant, FOREGROUND scan for many packets - like ConfigurableDevice, Eddystone, Nearable, EstimoteLocation etc.
You can configure scanning periods using Some explanation of basic definitions used here:
- Foreground - Scan is being scheduled with use of internal Estimote scheduling mechanism. Results are delivered precisely at given periods and readings are much more responsive than in background. This does not allow for scanning when app is killed or in background - there is no possibility to invoke periodical scans outside of an app. Use monitoring instead if you need this kind of behaviour.
- Background - Scan is being scheduled with Android alarm mechanism which allows to scan when app is in background/killed. Potential drawback of this mechanism is that results may be delivered with delay - system alarms are inexact. Although this allows to reduce battery drain and notify your app when it is in background.
- Single packet - Received packet from scanned device. It is the most basic data that can be acquired via discovery. Each time the device advertises new packet (depends on device’s advertising interval and TX power) the listener should be notified about this fact. There are some cases, when data is too large to fit into one BLE packet, so it is splitted into two or more frames and advertised separately. The discovery time is longer, because we need to wait for two (or more) packets in order to merge them. Telemetry readings are a good example for this case.
- Region - Defines zone for “geo-fencing” like behaviour. This is an abstraction level a top of single packets. You can define region using iBeacons, or any other set of rules and predicates - like a set of Configurable devices, or bunch of Mirror devices. The region is used mostly to catch enter/exit events without focusing on constantly updating distance - except Ranging.
- Discovery - constant scan in foreground for packets of given type.
- Ranging - constant scan in foreground for devices in given Region.
- Monitoring - background scanning for enter/exit events in given Region.
Example use for beacon ranging & Nearables discovery:
```
   
   private static final UUID ESTIMOTE_PROXIMITY_UUID = UUID.fromString("B9407F30-F5F8-466E-AFF9-25556B57FE6D");
   private static final BeaconRegion ALL_ESTIMOTE_BEACONS_REGION = new BeaconRegion("rid", ESTIMOTE_PROXIMITY_UUID, null, null);

   BeaconManager beaconManager = new BeaconManager(context);

   beaconManager.setRangingListener(new BeaconManager.BeaconRangingListener() {
     {@literal @Override} public void onBeaconsDiscovered(BeaconRegion region, final List<Beacon> beacons) {
       Log.d(TAG, "Ranged beacons: " + beacons);
     }
   });

   beaconManager.setNearableListener(new BeaconManager.NearableListener() {
     {@literal @Override} public void onNearablesDiscovered(List<Nearable> nearables) {
       Log.d(TAG, "Discovered nearables: " + nearables);
     }
   });

   beaconManager.setEddystoneListener(new BeaconManager.EddystoneListener() {
     {@literal @Override} public void onEddystonesFound(List<Eddystone> eddystones) {
       Log.d(TAG, "Nearby eddystones: " + eddystones);
     }
   });
   // Before starting scan, manager needs to establish connection to the background service, which handles scanning.
   // This may take some time and is asynchronous, so we need to wait for callback.
   // After connecting, manager is ready to start doing its job.
   beaconManager.connect(new BeaconManager.ServiceReadyCallback() {
     {@literal @Override} public void onServiceReady() {

       // Beacons ranging.
       beaconManager.startRanging(ALL_ESTIMOTE_BEACONS_REGION);

       // Nearable discovery.
       beaconManager.startNearableDiscovery();

       // Eddystone scanning.
       beaconManager.startEddystoneScanning();
     }
   });

   // When no longer needed. Note that beacon ranging, nearables discovery, Eddystone scanning will stop.
   beaconManager.disconnect();
   
 
```
It is a good practice to have only one instance of BeaconManager per application stored in your Application subclass.
If you want to use beacons with enabled Secure UUID. Use SecureBeaconRegion instead of BeaconRegion class when starting ranging or monitoring.
Some methods throw RemoteException. This can happen if service call happened and hosting process no longer exists (only if service is remote process).
Author:

wiktor@estimote.com (Wiktor Gworek)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`BeaconManager.BeaconMonitoringListener` Callback to be invoked when beacons are discovered in a region.
`static interface`	`BeaconManager.BeaconRangingListener` Callback to be invoked when beacons are ranged.
`static interface`	`BeaconManager.ConfigurableDevicesListener` Callback to be invoked when Estimote Configurable packets are discovered nearby.
`static interface`	`BeaconManager.EddystoneListener` Callback to be invoked when Eddystone beacons are in range.
`static interface`	`BeaconManager.ErrorListener` Callback to be invoked when any error happened while performing low energy scanning.
`static interface`	`BeaconManager.LocationListener` Callback to be invoked when Estmimote Location packets are discovered nearby.
`static interface`	`BeaconManager.MirrorListener` Callback to be invoked when Estmimote Location packets are discovered nearby.
`static interface`	`BeaconManager.MirrorMonitoringListener` Callback to be invoked when mirrors are discovered .
`static interface`	`BeaconManager.MirrorRangingListener` Callback to be invoked when mirrors are ranged.
`static interface`	`BeaconManager.NearableListener` Callback to be invoked when nearables are discovered nearby.
`static interface`	`BeaconManager.ScanStatusListener` Callback to inform client when scanning is started and stopped.
`static interface`	`BeaconManager.ServiceReadyCallback` Callback to inform client when service is ready to use.
`static interface`	`BeaconManager.TelemetryListener` Callback to be invoked when Estmimote telemetry packets are discovered nearby.

Constructor Summary

Constructors
Constructor and Description

BeaconManager(android.content.Context context)
Constructs BeaconManager instance.

Constructors
Constructor and Description
`BeaconManager(android.content.Context context)` Constructs `BeaconManager` instance.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`connect(BeaconManager.ServiceReadyCallback callback)` Connects to `BeaconService`.
`void`	`disconnect()` Disconnects from `BeaconService`.
`void`	`setBackgroundScanPeriod(long scanPeriodMillis, long waitTimeMillis)` Changes defaults scanning periods when only monitoring is performed.
`void`	`setConfigurableDevicesListener(BeaconManager.ConfigurableDevicesListener listener)` Sets new Estimote Configurable packet listener.
`void`	`setEddystoneListener(BeaconManager.EddystoneListener listener)` Sets new Eddystone listener.
`void`	`setErrorListener(BeaconManager.ErrorListener listener)` Sets new error listener.
`void`	`setForegroundScanPeriod(long scanPeriodMillis, long waitTimeMillis)` Changes defaults scanning periods when ranging is performed.
`void`	`setLocationListener(BeaconManager.LocationListener listener)` Sets new Estimote Location packet listener.
`void`	`setMirrorListener(BeaconManager.MirrorListener listener)` Sets new Estimote Mirror listener.
`void`	`setMonitoringListener(BeaconManager.BeaconMonitoringListener listener)` Sets new beacon monitoring listener.
`void`	`setMonitoringListener(BeaconManager.MirrorMonitoringListener listener)` Sets new Estimote Mirror listener.
`void`	`setNearableListener(BeaconManager.NearableListener listener)` Sets new Nearable listener.
`void`	`setRangingListener(BeaconManager.BeaconRangingListener listener)` Sets new ranging listener.
`void`	`setRangingListener(BeaconManager.MirrorRangingListener listener)` Sets new ranging listener.
`void`	`setRegionExitExpiration(long period)` Changes expiration time for beacons.
`void`	`setScanRequestDelay(long delayMillis)` Since Nougat, every application is allowed to start/stop BLE scan a maximum of 5 times per 30s.
`void`	`setScanStatusListener(BeaconManager.ScanStatusListener listener)` Sets new scan status listener.
`void`	`setTelemetryListener(BeaconManager.TelemetryListener listener)` Sets new Estimote telemetry listener.
`void`	`startConfigurableDevicesDiscovery()` Starts scanning for Estimote Mirrors in your vicinity.
`void`	`startEddystoneDiscovery()` Starts scanning for all Eddystone beacons in your vicinity.
`void`	`startEddystoneScanning()` Deprecated. Please use `startEddystoneDiscovery()` instead.
`void`	`startLocationDiscovery()` Starts scanning for Estimote Location packets in your vicinity.
`void`	`startMirrorDiscovery()` Starts scanning for Estimote Mirrors in your vicinity.
`void`	`startMonitoring(BeaconRegion beaconRegion)` Starts beacon monitoring.
`void`	`startMonitoring(MirrorRegion mirrorRegion)` Starts Mirror monitoring.
`void`	`startNearableDiscovery()` Starts scanning for all Nearables in your vicinity.
`void`	`startRanging(BeaconRegion beaconRegion)` Starts ranging given range.
`void`	`startRanging(MirrorRegion mirrorRegion)` Starts ranging given range.
`void`	`startTelemetryDiscovery()` Starts scanning for Estimote telemetry packets in your vicinity.
`void`	`stopConfigurableDevicesDiscovery()` Stops discovery of Estimote Mirrors.
`void`	`stopEddystoneDiscovery()` Stops scanning of Eddystone beacons.
`void`	`stopEddystoneScanning()` Deprecated. Please use `stopEddystoneDiscovery()` instead.
`void`	`stopLocationDiscovery()` Stops discovery of Estimote Location packets.
`void`	`stopMirrorDiscovery()` Stops discovery of Estimote Mirrors.
`void`	`stopMonitoring(java.lang.String regionId)` Stops monitoring for given region.
`void`	`stopNearableDiscovery()` Stops discovery of nearables.
`void`	`stopRanging(BeaconRegion beaconRegion)` Stops ranging for beacons that was starting with `startRanging(BeaconRegion)` method.
`void`	`stopRanging(MirrorRegion mirrorRegion)` Stops ranging for mirrors that was starting with `startRanging(MirrorRegion)` method.
`void`	`stopTelemetryDiscovery()` Stops discovery of Estimote telemetry.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - BeaconManager
```
public BeaconManager(android.content.Context context)
```
    Constructs BeaconManager instance. It's good practice to have only one per application stored in your Application subclass.
    
    Parameters:
    
    context - Context to wire up BeaconManager.
- Method Detail
  - connect
```
public void connect(BeaconManager.ServiceReadyCallback callback)
```
    Connects to BeaconService.
    
    Parameters:
    
    callback - Callback to be invoked when connection is made to service.
  - disconnect
```
public void disconnect()
```
    Disconnects from BeaconService. If there were any ranging or monitoring in progress, they will be stopped. All listeners will be set to null. This should be typically called in onDestroy method.
  - setScanStatusListener
```
public void setScanStatusListener(BeaconManager.ScanStatusListener listener)
```
    Sets new scan status listener. Old one will be discarded.
    Scan status listener can be used to detect that scanning was started/stopped due to external circumstances like user enabling/disabling Bluetooth adapter.
    
    Note: This listener is not invoked during scan cycles. It only is called when user starts scanning, stops it or disables Bluetooth effectively stopping scanning.
    
    Note: You will receive notification if BeaconManager is still connected to BeaconService. If you call disconnect() you will no longer receive this notification.
    
    Parameters:
    
    listener - New listener.
  - setRangingListener
```
public void setRangingListener(BeaconManager.BeaconRangingListener listener)
```
    Sets new ranging listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setRangingListener
```
public void setRangingListener(BeaconManager.MirrorRangingListener listener)
```
    Sets new ranging listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setMonitoringListener
```
public void setMonitoringListener(BeaconManager.BeaconMonitoringListener listener)
```
    Sets new beacon monitoring listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setMonitoringListener
```
public void setMonitoringListener(BeaconManager.MirrorMonitoringListener listener)
```
    Sets new Estimote Mirror listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setEddystoneListener
```
public void setEddystoneListener(BeaconManager.EddystoneListener listener)
```
    Sets new Eddystone listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setNearableListener
```
public void setNearableListener(BeaconManager.NearableListener listener)
```
    Sets new Nearable listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setTelemetryListener
```
public void setTelemetryListener(BeaconManager.TelemetryListener listener)
```
    Sets new Estimote telemetry listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setLocationListener
```
public void setLocationListener(BeaconManager.LocationListener listener)
```
    Sets new Estimote Location packet listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setConfigurableDevicesListener
```
public void setConfigurableDevicesListener(BeaconManager.ConfigurableDevicesListener listener)
```
    Sets new Estimote Configurable packet listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setMirrorListener
```
public void setMirrorListener(BeaconManager.MirrorListener listener)
```
    Sets new Estimote Mirror listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setErrorListener
```
public void setErrorListener(BeaconManager.ErrorListener listener)
```
    Sets new error listener. Old one will be discarded.
    
    Parameters:
    
    listener - New error listener.
  - setForegroundScanPeriod
```
public void setForegroundScanPeriod(long scanPeriodMillis,
                                    long waitTimeMillis)
```
    Changes defaults scanning periods when ranging is performed. Default values: scanPeriod=1s, waitTime=0s Minimum values: scanPeriod=0.2s waitTime=0s
    Note: These are only suggested values. Scan period times may be adjusted by internal algorithms or operating system.
    
    Parameters:
    
    scanPeriodMillis - How long to perform Bluetooth Low Energy scanning?
    
    waitTimeMillis - How long to wait until performing next scanning?
  - setBackgroundScanPeriod
```
public void setBackgroundScanPeriod(long scanPeriodMillis,
                                    long waitTimeMillis)
```
    Changes defaults scanning periods when only monitoring is performed. Default values: scanPeriod=5s, waitTime=25s Minimum values: scanPeriod=0.2s waitTime=0s
    Note: These are only suggested values. Scan period times may be adjusted by internal algorithms or operating system.
    
    Note: Setting scan time to less than second is not recommended, because by default beacons' broadcast interval is 950ms.
    
    Parameters:
    
    scanPeriodMillis - How long to perform Bluetooth Low Energy scanning?
    
    waitTimeMillis - How long to wait until performing next scanning?
  - setRegionExitExpiration
```
public void setRegionExitExpiration(long period)
```
    Changes expiration time for beacons. The longer this period is, the less responsive onExit events are. On the other hand, there is less possible to throw short onExit/onEnter events during monitoring. Please bear in mind, that this is strictly connected to beacon advertising interval - the lower the value is, the more possible for device is to find an advertised packet. The clue is to find a sweet spot between advertising interval and expiration time. The default value is set to 20s (2000ms).
    
    Parameters:
    
    period - - expiration period from 1000-60000ms range.
  - setScanRequestDelay
```
public void setScanRequestDelay(long delayMillis)
```
    Since Nougat, every application is allowed to start/stop BLE scan a maximum of 5 times per 30s. Tweaking this delay prevents many scan start/stop events, which resulted in "App XXX is scanning too frequently" logs. All start/stop requests are buffered and the most recent is executed after the delay time. Here is a little example to visualise you the problem: ----- 12:10:10 - User navigates to list of nearby devices -> Start monitoring 12:10:11 - User clicks on selected beacon from the list -> Stop monitoring, start ranging 12:10:12 - "Oops! Wrong beacon, I need to choose another one!" and he clicks 'back' button -> Stop ranging, start monitoring 12:10:13 - Correct beacon is selected -> Stop monitoring, start ranging. ----- Result: 4 scan starts in about 3 seconds. The next scan cycle will be blocked for 30s due to Android 7.0 restrictions. You can tweak this delay to avoid such situations. Pros: SDK will be more resilient to user interactions resulting in many start/stop requests. Cons: The scan results will be delivered with a slight delay shortly after start.
    
    Parameters:
    
    delayMillis - delay in milliseconds. Must be greater or equal to zero. The default delay value is set to 1.5s (1500millis).
  - startRanging
```
public void startRanging(BeaconRegion beaconRegion)
```
    Starts ranging given range. Ranging results will be delivered to listener registered via setRangingListener(BeaconRangingListener). If given region is already ranged, this is no-op. You can range multiple beaconRegions at the same time. Listener will be called for each region separately.
    You can use SecureBeaconRegion to get beacons that are using Secure UUID with real location UUID, major and minor numbers (only if you own those beacons).
    
    Parameters:
    
    beaconRegion - BeaconRegion to range.
  - startRanging
```
public void startRanging(MirrorRegion mirrorRegion)
```
    Starts ranging given range. Ranging results will be delivered to listener registered via setRangingListener(BeaconRangingListener). If given region is already ranged, this is no-op. You can range multiple beaconRegions at the same time. Listener will be called for each region separately.
    You can use SecureBeaconRegion to get beacons that are using Secure UUID with real location UUID, major and minor numbers (only if you own those beacons).
    
    Parameters:
    
    mirrorRegion - BeaconRegion to range.
  - stopRanging
```
public void stopRanging(BeaconRegion beaconRegion)
```
    Stops ranging for beacons that was starting with startRanging(BeaconRegion) method.
    
    Parameters:
    
    beaconRegion - BeaconRegion that was previously ranged.
  - stopRanging
```
public void stopRanging(MirrorRegion mirrorRegion)
```
    Stops ranging for mirrors that was starting with startRanging(MirrorRegion) method.
    
    Parameters:
    
    mirrorRegion - mirror region that was previously ranged.
  - startEddystoneDiscovery
```
public void startEddystoneDiscovery()
```
    Starts scanning for all Eddystone beacons in your vicinity. Results are delivered asynchronously to listener set in setEddystoneListener(EddystoneListener).
  - stopEddystoneDiscovery
```
public void stopEddystoneDiscovery()
```
    Stops scanning of Eddystone beacons.
  - startEddystoneScanning
```
@Deprecated
public void startEddystoneScanning()
```
    Deprecated. Please use startEddystoneDiscovery() instead.
    
    Starts scanning for all Eddystone beacons in your vicinity. Results are delivered asynchronously to listener set in setEddystoneListener(EddystoneListener).
  - stopEddystoneScanning
```
@Deprecated
public void stopEddystoneScanning()
```
    Deprecated. Please use stopEddystoneDiscovery() instead.
    
    Stops scanning of Eddystone beacons.
  - startNearableDiscovery
```
public void startNearableDiscovery()
```
    Starts scanning for all Nearables in your vicinity. Results are delivered asynchronously to listener set in setNearableListener(NearableListener).
  - stopNearableDiscovery
```
public void stopNearableDiscovery()
```
    Stops discovery of nearables.
  - startTelemetryDiscovery
```
public void startTelemetryDiscovery()
```
    Starts scanning for Estimote telemetry packets in your vicinity. Results are delivered asynchronously to listener set in setNearableListener(NearableListener).
  - stopTelemetryDiscovery
```
public void stopTelemetryDiscovery()
```
    Stops discovery of Estimote telemetry.
  - startLocationDiscovery
```
public void startLocationDiscovery()
```
    Starts scanning for Estimote Location packets in your vicinity. Results are delivered asynchronously to listener set in setNearableListener(NearableListener).
  - stopLocationDiscovery
```
public void stopLocationDiscovery()
```
    Stops discovery of Estimote Location packets.
  - startMirrorDiscovery
```
public void startMirrorDiscovery()
```
    Starts scanning for Estimote Mirrors in your vicinity. Results are delivered asynchronously to listener set in setNearableListener(NearableListener).
  - stopMirrorDiscovery
```
public void stopMirrorDiscovery()
```
    Stops discovery of Estimote Mirrors.
  - startConfigurableDevicesDiscovery
```
public void startConfigurableDevicesDiscovery()
```
    Starts scanning for Estimote Mirrors in your vicinity. Results are delivered asynchronously to listener set in setNearableListener(NearableListener).
  - stopConfigurableDevicesDiscovery
```
public void stopConfigurableDevicesDiscovery()
```
    Stops discovery of Estimote Mirrors.
  - startMonitoring
```
public void startMonitoring(BeaconRegion beaconRegion)
```
    Starts beacon monitoring. You can monitor multiple beaconRegions at the same time. Listener will be called for each region separately.
    You can use SecureBeaconRegion to get beacons that are using Secure UUID with real location UUID, major and minor numbers (only if you own those beacons).
    
    Parameters:
    
    beaconRegion - BeaconRegion to monitor.
  - startMonitoring
```
public void startMonitoring(MirrorRegion mirrorRegion)
```
    Starts Mirror monitoring. You can monitor multiple MirrorRegions at the same time. Listener will be called for each region separately.
    
    Parameters:
    
    mirrorRegion - MirrorRegion to monitor.
  - stopMonitoring
```
public void stopMonitoring(java.lang.String regionId)
```
    Stops monitoring for given region.
    
    Parameters:
    
    regionId - string with unique region id. Can be obtained from for example startMonitoring(BeaconRegion)

Class BeaconManager

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BeaconManager

Method Detail

connect

disconnect

setScanStatusListener

setRangingListener

setRangingListener

setMonitoringListener

setMonitoringListener

setEddystoneListener

setNearableListener

setTelemetryListener

setLocationListener

setConfigurableDevicesListener

setMirrorListener

setErrorListener

setForegroundScanPeriod

setBackgroundScanPeriod

setRegionExitExpiration

setScanRequestDelay

startRanging

startRanging

stopRanging

stopRanging

startEddystoneDiscovery

stopEddystoneDiscovery

startEddystoneScanning

stopEddystoneScanning

startNearableDiscovery

stopNearableDiscovery

startTelemetryDiscovery

stopTelemetryDiscovery

startLocationDiscovery

stopLocationDiscovery

startMirrorDiscovery

stopMirrorDiscovery

startConfigurableDevicesDiscovery

stopConfigurableDevicesDiscovery

startMonitoring

startMonitoring

stopMonitoring