Mbed OS Reference | iBeacon.h Source File

 /* mbed Microcontroller Library
 * Copyright (c) 2006-2015 ARM Limited
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 #ifndef MBED_BLE_IBEACON_H__
 #define MBED_BLE_IBEACON_H__
 
 #include "cmsis_compiler.h"
 #include "ble/BLE.h"
 #include "ble/pal/Deprecated.h"
 
 #if BLE_FEATURE_GATT_SERVER
 
 BLE_DEPRECATED_API_USE_BEGIN()
 
 /**
  * iBeacon Service.
  *
  * @par Purpose
  *
  * iBeacons are Bluetooth Low Energy (BLE) devices advertising an identification
  * number generally used to determine the location of devices or physical objects
  * near a mobile phone user.
  *
  * iOS scans for iBeacon devices in a background task and notifies apps
  * that subscribe to a specific region when a device enters or leaves an area. Apps may
  * use this information to display context-aware content to users.
  *
  * As an example, a museum can deploy an app that informs the user when one of
  * its exhibitions is entered and then displays specific information about exposed
  * pieces of art when the user is sufficiently close to them.
  *
  * @par Positioning
  *
  * Location information is hierarchically structured. A UUID specific to the
  * application and its deployment is used to identify a region. That region
  * usually identifies an organization. The region is divided into subregions
  * identified by a major ID. The subregion contains related points of interest
  * which a minor ID distinguishes.
  *
  * As an example, a city willing to improve tourist's experience can deploy a fleet
  * of iBeacons in relevant touristic locations it operates. The UUID may
  * identify a place managed by the city. The major ID would identify the place;
  * it can be a museum, a historic monument, a metro station and so on. The minor ID
  * would identify a specific spot within a specific city place. It can be a
  * piece of art, a ticket dispenser or a relevant point of interest.
  *
  * Each iBeacon device is physically attached to the spot it locates and
  * advertises the triplet UUID, major ID and minor ID.
  *
  * @par Proximity
  *
  * The beacon advertises the signal strength measured by an iOS device at a
  * distance of one meter. iOS uses this information to approximate the
  * proximity to a given beacon:
  *   - Immediate: The beacon is less than one meter away from the user.
  *   - Near: The beacon is one to three meters away from the user.
  *   - Far: The user is not near the beacon; the distance highly depends on
  *     the physical environment.
  *
  * Ideally, beacons should be calibrated at their deployment location because the
  * surrounding environment affects the strength of the advertised signal.
  *
  * @par Usage
  *
  * Mbed OS applications can use this class to configure a device to broadcast
  * advertising packets mimicking an iBeacon. The construction automatically
  * creates the payload identifying the beacon and registers it as part of the
  * advertising payload of the device.
  *
  * Beacon configuration and advertising commencement is left to the user.
  *
  * @attention If you are interested in manufacturing iBeacons, you must obtain a
  * license from Apple. More information at https://developer.apple.com/ibeacon/.
  * The license also grant access to the iBeacons technical specification.
  *
  * @note More information at https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf
  *
  * @deprecated This service is deprecated, and no replacement is currently available.
  */
 MBED_DEPRECATED_SINCE(
     "mbed-os-5.11",
     "This service is deprecated, and no replacement is currently available."
 )
 class iBeacon {
 public:
 #if !(DOXYGEN_ONLY)
     /**
      * Data buffer of a location UUID.
      */
     typedef const uint8_t LocationUUID_t[16];
 
     /**
      * iBeacon payload builder.
      *
      * This data structure contains the payload of an iBeacon. The payload is
      * built at construction time and application code can set up an iBeacon by
      * injecting the raw field into the GAP advertising payload as a
      * GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA.
      */
     union Payload {
         /**
          * Raw data of the payload.
          */
         uint8_t raw[25];
         struct {
             /**
              * Beacon manufacturer identifier.
              */
             uint16_t companyID;
 
             /**
              * Packet ID; equal to 2 for an iBeacon.
              */
             uint8_t ID;
 
             /**
              * Length of the remaining data present in the payload.
              */
             uint8_t len;
 
             /**
              * Beacon UUID.
              */
             uint8_t proximityUUID[16];
 
             /**
              * Beacon major group ID.
              */
             uint16_t majorNumber;
 
             /**
              * Beacon minor ID.
              */
             uint16_t minorNumber;
 
             /**
              * Tx power received at 1 meter; in dBm.
              */
             uint8_t txPower;
         };
 
         /**
          * Assemble an iBeacon payload.
          *
          * @param[in] uuid Beacon network ID. iBeacon operators use this value
          * to group their iBeacons into a single network, a single region, and
          * identify their organization among others.
          *
          * @param[in] majNum Beacon major group ID. iBeacon exploitants may use
          * this field to divide the region into subregions, and their network into
          * subnetworks.
          *
          * @param[in] minNum Identifier of the Beacon in its subregion.
          *
          * @param[in] transmitPower Measured transmit power of the beacon at 1
          * meter. Scanners use this parameter to approximate the distance
          * to the beacon.
          *
          * @param[in] companyIDIn ID of the beacon manufacturer.
          */
         Payload(
             LocationUUID_t uuid,
             uint16_t majNum,
             uint16_t minNum,
             uint8_t transmitPower,
             uint16_t companyIDIn
         ) : companyID(companyIDIn),
             ID(0x02),
             len(0x15),
             majorNumber(__REV16(majNum)),
             minorNumber(__REV16(minNum)),
             txPower(transmitPower)
         {
             memcpy(proximityUUID, uuid, sizeof(LocationUUID_t));
         }
     };
 #endif //#if !(DOXYGEN_ONLY)
 public:
     /**
      * Construct an iBeacon::Payload and register it into Gap.
      *
      * @param[in] _ble The BLE interface to configure with the iBeacon payload.
      *
      * @param[in] uuid Beacon network ID. iBeacon operators use this value
      * to group their iBeacons into a single network, a single region, and
      * identify their organization among others.
      *
      * @param[in] majNum Beacon major group ID. iBeacon fleet operators may use
      * this field to divide the region into subregions, and their network into
      * subnetworks.
      *
      * @param[in] minNum Identifier of the Beacon in its subregion.
      *
      * @param[in] txP Measured transmit power of the beacon at distance of
      * one meter. Scanners use this parameter to approximate the distance
      * to the beacon.
      *
      * @param[in] compID ID of the beacon manufacturer.
      *
      * @deprecated This service is deprecated, and no replacement is currently available.
      */
     MBED_DEPRECATED_SINCE(
         "mbed-os-5.11",
         "This service is deprecated, and no replacement is currently available."
     )
     iBeacon(
         BLE &_ble,
         LocationUUID_t uuid,
         uint16_t majNum,
         uint16_t minNum,
         uint8_t txP = 0xC8,
         uint16_t compID = 0x004C
     ) : ble(_ble),
         data(uuid, majNum, minNum, txP, compID)
     {
         // Generate the 0x020106 part of the iBeacon Prefix.
         ble.accumulateAdvertisingPayload(
             GapAdvertisingData::BREDR_NOT_SUPPORTED |
             GapAdvertisingData::LE_GENERAL_DISCOVERABLE
         );
         // Generate the 0x1AFF part of the iBeacon Prefix.
         ble.accumulateAdvertisingPayload(
             GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA,
             data.raw,
             sizeof(data.raw)
         );
 
         // Set advertising type.
         ble.setAdvertisingType(
             GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED
         );
     }
 
 protected:
     BLE &ble;
     Payload data;
 };
 
 /**
  * iBeacon alias.
  *
  * @deprecated Please use iBeacon directly. This alias may be dropped from a
  * future release.
  */
 typedef iBeacon iBeaconService;
 
 BLE_DEPRECATED_API_USE_END()
 
 #endif // BLE_FEATURE_GATT_SERVER
 
 #endif //MBED_BLE_IBEACON_H__
Important Information for this Arm website
