This class implements the Eddystone-URL Config Service and the Eddystone Protocol Specification as defined in the publicly available specification at https://github.com/google/eddystone/blob/master/protocol-specification.md. More...

#include <EddystoneService.h>

Data Structures
struct	EddystoneParams_t
	Structure that encapsulates the Eddystone configuration parameters. More...
Public Types
enum	OperationModes { EDDYSTONE_MODE_NONE, EDDYSTONE_MODE_CONFIG, EDDYSTONE_MODE_BEACON }
	Enumeration that defines the various operation modes of the EddystoneService. More...
enum	EddystoneError_t { EDDYSTONE_ERROR_NONE, EDDYSTONE_ERROR_INVALID_ADVERTISING_INTERVAL, EDDYSTONE_ERROR_INVALID_STATE }
	Enumeration that defines the various error codes for EddystoneService. More...
enum	FrameType { EDDYSTONE_FRAME_URL, EDDYSTONE_FRAME_UID, EDDYSTONE_FRAME_TLM, NUM_EDDYSTONE_FRAMES }
	Enumeration that defines the available frame types within Eddystone advertising packets. More...
Public Member Functions
	EddystoneService (BLE &bleIn, EddystoneParams_t &paramsIn, const PowerLevels_t &radioPowerLevelsIn, events::EventQueue &eventQueue, uint32_t advConfigIntervalIn=DEFAULT_CONFIG_PERIOD_MSEC)
	Constructor that Initializes the EddystoneService using parameters from the supplied EddystoneParams_t.
	EddystoneService (BLE &bleIn, const PowerLevels_t &advPowerLevelsIn, const PowerLevels_t &radioPowerLevelsIn, EventQueue &eventQueue, uint32_t advConfigIntervalIn=DEFAULT_CONFIG_PERIOD_MSEC)
	Constructor to initialize the EddystoneService to default values.
void	onTLMBatteryVoltageUpdate (TlmUpdateCallback_t tlmBatteryVoltageCallbackIn)
	Setup callback to update BatteryVoltage in Eddystone-TLM frames.
void	onTLMBeaconTemperatureUpdate (TlmUpdateCallback_t tlmBeaconTemperatureCallbackIn)
	Setup callback to update BeaconTemperature in Eddystone-TLM frames.
void	setTLMData (uint8_t tlmVersionIn=0)
	Set the Eddystone-TLM frame version.
void	setURLData (const char *urlDataIn)
	Set the Eddystone-URL frame URL data.
void	setUIDData (const UIDNamespaceID_t &uidNamespaceIDIn, const UIDInstanceID_t &uidInstanceIDIn)
	Set the Eddystone-UID namespace and instance IDs.
void	setURLFrameAdvertisingInterval (uint16_t urlFrameIntervalIn=DEFAULT_URL_FRAME_PERIOD_MSEC)
	Set the interval of the Eddystone-URL frames.
void	setUIDFrameAdvertisingInterval (uint16_t uidFrameIntervalIn=DEFAULT_UID_FRAME_PERIOD_MSEC)
	Set the interval of the Eddystone-UID frames.
void	setTLMFrameAdvertisingInterval (uint16_t tlmFrameIntervalIn=DEFAULT_TLM_FRAME_PERIOD_MSEC)
	Set the interval for the Eddystone-TLM frames.
EddystoneError_t	startConfigService (void)
	Change the EddystoneService OperationMode to EDDYSTONE_MODE_CONFIG.
EddystoneError_t	startBeaconService (void)
	Change the EddystoneService OperationMode to EDDYSTONE_MODE_BEACON.
EddystoneError_t	stopCurrentService (void)
	Change the EddystoneService OperationMode to EDDYSTONE_MODE_NONE.
ble_error_t	setCompleteDeviceName (const char *deviceNameIn)
	Set the Comple Local Name for the BLE device.
void	getEddystoneParams (EddystoneParams_t &params)
	Get the Eddystone Configuration parameters.
Static Public Attributes
static const uint16_t	TOTAL_CHARACTERISTICS = 9
	Total number of GATT Characteristics in the Eddystonei-URL Configuration Service.
static const uint32_t	DEFAULT_CONFIG_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_EDDYSTONE_URL_CONFIG_ADV_INTERVAL
	Default interval for advertising packets for the Eddystone-URL Configuration Service.
