eddystone.h File Reference

Eddystone Beacons Support.

Copyright (c) 2017-2018 Microchip Technology Inc. and its subsidiaries.

#include "at_ble_api.h"
#include "ble_manager.h"
#include "conf_eddystone.h"

Data Structures
union	beacon_id_t
	Eddystone-UID beacon structure. More...
struct	eddystone_tlm_data_t
	Eddystone-TLM frame data. More...
struct	esurl_conf_gatt_service_t
	URL configuration service GATT characteristics. More...

Macros
#define	EDDYSTONE_16_BIT_UUID   0xFEAA
	16-bit Eddystone Service UUID More...
#define	EDDYSTONE_BEACON_INTERVAL_MS_MAX   (10240)
	Maximum beacon interval in ms (10240ms or 10.24s) More...
#define	EDDYSTONE_BEACON_INTERVAL_MS_MIN   (100)
	Minimum beacon interval in ms (100ms) More...
#define	EDDYSTONE_TLM_FRAME_VERSION   (0x00)
	Version number of the supported TLM frame. More...
#define	EDDYSTONE_TOTAL_TLM_FRAME_LENGTH   (22)
	Total number of bytes for the Eddystone TLM frame. More...
#define	EDDYSTONE_TOTAL_UID_FRAME_LENGTH   (28)
	Total number of bytes for the Eddystone UID frame. More...
#define	EDDYSTONE_URI_DATA_MAX_SIZE   (17 + 1)
	Maximum number of bytes in the encoded URL including the encoded scheme prefix. More...
#define	EDDYSTONE_URI_FLAG   (0x10)
	Value of the URI flag characteristics. More...
#define	EDDYSTONE_URL_CONF_SERVICE_UUID   ("\xd8\x81\xc9\x1a\xb9\x99\x96\xab\xba\x40\x86\x87\x80\x20\x0c\xee")
	Eddystone-URL configuration service defines. More...
#define	ESURL_CONF_ADV_INTERVAL   (160)
	Advertisement interval between 0x0020 and 0x4000 in 0.625ms units [20ms to 10.24s]. More...
#define	ESURL_CONF_ADV_TIMEOUT   (655)
	Advertisement timeout between 0x0001 and 0x3FFF in seconds, 0x0000 disables time-out. More...
#define	FIX88_2_FLOAT(a)   ((float)(a/256.0))
#define	FIX88_2_INT(a)   ((int16_t)((a) >> 8))
#define	FLOAT_2_FIX88(a)   ((int16_t)((a)*256.0))
	Conversion between float and 8:8 fixed point format. More...
#define	INT_2_FIX88(a)   (((int16_t)(a)) << 8)
	Conversion between integer and 8:8 fixed point format. More...

Typedefs
typedef union beacon_id_t	beacon_id_t
	Eddystone-UID beacon structure. More...
typedef struct eddystone_tlm_data_t	eddystone_tlm_data_t
	Eddystone-TLM frame data. More...
typedef struct esurl_conf_gatt_service_t	esurl_conf_gatt_service_t
	URL configuration service GATT characteristics. More...

Enumerations
enum	eddystone_frame_t {   EDDYSTONE_UID = 0x00,   EDDYSTONE_URL = 0x10,   EDDYSTONE_TLM = 0x20 }
	Three Types of Eddystone frames. More...
enum	eddystone_mode_t {   EDDYSTONE_IDLE_MODE = 0x00,   EDDYSTONE_BEACON_MODE,   EDDYSTONE_URL_CONFIG_MODE_ADV,   EDDYSTONE_URL_CONFIG_MODE_CONNECTED }
	Different modes present in Eddystone application. More...
enum	eddystone_tx_power_mode_t {   TX_POWER_MODE_LOWEST = 0x00,   TX_POWER_MODE_LOW,   TX_POWER_MODE_MEDIUM,   TX_POWER_MODE_HIGH }
	TX power modes supported. More...
