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