Page tree
Skip to end of metadata
Go to start of metadata

iBeacon is a new technology that extends Location Services in iOS. Your iOS device can alert apps when you approach or leave a location with an iBeacon. In addition to monitoring location, an app can estimate your proximity to an iBeacon (for example, a display or checkout counter in a retail store). Instead of using latitude and longitude to define the location, iBeacon uses a Bluetooth low energy signal, which iOS devices can detect.

To use iBeacon, you need iOS 7 or later, Bluetooth turned on and a compatible iOS device:

  • iPhone 4s or later
  • iPad (3rd generation) or later
  • iPad mini or later
  • iPod touch (5th generation) or later

With the iBeacon technology you can detect the beacon devices or make your iOS device act as a transmitting beacon.

It is recommended to read Apple’s Getting Started with iBeacon document first before getting further in this article.

There are some properties to set a transmitter identity:

proximityUUID: A property contains the identifier that you use to identify your company’s beacons. You typically generate only one UUID for your company’s beacons but you can generate more as you needed. You generate this value using the command-line tool (can be Powershell on Windows). It provides a UUID such as “0AA62D26-CC69-4AAC-8A5B-BFAB50DAC814″.

major: A property contains a value that can be used to group related sets of beacons. For example, a department store might assign the same major value for all of the beacons on the same region.

minor: A property specifies the individual beacon within a group. For example, for a group of beacons on the same floor of a department store, this value might be assigned to a beacon in a particular section.

identifer: A unique identifier to associate with the returned region object. You use this identifier to differentiate regions within your application.

We will make two examples in this article. First one is detecting a beacon other one is a broadcasting app :

Detecting a Beacon

The iBeacon framework can understand when you enter the region of a beacon. When you are in the region you can range it to find out information about it.

At first, we create a beacon region object with the transmitting properties of device so that the app can understand if it is in transmitting device’s region or not. We generate the proximityUUID with a UUID creation tool.

var beaconRegion = new SMF.Bluetooth.BLE.BeaconRegion({
		proximityUUID : "B9407F30-F5F8-466E-AFF9-25556B57FE6D",
		identifier : "io.smartface.beaconapp",
		major : 1,
		minor : 1
	});

Then, we start to monitor devices by using this beacon region :

var Label1 = new SMF.UI.Label({
		name : "lbl",
		text : "",
		left : "15%",
		top : "30%",
		width : "70%",
		height : "10%",
		text : lang.done
	});
page1.add(Label1);
 
SMF.Bluetooth.BLE.startMonitoringForRegion({
	region : beaconRegion,
	onEnterRegion : function (e) {
		alert("Enter region: " + JSON.stringify(e));
		SMF.Bluetooth.BLE.startRangingBeaconsInRegion(beaconRegion);
	},
	onExitRegion : function (e) {
		alert("Exit region: " + JSON.stringify(e));
		SMF.Bluetooth.BLE.stopRangingBeaconsInRegion(beaconRegion);
	},
	onStartMonitoringForRegion : function (e) {
		alert("Monitoring started. " + JSON.stringify(e));
	},
	onDetermineState : function (e) {
		var state = "";
		if (e.state == SMF.Bluetooth.BLE.RegionState.UNKNOWN) {
			state = "Unknown";
		} else if (e.state == SMF.Bluetooth.BLE.RegionState.INSIDE) {
			state = "Inside";
		} else if (e.state == SMF.Bluetooth.BLE.RegionState.OUTSIDE) {
			state = "Outside";
		}
		alert("State: " + state);
	},
	onRangeBeacons : function (e) {
		if (e.beacons.length > 0) {
			beacon = e.beacons[0];
			var proximity = "-";
			switch (beacon.proximity) {
			case SMF.Bluetooth.BLE.Proximity.UNKNOWN:
				proximity = "Unknown";
				break;
			case SMF.Bluetooth.BLE.Proximity.IMMEDIATE:
				proximity = "Immediate";
				break;
			case SMF.Bluetooth.BLE.Proximity.NEAR:
				proximity = "Near";
				break;
			case SMF.Bluetooth.BLE.Proximity.FAR:
				proximity = "Far";
				break;
			}
			Label1.text = JSON.stringify(beacon);
		}
	},
	onFailForRegion : function (e) {
		alert("Error: " + e.message);
	}
});

When you call startMonitoringForRegion method, you will define several callback methods in it. These callbacks are triggered due to your monitoring or ranging state.

When you enter the region you call startRangingBeaconsInRegion to range devices. As you exit the region you will call stopRangingBeaconsInRegion method.

When your app find the device, it will start ranging it to get information about it. You can find out the proximity (the relative distance to the beacon) and accuracy (the accuracy of the proximity value, measured in meters from the beacon).

After starting monitor devices, we will start ranging them as below:

SMF.Bluetooth.BLE.startRangingBeaconsInRegion(beaconRegion);

Now, we can detect beacons with their information and proximity.

Broadcasting

We will set a UUID to the app then it will start broadcasting this UUID and the receiver app will be able to detect.

At first we need to create an empty beacon data object that we will assign later and a beacon region to broadcast.

var beaconData = {};
var beaconRegion = new SMF.Bluetooth.BLE.BeaconRegion({
		proximityUUID : "B9407F30-F5F8-466E-AFF9-25556B57FE6D",
		identifier : "io.smartface.beaconapp",
		major : 1,
		minor : 1
	});

Then, create beacon data that can be used to advertise the current device as a beacon with peripheralDataWithMeasuredPower method as below:

beaconData = beaconRegion.peripheralDataWithMeasuredPower(null);

Now create a peripheral manager as below:

var Label2 = new SMF.UI.Label({
		name : "lbl",
		text : "",
		left : "15%",
		top : "30%",
		width : "70%",
		height : "10%",
		text : lang.done
	});
page1.add(Label2);
var myPeripheralManager = new SMF.Bluetooth.BLE.PeripheralManager({
		onUpdateState : function (e) {
			if (e.state == SMF.Bluetooth.BLE.PeripheralManagerState.POWEREDON) {
				this.startAdvertising(beaconData);
				Label2.text = "Broadcasting...";
			} else if (e.state == SMF.Bluetooth.BLE.PeripheralManagerState.POWEREDOFF) {
				this.stopAdvertising();
				alert("Powered Off");
			} else if (e.state == SMF.Bluetooth.BLE.PeripheralManagerState.UNSUPPORTED) {
				alert("Unsupported");
			}
		}
	});

With the peripheral manager, app will check if bluetooth supports iBeacon and powered on. If it is powered on we call startAdvertising method. Then app starts to broadcast.

More Bluetooth Low Energy features will be implemented in the next releases.