Bluetooth Low Energy
The Uniform Resource Identifier Beacon (UriBeacon) defines Bluetooth 4.0 Advertisement Data that contain Web URIs. URIBeacon provides a way for Bluetooth Low Energy devices to discover nearby URIs, for example, provides a way for a user to discover a short URL and then download it on their smartphone.
Dependencies: BLE_API mbed nRF51822
Fork of
BLE_PhysicalWeb
by 
Bluetooth Low Energy
This example demonstrates how to set up and initialize a basic URI Beacon. For a more advanced example of using a URI beacon please see the BLE_PhysicalWeb project. The Google Github Page also gives a great description of what UriBeacons are and how to use them.
Basic Details
URI Beacons are a standard way of providing a URI link in a BLE advertising packet. Website URL's are the most popular URI's. The goal of URI Beacons are to act as a bridge between the physical and digital worlds. Since the URI can be any web capable link the possibilities for use are really endless. The UriBeacons can be thought of as a natural extension of and more useful version of QR codes.
Smartphone App Links
Walkthrough of Physical Web application
Size of URI
The UriBeacon has one purpose, to advertise a web link. Because of the nature of BLE these web links have to be small. In order to provide a nice balance of small and useful the UriBeacon specification has abstracted out the representation of the URI prefix('http://www.', 'https://www.' , ...etc) and suffix ('.com','.org','.edu','.gov' ...etc) to a single byte each. Of the 27 bytes available for a usual BLE payload the UriBeacon has 19 bytes available for the URI. Of these 19bytes one byte must be given to the prefix. That leaves 18 bytes to fit the address and the suffix into. If the suffix used is not one of the standard ones in the UriBeacon specification then each letter will take up 1 byte instead of the entire suffix being abbreviated into a single byte.
Here are the acceptable abbreviations currently available
| PreFix | Suffix |
|---|---|
| http://www. | .com/ |
| https://www. | .org/ |
| http:// | .edu/ |
| https:// | .net/ |
| urn:uuid: | .info/ |
| .biz/ | |
| .gov/ | |
| .com | |
| .org | |
| .edu | |
| .net | |
| .info | |
| .biz | |
| .gov |
So for example the address "http://www.google.com" would take up 8 bytes. Both "http://www." and ".com" are supported abbreviations so each will be shortened to 1 byte.
| Number of Bytes | Data |
|---|---|
| 1 | "http://www." abbreviated |
| 6 | "google", 1 byte for each letter |
| 1 | ".com/" abbreviated |
An address like "http://www.bit.ly/xyz" would take up 11 bytes. Notice that ".ly" is not a supported suffix, so each letter takes up 1 byte.
| Number of Bytes | Data |
|---|---|
| 1 | "http://www." abbreviated |
| 10 | "bit.ly/xyz" |
Even addresses with the suffix in the middle are abbreviated, ie "http://www.youtube.com/XYZ". Notice here that the '.com' is in the middle of an address, it is still shortened to just 1 byte.
| Number of Bytes | Data |
|---|---|
| 1 | "http://www." abbreviated |
| 7 | "youtube" |
| 1 | ".com/" abbreviated |
| 4 | "XYZ" |
Using UriBeacons with mbed BLE API
Using the UriBeacon with the mbed API is rather simple. Just like any other BLE project you must first initialize the BLE baselayer by creating a ble object.
Initialize_bl_object
BLEDevice ble;
Then you pass the BLE object to a UriBeacon config service.
Configure_UriBeacon_Service
URIBeaconConfigService *uriBeaconConfig; uriBeaconConfig = new URIBeaconConfigService(ble, "http://www.mbed.org");
Optionally you can then adjust settings of the UriBeacon such as transmission power levels, grabbing verbose debug information and other handy dandy services.
Optional_UriBeacon_configuration
/* Adjust the TX Power Level */
const int8_t powerLevels[] = {-20, -4, 0, 10};
uriBeaconConfig->setTxPowerLevels(powerLevels); // Set TX power levels, Lowest(-20), Low(-4), Medium(0), High(10)
uriBeaconConfig->setTxPowerMode(URIBeaconConfigService::TX_POWER_MODE_LOW); // Set transmission in Low power mode
/* Adjust Beacon Period*/
setBeaconPeriod(1000); // Set beacon to advertise every 1000ms
Other UriBeacon Services
This is just the bare basics of how URI beacons work. There is also a configuration service that allows URI beacons to be updated, locked, and provides other management feature. That is beyond the scope of this example but details can be found in the Technical Details section below.
Technical Details
For more details on how URI beacons work please see these websites:
UriBeacon Github Project : the github home for all things UriBeacon (maintained by google)
UriBeacon Specification : lots of good technical details
UriBeacon configuration service - This is a service that pairs with the UriBeacon that allows changing the URI's, locking them, and some other cool features. This service is not detailed in this example application.
Android App : smartphone application to view nearby UriBeacons.
iOS App : Sample code for using UriBeacons with iOS.
The PhysicalWeb Project : a project that the UriBeacon is central to.
In case you're really interested here is a diagram that nicely sums up how the 27bytes of advertising data payload are used.
Diff: main.cpp
- Revision:
- 16:1daa78939a3b
- Parent:
- 14:868a1207022d
- Child:
- 17:e2c0a1696e39
--- a/main.cpp Fri Mar 06 09:23:50 2015 +0000
+++ b/main.cpp Mon Mar 09 16:35:03 2015 +0000
@@ -14,244 +14,49 @@
* limitations under the License.
*/
-#include <stdint.h>
-#include <stddef.h>
-#include <nrf_error.h>
#include "mbed.h"
#include "BLEDevice.h"
#include "URIBeaconConfigService.h"
#include "DFUService.h"
-#include "pstorage.h"
#include "DeviceInformationService.h"
-
-// Struct to hold persistent data across power cycles
-struct PersistentData_t {
- uint32_t magic;
- URIBeaconConfigService::Params_t params;
- uint8_t pad[4];
-} __attribute__ ((aligned (4)));
-
-static const int PERSISTENT_DATA_ALIGNED_SIZE = sizeof(PersistentData_t);
-// Seconds after power-on that config service is available.
-static const int ADVERTISING_TIMEOUT_SECONDS = 60;
-// Advertising interval for config service.
-static const int ADVERTISING_INTERVAL_MSEC = 1000;
-// Maximum size of service data in ADV packets
-static const int SERVICE_DATA_MAX = 31;
-// Magic that identifies persistent storage
-static const uint32_t MAGIC = 0x1BEAC000;
-// Values for ADV packets related to firmware levels
-static URIBeaconConfigService::PowerLevels_t defaultAdvPowerLevels = {-20, -4, 0, 10};
-// Values for setTxPower() indexed by power mode.
-static const int8_t firmwarePowerLevels[] = {-20, -4, 0, 10};
+#include "ConfigParamsPersistence.h"
BLEDevice ble;
URIBeaconConfigService *uriBeaconConfig;
-pstorage_handle_t pstorageHandle;
-PersistentData_t persistentData;
-/* LEDs for indication */
-DigitalOut connectionStateLed(LED1);
-DigitalOut advertisingStateLed(LED2);
-
-/* Dummy callback handler needed by Nordic's pstorage module. */
-void pstorageNotificationCallback(pstorage_handle_t *p_handle,
- uint8_t op_code,
- uint32_t result,
- uint8_t * p_data,
- uint32_t data_len) {
- /* APP_ERROR_CHECK(result); */
-}
-
-void pstorageLoad() {
- pstorage_init();
- pstorage_module_param_t pstorageParams = {
- .cb = pstorageNotificationCallback,
- .block_size = PERSISTENT_DATA_ALIGNED_SIZE,
- .block_count = 1
- };
- pstorage_register(&pstorageParams, &pstorageHandle);
- if (pstorage_load(reinterpret_cast<uint8_t *>(&persistentData),
- &pstorageHandle, PERSISTENT_DATA_ALIGNED_SIZE, 0) != NRF_SUCCESS) {
- // On failure zero out and let the service reset to defaults
- memset(&persistentData, 0, sizeof(PersistentData_t));
- }
-}
-
-
-void pstorageSave() {
- if (persistentData.magic != MAGIC) {
- persistentData.magic = MAGIC;
- pstorage_store(&pstorageHandle,
- reinterpret_cast<uint8_t *>(&persistentData),
- sizeof(PersistentData_t),
- 0 /* offset */);
- } else {
- pstorage_update(&pstorageHandle,
- reinterpret_cast<uint8_t *>(&persistentData),
- sizeof(PersistentData_t),
- 0 /* offset */);
- }
-}
-
-void startAdvertisingUriBeaconConfig() {
- char DEVICE_NAME[] = "mUriBeacon Config";
-
- ble.clearAdvertisingPayload();
-
- // Stops advertising the UriBeacon Config Service after a delay
- ble.setAdvertisingTimeout(ADVERTISING_TIMEOUT_SECONDS);
-
- ble.accumulateAdvertisingPayload(
- GapAdvertisingData::BREDR_NOT_SUPPORTED |
- GapAdvertisingData::LE_GENERAL_DISCOVERABLE);
-
- // UUID is in different order in the ADV frame (!)
- uint8_t reversedServiceUUID[sizeof(UUID_URI_BEACON_SERVICE)];
- for (unsigned int i = 0; i < sizeof(UUID_URI_BEACON_SERVICE); i++) {
- reversedServiceUUID[i] =
- UUID_URI_BEACON_SERVICE[sizeof(UUID_URI_BEACON_SERVICE) - i - 1];
- }
- ble.accumulateAdvertisingPayload(
- GapAdvertisingData::COMPLETE_LIST_128BIT_SERVICE_IDS,
- reversedServiceUUID,
- sizeof(reversedServiceUUID));
-
- ble.accumulateAdvertisingPayload(GapAdvertisingData::GENERIC_TAG);
- ble.accumulateScanResponse(
- GapAdvertisingData::COMPLETE_LOCAL_NAME,
- reinterpret_cast<uint8_t *>(&DEVICE_NAME),
- sizeof(DEVICE_NAME));
- ble.accumulateScanResponse(
- GapAdvertisingData::TX_POWER_LEVEL,
- reinterpret_cast<uint8_t *>(
- &defaultAdvPowerLevels[URIBeaconConfigService::TX_POWER_MODE_LOW]),
- sizeof(uint8_t));
-
- ble.setTxPower(
- firmwarePowerLevels[URIBeaconConfigService::TX_POWER_MODE_LOW]);
-
- ble.setDeviceName(reinterpret_cast<uint8_t *>(&DEVICE_NAME));
- ble.setAdvertisingType(GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED);
- ble.setAdvertisingInterval(
- Gap::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(ADVERTISING_INTERVAL_MSEC));
+void disconnectionCallback(Gap::Handle_t handle, Gap::DisconnectionReason_t reason)
+{
ble.startAdvertising();
}
-void startAdvertisingUriBeacon() {
- uint8_t serviceData[SERVICE_DATA_MAX];
- int serviceDataLen = 0;
-
- advertisingStateLed = 1;
- connectionStateLed = 1;
-
- ble.shutdown();
- ble.init();
-
- // Fields from the Service
- int beaconPeriod = persistentData.params.beaconPeriod;
- int txPowerMode = persistentData.params.txPowerMode;
- int uriDataLength = persistentData.params.uriDataLength;
- URIBeaconConfigService::UriData_t &uriData = persistentData.params.uriData;
- URIBeaconConfigService::PowerLevels_t &advPowerLevels = persistentData.params.advPowerLevels;
- uint8_t flags = persistentData.params.flags;
-
- pstorageSave();
-
- delete uriBeaconConfig;
- uriBeaconConfig = NULL;
-
- ble.clearAdvertisingPayload();
- ble.setTxPower(firmwarePowerLevels[txPowerMode]);
-
- ble.setAdvertisingType(
- GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED);
-
- ble.setAdvertisingInterval(
- Gap::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(beaconPeriod));
-
- ble.accumulateAdvertisingPayload(
- GapAdvertisingData::BREDR_NOT_SUPPORTED |
- GapAdvertisingData::LE_GENERAL_DISCOVERABLE);
-
- ble.accumulateAdvertisingPayload(
- GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, BEACON_UUID,
- sizeof(BEACON_UUID));
-
- serviceData[serviceDataLen++] = BEACON_UUID[0];
- serviceData[serviceDataLen++] = BEACON_UUID[1];
- serviceData[serviceDataLen++] = flags;
- serviceData[serviceDataLen++] = advPowerLevels[txPowerMode];
- for (int j=0; j < uriDataLength; j++) {
- serviceData[serviceDataLen++] = uriData[j];
- }
-
- ble.accumulateAdvertisingPayload(
- GapAdvertisingData::SERVICE_DATA,
- serviceData, serviceDataLen);
-
- ble.startAdvertising();
-}
-
-// After advertising timeout, stop config and switch to UriBeacon
-void timeout(void) {
- Gap::GapState_t state;
- state = ble.getGapState();
- if (!state.connected) {
- startAdvertisingUriBeacon();
- }
-}
-
-// When connected to config service, change the LEDs
-void connectionCallback(Gap::Handle_t handle,
- Gap::addr_type_t peerAddrType,
- const Gap::address_t peerAddr,
- const Gap::ConnectionParams_t *params) {
- advertisingStateLed = 1;
- connectionStateLed = 0;
-}
-
-// When disconnected from config service, start advertising UriBeacon
-void disconnectionCallback(Gap::Handle_t handle,
- Gap::DisconnectionReason_t reason) {
- advertisingStateLed = 0; // on
- connectionStateLed = 1; // off
- startAdvertisingUriBeacon();
-}
-
int main(void)
{
- advertisingStateLed = 0; // on
- connectionStateLed = 1; // off
-
ble.init();
ble.onDisconnection(disconnectionCallback);
- ble.onConnection(connectionCallback);
- // Advertising timeout
- ble.onTimeout(timeout);
-
- pstorageLoad();
- bool resetToDefaults = persistentData.magic != MAGIC;
- URIBeaconConfigService::UriData_t defaultUriData;
- size_t defaultUriDataLength;
- URIBeaconConfigService::encodeURI("http://uribeacon.org", defaultUriData, defaultUriDataLength);
+ /*
+ * Load parameters from (platform specific) persistent storage. Parameters
+ * can be set to non-default values while the URIBeacon is in configuration
+ * mode (within the first 60 seconds of power-up). Thereafter, parameters
+ * get copied out to persistent storage before switching to normal URIBeacon
+ * operation.
+ */
+ URIBeaconConfigService::Params_t params;
+ loadURIBeaconConfigParams(¶ms);
- uriBeaconConfig = new URIBeaconConfigService(ble, persistentData.params, resetToDefaults,
- defaultUriData, defaultUriDataLength, defaultAdvPowerLevels);
+ /* Initialize a URIBeaconConfig service providing config params, default URI, and power levels. */
+ static URIBeaconConfigService::PowerLevels_t defaultAdvPowerLevels = {-20, -4, 0, 10}; // Values for ADV packets related to firmware levels
+ uriBeaconConfig = new URIBeaconConfigService(ble, params, "http://uribeacon.org", defaultAdvPowerLevels);
if (!uriBeaconConfig->configuredSuccessfully()) {
error("failed to accommodate URI");
}
// Setup auxiliary services to allow over-the-air firmware updates, etc
DFUService dfu(ble);
- DeviceInformationService deviceInfo(
- ble, "ARM", "UriBeacon", "SN1", "hw-rev1", "fw-rev1", "soft-rev1");
+ DeviceInformationService deviceInfo(ble, "ARM", "UriBeacon", "SN1", "hw-rev1", "fw-rev1", "soft-rev1");
- /* Start out by advertising the configService for a limited time after
- * startup; and switch to the normal non-connectible beacon functionality
- * afterwards. */
- startAdvertisingUriBeaconConfig();
+ ble.startAdvertising(); /* Set the whole thing in motion. After this call a GAP central can scan the URIBeaconConfig
+ * service, which then automatically switches to the URIBeacon after a timeout. */
while (true) {
ble.waitForEvent();