static const uint16_t	DEFAULT_URL_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_URL_FRAME_INTERVAL
	Recommended interval for advertising packets containing Eddystone URL frames.
static const uint16_t	DEFAULT_UID_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_UID_FRAME_INTERVAL
	Recommended interval for advertising packets containing Eddystone UID frames.
static const uint16_t	DEFAULT_TLM_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_TLM_FRAME_INTERVAL
	Recommended interval for advertising packets containing Eddystone TLM frames.
static const uint16_t	ADV_FRAME_QUEUE_SIZE = NUM_EDDYSTONE_FRAMES
	The size of the advertising frame queue.

Detailed Description

This class implements the Eddystone-URL Config Service and the Eddystone Protocol Specification as defined in the publicly available specification at https://github.com/google/eddystone/blob/master/protocol-specification.md.

Definition at line 56 of file EddystoneService.h.

Member Enumeration Documentation

enum EddystoneError_t

Enumeration that defines the various error codes for EddystoneService.

Enumerator:

EDDYSTONE_ERROR_NONE

No error occurred.

EDDYSTONE_ERROR_INVALID_ADVERTISING_INTERVAL

The supplied advertising interval is invalid.

The interval may be too short/long for the type of advertising packets being broadcast.

Note:

For the acceptable range of advertising interval refer to the following functions in mbed BLE API:

Gap::getMinNonConnectableAdvertisingInterval()
Gap::getMinAdvertisingInterval()
Gap::getMaxAdvertisingInterval()

EDDYSTONE_ERROR_INVALID_STATE

The result of executing a call when the the EddystoneService is in the incorrect operation mode.

Definition at line 220 of file EddystoneService.h.

enum FrameType

Enumeration that defines the available frame types within Eddystone advertising packets.

Enumerator:

EDDYSTONE_FRAME_URL	The Eddystone-URL frame. Refer to https://github.com/google/eddystone/tree/master/eddystone-url.
EDDYSTONE_FRAME_UID	The Eddystone-URL frame. Refer to https://github.com/google/eddystone/tree/master/eddystone-uid.
EDDYSTONE_FRAME_TLM	The Eddystone-URL frame. Refer to https://github.com/google/eddystone/tree/master/eddystone-tlm.
NUM_EDDYSTONE_FRAMES	The total number Eddystone frame types.

Definition at line 247 of file EddystoneService.h.

enum OperationModes

Enumeration that defines the various operation modes of the EddystoneService.

Note:: The main app can change the mode of EddystoneService at any point of time by calling startConfigService() or startBeaconService(). Resources from the previous mode will be freed.; It is currently NOT possible to force EddystoneService back into EDDYSTONE_MODE_NONE.

Enumerator:

EDDYSTONE_MODE_NONE

NONE: EddystoneService has been initialized but no memory has been dynamically allocated.

Additionally, no services are running nothing is being advertised.

EDDYSTONE_MODE_CONFIG

CONFIG: EddystoneService has been initialized, the configuration service started and memory has been allocated for BLE characteristics.

Memory consumption peaks during CONFIG mode.

EDDYSTONE_MODE_BEACON

BEACON: Eddystone service is running as a beacon advertising URL, UID and/or TLM frames depending on how it is configured.

Definition at line 97 of file EddystoneService.h.

Constructor & Destructor Documentation

EddystoneService	(	BLE &	bleIn,
		EddystoneParams_t &	paramsIn,
		const PowerLevels_t &	radioPowerLevelsIn,
		events::EventQueue &	eventQueue,
		uint32_t	advConfigIntervalIn = `DEFAULT_CONFIG_PERIOD_MSEC`
	)

Constructor that Initializes the EddystoneService using parameters from the supplied EddystoneParams_t.

This constructor is particularly useful for configuring the EddystoneService with parameters fetched from persistent storage.

Parameters:

[in]	bleIn	The BLE instance.
[in]	paramIn	The input Eddystone configuration parameters.
[in]	radioPowerLevelsIn	The value set internally into the radion tx power.
[in]	advConfigIntervalIn	The advertising interval for advertising packets of the Eddystone-URL Configuration Service.

EddystoneService	(	BLE &	bleIn,
		const PowerLevels_t &	advPowerLevelsIn,
		const PowerLevels_t &	radioPowerLevelsIn,
		EventQueue &	eventQueue,
		uint32_t	advConfigIntervalIn = `DEFAULT_CONFIG_PERIOD_MSEC`
	)

