Microchip® Advanced Software Framework

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.

Eddystone-TLM frame data.

URL configuration service GATT characteristics.

Three Types of Eddystone frames.

Enumerator
EDDYSTONE_UID 
EDDYSTONE_URL 
EDDYSTONE_TLM 

Different modes present in Eddystone application.

Enumerator
EDDYSTONE_IDLE_MODE 
EDDYSTONE_BEACON_MODE 
EDDYSTONE_URL_CONFIG_MODE_ADV 
EDDYSTONE_URL_CONFIG_MODE_CONNECTED 

TX power modes supported.

Enumerator
TX_POWER_MODE_LOWEST 
TX_POWER_MODE_LOW 
TX_POWER_MODE_MEDIUM 
TX_POWER_MODE_HIGH 

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, and es_mode.

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]uidThe 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_msInterval 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, and LOW_BYTE.

at_ble_status_t eddystone_set_encoded_url ( uint8_t *  url_val,
uint8_t  len 
)

Update the Eddystone URL value.

Parameters
[in]url_valPointer to the encoded URL data.
[in]lenNumber 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, 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_modeOne 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, 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_0mCalibrated TX power level at 0 meters which is advertised in the UID frame.
[in]radio_tx_powerRadio 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, and es_mode.

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, and es_mode.

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, and es_url_adv_data.

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_intervalAdvertising 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, 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]servPointer 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, 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().