enum	esurl_conf_serv_characteristic_t {   CHAR_LOCK_STATE = 0x00,   CHAR_LOCK,   CHAR_UNLOCK,   CHAR_URI_DATA,   CHAR_URI_FLAGS,   CHAR_ADV_TX_POWER_LEVELS,   CHAR_TX_POWER_MODE,   CHAR_BEACON_PERIOD,   CHAR_RESET,   ESURL_CONF_CHAR_NUM }
	Different characteristics present in Eddystone URL configuration service. More...

Functions
at_ble_status_t	eddystone_adv_stop (void)
	Stop transmitting Eddystone beacons. More...
eddystone_mode_t	eddystone_get_mode (void)
	Obtain the current mode of the Eddystone beacon. More...
at_ble_status_t	eddystone_init (void)
	Eddystone initialization; all UID and URL data are reset to default values. More...
at_ble_status_t	eddystone_set_beacon_id (beacon_id_t *uid)
	Update the Eddystone-UID (beacon ID). More...
at_ble_status_t	eddystone_set_beacon_interval (uint16_t beacon_interval_ms)
	Update the beacon interval. More...
at_ble_status_t	eddystone_set_encoded_url (uint8_t *url_val, uint8_t len)
	Update the Eddystone URL value. More...
at_ble_status_t	eddystone_set_power_mode (eddystone_tx_power_mode_t tx_power_mode)
	Update the TX power mode to be advertised. More...
at_ble_status_t	eddystone_set_uid_calib_tx_power (int8_t tx_power_0m, at_ble_tx_power_level_t radio_tx_power)
	Update the calibrated TX power value present in the Eddystone-UID frame. More...
at_ble_status_t	eddystone_tlm_frame_send (eddystone_tlm_data_t *tlm_data)
	Start sending Eddystone TLM beacons continuously The TLM frame is created out of battery voltage value, beacon temperature, advertisement PDU count and time since boot up. More...
at_ble_status_t	eddystone_uid_frame_send (void)
	Start sending Eddystone UID beacons continuously The UID frame is created out of parameters like Beacon ID and calibrated tx power at 0m. More...
at_ble_status_t	eddystone_url_frame_send (void)
	Start sending Eddystone URL beacons continuously The URL frame is created out of encoded URL and advertised tx power level at 0m. More...
at_ble_status_t	esurl_conf_adv_start (uint16_t adv_interval)
	Start the Eddystone-URL configuration service. More...
at_ble_status_t	esurl_conf_service_init (esurl_conf_gatt_service_t *serv)
	Eddystone URL Configuration Service and Characteristics initialization. More...

Variables
volatile uint32_t	eddystone_100ms_counter
	100ms counter value used in the creation of TLM frame. More...
const ble_gap_event_cb_t	esurl_conf_gap_cb
	Eddystone GAP events callback handler. More...
const ble_gatt_server_event_cb_t	esurl_conf_gatt_server_cb
	Eddystone GATT server events callback handler. More...
esurl_conf_gatt_service_t	esurl_conf_service
	Eddystone-URL configuration service information. More...

#define EDDYSTONE_16_BIT_UUID   0xFEAA

16-bit Eddystone Service UUID

#define EDDYSTONE_BEACON_INTERVAL_MS_MAX   (10240)

Maximum beacon interval in ms (10240ms or 10.24s)

Referenced by esurl_write_authorize_event().

#define EDDYSTONE_BEACON_INTERVAL_MS_MIN   (100)

Minimum beacon interval in ms (100ms)

Referenced by esurl_write_authorize_event().

#define EDDYSTONE_TLM_FRAME_VERSION   (0x00)

Version number of the supported TLM frame.

Referenced by eddystone_create_tlm_frame().

#define EDDYSTONE_TOTAL_TLM_FRAME_LENGTH   (22)

Total number of bytes for the Eddystone TLM frame.

Referenced by eddystone_adv_start().

#define EDDYSTONE_TOTAL_UID_FRAME_LENGTH   (28)

Total number of bytes for the Eddystone UID frame.

Referenced by eddystone_adv_start().

#define EDDYSTONE_URI_DATA_MAX_SIZE   (17 + 1)

Maximum number of bytes in the encoded URL including the encoded scheme prefix.

Referenced by esurl_conf_service_init().

#define EDDYSTONE_URI_FLAG   (0x10)

Value of the URI flag characteristics.