Constructor to initialize the EddystoneService to default values.

Parameters:

[in]	bleIn	The BLE instance.
[in]	advPowerLevelsIn	The value of the Eddystone-URL Configuration Service TX Power Mode characteristic.
[in]	radioPowerLevelsIn	The value set internally into the radion tx power.
[in]	advConfigIntervalIn	The advertising interval for advertising packets of the Eddystone-URL Configuration Service.

Note:: When using this constructor the setURLData(), setTMLData() and setUIDData() functions must be called to initialize EddystoneService manually.

Definition at line 59 of file EddystoneService.cpp.

Member Function Documentation

void getEddystoneParams ( EddystoneParams_t & params )

Get the Eddystone Configuration parameters.

This is particularly useful for storing the configuration parameters in persistent storage. It is not the responsibility of the Eddystone implementation to store the configured parameters in persistent storage since this is platform-specific.

Parameters:

[out] params A reference to an EddystoneParams_t structure with the configured parameters of the EddystoneService.

Definition at line 227 of file EddystoneService.cpp.

void onTLMBatteryVoltageUpdate ( TlmUpdateCallback_t tlmBatteryVoltageCallbackIn )

Setup callback to update BatteryVoltage in Eddystone-TLM frames.

Parameters:

[in] tlmBatteryVoltageCallbackIn The callback being registered.

Definition at line 94 of file EddystoneService.cpp.

void onTLMBeaconTemperatureUpdate ( TlmUpdateCallback_t tlmBeaconTemperatureCallbackIn )

Setup callback to update BeaconTemperature in Eddystone-TLM frames.

Parameters:

[in] tlmBeaconTemperatureCallbackIn The callback being registered.

Definition at line 100 of file EddystoneService.cpp.

ble_error_t setCompleteDeviceName ( const char * deviceNameIn )

Set the Comple Local Name for the BLE device.

This not only updates the value of the Device Name Characteristic, it also updates the scan response payload if the EddystoneService is currently in EDDYSTONE_MODE_CONFIG.

Parameters:

[in] deviceNameIn A pointer to a null terminated string containing the new device name.

Returns:: BLE_ERROR_NONE if the name was successfully set. Otherwise an appropriate error.

Note:: EddystoneService does not make an internal copy of the string pointed to by deviceNameIn. Therefore, the user is responsible for ensuring that the string persists in memory as long as it is in use by the EddystoneService.; The device name is not considered an Eddystone configuration parameter; therefore, it is not contained within the EddystoneParams_t structure and must be stored to persistent storage separately.

Definition at line 206 of file EddystoneService.cpp.

void setTLMData ( uint8_t tlmVersionIn = 0 )

Set the Eddystone-TLM frame version.

The other components of Eddystone-TLM frames are updated just before the frame is broadcast since information such as beacon temperature and time since boot changes relatively quickly.

Parameters:

[in] tlmVersionIn The Eddyston-TLM version to set.

Definition at line 105 of file EddystoneService.cpp.

void setTLMFrameAdvertisingInterval ( uint16_t tlmFrameIntervalIn = DEFAULT_TLM_FRAME_PERIOD_MSEC )

Set the interval for the Eddystone-TLM frames.

Parameters:

[in] tlmFrameIntervalIn The new frame interval in milliseconds. The default is DEFAULT_TLM_FRAME_PERIOD_MSEC.

Note:: A value of zero desables Eddystone-TLM frames.

Definition at line 809 of file EddystoneService.cpp.

void setUIDData	(	const UIDNamespaceID_t &	uidNamespaceIDIn,
		const UIDInstanceID_t &	uidInstanceIDIn
	)

Set the Eddystone-UID namespace and instance IDs.

Parameters:

[in]	uidNamespaceIDIn	The new Eddystone-UID namespace ID.
[in]	uidInstanceIDIn	The new Eddystone-UID instance ID.

Definition at line 115 of file EddystoneService.cpp.

void setUIDFrameAdvertisingInterval ( uint16_t uidFrameIntervalIn = DEFAULT_UID_FRAME_PERIOD_MSEC )

Set the interval of the Eddystone-UID frames.

Parameters:

[in] uidFrameIntervalIn The new frame interval in milliseconds. The default is DEFAULT_UID_FRAME_PERIOD_MSEC.

Note:: A value of zero disables Eddystone-UID frame transmissions.

