iBeacon.h

00001 /* mbed Microcontroller Library
00002 * Copyright (c) 2006-2015 ARM Limited
00003 *
00004 * Licensed under the Apache License, Version 2.0 (the "License");
00005 * you may not use this file except in compliance with the License.
00006 * You may obtain a copy of the License at
00007 *
00008 *     http://www.apache.org/licenses/LICENSE-2.0
00009 *
00010 * Unless required by applicable law or agreed to in writing, software
00011 * distributed under the License is distributed on an "AS IS" BASIS,
00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013 * See the License for the specific language governing permissions and
00014 * limitations under the License.
00015 */
00016 #ifndef MBED_BLE_IBEACON_H__
00017 #define MBED_BLE_IBEACON_H__
00018 
00019 #include "cmsis_compiler.h"
00020 #include "ble/BLE.h"
00021 #include "ble/pal/Deprecated.h"
00022 
00023 #if BLE_FEATURE_GATT_SERVER
00024 
00025 BLE_DEPRECATED_API_USE_BEGIN()
00026 
00027 /**
00028  * iBeacon Service.
00029  *
00030  * @par Purpose
00031  *
00032  * iBeacons are Bluetooth Low Energy (BLE) devices advertising an identification
00033  * number generally used to determine the location of devices or physical objects
00034  * near a mobile phone user.
00035  *
00036  * iOS scans for iBeacon devices in a background task and notifies apps
00037  * that subscribe to a specific region when a device enters or leaves an area. Apps may
00038  * use this information to display context-aware content to users.
00039  *
00040  * As an example, a museum can deploy an app that informs the user when one of
00041  * its exhibitions is entered and then displays specific information about exposed
00042  * pieces of art when the user is sufficiently close to them.
00043  *
00044  * @par Positioning
00045  *
00046  * Location information is hierarchically structured. A UUID specific to the
00047  * application and its deployment is used to identify a region. That region
00048  * usually identifies an organization. The region is divided into subregions
00049  * identified by a major ID. The subregion contains related points of interest
00050  * which a minor ID distinguishes.
00051  *
00052  * As an example, a city willing to improve tourist's experience can deploy a fleet
00053  * of iBeacons in relevant touristic locations it operates. The UUID may
00054  * identify a place managed by the city. The major ID would identify the place;
00055  * it can be a museum, a historic monument, a metro station and so on. The minor ID
00056  * would identify a specific spot within a specific city place. It can be a
00057  * piece of art, a ticket dispenser or a relevant point of interest.
00058  *
00059  * Each iBeacon device is physically attached to the spot it locates and
00060  * advertises the triplet UUID, major ID and minor ID.
00061  *
00062  * @par Proximity
00063  *
00064  * The beacon advertises the signal strength measured by an iOS device at a
00065  * distance of one meter. iOS uses this information to approximate the
00066  * proximity to a given beacon:
00067  *   - Immediate: The beacon is less than one meter away from the user.
00068  *   - Near: The beacon is one to three meters away from the user.
00069  *   - Far: The user is not near the beacon; the distance highly depends on
00070  *     the physical environment.
00071  *
00072  * Ideally, beacons should be calibrated at their deployment location because the
00073  * surrounding environment affects the strength of the advertised signal.
00074  *
00075  * @par Usage
00076  *
00077  * Mbed OS applications can use this class to configure a device to broadcast
00078  * advertising packets mimicking an iBeacon. The construction automatically
00079  * creates the payload identifying the beacon and registers it as part of the
00080  * advertising payload of the device.
00081  *
00082  * Beacon configuration and advertising commencement is left to the user.
00083  *
00084  * @attention If you are interested in manufacturing iBeacons, you must obtain a
00085  * license from Apple. More information at https://developer.apple.com/ibeacon/.
00086  * The license also grant access to the iBeacons technical specification.
00087  *
00088  * @note More information at https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf
00089  *
00090  * @deprecated This service is deprecated, and no replacement is currently available.
00091  */
00092 MBED_DEPRECATED_SINCE (
00093     "mbed-os-5.11",
00094     "This service is deprecated, and no replacement is currently available."
00095 )
00096 class iBeacon {
00097 public:
00098 #if !(DOXYGEN_ONLY)
00099     /**
00100      * Data buffer of a location UUID.
00101      */
00102     typedef const uint8_t LocationUUID_t[16];
00103 
00104     /**
00105      * iBeacon payload builder.
00106      *
00107      * This data structure contains the payload of an iBeacon. The payload is
00108      * built at construction time and application code can set up an iBeacon by
00109      * injecting the raw field into the GAP advertising payload as a
00110      * GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA.
00111      */
00112     union Payload {
00113         /**
00114          * Raw data of the payload.
00115          */
00116         uint8_t raw[25];
00117         struct {
00118             /**
00119              * Beacon manufacturer identifier.
00120              */
00121             uint16_t companyID;
00122 
00123             /**
00124              * Packet ID; equal to 2 for an iBeacon.
00125              */
00126             uint8_t ID;
00127 
00128             /**
00129              * Length of the remaining data present in the payload.
00130              */
00131             uint8_t len;
00132 
00133             /**
00134              * Beacon UUID.
00135              */
00136             uint8_t proximityUUID[16];
00137 
00138             /**
00139              * Beacon major group ID.
00140              */
00141             uint16_t majorNumber;
00142 
00143             /**
00144              * Beacon minor ID.
00145              */
00146             uint16_t minorNumber;
00147 
00148             /**
00149              * Tx power received at 1 meter; in dBm.
00150              */
00151             uint8_t txPower;
00152         };
00153 
00154         /**
00155          * Assemble an iBeacon payload.
00156          *
00157          * @param[in] uuid Beacon network ID. iBeacon operators use this value
00158          * to group their iBeacons into a single network, a single region, and
00159          * identify their organization among others.
00160          *
00161          * @param[in] majNum Beacon major group ID. iBeacon exploitants may use
00162          * this field to divide the region into subregions, and their network into
00163          * subnetworks.
00164          *
00165          * @param[in] minNum Identifier of the Beacon in its subregion.
00166          *
00167          * @param[in] transmitPower Measured transmit power of the beacon at 1
00168          * meter. Scanners use this parameter to approximate the distance
00169          * to the beacon.
00170          *
00171          * @param[in] companyIDIn ID of the beacon manufacturer.
00172          */
00173         Payload(
00174             LocationUUID_t uuid,
00175             uint16_t majNum,
00176             uint16_t minNum,
00177             uint8_t transmitPower,
00178             uint16_t companyIDIn
00179         ) : companyID(companyIDIn),
00180             ID(0x02),
00181             len(0x15),
00182             majorNumber(__REV16(majNum)),
00183             minorNumber(__REV16(minNum)),
00184             txPower(transmitPower)
00185         {
00186             memcpy(proximityUUID, uuid, sizeof(LocationUUID_t));
00187         }
00188     };
00189 #endif //#if !(DOXYGEN_ONLY)
00190 public:
00191     /**
00192      * Construct an iBeacon::Payload and register it into Gap.
00193      *
00194      * @param[in] _ble The BLE interface to configure with the iBeacon payload.
00195      *
00196      * @param[in] uuid Beacon network ID. iBeacon operators use this value
00197      * to group their iBeacons into a single network, a single region, and
00198      * identify their organization among others.
00199      *
00200      * @param[in] majNum Beacon major group ID. iBeacon fleet operators may use
00201      * this field to divide the region into subregions, and their network into
00202      * subnetworks.
00203      *
00204      * @param[in] minNum Identifier of the Beacon in its subregion.
00205      *
00206      * @param[in] txP Measured transmit power of the beacon at distance of
00207      * one meter. Scanners use this parameter to approximate the distance
00208      * to the beacon.
00209      *
00210      * @param[in] compID ID of the beacon manufacturer.
00211      *
00212      * @deprecated This service is deprecated, and no replacement is currently available.
00213      */
00214     MBED_DEPRECATED_SINCE (
00215         "mbed-os-5.11",
00216         "This service is deprecated, and no replacement is currently available."
00217     )
00218     iBeacon(
00219         BLE &_ble,
00220         LocationUUID_t uuid,
00221         uint16_t majNum,
00222         uint16_t minNum,
00223         uint8_t txP = 0xC8,
00224         uint16_t compID = 0x004C
00225     ) : ble(_ble),
00226         data(uuid, majNum, minNum, txP, compID)
00227     {
00228         // Generate the 0x020106 part of the iBeacon Prefix.
00229         ble.accumulateAdvertisingPayload(
00230             GapAdvertisingData::BREDR_NOT_SUPPORTED |
00231             GapAdvertisingData::LE_GENERAL_DISCOVERABLE
00232         );
00233         // Generate the 0x1AFF part of the iBeacon Prefix.
00234         ble.accumulateAdvertisingPayload(
00235             GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA,
00236             data.raw,
00237             sizeof(data.raw)
00238         );
00239 
00240         // Set advertising type.
00241         ble.setAdvertisingType(
00242             GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED
00243         );
00244     }
00245 
00246 protected:
00247     BLE &ble;
00248     Payload data;
00249 };
00250 
00251 /**
00252  * iBeacon alias.
00253  *
00254  * @deprecated Please use iBeacon directly. This alias may be dropped from a
00255  * future release.
00256  */
00257 typedef iBeacon iBeaconService;
00258 
00259 BLE_DEPRECATED_API_USE_END()
00260 
00261 #endif // BLE_FEATURE_GATT_SERVER
00262 
00263 #endif //MBED_BLE_IBEACON_H__