Referenced by esurl_data_reset().

#define EDDYSTONE_URL_CONF_SERVICE_UUID   ("\xd8\x81\xc9\x1a\xb9\x99\x96\xab\xba\x40\x86\x87\x80\x20\x0c\xee")

Eddystone-URL configuration service defines.

128-bit UUID of the Eddystone-URL configuration service

Referenced by esurl_conf_adv_start(), and esurl_conf_service_init().

#define ESURL_CONF_ADV_INTERVAL   (160)

Advertisement interval between 0x0020 and 0x4000 in 0.625ms units [20ms to 10.24s].

Referenced by eddystone_custom_event().

#define ESURL_CONF_ADV_TIMEOUT   (655)

Advertisement timeout between 0x0001 and 0x3FFF in seconds, 0x0000 disables time-out.

Referenced by esurl_conf_adv_start().

#define FIX88_2_FLOAT

(

a

)

((float)(a/256.0))

#define FIX88_2_INT

(

a

)

((int16_t)((a) >> 8))

#define FLOAT_2_FIX88

(

a

)

((int16_t)((a)*256.0))

Conversion between float and 8:8 fixed point format.

Referenced by read_temperature_fix88().

#define INT_2_FIX88

(

a

)

(((int16_t)(a)) << 8)

Conversion between integer and 8:8 fixed point format.

typedef union beacon_id_t beacon_id_t

Eddystone-UID beacon structure.

typedef struct eddystone_tlm_data_t eddystone_tlm_data_t

Eddystone-TLM frame data.

typedef struct esurl_conf_gatt_service_t esurl_conf_gatt_service_t

URL configuration service GATT characteristics.

enum eddystone_frame_t

Three Types of Eddystone frames.

Enumerator
EDDYSTONE_UID
EDDYSTONE_URL
EDDYSTONE_TLM

enum eddystone_mode_t

Different modes present in Eddystone application.

Enumerator
EDDYSTONE_IDLE_MODE
EDDYSTONE_BEACON_MODE
EDDYSTONE_URL_CONFIG_MODE_ADV
EDDYSTONE_URL_CONFIG_MODE_CONNECTED

enum eddystone_tx_power_mode_t

TX power modes supported.

Enumerator
TX_POWER_MODE_LOWEST
TX_POWER_MODE_LOW
TX_POWER_MODE_MEDIUM
TX_POWER_MODE_HIGH

enum esurl_conf_serv_characteristic_t

Different characteristics present in Eddystone URL configuration service.

Enumerator
CHAR_LOCK_STATE
CHAR_LOCK
CHAR_UNLOCK
CHAR_URI_DATA
CHAR_URI_FLAGS
CHAR_ADV_TX_POWER_LEVELS
CHAR_TX_POWER_MODE
CHAR_BEACON_PERIOD
CHAR_RESET
ESURL_CONF_CHAR_NUM

at_ble_status_t eddystone_adv_stop

(

void

)

Stop transmitting Eddystone beacons.

Returns

AT_BLE_SUCCESS Stopped beacons successfully.

at_ble_status_t Failed to stop beacon transmissions.

Stop transmitting Eddystone beacons.

References at_ble_adv_stop(), AT_BLE_FAILURE, AT_BLE_SUCCESS, eddystone_adv_enabled, EDDYSTONE_IDLE_MODE, es_mode, and status.

Referenced by eddystone_tlm_frame_send(), eddystone_uid_frame_send(), eddystone_url_frame_send(), and esurl_conf_adv_start().

eddystone_mode_t eddystone_get_mode

(

void

)

Obtain the current mode of the Eddystone beacon.

Returns

eddystone_mode_t Returns one of the three modes in which the beacon operates.

Obtain the current mode of the Eddystone beacon.

References es_mode.

Referenced by eddystone_custom_event(), and main().

at_ble_status_t eddystone_init

(

void

)

Eddystone initialization; all UID and URL data are reset to default values.

Returns

AT_BLE_SUCCESS Initialized successfully.

AT_BLE_FAILURE Error in initialization.

Eddystone initialization; all UID and URL data are reset to default values.

References AT_BLE_SUCCESS, esuid_data_reset(), and esurl_data_reset().

