mbed-os-examples / Mbed OS mbed-os-example-ble-Beacon

This example creates a BLE beacon: a method of advertising a small amount of information to nearby devices. The information doesn't have to be human-readable; it can be in a format that only an application can use. Beacons are very easy to set up: the code for all beacons is the same, and only the information you want to advertise - the beacon payload - needs to change. he canonical source for this example lives at https://github.com/ARMmbed/mbed-os-example-ble/tree/master/BLE_Beacon

This example creates a BLE beacon: a method of advertising a small amount of information to nearby devices. The information doesn't have to be human-readable; it can be in a format that only an application can use.

Beacons are very easy to set up: the code for all beacons is the same, and only the information you want to advertise - the beacon payload - needs to change.

This example advertises a UUID, a major and minor number and the transmission strength. The major and minor numbers are an example of information that is not (normally) meaningful to humans, but that an application can use to identify the beacon and display related information. For example, if the major number is a store ID and the minor number is a location in that store, then a matching application can use these numbers to query a database and display location-specific information.

Running the application

Requirements

The sample application can be seen on any BLE scanner on a smartphone. If you don't have a scanner on your phone, please install :

- nRF Master Control Panel for Android.

- LightBlue for iPhone.

Hardware requirements are in the main readme.

Building instructions

Building with mbed CLI

If you'd like to use mbed CLI to build this, then you should refer to the main readme. The instructions here relate to using the developer.mbed.org Online Compiler

In order to build this example in the mbed Online Compiler, first import the example using the ‘Import’ button on the right hand side.

Next, select a platform to build for. This must either be a platform that supports BLE, for example the NRF51-DK, or one of the following:

List of platforms supporting Bluetooth Low Energy

Or you must also add a piece of hardware and the supporting library that includes a Bluetooth Low Energy driver for that hardware, for example the K64F or NUCLEO_F401RE with the X-NUCLEO-IDB05A1

List of components supporting Bluetooth Low Energy.

Once you have selected your platform, compile the example and drag and drop the resulting binary onto your board.

For general instructions on using the mbed Online Compiler, please see the mbed Handbook

Checking for success

Note: Screens captures depicted below show what is expected from this example if the scanner used is nRF Master Control Panel version 4.0.5. If you encounter any difficulties consider trying another scanner or another version of nRF Master Control Panel. Alternative scanners may require reference to their manuals.

  • Build the application and install it on your board as explained in the building instructions.
  • Open the BLE scanner on your phone.
  • Start a scan.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Beacon/raw-file/66b59f6860ed/img/start_scan.png

figure 1 How to start scan using nRF Master Control Panel 4.0.5

1. Find your device; it should be tagged as an `iBeacon` and observe its advertisements (there is no need to connect to the beacon).

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Beacon/raw-file/66b59f6860ed/img/discovery.png

figure 2 Scan results using nRF Master Control Panel 4.0.5

  • View the beacon's details; the exact steps depend on which scanner you're using.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Beacon/raw-file/66b59f6860ed/img/beacon_details.png

figure 3 Beacon details using nRF Master Control Panel 4.0.5

Tip: If you are in an area with many BLE devices, it may be difficult to identify your beacon. The simplest solution is to turn your board off and on, initiate a new scan on your BLE scanner every time, and look for the beacon that appears only when your board is on.

If you can see the beacon and all its information, the application worked properly.

For more information, see the mbed Classic version of this application.

source/main.cpp@1:2fd54f1254fe, 2016-07-28 (annotated)

Committer:
mbed_official
Date:
Thu Jul 28 23:14:25 2016 +0100
Revision:
1:2fd54f1254fe
Parent:
0:66b59f6860ed
Child:
2:401488de6e22
Merge branch 'master' of https://github.com/ARMmbed/mbed-os-example-ble





Commit copied from ./src/github.com/ARMmbed/mbed-os-example-ble

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 1:2fd54f1254fe 1 /* mbed Microcontroller Library
mbed_official 1:2fd54f1254fe 2 * Copyright (c) 2006-2015 ARM Limited
mbed_official 1:2fd54f1254fe 3 *
mbed_official 1:2fd54f1254fe 4 * Licensed under the Apache License, Version 2.0 (the "License");
mbed_official 1:2fd54f1254fe 5 * you may not use this file except in compliance with the License.
mbed_official 1:2fd54f1254fe 6 * You may obtain a copy of the License at
mbed_official 1:2fd54f1254fe 7 *
mbed_official 1:2fd54f1254fe 8 * http://www.apache.org/licenses/LICENSE-2.0
mbed_official 1:2fd54f1254fe 9 *
mbed_official 1:2fd54f1254fe 10 * Unless required by applicable law or agreed to in writing, software
mbed_official 1:2fd54f1254fe 11 * distributed under the License is distributed on an "AS IS" BASIS,
mbed_official 1:2fd54f1254fe 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
mbed_official 1:2fd54f1254fe 13 * See the License for the specific language governing permissions and
mbed_official 1:2fd54f1254fe 14 * limitations under the License.
mbed_official 1:2fd54f1254fe 15 */
mbed_official 1:2fd54f1254fe 16
mbed_official 1:2fd54f1254fe 17 #include <mbed-events/events.h>
mbed_official 1:2fd54f1254fe 18 #include <mbed.h>
mbed_official 1:2fd54f1254fe 19 #include "ble/BLE.h"
mbed_official 1:2fd54f1254fe 20 #include "ble/services/iBeacon.h"
mbed_official 1:2fd54f1254fe 21
mbed_official 1:2fd54f1254fe 22 static iBeacon* ibeaconPtr;
mbed_official 1:2fd54f1254fe 23
mbed_official 1:2fd54f1254fe 24 static EventQueue eventQueue(
mbed_official 1:2fd54f1254fe 25 /* event count */ 4 * /* event size */ 32
mbed_official 1:2fd54f1254fe 26 );
mbed_official 1:2fd54f1254fe 27
mbed_official 1:2fd54f1254fe 28 /**
mbed_official 1:2fd54f1254fe 29 * This function is called when the ble initialization process has failled
mbed_official 1:2fd54f1254fe 30 */
mbed_official 1:2fd54f1254fe 31 void onBleInitError(BLE &ble, ble_error_t error)
mbed_official 1:2fd54f1254fe 32 {
mbed_official 1:2fd54f1254fe 33 /* Initialization error handling should go here */
mbed_official 1:2fd54f1254fe 34 }
mbed_official 1:2fd54f1254fe 35
mbed_official 1:2fd54f1254fe 36 /**
mbed_official 1:2fd54f1254fe 37 * Callback triggered when the ble initialization process has finished
mbed_official 1:2fd54f1254fe 38 */
mbed_official 1:2fd54f1254fe 39 void bleInitComplete(BLE::InitializationCompleteCallbackContext *params)
mbed_official 1:2fd54f1254fe 40 {
mbed_official 1:2fd54f1254fe 41 BLE& ble = params->ble;
mbed_official 1:2fd54f1254fe 42 ble_error_t error = params->error;
mbed_official 1:2fd54f1254fe 43
mbed_official 1:2fd54f1254fe 44 if (error != BLE_ERROR_NONE) {
mbed_official 1:2fd54f1254fe 45 /* In case of error, forward the error handling to onBleInitError */
mbed_official 1:2fd54f1254fe 46 onBleInitError(ble, error);
mbed_official 1:2fd54f1254fe 47 return;
mbed_official 1:2fd54f1254fe 48 }
mbed_official 1:2fd54f1254fe 49
mbed_official 1:2fd54f1254fe 50 /* Ensure that it is the default instance of BLE */
mbed_official 1:2fd54f1254fe 51 if(ble.getInstanceID() != BLE::DEFAULT_INSTANCE) {
mbed_official 1:2fd54f1254fe 52 return;
mbed_official 1:2fd54f1254fe 53 }
mbed_official 1:2fd54f1254fe 54
mbed_official 1:2fd54f1254fe 55 /**
mbed_official 1:2fd54f1254fe 56 * The Beacon payload has the following composition:
mbed_official 1:2fd54f1254fe 57 * 128-Bit / 16byte UUID = E2 0A 39 F4 73 F5 4B C4 A1 2F 17 D1 AD 07 A9 61
mbed_official 1:2fd54f1254fe 58 * Major/Minor = 0x1122 / 0x3344
mbed_official 1:2fd54f1254fe 59 * Tx Power = 0xC8 = 200, 2's compliment is 256-200 = (-56dB)
mbed_official 1:2fd54f1254fe 60 *
mbed_official 1:2fd54f1254fe 61 * Note: please remember to calibrate your beacons TX Power for more accurate results.
mbed_official 1:2fd54f1254fe 62 */
mbed_official 1:2fd54f1254fe 63 static const uint8_t uuid[] = {0xE2, 0x0A, 0x39, 0xF4, 0x73, 0xF5, 0x4B, 0xC4,
mbed_official 1:2fd54f1254fe 64 0xA1, 0x2F, 0x17, 0xD1, 0xAD, 0x07, 0xA9, 0x61};
mbed_official 1:2fd54f1254fe 65 uint16_t majorNumber = 1122;
mbed_official 1:2fd54f1254fe 66 uint16_t minorNumber = 3344;
mbed_official 1:2fd54f1254fe 67 uint16_t txPower = 0xC8;
mbed_official 1:2fd54f1254fe 68 ibeaconPtr = new iBeacon(ble, uuid, majorNumber, minorNumber, txPower);
mbed_official 1:2fd54f1254fe 69
mbed_official 1:2fd54f1254fe 70 ble.gap().setAdvertisingInterval(1000); /* 1000ms. */
mbed_official 1:2fd54f1254fe 71 ble.gap().startAdvertising();
mbed_official 1:2fd54f1254fe 72 }
mbed_official 1:2fd54f1254fe 73
mbed_official 1:2fd54f1254fe 74 void scheduleBleEventsProcessing(BLE::OnEventsToProcessCallbackContext* context) {
mbed_official 1:2fd54f1254fe 75 BLE &ble = BLE::Instance();
mbed_official 1:2fd54f1254fe 76 eventQueue.post(Callback<void()>(&ble, &BLE::processEvents));
mbed_official 1:2fd54f1254fe 77 }
mbed_official 1:2fd54f1254fe 78
mbed_official 1:2fd54f1254fe 79 int main()
mbed_official 1:2fd54f1254fe 80 {
mbed_official 1:2fd54f1254fe 81 BLE &ble = BLE::Instance();
mbed_official 1:2fd54f1254fe 82 ble.onEventsToProcess(scheduleBleEventsProcessing);
mbed_official 1:2fd54f1254fe 83 ble.init(bleInitComplete);
mbed_official 1:2fd54f1254fe 84
mbed_official 1:2fd54f1254fe 85 while (true) {
mbed_official 1:2fd54f1254fe 86 eventQueue.dispatch();
mbed_official 1:2fd54f1254fe 87 }
mbed_official 1:2fd54f1254fe 88
mbed_official 1:2fd54f1254fe 89 return 0;
mbed_official 1:2fd54f1254fe 90 }