EddystoneService.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __EDDYSTONESERVICE_H__
00018 #define __EDDYSTONESERVICE_H__
00019 
00020 #include <events/mbed_events.h>
00021 #include "ble/BLE.h"
00022 #include "EddystoneTypes.h"
00023 #include "URLFrame.h"
00024 #include "UIDFrame.h"
00025 #include "TLMFrame.h"
00026 #include <string.h>
00027 #ifdef YOTTA_CFG_MBED_OS
00028     #include <mbed.h>
00029     #include "mbed-drivers/CircularBuffer.h"
00030 #else
00031     #include "mbed.h"
00032     #include "CircularBuffer.h"
00033 #endif
00034 
00035 #ifndef YOTTA_CFG_EDDYSTONE_DEFAULT_URL_FRAME_INTERVAL
00036     #define YOTTA_CFG_EDDYSTONE_DEFAULT_URL_FRAME_INTERVAL 700
00037 #endif
00038 
00039 #ifndef YOTTA_CFG_EDDYSTONE_DEFAULT_UID_FRAME_INTERVAL
00040     #define YOTTA_CFG_EDDYSTONE_DEFAULT_UID_FRAME_INTERVAL 300
00041 #endif
00042 
00043 #ifndef YOTTA_CFG_EDDYSTONE_DEFAULT_TLM_FRAME_INTERVAL
00044     #define YOTTA_CFG_EDDYSTONE_DEFAULT_TLM_FRAME_INTERVAL 2000
00045 #endif
00046 
00047 #ifndef YOTTA_CFG_EDDYSTONE_DEFAULT_EDDYSTONE_URL_CONFIG_ADV_INTERVAL
00048     #define YOTTA_CFG_EDDYSTONE_DEFAULT_EDDYSTONE_URL_CONFIG_ADV_INTERVAL 1000
00049 #endif
00050 
00051 /**
00052  * This class implements the Eddystone-URL Config Service and the Eddystone
00053  * Protocol Specification as defined in the publicly available specification at
00054  * https://github.com/google/eddystone/blob/master/protocol-specification.md.
00055  */
00056 class EddystoneService
00057 {
00058 public:
00059     /**
00060      * Total number of GATT Characteristics in the Eddystonei-URL Configuration
00061      * Service.
00062      */
00063     static const uint16_t TOTAL_CHARACTERISTICS = 9;
00064 
00065     /**
00066      * Default interval for advertising packets for the Eddystone-URL
00067      * Configuration Service.
00068      */
00069     static const uint32_t DEFAULT_CONFIG_PERIOD_MSEC    = YOTTA_CFG_EDDYSTONE_DEFAULT_EDDYSTONE_URL_CONFIG_ADV_INTERVAL;
00070     /**
00071      * Recommended interval for advertising packets containing Eddystone URL
00072      * frames.
00073      */
00074     static const uint16_t DEFAULT_URL_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_URL_FRAME_INTERVAL;
00075     /**
00076      * Recommended interval for advertising packets containing Eddystone UID
00077      * frames.
00078      */
00079     static const uint16_t DEFAULT_UID_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_UID_FRAME_INTERVAL;
00080     /**
00081      * Recommended interval for advertising packets containing Eddystone TLM
00082      * frames.
00083      */
00084     static const uint16_t DEFAULT_TLM_FRAME_PERIOD_MSEC = YOTTA_CFG_EDDYSTONE_DEFAULT_TLM_FRAME_INTERVAL;
00085 
00086     /**
00087      * Enumeration that defines the various operation modes of the
00088      * EddystoneService.
00089      *
00090      * @note The main app can change the mode of EddystoneService at any point
00091      *       of time by calling startConfigService() or startBeaconService().
00092      *       Resources from the previous mode will be freed.
00093      *
00094      * @note It is currently NOT possible to force EddystoneService back into
00095      *       EDDYSTONE_MODE_NONE.
00096      */
00097     enum OperationModes {
00098         /**
00099          * NONE: EddystoneService has been initialized but no memory has been
00100          * dynamically allocated. Additionally, no services are running
00101          * nothing is being advertised.
00102          */
00103         EDDYSTONE_MODE_NONE,
00104         /**
00105          * CONFIG: EddystoneService has been initialized, the configuration
00106          *         service started and memory has been allocated for BLE
00107          *         characteristics. Memory consumption peaks during CONFIG
00108          *         mode.
00109          */
00110         EDDYSTONE_MODE_CONFIG,
00111         /**
00112          * BEACON: Eddystone service is running as a beacon advertising URL,
00113          *         UID and/or TLM frames depending on how it is configured.
00114          */
00115         EDDYSTONE_MODE_BEACON
00116     };
00117 
00118     /**
00119      * Structure that encapsulates the Eddystone configuration parameters. This
00120      * structure is particularly useful when storing the parameters to
00121      * persistent storage.
00122      */
00123     struct EddystoneParams_t {
00124         /**
00125          * The value of the Eddystone-URL Configuration Service Lock State
00126          * characteristic.
00127          */
00128         bool             lockState;
00129         /**
00130          * The value of the Eddystone-URL Configuration Service Lock
00131          * characteristic that can be used to lock the beacon and set the
00132          * single-use lock-code.
00133          */
00134         Lock_t           lock;
00135         /**
00136          * The value of the Eddystone-URL Configuration Service Unlock
00137          * characteristic that can be used to unlock the beacon and clear the
00138          * single-use lock-code.
00139          */
00140         Lock_t           unlock;
00141         /**
00142          * The value of the Eddystone-URL Configuration Service Flags
00143          * characteristic. This value is currently fixed to 0x10.
00144          */
00145         uint8_t          flags;
00146         /**
00147          * The value of the Eddystone-URL Configuration Service Advertised TX
00148          * Power Levels characteristic that is an array of bytes whose values
00149          * are put into the advertising packets when in EDDYSTONE_BEACON_MODE.
00150          *
00151          * @note These are not the same values set internally into the radio tx
00152          *       power.
00153          */
00154         PowerLevels_t    advPowerLevels;
00155         /**
00156          * The value of the Eddystone-URL Configuration Service TX Power Mode
00157          * characteristic. This value is an index into the
00158          * EddystoneParams_t::advPowerLevels array.
00159          */
00160         uint8_t          txPowerMode;
00161         /**
00162          * The value of the Eddystone-URL Configuration Service Beacon Period
00163          * characteristic that is the interval (in milliseconds) of the
00164          * Eddystone-URL frames.
00165          *
00166          * @note A value of zero disables Eddystone-URL frame trasmissions.
00167          */
00168         uint16_t         urlFramePeriod;
00169         /**
00170          * The configured interval (in milliseconds) of the Eddystone-UID
00171          * frames.
00172          *
00173          * @note A value of zero disables Eddystone-UID frame transmissions.
00174          *
00175          * @note Currently it is only possible to modify this value by using
00176          *       the setUIDFrameAdvertisingInterval() API.
00177          */
00178         uint16_t         uidFramePeriod;
00179         /**
00180          * The configured interval (in milliseconds) of the Eddystone-TLM
00181          * frames.
00182          *
00183          * @note A value of zero disables Eddystone-TLM frame transmissions.
00184          *
00185          * @note Currently it is only possible to modify this value by using
00186          *       the setTLMFrameAdvertisingInterval() API.
00187          */
00188         uint16_t         tlmFramePeriod;
00189         /**
00190          * The configured version of the Eddystone-TLM frames.
00191          */
00192         uint8_t          tlmVersion;
00193         /**
00194          * The length of the encoded URL in EddystoneParams_t::urlData used
00195          * within Eddystone-URL frames.
00196          */
00197         uint8_t          urlDataLength;
00198         /**
00199          * The value of the Eddystone-URL Configuration Service URI Data
00200          * characteristic that contains an encoded URL as described in the
00201          * Eddystone Specification at
00202          * https://github.com/google/eddystone/blob/master/eddystone-url/README.md#eddystone-url-http-url-encoding.
00203          */
00204         UrlData_t        urlData;
00205         /**
00206          * The configured 10-byte namespace ID in Eddystone-UID frames that may
00207          * be used to group a particular set of beacons.
00208          */
00209         UIDNamespaceID_t uidNamespaceID;
00210         /**
00211          * The configured 6-byte instance ID that may be used to uniquely
00212          * identify individual devices in a group.
00213          */
00214         UIDInstanceID_t  uidInstanceID;
00215     };
00216 
00217     /**
00218      * Enumeration that defines the various error codes for EddystoneService.
00219      */
00220     enum EddystoneError_t {
00221         /**
00222          * No error occurred.
00223          */
00224         EDDYSTONE_ERROR_NONE,
00225         /**
00226          * The supplied advertising interval is invalid. The interval may be
00227          * too short/long for the type of advertising packets being broadcast.
00228          *
00229          * @note For the acceptable range of advertising interval refer to the
00230          *       following functions in mbed BLE API:
00231          *       - Gap::getMinNonConnectableAdvertisingInterval()
00232          *       - Gap::getMinAdvertisingInterval()
00233          *       - Gap::getMaxAdvertisingInterval()
00234          */
00235         EDDYSTONE_ERROR_INVALID_ADVERTISING_INTERVAL,
00236         /**
00237          * The result of executing a call when the the EddystoneService is in
00238          * the incorrect operation mode.
00239          */
00240         EDDYSTONE_ERROR_INVALID_STATE
00241     };
00242 
00243     /**
00244      * Enumeration that defines the available frame types within Eddystone
00245      * advertising packets.
00246      */
00247     enum FrameType {
00248         /**
00249          * The Eddystone-URL frame. Refer to
00250          * https://github.com/google/eddystone/tree/master/eddystone-url.
00251          */
00252         EDDYSTONE_FRAME_URL,
00253         /**
00254          * The Eddystone-URL frame. Refer to
00255          * https://github.com/google/eddystone/tree/master/eddystone-uid.
00256          */
00257         EDDYSTONE_FRAME_UID,
00258         /**
00259          * The Eddystone-URL frame. Refer to
00260          * https://github.com/google/eddystone/tree/master/eddystone-tlm.
00261          */
00262         EDDYSTONE_FRAME_TLM,
00263         /**
00264          * The total number Eddystone frame types.
00265          */
00266         NUM_EDDYSTONE_FRAMES
00267     };
00268 
00269     /**
00270      * The size of the advertising frame queue.
00271      *
00272      * @note [WARNING] If the advertising rate for any of the frames is higher
00273      *       than 100ms then frames will be dropped, this value must be
00274      *       increased.
00275      */
00276     static const uint16_t ADV_FRAME_QUEUE_SIZE = NUM_EDDYSTONE_FRAMES;
00277 
00278 
00279     /**
00280      * Constructor that Initializes the EddystoneService using parameters from
00281      * the supplied EddystoneParams_t. This constructor is particularly useful
00282      * for configuring the EddystoneService with parameters fetched from
00283      * persistent storage.
00284      *
00285      * @param[in] bleIn
00286      *              The BLE instance.
00287      * @param[in] paramIn
00288      *              The input Eddystone configuration parameters.
00289      * @param[in] radioPowerLevelsIn
00290      *              The value set internally into the radion tx power.
00291      * @param[in] advConfigIntervalIn
00292      *              The advertising interval for advertising packets of the
00293      *              Eddystone-URL Configuration Service.
00294      */
00295     EddystoneService(BLE                 &bleIn,
00296                      EddystoneParams_t   &paramsIn,
00297                      const PowerLevels_t &radioPowerLevelsIn,
00298                      events::EventQueue& eventQueue,
00299                      uint32_t            advConfigIntervalIn = DEFAULT_CONFIG_PERIOD_MSEC);
00300 
00301     /**
00302      * Constructor to initialize the EddystoneService to default values.
00303      *
00304      * @param[in] bleIn
00305      *              The BLE instance.
00306      * @param[in] advPowerLevelsIn
00307      *              The value of the Eddystone-URL Configuration Service TX
00308      *              Power Mode characteristic.
00309      * @param[in] radioPowerLevelsIn
00310      *              The value set internally into the radion tx power.
00311      * @param[in] advConfigIntervalIn
00312      *              The advertising interval for advertising packets of the
00313      *              Eddystone-URL Configuration Service.
00314      *
00315      * @note When using this constructor the setURLData(), setTMLData() and
00316      *       setUIDData() functions must be called to initialize
00317      *       EddystoneService manually.
00318      */
00319     EddystoneService(BLE                 &bleIn,
00320                      const PowerLevels_t &advPowerLevelsIn,
00321                      const PowerLevels_t &radioPowerLevelsIn,
00322                      EventQueue          &eventQueue,
00323                      uint32_t            advConfigIntervalIn = DEFAULT_CONFIG_PERIOD_MSEC);
00324 
00325     /**
00326      * Setup callback to update BatteryVoltage in Eddystone-TLM frames
00327      *
00328      * @param[in] tlmBatteryVoltageCallbackIn
00329      *              The callback being registered.
00330      */
00331     void onTLMBatteryVoltageUpdate(TlmUpdateCallback_t tlmBatteryVoltageCallbackIn);
00332 
00333     /**
00334      * Setup callback to update BeaconTemperature in Eddystone-TLM frames
00335      *
00336      * @param[in] tlmBeaconTemperatureCallbackIn
00337      *              The callback being registered.
00338      */
00339     void onTLMBeaconTemperatureUpdate(TlmUpdateCallback_t tlmBeaconTemperatureCallbackIn);
00340 
00341     /**
00342      * Set the Eddystone-TLM frame version. The other components of
00343      * Eddystone-TLM frames are updated just before the frame is broadcast
00344      * since information such as beacon temperature and time since boot changes
00345      * relatively quickly.
00346      *
00347      * @param[in] tlmVersionIn
00348      *              The Eddyston-TLM version to set.
00349      */
00350     void setTLMData(uint8_t tlmVersionIn = 0);
00351 
00352     /**
00353      * Set the Eddystone-URL frame URL data.
00354      *
00355      * @param[in] urlDataIn
00356      *              A pointer to the plain null terminated string representing
00357      *              a URL to be encoded.
00358      */
00359     void setURLData(const char *urlDataIn);
00360 
00361     /**
00362      * Set the Eddystone-UID namespace and instance IDs.
00363      *
00364      * @param[in] uidNamespaceIDIn
00365      *              The new Eddystone-UID namespace ID.
00366      * @param[in] uidInstanceIDIn
00367      *              The new Eddystone-UID instance ID.
00368      */
00369     void setUIDData(const UIDNamespaceID_t &uidNamespaceIDIn, const UIDInstanceID_t &uidInstanceIDIn);
00370 
00371     /**
00372      * Set the interval of the Eddystone-URL frames.
00373      *
00374      * @param[in] urlFrameIntervalIn
00375      *              The new frame interval in milliseconds. The default is
00376      *              DEFAULT_URL_FRAME_PERIOD_MSEC.
00377      *
00378      * @note A value of zero disables Eddystone-URL frame transmissions.
00379      */
00380     void setURLFrameAdvertisingInterval(uint16_t urlFrameIntervalIn = DEFAULT_URL_FRAME_PERIOD_MSEC);
00381 
00382     /**
00383      * Set the interval of the Eddystone-UID frames.
00384      *
00385      * @param[in] uidFrameIntervalIn
00386      *              The new frame interval in milliseconds. The default is
00387      *              DEFAULT_UID_FRAME_PERIOD_MSEC.
00388      *
00389      * @note A value of zero disables Eddystone-UID frame transmissions.
00390      */
00391     void setUIDFrameAdvertisingInterval(uint16_t uidFrameIntervalIn = DEFAULT_UID_FRAME_PERIOD_MSEC);
00392 
00393     /**
00394      * Set the interval for the Eddystone-TLM frames.
00395      *
00396      * @param[in] tlmFrameIntervalIn
00397      *              The new frame interval in milliseconds. The default is
00398      *              DEFAULT_TLM_FRAME_PERIOD_MSEC.
00399      *
00400      * @note A value of zero desables Eddystone-TLM frames.
00401      */
00402     void setTLMFrameAdvertisingInterval(uint16_t tlmFrameIntervalIn = DEFAULT_TLM_FRAME_PERIOD_MSEC);
00403 
00404     /**
00405      * Change the EddystoneService OperationMode to EDDYSTONE_MODE_CONFIG.
00406      *
00407      * @retval EDDYSTONE_ERROR_NONE if the operation succeeded.
00408      * @retval EDDYSONE_ERROR_INVALID_ADVERTISING_INTERVAL if the configured
00409      *         advertising interval is zero.
00410      *
00411      * @note If EddystoneService was previously in EDDYSTONE_MODE_BEACON, then
00412      *       the resources allocated to that mode of operation such as memory
00413      *       are freed and the BLE instance shutdown before the new operation
00414      *       mode is configured.
00415      */
00416     EddystoneError_t startConfigService(void);
00417 
00418     /**
00419      * Change the EddystoneService OperationMode to EDDYSTONE_MODE_BEACON.
00420      *
00421      * @retval EDDYSTONE_ERROR_NONE if the operation succeeded.
00422      * @retval EDDYSONE_ERROR_INVALID_ADVERTISING_INTERVAL if the configured
00423      *         advertising interval is zero.
00424      *
00425      * @note If EddystoneService was previously in EDDYSTONE_MODE_CONFIG, then
00426      *       the resources allocated to that mode of operation such as memory
00427      *       are freed and the BLE instance shutdown before the new operation
00428      *       mode is configured.
00429      */
00430     EddystoneError_t startBeaconService(void);
00431 
00432     /**
00433      * Change the EddystoneService OperationMode to EDDYSTONE_MODE_NONE.
00434      *
00435      * @retval EDDYSTONE_ERROR_NONE if the operation succeeded.
00436      * @retval EDDYSTONE_ERROR_INVALID_STATE if the state of the
00437      *         EddystoneService already is EDDYSTONE_MODE_NONE.
00438      *
00439      * @note If EddystoneService was previously in EDDYSTONE_MODE_CONFIG or
00440      *       EDDYSTONE_MODE_BEACON, then the resources allocated to that mode
00441      *       of operation such as memory are freed and the BLE instance
00442      *       shutdown before the new operation mode is configured.
00443      */
00444     EddystoneError_t stopCurrentService(void);
00445 
00446     /**
00447      * Set the Comple Local Name for the BLE device. This not only updates
00448      * the value of the Device Name Characteristic, it also updates the scan
00449      * response payload if the EddystoneService is currently in
00450      * EDDYSTONE_MODE_CONFIG.
00451      *
00452      * @param[in] deviceNameIn
00453      *              A pointer to a null terminated string containing the new
00454      *              device name.
00455      *
00456      * @return BLE_ERROR_NONE if the name was successfully set. Otherwise an
00457      *         appropriate error.
00458      *
00459      * @note EddystoneService does not make an internal copy of the string
00460      *       pointed to by @p deviceNameIn. Therefore, the user is responsible
00461      *       for ensuring that the string persists in memory as long as it is
00462      *       in use by the EddystoneService.
00463      *
00464      * @note The device name is not considered an Eddystone configuration
00465      *       parameter; therefore, it is not contained within the
00466      *       EddystoneParams_t structure and must be stored to persistent
00467      *       storage separately.
00468      */
00469     ble_error_t setCompleteDeviceName(const char *deviceNameIn);
00470 
00471     /**
00472      * Get the Eddystone Configuration parameters. This is particularly useful
00473      * for storing the configuration parameters in persistent storage.
00474      * It is not the responsibility of the Eddystone implementation to store
00475      * the configured parameters in persistent storage since this is
00476      * platform-specific.
00477      *
00478      * @param[out] params
00479      *              A reference to an EddystoneParams_t structure with the
00480      *              configured parameters of the EddystoneService.
00481      */
00482     void getEddystoneParams(EddystoneParams_t &params);
00483 
00484 private:
00485     /**
00486      * Helper function used only once during construction of an
00487      * EddystoneService object to avoid duplicated code.
00488      *
00489      * @param[in] advPowerLevelsIn
00490      *              The value of the Eddystone-URL Configuration Service TX
00491      *              Power Mode characteristic.
00492      * @param[in] radioPowerLevelsIn
00493      *              The value set internally into the radion tx power.
00494      * @param[in] advConfigIntervalIn
00495      *              The advertising interval for advertising packets of the
00496      *              Eddystone-URL Configuration Service.
00497      */
00498     void eddystoneConstructorHelper(const PowerLevels_t &advPowerLevelsIn,
00499                                     const PowerLevels_t &radioPowerLevelsIn,
00500                                     uint32_t            advConfigIntervalIn);
00501 
00502     /**
00503      * Helper funtion that will be registered as an initialization complete
00504      * callback when BLE::shutdown() is called. This is necessary when changing
00505      * Eddystone OperationModes. Once the BLE initialization is complete, this
00506      * callback will initialize all the necessary resource to operate
00507      * Eddystone service in the selected mode.
00508      *
00509      * @param[in] initContext
00510      *              The context provided by BLE API when initialization
00511      *              completes.
00512      */
00513     void bleInitComplete(BLE::InitializationCompleteCallbackContext* initContext);
00514 
00515     /**
00516      * When in EDDYSTONE_MODE_BEACON this function is called to update the
00517      * advertising payload to contain the information related to the specified
00518      * FrameType.
00519      *
00520      * @param[in] frameType
00521      *              The frame to populate the advertising payload with.
00522      */
00523     void swapAdvertisedFrame(FrameType frameType);
00524 
00525     /**
00526      * Helper function that manages the BLE radio that is used to broadcast
00527      * advertising packets. To advertise frames at the configured intervals
00528      * the actual advertising interval of the BLE instance is set to the value
00529      * returned by Gap::getMaxAdvertisingInterval() from the BLE API. When a
00530      * frame needs to be advertised, the enqueueFrame() callbacks add the frame
00531      * type to the advFrameQueue and post a manageRadio() callback. When the
00532      * callback is executed, the frame is dequeued and advertised using the
00533      * radio (by updating the advertising payload). manageRadio() also posts a
00534      * callback to itself Gap::getMinNonConnectableAdvertisingInterval()
00535      * milliseconds later. In this callback, manageRadio() will advertise the
00536      * next frame in the queue, yet if there is none it calls
00537      * Gap::stopAdvertising() and does not post any further callbacks.
00538      */
00539     void manageRadio(void);
00540 
00541     /**
00542      * Regular callbacks posted at the rate of urlFramePeriod, uidFramePeriod
00543      * and tlmFramePeriod milliseconds enqueue frames to be advertised. If the
00544      * frame queue is currently empty, then this function directly calls
00545      * manageRadio() to broadcast the required FrameType.
00546      *
00547      * @param[in] frameType
00548      *              The FrameType to enqueue for broadcasting.
00549      */
00550     void enqueueFrame(FrameType frameType);
00551 
00552     /**
00553      * Helper function that updates the advertising payload when in
00554      * EDDYSTONE_MODE_BEACON to contain a new frame.
00555      *
00556      * @param[in] rawFrame
00557      *              The raw bytes of the frame to advertise.
00558      * @param[in] rawFrameLength
00559      *              The length in bytes of the array pointed to by @p rawFrame.
00560      */
00561     void updateAdvertisementPacket(const uint8_t* rawFrame, size_t rawFrameLength);
00562 
00563     /**
00564      * Helper function that updates the information in the Eddystone-TLM frames
00565      * Internally, this function executes the registered callbacks to update
00566      * beacon Battery Voltage and Temperature (if available). Furthermore, this
00567      * function updates the raw frame data. This operation must be done fairly
00568      * often because the Eddystone-TLM frame Time Since Boot must have a 0.1
00569      * seconds resolution according to the Eddystone specification.
00570      */
00571     void updateRawTLMFrame(void);
00572 
00573     /**
00574      * Initialize the resources required when switching to
00575      * EDDYSTONE_MODE_BEACON.
00576      */
00577     void setupBeaconService(void);
00578 
00579     /**
00580      * Initialize the resources required when switching to
00581      * EDDYSTONE_MODE_CONFIG. This includes the GATT services and
00582      * characteristics required by the Eddystone-URL Configuration Service.
00583      */
00584     void setupConfigService(void);
00585 
00586     /**
00587      * Free the resources acquired by a call to setupConfigService().
00588      */
00589     void freeConfigCharacteristics(void);
00590 
00591     /**
00592      * Free the resources acquired by a call to setupBeaconService() and
00593      * cancel all pending callbacks that operate the radio and frame queue.
00594      *
00595      * @note This call will not modify the current state of the BLE device.
00596      *       EddystoneService::stopBeaconService should only be called after
00597      *       a call to BLE::shutdown().
00598      */
00599     void stopBeaconService(void);
00600 
00601     /**
00602      * Helper function used to update the GATT database following any
00603      * change to the internal state of the service object.
00604      */
00605     void updateCharacteristicValues(void);
00606 
00607     /**
00608      * Setup the payload of advertising packets for Eddystone-URL Configuration
00609      * Service.
00610      */
00611     void setupEddystoneConfigAdvertisements(void);
00612 
00613     /**
00614      * Helper function to setup the payload of scan response packets for
00615      * Eddystone-URL Configuration Service.
00616      */
00617     void setupEddystoneConfigScanResponse(void);
00618 
00619     /**
00620      * Callback registered to the BLE API to authorize write operations to the
00621      * Eddystone-URL Configuration Service Lock characteristic.
00622      *
00623      * @param[in] authParams
00624      *              Write authentication information.
00625      */
00626     void lockAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00627 
00628     /**
00629      * Callback registered to the BLE API to authorize write operations to the
00630      * Eddystone-URL Configuration Service Unlock characteristic.
00631      *
00632      * @param[in] authParams
00633      *              Write authentication information.
00634      */
00635     void unlockAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00636 
00637     /**
00638      * Callback registered to the BLE API to authorize write operations to the
00639      * Eddystone-URL Configuration Service URI Data characteristic.
00640      *
00641      * @param[in] authParams
00642      *              Write authentication information.
00643      */
00644     void urlDataWriteAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00645 
00646     void powerModeAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00647 
00648     /**
00649      * Callback registered to the BLE API to authorize write operations to the
00650      * following Eddystone-URL Configuration Service characteristics:
00651      * - Flags
00652      * - Beacon Period
00653      * - Reset
00654      *
00655      * @param[in] authParams
00656      *              Write authentication information.
00657      */
00658     template <typename T>
00659     void basicAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00660 
00661     /**
00662      * This callback is invoked when a GATT client attempts to modify any of the
00663      * characteristics of this service. Attempts to do so are also applied to
00664      * the internal state of this service object.
00665      *
00666      * @param[in] writeParams
00667      *              Information about the values that are being written.
00668      */
00669     void onDataWrittenCallback(const GattWriteCallbackParams *writeParams);
00670 
00671     /**
00672      * Correct the advertising interval for non-connectable packets.
00673      *
00674      * @param[in] beaconPeriodIn
00675      *              The input interval in milliseconds.
00676      *
00677      * @return The corrected interval in milliseconds.
00678      *
00679      * @note For the acceptable range of advertising interval refer to the
00680      *       following functions in mbed BLE API:
00681      *       - Gap::getMinNonConnectableAdvertisingInterval()
00682      *       - Gap::getMaxAdvertisingInterval()
00683      */
00684     uint16_t correctAdvertisementPeriod(uint16_t beaconPeriodIn) const;
00685 
00686     /**
00687      * BLE instance that EddystoneService will operate on.
00688      */
00689     BLE                                                             &ble;
00690     /**
00691      * The advertising interval for Eddystone-URL Config Service advertising
00692      * packets.
00693      */
00694     uint32_t                                                        advConfigInterval;
00695     /**
00696      * Current EddystoneServce operation mode.
00697      */
00698     uint8_t                                                         operationMode;
00699 
00700     /**
00701      * Encapsulation of a URL frame.
00702      */
00703     URLFrame                                                        urlFrame;
00704     /**
00705      * Encapsulation of a UID frame.
00706      */
00707     UIDFrame                                                        uidFrame;
00708     /**
00709      * Encapsulation of a TLM frame.
00710      */
00711     TLMFrame                                                        tlmFrame;
00712 
00713     /**
00714      * The value set internally into the radion tx power.
00715      */
00716     PowerLevels_t                                                   radioPowerLevels;
00717     /**
00718      * An array containing possible values for advertised tx power in Eddystone
00719      * frames. Also, the value of the Eddystone-URL Configuration Service
00720      * Advertised TX Power Levels characteristic.
00721      */
00722     PowerLevels_t                                                   advPowerLevels;
00723     /**
00724      * The value of the Eddystone-URL Configuration Service Lock State
00725      * characteristic.
00726      */
00727     bool                                                            lockState;
00728     /**
00729      * The value of the Eddystone-URL Configuration Service reset
00730      * characteristic.
00731      */
00732     bool                                                            resetFlag;
00733     /**
00734      * The value of the Eddystone-URL Configuration Service Lock
00735      * characteristic.
00736      */
00737     Lock_t                                                          lock;
00738     /**
00739      * The value of the Eddystone-URL Configuration Service Unlock
00740      * characteristic.
00741      */
00742     Lock_t                                                          unlock;
00743     /**
00744      * The value of the Eddystone-URL Configuration Service Flags
00745      * characteristic.
00746      */
00747     uint8_t                                                         flags;
00748     /**
00749      * The value of the Eddystone-URL Configuration Service TX Power Mode
00750      * characteristic.
00751      */
00752     uint8_t                                                         txPowerMode;
00753     /**
00754      * The value of the Eddystone-URL Configuration Service Beacon Period
00755      * characteristic. Also, the advertising interval (in milliseconds) of
00756      * Eddystone-URL frames.
00757      */
00758     uint16_t                                                        urlFramePeriod;
00759     /**
00760      * The advertising interval (in milliseconds) of Eddystone-UID frames.
00761      */
00762     uint16_t                                                        uidFramePeriod;
00763     /**
00764      * The advertising interval (in milliseconds) of Eddystone-TLM frames.
00765      */
00766     uint16_t                                                        tlmFramePeriod;
00767 
00768     /**
00769      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00770      * Configuration Service Lock State characteristic.
00771      */
00772     ReadOnlyGattCharacteristic<bool>                                *lockStateChar;
00773     /**
00774      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00775      * Configuration Service Lock characteristic.
00776      */
00777     WriteOnlyArrayGattCharacteristic<uint8_t, sizeof(Lock_t)>       *lockChar;
00778     /**
00779      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00780      * Configuration Service Unlock characteristic.
00781      */
00782     WriteOnlyArrayGattCharacteristic<uint8_t, sizeof(Lock_t)>       *unlockChar;
00783     /**
00784      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00785      * Configuration Service URI Data characteristic.
00786      */
00787     GattCharacteristic                                              *urlDataChar;
00788     /**
00789      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00790      * Configuration Service Flags characteristic.
00791      */
00792     ReadWriteGattCharacteristic<uint8_t>                            *flagsChar;
00793     /**
00794      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00795      * Configuration Service Advertised TX Power Levels characteristic.
00796      */
00797     ReadWriteArrayGattCharacteristic<int8_t, sizeof(PowerLevels_t)> *advPowerLevelsChar;
00798     /**
00799      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00800      * Configuration Service TX Power Mode characteristic.
00801      */
00802     ReadWriteGattCharacteristic<uint8_t>                            *txPowerModeChar;
00803     /**
00804      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00805      * Configuration Service Beacon Period characteristic.
00806      */
00807     ReadWriteGattCharacteristic<uint16_t>                           *beaconPeriodChar;
00808     /**
00809      * Pointer to the BLE API characteristic encapsulation for the Eddystone-URL
00810      * Configuration Service Reset characteristic.
00811      */
00812     WriteOnlyGattCharacteristic<bool>                               *resetChar;
00813 
00814     /**
00815      * Pointer to the raw bytes that will be used to populate Eddystone-URL
00816      * frames.
00817      */
00818     uint8_t                                                         *rawUrlFrame;
00819     /**
00820      * Pointer to the raw bytes that will be used to populate Eddystone-UID
00821      * frames.
00822      */
00823     uint8_t                                                         *rawUidFrame;
00824     /**
00825      * Pointer to the raw bytes that will be used to populate Eddystone-TLM
00826      * frames.
00827      */
00828     uint8_t                                                         *rawTlmFrame;
00829 
00830     /**
00831      * Circular buffer that represents of Eddystone frames to be advertised.
00832      */
00833     CircularBuffer<FrameType, ADV_FRAME_QUEUE_SIZE>                 advFrameQueue;
00834 
00835     /**
00836      * The registered callback to update the Eddystone-TLM frame Battery
00837      * Voltage.
00838      */
00839     TlmUpdateCallback_t                                             tlmBatteryVoltageCallback;
00840     /**
00841      * The registered callback to update the Eddystone-TLM frame Beacon
00842      * Temperature.
00843      */
00844     TlmUpdateCallback_t                                             tlmBeaconTemperatureCallback;
00845 
00846     /**
00847      * Timer that keeps track of the time since boot.
00848      */
00849     Timer                                                           timeSinceBootTimer;
00850 
00851     /**
00852      * Callback handle to keep track of periodic
00853      * enqueueFrame(EDDYSTONE_FRAME_UID) callbacks that populate the
00854      * advFrameQueue.
00855      */
00856     int                                                             uidFrameCallbackHandle;
00857     /**
00858      * Minar callback handle to keep track of periodic
00859      * enqueueFrame(EDDYSTONE_FRAME_URL) callbacks that populate the
00860      * advFrameQueue.
00861      */
00862     int                                                             urlFrameCallbackHandle;
00863     /**
00864      * Minar callback handle to keep track of periodic
00865      * enqueueFrame(EDDYSTONE_FRAME_TLM) callbacks that populate the
00866      * advFrameQueue.
00867      */
00868     int                                                             tlmFrameCallbackHandle;
00869     /**
00870      * Minar callback handle to keep track of manageRadio() callbacks.
00871      */
00872     int                                                             radioManagerCallbackHandle;
00873 
00874     /**
00875      * GattCharacteristic table used to populate the BLE ATT table in the
00876      * GATT Server.
00877      */
00878     GattCharacteristic                                              *charTable[TOTAL_CHARACTERISTICS];
00879 
00880     /**
00881      * Pointer to the device name currently being used.
00882      */
00883     const char                                                      *deviceName;
00884 
00885     /**
00886      * Event queue used to post callbacks s
00887      */
00888     EventQueue& eventQueue;
00889 };
00890 
00891 #endif  /* __EDDYSTONESERVICE_H__ */