Referenced by eddystone_app_init().

at_ble_status_t eddystone_set_beacon_id

(

beacon_id_t *

uid

)

Update the Eddystone-UID (beacon ID).

Parameters

[in]

uid

The 16-byte UID value to be set; It must be in big endian format. UID consists of 10-byte Namespace ID and 6-byte Instance ID.

Returns

AT_BLE_SUCCESS Updated the beacon ID successfully.

AT_BLE_FAILURE Failed to set the beacon ID.

Update the Eddystone-UID (beacon ID).

References AT_BLE_SUCCESS, esuid_data_t::beacon_id, beacon_id_t::instance_id, and beacon_id_t::namespace_id.

at_ble_status_t eddystone_set_beacon_interval

(

uint16_t

beacon_interval_ms

)

Update the beacon interval.

This update requires a restart of the Eddystone frames to use this new beacon interval value.

Parameters

[in]

beacon_interval_ms

Interval period in ms [100ms to 10240ms]

Returns

AT_BLE_SUCCESS Updated the beacon interval successfully.

AT_BLE_FAILURE Failed to set the beacon interval.

Update the beacon interval.

Restart sending the Eddystone frames to use the updated beacon interval

References at_ble_characteristic_value_set(), AT_BLE_FAILURE, esurl_data_t::beacon_period, CHAR_BEACON_PERIOD, at_ble_characteristic_t::char_val_handle, esurl_conf_gatt_service_t::chars, esurl_conf_char_initialized, HIGH_BYTE, LOW_BYTE, and status.

at_ble_status_t eddystone_set_encoded_url	(	uint8_t *	url_val,
		uint8_t	len
	)

Update the Eddystone URL value.

Parameters

[in]	url_val	Pointer to the encoded URL data.
[in]	len	Number of bytes in the URL data.

Returns

AT_BLE_SUCCESS Updated URL value successfully

AT_BLE_FAILURE Failed to update the URL value.

Update the Eddystone URL value.

References at_ble_characteristic_value_set(), AT_BLE_FAILURE, CHAR_URI_DATA, at_ble_characteristic_t::char_val_handle, esurl_conf_gatt_service_t::chars, EDDYSTONE_MAX_URL_ENC_LEN, esurl_conf_char_initialized, len, esurl_data_t::uri_data, and esurl_data_t::uri_len.

at_ble_status_t eddystone_set_power_mode

(

eddystone_tx_power_mode_t

tx_power_mode

)

Update the TX power mode to be advertised.

This change in TX power mode will set the radio TX power accordingly.

Parameters

[in]

tx_power_mode

One of the four power modes supported by Eddystone (eddystone_tx_power_mode_t)

Returns

AT_BLE_SUCCESS Updated TX power mode successfully.

AT_BLE_FAILURE Failed to update the TX power mode.

Update the TX power mode to be advertised.

References at_ble_characteristic_value_set(), AT_BLE_FAILURE, CHAR_TX_POWER_MODE, at_ble_characteristic_t::char_val_handle, esurl_conf_gatt_service_t::chars, esurl_conf_char_initialized, status, and esurl_data_t::tx_power_mode.

at_ble_status_t eddystone_set_uid_calib_tx_power	(	int8_t	tx_power_0m,
		at_ble_tx_power_level_t	radio_tx_power
	)

Update the calibrated TX power value present in the Eddystone-UID frame.

Parameters

[in]	tx_power_0m	Calibrated TX power level at 0 meters which is advertised in the UID frame.
[in]	radio_tx_power	Radio TX power to be set in the BLE device to achieve the advertised TX power at 0 meters.

Returns

AT_BLE_SUCCESS Updated the TX power levels successfully.

AT_BLE_FAILURE Failed to update the TX power levels.

Update the calibrated TX power value present in the Eddystone-UID frame.

References AT_BLE_SUCCESS, esuid_data_t::radio_tx_power, and esuid_data_t::tx_power_0m.

at_ble_status_t eddystone_tlm_frame_send

(

eddystone_tlm_data_t *

tlm_data

)

Start sending Eddystone TLM beacons continuously The TLM frame is created out of battery voltage value, beacon temperature, advertisement PDU count and time since boot up.

