Bluetooth Low Energy / Mbed 2 deprecated BLE_iBeacon Featured

Beacon demo for the BLE API using the nRF51822 native mode drivers

Dependencies:   BLE_API mbed nRF51822 X_NUCLEO_IDB0XA1

Introduction

Bluetooth Low Energy Beacons are a service that allow for highly localized positioning. The Beacon service is particularly useful for indoor positioning, low power positioning and location aware software. A particular use of the Beacon service is iBeacon. The iBeacon standard is a Apple specific implementation of Beacons.

The Basics

The Beacon service is a BLE Service that operates in advertising mode only. A Beacon service advertises 4 things:

  • A company ID
  • A unique UUID (unique to a retailer)
  • A Major number (ex a store number)
  • A Minor number (ex a location in the store)
  • Signal Strength at transmitter (requires calibration per each device)

These pieces of information are all you need for a Beacon service to work. The majority of the heavy lifting is done by the smart phone application that reads these four fields and then uses a web app or a database of some sort to turn these numbers into valuable information about what you are near and how near you are to it.

The signal strength field is compared to the actual signal strength at the receiver to determine how close the beacon is to the phone. The number used is the calibrated signal strength 1 meter from the device. By doing this 1 meter increments can be used to measure distance from the Beacon. The distances usually get broken down into 3 ranges:

  • Immediate: Within a few centimeters
  • Near: Within a couple of meters
  • Far: Greater than 10 meters away

Company ID's are used to make beacon UUID's unique to companies. Some example company UUID's are:

  • 0x004C - Apple Inc.
  • 0x0059 - Nordic Semiconductor
  • 0x0078 - Nike
  • ​0x015D - Estimote
  • ​0x0171 - Amazon Fulfillment Service
  • 0xFFFF - reserved for internal testing before release

Here is the Bluetooth SIG's full list of Company ID's.

Example : Coffee Shop X

For example, if a smartphone app reads a BLE Beacon with UUID = 0x1234546... , Major Number=5, Minor number = 3, it would check that against a database. From that database it would find out that UUID 0x123456... is owned by Coffee Shop X, that Major number 5 belongs to the store on main street and that Minor number 3 belongs to the coffee rack in that store. Then the application could check to see if there are any deals for the Coffee Shop X on Main Street on Coffee today. If there are any deals the phone could then alert the user and display a coupon code.

Example : museum

The Beacon service also provides a way for the phone to tell how close it is to the beacon. This can be useful for location aware applications, such as in a museum. For example, the smartphone reads a BLE Beacon with UUID = 0x98765....., Major Number=1, minor number = 0. The smartphone then looks this up in a database and find the UUID is for the Natural Science Museum, Major Number 1 = the Art Gallery room 1, and the minor number 0 = an abstract painting of a duck. If we assume all the paintings are spread out at 10feet each, then the application can sense when you are within 3 feet of the painting (based on signal strength of the Beacon) and give the user information about the painting they are approaching.

Technical Details

An iBeacon is just a normal Bluetooth LE device broadcasting advertisements with special data shoved into the Manufacturer Specific Data field.

The iBeacon prefix is little more than metadata about the advertisement packet.

BytesDatadescription
0,1,20x020106This sets the flags for General Discoverable and BR/EDR not supported
3,40x1AFFThis says the length of the Manufacturer specific data field will be 26 bytes
0,10x4C00Company ID
20x02ID
30x15length of remaining data in bytes (16B UUID+ 2B major, 2B minor, 1B Txpower)

Note that bytes 0-4 are set implicitly by the API by declaring the advertising data to be LE General Discoverable and BR/EDR not supported. The remaining fields that make up an iBeacon advertisement packet can be clearly seen in the image below.

http://www.havlena.net/wp-content/uploads/ibeacon-packet.png

For a more depth explanation please see these well done explanations:

main.cpp@79:4e16bde5c10a, 2016-09-20 (annotated)

Committer:
Vincent Coubard
Date:
Tue Sep 20 12:41:28 2016 +0100
Revision:
79:4e16bde5c10a
Parent:
77:7674b63f8aea 
Update libraries.

