Mistake on this page?
Report an issue in GitHub or email us
iBeacon.h
1 /* mbed Microcontroller Library
2 * Copyright (c) 2006-2015 ARM Limited
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 #ifndef MBED_BLE_IBEACON_H__
17 #define MBED_BLE_IBEACON_H__
18 
19 #include "cmsis_compiler.h"
20 #include "ble/BLE.h"
21 
22 #if BLE_FEATURE_GATT_SERVER
23 
24 /**
25  * iBeacon Service.
26  *
27  * @par Purpose
28  *
29  * iBeacons are Bluetooth Low Energy (BLE) devices advertising an identification
30  * number generally used to determine the location of devices or physical objects
31  * near a mobile phone user.
32  *
33  * iOS scans for iBeacon devices in a background task and notifies apps
34  * that subscribe to a specific region when a device enters or leaves an area. Apps may
35  * use this information to display context-aware content to users.
36  *
37  * As an example, a museum can deploy an app that informs the user when one of
38  * its exhibitions is entered and then displays specific information about exposed
39  * pieces of art when the user is sufficiently close to them.
40  *
41  * @par Positioning
42  *
43  * Location information is hierarchically structured. A UUID specific to the
44  * application and its deployment is used to identify a region. That region
45  * usually identifies an organization. The region is divided into subregions
46  * identified by a major ID. The subregion contains related points of interest
47  * which a minor ID distinguishes.
48  *
49  * As an example, a city willing to improve tourist's experience can deploy a fleet
50  * of iBeacons in relevant touristic locations it operates. The UUID may
51  * identify a place managed by the city. The major ID would identify the place;
52  * it can be a museum, a historic monument, a metro station and so on. The minor ID
53  * would identify a specific spot within a specific city place. It can be a
54  * piece of art, a ticket dispenser or a relevant point of interest.
55  *
56  * Each iBeacon device is physically attached to the spot it locates and
57  * advertises the triplet UUID, major ID and minor ID.
58  *
59  * @par Proximity
60  *
61  * The beacon advertises the signal strength measured by an iOS device at a
62  * distance of one meter. iOS uses this information to approximate the
63  * proximity to a given beacon:
64  * - Immediate: The beacon is less than one meter away from the user.
65  * - Near: The beacon is one to three meters away from the user.
66  * - Far: The user is not near the beacon; the distance highly depends on
67  * the physical environment.
68  *
69  * Ideally, beacons should be calibrated at their deployment location because the
70  * surrounding environment affects the strength of the advertised signal.
71  *
72  * @par Usage
73  *
74  * Mbed OS applications can use this class to configure a device to broadcast
75  * advertising packets mimicking an iBeacon. The construction automatically
76  * creates the payload identifying the beacon and registers it as part of the
77  * advertising payload of the device.
78  *
79  * Beacon configuration and advertising commencement is left to the user.
80  *
81  * @attention If you are interested in manufacturing iBeacons, you must obtain a
82  * license from Apple. More information at https://developer.apple.com/ibeacon/.
83  * The license also grant access to the iBeacons technical specification.
84  *
85  * @note More information at https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf
86  *
87  * @deprecated This service is deprecated, and no replacement is currently available.
88  */
90  "mbed-os-5.11",
91  "This service is deprecated, and no replacement is currently available."
92 )
93 class iBeacon {
94 public:
95 #if !(DOXYGEN_ONLY)
96  /**
97  * Data buffer of a location UUID.
98  */
99  typedef const uint8_t LocationUUID_t[16];
100 
101  /**
102  * iBeacon payload builder.
103  *
104  * This data structure contains the payload of an iBeacon. The payload is
105  * built at construction time and application code can set up an iBeacon by
106  * injecting the raw field into the GAP advertising payload as a
107  * GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA.
108  */
109  union Payload {
110  /**
111  * Raw data of the payload.
112  */
113  uint8_t raw[25];
114  struct {
115  /**
116  * Beacon manufacturer identifier.
117  */
118  uint16_t companyID;
119 
120  /**
121  * Packet ID; equal to 2 for an iBeacon.
122  */
123  uint8_t ID;
124 
125  /**
126  * Length of the remaining data present in the payload.
127  */
128  uint8_t len;
129 
130  /**
131  * Beacon UUID.
132  */
133  uint8_t proximityUUID[16];
134 
135  /**
136  * Beacon major group ID.
137  */
138  uint16_t majorNumber;
139 
140  /**
141  * Beacon minor ID.
142  */
143  uint16_t minorNumber;
144 
145  /**
146  * Tx power received at 1 meter; in dBm.
147  */
148  uint8_t txPower;
149  };
150 
151  /**
152  * Assemble an iBeacon payload.
153  *
154  * @param[in] uuid Beacon network ID. iBeacon operators use this value
155  * to group their iBeacons into a single network, a single region, and
156  * identify their organization among others.
157  *
158  * @param[in] majNum Beacon major group ID. iBeacon exploitants may use
159  * this field to divide the region into subregions, and their network into
160  * subnetworks.
161  *
162  * @param[in] minNum Identifier of the Beacon in its subregion.
163  *
164  * @param[in] transmitPower Measured transmit power of the beacon at 1
165  * meter. Scanners use this parameter to approximate the distance
166  * to the beacon.
167  *
168  * @param[in] companyIDIn ID of the beacon manufacturer.
169  */
170  Payload(
171  LocationUUID_t uuid,
172  uint16_t majNum,
173  uint16_t minNum,
174  uint8_t transmitPower,
175  uint16_t companyIDIn
176  ) : companyID(companyIDIn),
177  ID(0x02),
178  len(0x15),
179  majorNumber(__REV16(majNum)),
180  minorNumber(__REV16(minNum)),
181  txPower(transmitPower)
182  {
183  memcpy(proximityUUID, uuid, sizeof(LocationUUID_t));
184  }
185  };
186 #endif //#if !(DOXYGEN_ONLY)
187 public:
188  /**
189  * Construct an iBeacon::Payload and register it into Gap.
190  *
191  * @param[in] _ble The BLE interface to configure with the iBeacon payload.
192  *
193  * @param[in] uuid Beacon network ID. iBeacon operators use this value
194  * to group their iBeacons into a single network, a single region, and
195  * identify their organization among others.
196  *
197  * @param[in] majNum Beacon major group ID. iBeacon fleet operators may use
198  * this field to divide the region into subregions, and their network into
199  * subnetworks.
200  *
201  * @param[in] minNum Identifier of the Beacon in its subregion.
202  *
203  * @param[in] txP Measured transmit power of the beacon at distance of
204  * one meter. Scanners use this parameter to approximate the distance
205  * to the beacon.
206  *
207  * @param[in] compID ID of the beacon manufacturer.
208  *
209  * @deprecated This service is deprecated, and no replacement is currently available.
210  */
212  "mbed-os-5.11",
213  "This service is deprecated, and no replacement is currently available."
214  )
215  iBeacon(
216  BLE &_ble,
217  LocationUUID_t uuid,
218  uint16_t majNum,
219  uint16_t minNum,
220  uint8_t txP = 0xC8,
221  uint16_t compID = 0x004C
222  ) : ble(_ble),
223  data(uuid, majNum, minNum, txP, compID)
224  {
225  // Generate the 0x020106 part of the iBeacon Prefix.
226  ble.accumulateAdvertisingPayload(
229  );
230  // Generate the 0x1AFF part of the iBeacon Prefix.
231  ble.accumulateAdvertisingPayload(
233  data.raw,
234  sizeof(data.raw)
235  );
236 
237  // Set advertising type.
238  ble.setAdvertisingType(
240  );
241  }
242 
243 protected:
244  BLE &ble;
245  Payload data;
246 };
247 
248 /**
249  * iBeacon alias.
250  *
251  * @deprecated Please use iBeacon directly. This alias may be dropped from a
252  * future release.
253  */
254 typedef iBeacon iBeaconService;
255 
256 #endif // BLE_FEATURE_GATT_SERVER
257 
258 #endif //MBED_BLE_IBEACON_H__
Abstract away BLE-capable radio transceivers or SOCs.
Definition: BLE.h:139
Peripheral device is discoverable at any moment.
Peripheral device is LE only and does not support Bluetooth Enhanced DataRate.
Device is not connectable and not scannable.
iBeacon Service.
Definition: iBeacon.h:93
Entry namespace for all BLE API definitions.
Definition: ArrayView.h:37
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.