Returns

AT_BLE_SUCCESS Successfully started TLM frames.

at_ble_status_t Failed to start the beacons.

Start sending Eddystone TLM beacons continuously The TLM frame is created out of battery voltage value, beacon temperature, advertisement PDU count and time since boot up.

References AT_BLE_SUCCESS, eddystone_adv_start(), eddystone_adv_stop(), eddystone_create_tlm_frame(), EDDYSTONE_URL_CONFIG_MODE_ADV, es_adv_data, es_mode, and status.

Referenced by main().

at_ble_status_t eddystone_uid_frame_send

(

void

)

Start sending Eddystone UID beacons continuously The UID frame is created out of parameters like Beacon ID and calibrated tx power at 0m.

Returns

AT_BLE_SUCCESS Successfully started UID beacons.

at_ble_status_t Failed to start the beacons.

Start sending Eddystone UID beacons continuously The UID frame is created out of parameters like Beacon ID and calibrated tx power at 0m.

References AT_BLE_SUCCESS, eddystone_adv_start(), eddystone_adv_stop(), eddystone_create_uid_frame(), EDDYSTONE_URL_CONFIG_MODE_ADV, es_adv_data, es_mode, and status.

Referenced by eddystone_app_init(), and main().

at_ble_status_t eddystone_url_frame_send

(

void

)

Start sending Eddystone URL beacons continuously The URL frame is created out of encoded URL and advertised tx power level at 0m.

Returns

AT_BLE_SUCCESS Successfully started URL beacons.

at_ble_status_t Failed to start the beacons.

Start sending Eddystone URL beacons continuously The URL frame is created out of encoded URL and advertised tx power level at 0m.

References at_ble_disconnect(), AT_BLE_SUCCESS, AT_BLE_TERMINATED_BY_USER, eddystone_adv_start(), eddystone_adv_stop(), eddystone_create_url_frame(), EDDYSTONE_URL_CONFIG_MODE_ADV, EDDYSTONE_URL_CONFIG_MODE_CONNECTED, es_conf_conn_handle, es_mode, es_url_adv_data, and status.

Referenced by eddystone_app_init(), eddystone_custom_event(), esurl_dev_disconnected_event(), and main().

at_ble_status_t esurl_conf_adv_start

(

uint16_t

adv_interval

)

Start the Eddystone-URL configuration service.

It starts the advertisement enabling any Central device to connect to the service.

Parameters

[in]

adv_interval

Advertising interval between AT_BLE_ADV_INTERVAL_MIN and AT_BLE_ADV_INTERVAL_MAX in 0.625 ms units (20ms to 10.24s).

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t.

Start the Eddystone-URL configuration service.

References esurl_data_t::adv_tx_power_level, ADV_TYPE_SIZE, at_ble_adv_data_set(), AT_BLE_ADV_FP_ANY, AT_BLE_ADV_GEN_DISCOVERABLE, at_ble_adv_start(), AT_BLE_ADV_TYPE_UNDIRECTED, AT_BLE_SUCCESS, at_ble_tx_power_set(), AT_BLE_UUID_128_LEN, COMPLETE_LIST_128BIT_SERV_UUIDS, COMPLETE_LOCAL_NAME, CONF_ES_CONF_ADV_DATA_COMPLETE_LOCAL_NAME, eddystone_adv_enabled, eddystone_adv_stop(), EDDYSTONE_URL_CONF_SERVICE_UUID, EDDYSTONE_URL_CONFIG_MODE_ADV, es_adv_data, es_mode, es_scan_data, ESURL_CONF_ADV_TIMEOUT, NULL, esurl_data_t::radio_tx_power_level, status, TX_POWER_LEVEL, TX_POWER_LEVEL_SIZE, and TX_POWER_MODE_MEDIUM.

Referenced by eddystone_custom_event().

at_ble_status_t esurl_conf_service_init

(

esurl_conf_gatt_service_t *

serv

)

Eddystone URL Configuration Service and Characteristics initialization.

It initializes the given service structure with required default values and registers it with the BLE stack. This configuration service should be used only when Eddystone-URL beacons are used. (Must be called only once by the user.)

