iBeacon Sample Project

In this post I want to show you how we can create the simplest iOS app that monitors and ranges devices that follow the iBeacon protocol. An iBeacon device is a BLE (Bluetooth Low Energy) device that transmits its identification information: UUID, major and minor.
You can learn more about iBeacon in this previous post here.

The complete xcode project that is explained in this post can be downloaded from my public github repository here.


Project setup

  1. Create a new empty project in XCode. You can select the Single View Application template.
  2. Enable the permissions needed to use the Core Location services. To do this, add the following two properties in the .plist file of your app:

    NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription.

    Here is an example of these two properties:

    <key>NSLocationWhenInUseUsageDescription</key>
    <string>Location is needed to monitor Beacons in range</string>
    <key>NSLocationAlwaysUsageDescription</key>
    <string>Location is needed to monitor Beacons in range</string>
    

My Location Manager

  1. Create the class that will manage all the beacon events: MyLocationManager.
  2. Import the CoreLocation library in the .h file of your new class:
    #import <CoreLocation/CoreLocation.h>
  3. The MyLocationManager class is going to implement the CLLocationManagerDelegate protocol to receive the beacon events:
    @interface MyLocationManager : NSObject <CLLocationManagerDelegate>
  4. The MyLocationManager class also needs two methods so the app can start/stop monitoring iBeacons. Add these methods to the interface:
    
    - (void)startMonitoringUUID:(NSString *)uuid;
    
    - (void)stop;
    
    

Monitoring iBeacons

  1. Open the implementation .m file of our MyLocationManager class and add a private property to keep an instance of the iOS system CLLocationManager class.
    @interface MyLocationManager ()
    @property (strong,nonatomic) CLLocationManager *locationManager;
    @end
    
  2. Implement the start method.
    - (void)startMonitoringUUID:(NSString *)uuid
    {
        self.locationManager = [[CLLocationManager alloc] init];
        self.locationManager.delegate = self;
    
        // Request permission (mandatory iOS8 + info.plist)
        if([self.locationManager respondsToSelector:@selector(requestAlwaysAuthorization)])
            [self.locationManager requestAlwaysAuthorization];
    
        CLBeaconRegion *region = [[CLBeaconRegion alloc]
           initWithProximityUUID:[[NSUUID alloc] initWithUUIDString:uuid]
           identifier: uuid];
    
        [self.locationManager startMonitoringForRegion:region];
    }
    

    Line 3. Create an object of the CLLocationManager class.
    Line 4. Set our MyLocationManager object as its delegate.
    Line 7-8. Request permission.
    Line 10-12. Create a region with the UUID received as parameter.
    Line 14. Start monitoring for the recently created region.

  3. Implement the delegate method to receive the iBeacon events. For this small sample app, iBeacon events are just printed to the app log:
    - (void)locationManager:(CLLocationManager *)manager didDetermineState:(CLRegionState)state forRegion:(CLRegion *)region
    {
        switch (state) {
            case CLRegionStateInside:
                NSLog(@"locationManager didDetermineState INSIDE for %@", region.identifier);
                break;
    
            case CLRegionStateOutside:
                NSLog(@"locationManager didDetermineState OUTSIDE for %@", region.identifier);
                break;
    
            default:
                NSLog(@"locationManager didDetermineState OTHER for %@", region.identifier);
        }
    }
    
  4. Finally implement the stop method:
    - (void)stop
    {
        for(id region in self.locationManager.monitoredRegions) {
            [self.locationManager stopMonitoringForRegion:region];
        }
    }
    

Ranging iBeacons

  1. Add the code to start ranging. A good approach is to start ranging once it has been detected that the user is inside a region. This code is added in the locationManager:didDetermineState:forRegion method:
    - (void)locationManager:(CLLocationManager *)manager didDetermineState:(CLRegionState)state forRegion:(CLRegion *)region
    {
        switch (state) {
            case CLRegionStateInside:
                NSLog(@"locationManager didDetermineState INSIDE for %@", region.identifier);
                [self.locationManager startRangingBeaconsInRegion:(CLBeaconRegion*)region];
                break;
    
            case CLRegionStateOutside:
                NSLog(@"locationManager didDetermineState OUTSIDE for %@", region.identifier);
                break;
    
            default:
                NSLog(@"locationManager didDetermineState OTHER for %@", region.identifier);
        }
    }
    
  2. Add the code to stop ranging. A good approach is to stop ranging when it is detected that the user is outside a region. This code is added in the locationManager:didDetermineState:forRegion method:
    - (void)locationManager:(CLLocationManager *)manager didDetermineState:(CLRegionState)state forRegion:(CLRegion *)region
    {
        switch (state) {
            case CLRegionStateInside:
                NSLog(@"locationManager didDetermineState INSIDE for %@", region.identifier);
                [self.locationManager startRangingBeaconsInRegion:(CLBeaconRegion*)region];
                break;
    
            case CLRegionStateOutside:
                NSLog(@"locationManager didDetermineState OUTSIDE for %@", region.identifier);
                [self.locationManager stopRangingBeaconsInRegion:(CLBeaconRegion*)region];
                break;
    
            default:
                NSLog(@"locationManager didDetermineState OTHER for %@", region.identifier);
        }
    }
    
  3. Finally implement the delegate method to receive the iBeacon ranging events. These ranging events are just printed to the app log:
    - (void)locationManager:(CLLocationManager *)manager didRangeBeacons:(NSArray *)beacons inRegion:(CLBeaconRegion *)region
    {
        if(beacons != nil && (0 < beacons.count)) {
            for(CLBeacon *b in beacons) {
                NSLog(@"%@/%@ %ld", b.major, b.minor, b.proximity);
            }
        }
    }
    

The complete xcode project that has been explained in this post can be downloaded from my public github repository here.

Read More

Introduction to iBeacon

The iBeacon standard is an extension of iOS Location Services. An iBeacon device is a BLE (Bluetooth Low Energy) device that transmits its identification information: UUID, major and minor. This information is hierarchical and the UUID is the beacon’s principal identifier.
The iBeacon functionality provided by iOS allows two types of actions:

  • Region Monitoring. Notifies when the user has entered the specified region.
  • Beacon Ranging. Determines the estimated proximity to the beacons in range: Immediate, Near, Far or Unknown.

A Region in iBeacon terms is a network of iBeacons defined by a shared identifier. A region can be specified by its UUID, major and minor. Major and minor identifiers are optional for a region, but the UUID is necessary.

iOS limits to 20 the number of regions that may be simultaneously monitored by a single app.

For example, if only the UUID is specified for a region, all the iBeacons with that UUID will be considered part of that region.

Beacons inside a UUID region

If we specify the UUID and also a major value for the region, then only the iBeacons with that UUID and major are considered as part of that region.

Beacons inside a UUID+major region

Once a region has been detected, the details of the iBeacons in range inside that region are obtained by ranging, not by monitoring.

Background detection

While the app is running in the foreground it can range to determine the signal strength between the iBeacons and the device. This ranging process is not allowed while the app is not running in the foreground. Only monitoring is allowed while the app is in the background/not running.
Region monitoring is capable of waking the app up from running in the background/not running when the app enters or exits the region. These are the only triggers that will wake the app from running the background/not running: entering or exiting a region. Once the app is awoken it can run for ~10 seconds if closed completely and ~2 minutes if it is running in the background.

Core Location Framework

iBeacon APIs are available in the Core Location Framework. The central point of this framework is the CLLocationManager class. An instance of this class is necessary to start/stop the location services, to configure them, and to receive the related events.
The CLLocationManager reference can be found here.

Read More