BeaconManager (Estimote SDK for Android)

java.lang.Object
- com.estimote.sdk.BeaconManager

public class BeaconManager
extends java.lang.Object

This is a class that clients should use to interact with Estimote beacons & nearables. It allows to:

range beacons (scan beacons and optionally filter them by their values)
monitor beacons (track beacons in order to get events that device has entered or leaved regions of interest)
discover nearables
scan nearby Eddystone beacons
range and monitor for Secure UUID (see SecureRegion)

Typical use for beacon ranging & nearables discovery:

   private static final UUID ESTIMOTE_PROXIMITY_UUID = UUID.fromString("B9407F30-F5F8-466E-AFF9-25556B57FE6D");
   private static final Region ALL_ESTIMOTE_BEACONS = new Region("rid", ESTIMOTE_PROXIMITY_UUID, null, null);

   BeaconManager beaconManager = new BeaconManager(context);

   beaconManager.setRangingListener(new BeaconManager.RangingListener() {
      @Override public void onBeaconsDiscovered(Region region, final List beacons) {
       Log.d(TAG, "Ranged beacons: " + beacons);
     }
   });

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

   beaconManager.setEddystoneListener(new BeaconManager.EddystoneListener() {
      @Override public void onEddystonesFound(List eddystones) {
       Log.d(TAG, "Nearby eddystones: " + eddystones);
     }
   });

   beaconManager.connect(new BeaconManager.ServiceReadyCallback() {
      @Override public void onServiceReady() {

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

       // 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.

This is wrapper around BeaconService that clients should use as implementation details of service can be changed in time.

If you want to use beacons with enabled Secure UUID. Use SecureRegion instead of Region 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).

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`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.MonitoringListener` Callback to be invoked when beacons are discovered in a region.
`static interface`	`BeaconManager.NearableListener` Callback to be invoked when nearables are discovered nearby.
`static interface`	`BeaconManager.RangingListener` Callback to be invoked when beacons are ranged.
`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
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`	`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`	`setMonitoringListener(BeaconManager.MonitoringListener listener)` Sets new monitoring listener.
`void`	`setNearableListener(BeaconManager.NearableListener listener)` Sets new Nearable listener.
`void`	`setRangingListener(BeaconManager.RangingListener listener)` Sets new ranging listener.
`void`	`setRegionExitExpiration(long period)` Changes expiration time for beacons.
`void`	`setScanStatusListener(BeaconManager.ScanStatusListener listener)` Sets new scan status listener.
`void`	`setTelemetryListener(BeaconManager.TelemetryListener listener)` Sets new Estimote telemetry listener.
`java.lang.String`	`startEddystoneScanning()` Starts scanning for all Eddystone beacons in your vicinity.
`java.lang.String`	`startLocationDiscovery()` Starts scanning for Estimote Location packets in your vicinity.
`void`	`startMonitoring(Region region)` Starts beacon monitoring.
`java.lang.String`	`startNearableDiscovery()` Starts scanning for all Nearables in your vicinity.
`void`	`startRanging(Region region)` Starts ranging given range.
`java.lang.String`	`startTelemetryDiscovery()` Starts scanning for Estimote telemetry packets in your vicinity.
`void`	`stopEddystoneScanning(java.lang.String scanId)` Stops scanning of Eddystone beacons.
`void`	`stopLocationDiscovery(java.lang.String scanId)` Stops discovery of Estimote Location packets.
`void`	`stopMonitoring(Region region)` Stops region monitoring that was previously started with `startMonitoring(Region)`.
`void`	`stopNearableDiscovery(java.lang.String scanId)` Stops discovery of nearables.
`void`	`stopRanging(Region region)` Stops ranging for beacons that was starting with `startRanging(Region)` method.
`void`	`stopTelemetryDiscovery(java.lang.String scanId)` 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.RangingListener listener)
```
    Sets new ranging listener. Old one will be discarded.
    
    Parameters:
    
    listener - New listener.
  - setMonitoringListener
```
public void setMonitoringListener(BeaconManager.MonitoringListener listener)
```
    Sets new monitoring 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.
  - 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.
  - startRanging
```
public void startRanging(Region region)
```
    Starts ranging given range. Ranging results will be delivered to listener registered via setRangingListener(RangingListener). If given region is already ranged, this is no-op. You can range multiple regions at the same time. Listener will be called for each region separately.
    You can use SecureRegion to get beacons that are using Secure UUID with real location UUID, major and minor numbers (only if you own those beacons).
    
    Parameters:
    
    region - Region to range.
  - startEddystoneScanning
```
public java.lang.String startEddystoneScanning()
```
    Starts scanning for all Eddystone beacons in your vicinity. Results are delivered asynchronously to listener set in setEddystoneListener(EddystoneListener).
    
    Returns:
    
    Scan identifier which is required to stop scanning (stopEddystoneScanning(String)).
  - stopEddystoneScanning
```
public void stopEddystoneScanning(java.lang.String scanId)
```
    Stops scanning of Eddystone beacons.
    
    Parameters:
    
    scanId - Scan identifier obtained from startEddystoneScanning().
  - startNearableDiscovery
```
public java.lang.String startNearableDiscovery()
```
    Starts scanning for all Nearables in your vicinity. Results are delivered asynchronously to listener set in setNearableListener(NearableListener).
    
    Returns:
    
    Scan identifier which is required to stop scanning (stopNearableDiscovery(String)).
  - stopNearableDiscovery
```
public void stopNearableDiscovery(java.lang.String scanId)
```
    Stops discovery of nearables.
    
    Parameters:
    
    scanId - Scan identifier obtained from startNearableDiscovery().
  - startTelemetryDiscovery
```
public java.lang.String startTelemetryDiscovery()
```
    Starts scanning for Estimote telemetry packets in your vicinity. Results are delivered asynchronously to listener set in setNearableListener(NearableListener).
    
    Returns:
    
    Scan identifier which is required to stop scanning (stopNearableDiscovery(String)).
  - stopTelemetryDiscovery
```
public void stopTelemetryDiscovery(java.lang.String scanId)
```
    Stops discovery of Estimote telemetry.
    
    Parameters:
    
    scanId - Scan identifier obtained from startNearableDiscovery().
  - startLocationDiscovery
```
public java.lang.String startLocationDiscovery()
```
    Starts scanning for Estimote Location packets in your vicinity. Results are delivered asynchronously to listener set in setNearableListener(NearableListener).
    
    Returns:
    
    Scan identifier which is required to stop scanning (stopNearableDiscovery(String)).
  - stopLocationDiscovery
```
public void stopLocationDiscovery(java.lang.String scanId)
```
    Stops discovery of Estimote Location packets.
    
    Parameters:
    
    scanId - Scan identifier obtained from startNearableDiscovery().
  - stopRanging
```
public void stopRanging(Region region)
```
    Stops ranging for beacons that was starting with startRanging(Region) method.
    
    Parameters:
    
    region - Region that was previously ranged.
  - startMonitoring
```
public void startMonitoring(Region region)
```
    Starts beacon monitoring. You can monitor multiple regions at the same time. Listener will be called for each region separately.
    You can use SecureRegion to get beacons that are using Secure UUID with real location UUID, major and minor numbers (only if you own those beacons).
    
    Parameters:
    
    region - Region to monitor.
  - stopMonitoring
```
public void stopMonitoring(Region region)
```
    Stops region monitoring that was previously started with startMonitoring(Region).
    
    Parameters:
    
    region - Region that was monitored.

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

setMonitoringListener

setEddystoneListener

setNearableListener

setTelemetryListener

setLocationListener

setErrorListener

setForegroundScanPeriod

setBackgroundScanPeriod

setRegionExitExpiration

startRanging

startEddystoneScanning

stopEddystoneScanning

startNearableDiscovery

stopNearableDiscovery

startTelemetryDiscovery

stopTelemetryDiscovery

startLocationDiscovery

stopLocationDiscovery

stopRanging

startMonitoring

stopMonitoring