Skip to content

Commit 7583107

Browse files
theotherjimmytheotherjimmy
authored
Merge pull request #5409 from pan-/fix-ibeacon-doc
BLE: Update iBeacon documentation.
2 parents 49883c3 + 3ad3942 commit 7583107

File tree

1 file changed

+188
-21
lines changed

1 file changed

+188
-21
lines changed

‎features/FEATURE_BLE/ble/services/iBeacon.h

Lines changed: 188 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -13,63 +13,230 @@
1313
* See the License for the specific language governing permissions and
1414
* limitations under the License.
1515
*/
16-
#ifndef __BLE_IBEACON_H__
17-
#define __BLE_IBEACON_H__
16+
#ifndef MBED_BLE_IBEACON_H__
17+
#define MBED_BLE_IBEACON_H__
1818

1919
#include "cmsis_compiler.h"
2020
#include "ble/BLE.h"
2121

2222
/**
23-
* @class iBeacon
24-
* @brief iBeacon Service. This sets up a device to broadcast advertising packets to mimic an iBeacon.
25-
*/
23+
* iBeacon Service.
24+
*
25+
* @par Purpose
26+
*
27+
* iBeacons are Bluetooth Low Energy (BLE) devices advertising an identification
28+
* number generally used to determine the location of devices or physical objects
29+
* near a mobile phone user.
30+
*
31+
* iOS scans for iBeacon devices in a background task and notifies Apps
32+
* subscribed to a specific region when the area is entered or left. Apps may
33+
* use this information to display context-aware content to users.
34+
*
35+
* As an example, a museum can deploy an app that informs the user when one of
36+
* its exhibitions is entered and then displays specific information about exposed
37+
* pieces of art when the user is sufficiently close to them.
38+
*
39+
* @par Positioning
40+
*
41+
* Location information is hierarchically structured. A UUID specific to the
42+
* application and its deployment is used to identify a region. That region
43+
* usually identifies an organization. The region is divided into subregions
44+
* identified by a major ID. The subregion contains related points of interest
45+
* which a minor ID distinguishes.
46+
*
47+
* As an example, a city willing to improve tourist's experience can deploy a fleet
48+
* of iBeacons in relevant touristic locations it operates. The UUID may
49+
* identify a place managed by the city. The major ID would identify the place;
50+
* it can be a museum, a historic monument, a metro station and so on. The minor ID
51+
* would locate a specific spot within a specific city place. It can be a
52+
* piece of art, a ticket dispenser or a relevant point of interest.
53+
*
54+
* Each iBeacon device is physically attached to the spot it locates and
55+
* advertises the triplet UUID, major ID and minor ID.
56+
*
57+
* @par Proximity
58+
*
59+
* The beacon advertises the signal strength measured by an iOS device at a
60+
* distance of one meter. iOS uses this information to approximate the
61+
* proximity to a given beacon:
62+
* - Immediate: The beacon is less than one meter away from the user.
63+
* - Near: The beacon is one to three meters away from the user.
64+
* - Far: The user is not near the beacon; the distance highly depends on
65+
* the physical environment.
66+
*
67+
* Ideally, beacons should be calibrated at their deployment location because the
68+
* surrounding environment affects the strength of the advertised signal.
69+
*
70+
* @par Usage
71+
*
72+
* Mbed OS applications can use this class to configure a device to broadcast
73+
* advertising packets mimicking an iBeacon. The construction automatically
74+
* creates the payload identifying the beacon and registers it as part of the
75+
* advertising payload of the device.
76+
*
77+
* Beacon configuration and advertising commencement is left to the user.
78+
*
79+
* @important If you are interested in manufacturing iBeacons, you must obtain a
80+
* license from Apple. More information at https://developer.apple.com/ibeacon/.
81+
* The licence also grant access to the iBeacons technical specification.
82+
*
83+
* @note More information at https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf
84+
*/
2685
class iBeacon
2786
{
2887
public:
88+
/**
89+
* Data buffer of a location UUID.
90+
*/
2991
typedef const uint8_t LocationUUID_t[16];
3092

93+
/**
94+
* iBeacon payload builder.
95+
*
96+
* This data structure contains the payload of an iBeacon. The payload is
97+
* built at construction time and application code can set up an iBeacon by
98+
* injecting the raw field into the GAP advertising payload as a
99+
* GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA.
100+
*/
31101
union Payload {
102+
/**
103+
* Raw data of the payload.
104+
*/
32105
uint8_t raw[25];
33106
struct {
107+
/**
108+
* Beacon manufacturer identifier.
109+
*/
34110
uint16_t companyID;
111+
112+
/**
113+
* Packet ID; Equal to 2 for an iBeacon.
114+
*/
35115
uint8_t ID;
116+
117+
/**
118+
* Length of the remaining data presents in the payload.
119+
*/
36120
uint8_t len;
121+
122+
/**
123+
* Beacon UUID.
124+
*/
37125
uint8_t proximityUUID[16];
126+
127+
/**
128+
* Beacon Major group ID.
129+
*/
38130
uint16_t majorNumber;
131+
132+
/**
133+
* Beacon minor ID.
134+
*/
39135
uint16_t minorNumber;
136+
137+
/**
138+
* Tx power received at 1 meter; in dBm.
139+
*/
40140
uint8_t txPower;
41141
};
42142

43-
Payload(LocationUUID_t uuid, uint16_t majNum, uint16_t minNum, uint8_t transmitPower, uint16_t companyIDIn) :
44-
companyID(companyIDIn), ID(0x02), len(0x15), majorNumber(__REV16(majNum)), minorNumber(__REV16(minNum)), txPower(transmitPower)
143+
/**
144+
* Assemble an iBeacon payload.
145+
*
146+
* @param[in] uuid Beacon network ID. iBeacon operators use this value
147+
* to group their iBeacons into a single network, a single region and
148+
* identify their organization among others.
149+
*
150+
* @param[in] majNum Beacon major group ID. iBeacon exploitants may use
151+
* this field to divide the region into subregions, their network into
152+
* subnetworks.
153+
*
154+
* @param[in] minNum Identifier of the Beacon in its subregion.
155+
*
156+
* @param[in] transmitPower Measured transmit power of the beacon at 1
157+
* meter. Scanners use this parameter to approximate the distance
158+
* to the beacon.
159+
*
160+
* @param[in] companyIDIn ID of the beacon manufacturer.
161+
*/
162+
Payload(
163+
LocationUUID_t uuid,
164+
uint16_t majNum,
165+
uint16_t minNum,
166+
uint8_t transmitPower,
167+
uint16_t companyIDIn
168+
) : companyID(companyIDIn),
169+
ID(0x02),
170+
len(0x15),
171+
majorNumber(__REV16(majNum)),
172+
minorNumber(__REV16(minNum)),
173+
txPower(transmitPower)
45174
{
46175
memcpy(proximityUUID, uuid, sizeof(LocationUUID_t));
47176
}
48177
};
49178

50179
public:
51-
iBeacon(BLE &_ble,
52-
LocationUUID_t uuid,
53-
uint16_t majNum,
54-
uint16_t minNum,
55-
uint8_t txP = 0xC8,
56-
uint16_t compID = 0x004C) :
57-
ble(_ble), data(uuid, majNum, minNum, txP, compID)
180+
/**
181+
* Construct an iBeacon::Payload and register it into Gap.
182+
*
183+
* @param[in] _ble The BLE interface to configure with the iBeacon payload.
184+
*
185+
* @param[in] uuid Beacon network ID. iBeacon operators use this value
186+
* to group their iBeacons into a single network, a single region and
187+
* identify their organization among others.
188+
*
189+
* @param[in] majNum Beacon major group ID. iBeacon exploitants may use
190+
* this field to divide the region into subregions, their network into
191+
* subnetworks.
192+
*
193+
* @param[in] minNum Identifier of the Beacon in its subregion.
194+
*
195+
* @param[in] txP Measured transmit power of the beacon at 1
196+
* meter. Scanners use this parameter to approximate the distance
197+
* to the beacon.
198+
*
199+
* @param[in] compID ID of the beacon manufacturer.
200+
*/
201+
iBeacon(
202+
BLE &_ble,
203+
LocationUUID_t uuid,
204+
uint16_t majNum,
205+
uint16_t minNum,
206+
uint8_t txP = 0xC8,
207+
uint16_t compID = 0x004C
208+
) : ble(_ble),
209+
data(uuid, majNum, minNum, txP, compID)
58210
{
59211
// Generate the 0x020106 part of the iBeacon Prefix.
60-
ble.accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED | GapAdvertisingData::LE_GENERAL_DISCOVERABLE );
212+
ble.accumulateAdvertisingPayload(
213+
GapAdvertisingData::BREDR_NOT_SUPPORTED |
214+
GapAdvertisingData::LE_GENERAL_DISCOVERABLE
215+
);
61216
// Generate the 0x1AFF part of the iBeacon Prefix.
62-
ble.accumulateAdvertisingPayload(GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA, data.raw, sizeof(data.raw));
217+
ble.accumulateAdvertisingPayload(
218+
GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA,
219+
data.raw,
220+
sizeof(data.raw)
221+
);
63222

64223
// Set advertising type.
65-
ble.setAdvertisingType(GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED);
224+
ble.setAdvertisingType(
225+
GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED
226+
);
66227
}
67228

68229
protected:
69-
BLE &ble;
70-
Payload data;
230+
BLE &ble;
231+
Payload data;
71232
};
72233

73-
typedef iBeacon iBeaconService; /* This type-alias is deprecated. Please use iBeacon directly. This alias may be dropped from a future release. */
234+
/**
235+
* iBeacon alias.
236+
*
237+
* @deprecated Please use iBeacon directly. This alias may be dropped from a
238+
* future release.
239+
*/
240+
typedef iBeacon iBeaconService;
74241

75-
#endif //__BLE_IBEACON_H__
242+
#endif //MBED_BLE_IBEACON_H__

0 commit comments

Comments
 (0)