Add ST shield via config system.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ktownsend 0:7613d21e5974 1 /* mbed Microcontroller Library
rgrover1 71:12660a3eb07d 2 * Copyright (c) 2006-2015 ARM Limited
ktownsend 0:7613d21e5974 3 *
ktownsend 0:7613d21e5974 4 * Licensed under the Apache License, Version 2.0 (the "License");
ktownsend 0:7613d21e5974 5 * you may not use this file except in compliance with the License.
ktownsend 0:7613d21e5974 6 * You may obtain a copy of the License at
ktownsend 0:7613d21e5974 7 *
ktownsend 0:7613d21e5974 8 * http://www.apache.org/licenses/LICENSE-2.0
ktownsend 0:7613d21e5974 9 *
ktownsend 0:7613d21e5974 10 * Unless required by applicable law or agreed to in writing, software
ktownsend 0:7613d21e5974 11 * distributed under the License is distributed on an "AS IS" BASIS,
ktownsend 0:7613d21e5974 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ktownsend 0:7613d21e5974 13 * See the License for the specific language governing permissions and
ktownsend 0:7613d21e5974 14 * limitations under the License.
ktownsend 0:7613d21e5974 15 */
ktownsend 0:7613d21e5974 16
ktownsend 0:7613d21e5974 17 #include "mbed.h"
rgrover1 71:12660a3eb07d 18 #include "ble/services/iBeacon.h"
mbedAustin 56:56bc0cab3916 19
rgrover1 69:f121dba6fcd3 20 BLE ble;
rgrover1 74:7754bf460f52 21
rgrover1 74:7754bf460f52 22 void bleInitComplete(BLE::InitializationCompleteCallbackContext *params)
ktownsend 0:7613d21e5974 23 {
rgrover1 74:7754bf460f52 24 BLE &ble = params->ble;
rgrover1 74:7754bf460f52 25 ble_error_t error = params->error;
mbedAustin 53:f9ec2c7a47f5 26
rgrover1 74:7754bf460f52 27 if (error != BLE_ERROR_NONE) {
rgrover1 74:7754bf460f52 28 return;
rgrover1 74:7754bf460f52 29 }
rgrover1 74:7754bf460f52 30
rgrover1 71:12660a3eb07d 31 /**
rgrover1 71:12660a3eb07d 32 * The Beacon payload has the following composition:
rgrover1 71:12660a3eb07d 33 * 128-Bit / 16byte UUID = E2 0A 39 F4 73 F5 4B C4 A1 2F 17 D1 AD 07 A9 61
rgrover1 71:12660a3eb07d 34 * Major/Minor = 0x1122 / 0x3344
rgrover1 71:12660a3eb07d 35 * Tx Power = 0xC8 = 200, 2's compliment is 256-200 = (-56dB)
rgrover1 71:12660a3eb07d 36 *
rgrover1 71:12660a3eb07d 37 * Note: please remember to calibrate your beacons TX Power for more accurate results.
rgrover1 71:12660a3eb07d 38 */
rgrover1 71:12660a3eb07d 39 const uint8_t uuid[] = {0xE2, 0x0A, 0x39, 0xF4, 0x73, 0xF5, 0x4B, 0xC4,
rgrover1 71:12660a3eb07d 40 0xA1, 0x2F, 0x17, 0xD1, 0xAD, 0x07, 0xA9, 0x61};
rgrover1 71:12660a3eb07d 41 uint16_t majorNumber = 1122;
rgrover1 71:12660a3eb07d 42 uint16_t minorNumber = 3344;
rgrover1 71:12660a3eb07d 43 uint16_t txPower = 0xC8;
rgrover1 74:7754bf460f52 44 iBeacon *ibeacon = new iBeacon(ble, uuid, majorNumber, minorNumber, txPower);
mbedAustin 53:f9ec2c7a47f5 45
rgrover1 69:f121dba6fcd3 46 ble.gap().setAdvertisingInterval(1000); /* 1000ms. */
rgrover1 69:f121dba6fcd3 47 ble.gap().startAdvertising();
rgrover1 74:7754bf460f52 48 }
rgrover1 74:7754bf460f52 49
rgrover1 74:7754bf460f52 50 int main(void)
rgrover1 74:7754bf460f52 51 {
rgrover1 74:7754bf460f52 52 ble.init(bleInitComplete);
rgrover1 75:b0385b4fdc3e 53
rgrover1 75:b0385b4fdc3e 54 /* SpinWait for initialization to complete. This is necessary because the
rgrover1 75:b0385b4fdc3e 55 * BLE object is used in the main loop below. */
rgrover1 77:7674b63f8aea 56 while (!ble.hasInitialized()) { /* spin loop */ }
ktownsend 0:7613d21e5974 57
rgrover1 72:eb4de3de66b8 58 while (true) {
mbedAustin 56:56bc0cab3916 59 ble.waitForEvent(); // allows or low power operation
ktownsend 0:7613d21e5974 60 }
Rohit Grover 10:391c1acf4b9d 61 }