Definition at line 771 of file EddystoneService.cpp.

void setURLData ( const char * urlDataIn )

Set the Eddystone-URL frame URL data.

Parameters:

[in] urlDataIn A pointer to the plain null terminated string representing a URL to be encoded.

Definition at line 110 of file EddystoneService.cpp.

void setURLFrameAdvertisingInterval ( uint16_t urlFrameIntervalIn = DEFAULT_URL_FRAME_PERIOD_MSEC )

Set the interval of the Eddystone-URL frames.

Parameters:

[in] urlFrameIntervalIn The new frame interval in milliseconds. The default is DEFAULT_URL_FRAME_PERIOD_MSEC.

Note:: A value of zero disables Eddystone-URL frame transmissions.

Definition at line 732 of file EddystoneService.cpp.

EddystoneService::EddystoneError_t startBeaconService ( void )

Change the EddystoneService OperationMode to EDDYSTONE_MODE_BEACON.

Return values:

EDDYSTONE_ERROR_NONE	if the operation succeeded.
EDDYSONE_ERROR_INVALID_ADVERTISING_INTERVAL	if the configured advertising interval is zero.

Note:: If EddystoneService was previously in EDDYSTONE_MODE_CONFIG, then the resources allocated to that mode of operation such as memory are freed and the BLE instance shutdown before the new operation mode is configured.

Definition at line 148 of file EddystoneService.cpp.

EddystoneService::EddystoneError_t startConfigService ( void )

Change the EddystoneService OperationMode to EDDYSTONE_MODE_CONFIG.

Return values:

EDDYSTONE_ERROR_NONE	if the operation succeeded.
EDDYSONE_ERROR_INVALID_ADVERTISING_INTERVAL	if the configured advertising interval is zero.

Note:: If EddystoneService was previously in EDDYSTONE_MODE_BEACON, then the resources allocated to that mode of operation such as memory are freed and the BLE instance shutdown before the new operation mode is configured.

Definition at line 120 of file EddystoneService.cpp.

EddystoneService::EddystoneError_t stopCurrentService ( void )

Change the EddystoneService OperationMode to EDDYSTONE_MODE_NONE.

Return values:

EDDYSTONE_ERROR_NONE	if the operation succeeded.
EDDYSTONE_ERROR_INVALID_STATE	if the state of the EddystoneService already is EDDYSTONE_MODE_NONE.

Note:: If EddystoneService was previously in EDDYSTONE_MODE_CONFIG or EDDYSTONE_MODE_BEACON, then the resources allocated to that mode of operation such as memory are freed and the BLE instance shutdown before the new operation mode is configured.

Definition at line 178 of file EddystoneService.cpp.

Field Documentation

const uint16_t ADV_FRAME_QUEUE_SIZE = NUM_EDDYSTONE_FRAMES [static]

The size of the advertising frame queue.

Note:: [WARNING] If the advertising rate for any of the frames is higher than 100ms then frames will be dropped, this value must be increased.

Definition at line 276 of file EddystoneService.h.

const uint32_t DEFAULT_CONFIG_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_EDDYSTONE_URL_CONFIG_ADV_INTERVAL [static]

Default interval for advertising packets for the Eddystone-URL Configuration Service.

Definition at line 69 of file EddystoneService.h.

const uint16_t DEFAULT_TLM_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_TLM_FRAME_INTERVAL [static]

Recommended interval for advertising packets containing Eddystone TLM frames.

Definition at line 84 of file EddystoneService.h.

const uint16_t DEFAULT_UID_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_UID_FRAME_INTERVAL [static]

Recommended interval for advertising packets containing Eddystone UID frames.

Definition at line 79 of file EddystoneService.h.

const uint16_t DEFAULT_URL_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_URL_FRAME_INTERVAL [static]

Recommended interval for advertising packets containing Eddystone URL frames.

Definition at line 74 of file EddystoneService.h.

const uint16_t TOTAL_CHARACTERISTICS = 9 [static]

Total number of GATT Characteristics in the Eddystonei-URL Configuration Service.

Definition at line 63 of file EddystoneService.h.

Type:	Library
Created:	28 Jul 2017
Imports:	85
Forks:	0
Commits:	42
Dependents:	0
Dependencies:	0
Followers:	398

EddystoneService Class Reference

Data Structures

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

EddystoneService Class Reference

Data Structures

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning