mirror of https://github.com/ARMmbed/mbed-os.git
BLE: Update iBeacon documentation.
Provide detailled description of the purpose, general concepts and usage.pull/5409/head
Vincent Coubard
parent
20d93bf78d
commit
62e984bdb3
|
|
@ -13,63 +13,228 @@
|
|||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
#ifndef __BLE_IBEACON_H__
|
||||
#define __BLE_IBEACON_H__
|
||||
#ifndef MBED_BLE_IBEACON_H__
|
||||
#define MBED_BLE_IBEACON_H__
|
||||
|
||||
#include "cmsis_compiler.h"
|
||||
#include "ble/BLE.h"
|
||||
|
||||
/**
|
||||
* @class iBeacon
|
||||
* @brief iBeacon Service. This sets up a device to broadcast advertising packets to mimic an iBeacon.
|
||||
*/
|
||||
* iBeacon Service.
|
||||
*
|
||||
* @par Purpose
|
||||
*
|
||||
* iBeacons are Bluetooth Low Energy (BLE) devices advertising an identification
|
||||
* number generally used to identify the location of devices or physical objects
|
||||
* nearby a mobile phone user.
|
||||
*
|
||||
* iOS scans for iBeacon devices in a background task and will notify Apps
|
||||
* subscribed to a specific region when the area is entered or left. Apps may
|
||||
* use this information to display context-aware content to users.
|
||||
*
|
||||
* As an example a museum can deploy an apps which inform the user when one of
|
||||
* its exhibition is enterred then display 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 identify an organization. The region is divided into subregions
|
||||
* identified by a major ID. The subregion may contain related points of
|
||||
* interrest. Finally specific points of interrest within a subregion are
|
||||
* distinguished by a minor ID.
|
||||
*
|
||||
* As an example a city willing to improve tourists 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 something such as a museum, an historic monument or a metro station.
|
||||
* The minor ID would locate a specific spot within the city place. It can be a
|
||||
* piece of art, a ticket dispenser or a relevant point of interrest. Each
|
||||
* iBeacon device is physically attached to the spot it identify and advertise
|
||||
* those three location information.
|
||||
*
|
||||
* @par Proximity
|
||||
*
|
||||
* The beacon advertise the signal strength measured by an iOS device at a
|
||||
* distance of one meter. This information is used by iOS 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 meter away from the user.
|
||||
* - Far: The application is not near the device, distance highly depends on
|
||||
* the physical environment.
|
||||
*
|
||||
* Ideally beacons should be calibrated at there deployment location because the
|
||||
* surrounding environment affect the strength of the advertised signal.
|
||||
*
|
||||
* @par Usage
|
||||
*
|
||||
* Mbed OS applications can use this class to set up a device to broadcast
|
||||
* advertising packets mimicking an iBeacon. The construction will automatically
|
||||
* create the payload identifying the beacon and register it as part of the
|
||||
* advertising payload of the device.
|
||||
*
|
||||
* @important If you are interested in manufacturing iBeacons, you must obtain a
|
||||
* license from Apple. More information at https://developer.apple.com/ibeacon/.
|
||||
* The licence also grant access to the iBeacons technical specification.
|
||||
*
|
||||
* @note More information at https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf
|
||||
*/
|
||||
class iBeacon
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* 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 presents 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;
|
||||
};
|
||||
|
||||
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)
|
||||
/**
|
||||
* 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 amongst others.
|
||||
*
|
||||
* @param[in] majNum Beacon major group ID. iBeacon exploitants may use
|
||||
* this field to divide the region into subregions, their network into
|
||||
* sub networks.
|
||||
*
|
||||
* @param[in] minNum Identifier of the Beacon in its subregion.
|
||||
*
|
||||
* @param[in] transmitPower Measured transmit power of the beacon at 1
|
||||
* meter. This parameter is used by scanners 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));
|
||||
}
|
||||
};
|
||||
|
||||
public:
|
||||
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)
|
||||
/**
|
||||
* 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 amongst others.
|
||||
*
|
||||
* @param[in] majNum Beacon major group ID. iBeacon exploitants may use
|
||||
* this field to divide the region into subregions, their network into
|
||||
* sub networks.
|
||||
*
|
||||
* @param[in] minNum Identifier of the Beacon in its subregion.
|
||||
*
|
||||
* @param[in] txP Measured transmit power of the beacon at 1
|
||||
* meter. This parameter is used by scanners to approximate the distance
|
||||
* to the beacon.
|
||||
*
|
||||
* @param[in] compID ID of the beacon manufacturer.
|
||||
*/
|
||||
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 );
|
||||
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));
|
||||
ble.accumulateAdvertisingPayload(
|
||||
GapAdvertisingData::MANUFACTURER_SPECIFIC_DATA,
|
||||
data.raw,
|
||||
sizeof(data.raw)
|
||||
);
|
||||
|
||||
// Set advertising type.
|
||||
ble.setAdvertisingType(GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED);
|
||||
ble.setAdvertisingType(
|
||||
GapAdvertisingParams::ADV_NON_CONNECTABLE_UNDIRECTED
|
||||
);
|
||||
}
|
||||
|
||||
protected:
|
||||
BLE &ble;
|
||||
Payload data;
|
||||
BLE &ble;
|
||||
Payload data;
|
||||
};
|
||||
|
||||
typedef iBeacon iBeaconService; /* This type-alias is deprecated. Please use iBeacon directly. This alias may be dropped from a future release. */
|
||||
/**
|
||||
* iBeacon alias.
|
||||
*
|
||||
* @deprecated Please use iBeacon directly. This alias may be dropped from a
|
||||
* future release.
|
||||
*/
|
||||
typedef iBeacon iBeaconService;
|
||||
|
||||
#endif //__BLE_IBEACON_H__
|
||||
#endif //MBED_BLE_IBEACON_H__
|
||||
|
|
|
|||
Loading…
Reference in New Issue