Parameters

[in]

serv

Pointer to store Eddystone configuration service information.

Returns

Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t.

Eddystone URL Configuration Service and Characteristics initialization.

References esurl_data_t::adv_tx_power_level, AT_BLE_ATTR_NO_PERMISSIONS, AT_BLE_ATTR_READABLE_NO_AUTHN_NO_AUTHR, AT_BLE_ATTR_READABLE_REQ_AUTHN_NO_AUTHR, AT_BLE_ATTR_WRITABLE_NO_AUTHN_REQ_AUTHR, AT_BLE_ATTR_WRITABLE_REQ_AUTHN_REQ_AUTHR, AT_BLE_CHAR_READ, AT_BLE_CHAR_WRITE, at_ble_primary_service_define(), AT_BLE_SUCCESS, AT_BLE_UUID_128, AT_BLE_UUID_128_LEN, esurl_data_t::beacon_period, BLE_PAIR_ENABLE, CHAR_ADV_TX_POWER_LEVELS, CHAR_BEACON_PERIOD, CHAR_LOCK, CHAR_LOCK_STATE, CHAR_RESET, CHAR_TX_POWER_MODE, CHAR_UNLOCK, CHAR_URI_DATA, CHAR_URI_FLAGS, at_ble_characteristic_t::char_val_handle, esurl_conf_gatt_service_t::chars, at_ble_characteristic_t::client_config_handle, at_ble_characteristic_t::client_config_permissions, CONF_ES_DEFAULT_URL_SIZE, EDDYSTONE_TX_POWER_MODES_NUM, EDDYSTONE_URI_DATA_MAX_SIZE, EDDYSTONE_URL_CONF_SERVICE_UUID, esurl_conf_char_initialized, ESURL_CONF_CHAR_NUM, ESURL_CONF_CHAR_UUID_DIFF_OFFSET, esurl_data_reset(), ESURL_LOCK_CODE_MAX_SIZE, esurl_conf_gatt_service_t::handle, at_ble_characteristic_t::init_value, esurl_data_t::lock_code, esurl_data_t::lock_code_len, esurl_data_t::lock_state, NULL, at_ble_characteristic_t::presentation_format, at_ble_characteristic_t::properties, at_ble_characteristic_t::server_config_handle, at_ble_characteristic_t::server_config_permissions, status, esurl_data_t::tx_power_mode, at_ble_uuid_t::type, esurl_data_t::uri_data, esurl_data_t::uri_flags, at_ble_characteristic_t::user_desc, at_ble_characteristic_t::user_desc_handle, at_ble_characteristic_t::user_desc_len, at_ble_characteristic_t::user_desc_max_len, at_ble_characteristic_t::user_desc_permissions, esurl_conf_gatt_service_t::uuid, at_ble_uuid_t::uuid, at_ble_characteristic_t::uuid, UUID_CHAR_ADV_TX_POWER, UUID_CHAR_BEACON_PERIOD, UUID_CHAR_FLAGS, UUID_CHAR_LOCK, UUID_CHAR_LOCK_STATE, UUID_CHAR_RESET, UUID_CHAR_TX_POWER_MODE, UUID_CHAR_UNLOCK, UUID_CHAR_URI_DATA, at_ble_characteristic_t::value_init_len, at_ble_characteristic_t::value_max_len, and at_ble_characteristic_t::value_permissions.

Referenced by eddystone_app_init().

volatile uint32_t eddystone_100ms_counter

100ms counter value used in the creation of TLM frame.

This counter variable needs to be updated by the application for every 100ms

Referenced by eddystone_create_tlm_frame(), and timer_callback_handler().

const ble_gap_event_cb_t esurl_conf_gap_cb

Eddystone GAP events callback handler.

Eddystone GAP events callback handler.

Referenced by eddystone_app_init().

const ble_gatt_server_event_cb_t esurl_conf_gatt_server_cb

Eddystone GATT server events callback handler.

Eddystone GATT server events callback handler.

Referenced by eddystone_app_init().

esurl_conf_gatt_service_t esurl_conf_service

Eddystone-URL configuration service information.

Referenced by eddystone_app_init().