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 "ble/BLE.h"
00021 #include "EddystoneTypes.h"
00022 #include "URLFrame.h"
00023 #include "UIDFrame.h"
00024 #include "TLMFrame.h"
00025 #include <string.h>
00026 #ifdef YOTTA_CFG_MBED_OS
00027     #include "mbed-drivers/mbed.h"
00028 #else
00029     #include "mbed.h"
00030 #endif
00031 
00032 class EddystoneService
00033 {
00034 public:
00035     static const uint16_t TOTAL_CHARACTERISTICS = 9;
00036 
00037     static const uint32_t DEFAULT_CONFIG_PERIOD_MSEC = 1000;
00038     static const uint16_t DEFAULT_BEACON_PERIOD_MSEC = 1000;
00039 
00040     /* Operation modes of the EddystoneService:
00041      *      NONE: EddystoneService has been initialised but no memory has been
00042      *            dynamically allocated. Additionally, no services are running
00043      *            nothing is being advertised.
00044      *      CONFIG: EddystoneService has been initialised, the configuration
00045      *              service started and memory has been allocated for BLE
00046      *              characteristics. Memory consumption peaks during CONFIG
00047      *              mode.
00048      *      BEACON: Eddystone service is running as a beacon advertising URL,
00049      *              UID and/or TLM frames depending on how it is configured.
00050      * Note: The main app can change the mode of EddystoneService at any point
00051      * of time by calling startConfigService() or startBeaconService().
00052      * Resources from the previous mode will be freed. It is currently NOT
00053      * possible to force EddystoneService back into MODE_NONE.
00054      */
00055     enum OperationModes {
00056         EDDYSTONE_MODE_NONE,
00057         EDDYSTONE_MODE_CONFIG,
00058         EDDYSTONE_MODE_BEACON
00059     };
00060 
00061     struct EddystoneParams_t {
00062         bool             lockState;
00063         Lock_t           lock;
00064         Lock_t           unlock;
00065         uint8_t          flags;
00066         PowerLevels_t    advPowerLevels;
00067         uint8_t          txPowerMode;
00068         uint16_t         beaconPeriod;
00069         uint8_t          tlmVersion;
00070         uint8_t          urlDataLength;
00071         UrlData_t        urlData;
00072         UIDNamespaceID_t uidNamespaceID;
00073         UIDInstanceID_t  uidInstanceID;
00074     };
00075 
00076     enum EddystoneError_t {
00077         EDDYSTONE_ERROR_NONE,
00078         EDDYSTONE_ERROR_INVALID_BEACON_PERIOD,
00079         EDDYSTONE_ERROR_INVALID_CONSEC_FRAMES,
00080         EDDYSTONE_ERROR_INVALID_ADVERTISING_INTERVAL
00081     };
00082 
00083     enum FrameType {
00084         EDDYSTONE_FRAME_URL,
00085         EDDYSTONE_FRAME_UID,
00086         EDDYSTONE_FRAME_TLM,
00087         NUM_EDDYSTONE_FRAMES
00088     };
00089 
00090     /* Initialise the EddystoneService using parameters from persistent storage */
00091     EddystoneService(BLE                 &bleIn,
00092                      EddystoneParams_t   &paramsIn,
00093                      const PowerLevels_t &advPowerLevelsIn,
00094                      const PowerLevels_t &radioPowerLevelsIn,
00095                      uint32_t            advConfigIntervalIn = DEFAULT_CONFIG_PERIOD_MSEC);
00096 
00097     /* When using this constructor we need to call setURLData,
00098      * setTMLData and setUIDData to initialise values manually
00099      */
00100     EddystoneService(BLE                 &bleIn,
00101                      const PowerLevels_t &advPowerLevelsIn,
00102                      const PowerLevels_t &radioPowerLevelsIn,
00103                      uint32_t            advConfigIntervalIn = DEFAULT_CONFIG_PERIOD_MSEC);
00104 
00105     /* Setup callback to update BatteryVoltage in TLM frame */
00106     void onTLMBatteryVoltageUpdate(TlmUpdateCallback_t tlmBatteryVoltageCallbackIn);
00107 
00108     /* Setup callback to update BeaconTemperature in TLM frame */
00109     void onTLMBeaconTemperatureUpdate(TlmUpdateCallback_t tlmBeaconTemperatureCallbackIn);
00110 
00111     void setTLMData(uint8_t tlmVersionIn = 0);
00112 
00113     void setURLData(const char *urlDataIn);
00114 
00115     void setUIDData(const UIDNamespaceID_t *uidNamespaceIDIn, const UIDInstanceID_t *uidInstanceIDIn);
00116 
00117     EddystoneError_t startConfigService(void);
00118 
00119     EddystoneError_t startBeaconService(uint16_t consecUrlFramesIn = 2, uint16_t consecUidFramesIn = 2, uint16_t consecTlmFramesIn = 2);
00120 
00121     /* It is not the responsibility of the Eddystone implementation to store
00122      * the configured parameters in persistent storage since this is
00123      * platform-specific. So we provide this function that returns the
00124      * configured values that need to be stored and the main application
00125      * takes care of storing them.
00126      */
00127     void getEddystoneParams(EddystoneParams_t *params);
00128 
00129 private:
00130     /* Helper function used only once during constructing the object to avoid
00131      * duplicated code.
00132      */
00133     void eddystoneConstructorHelper(const PowerLevels_t &advPowerLevelsIn,
00134                                     const PowerLevels_t &radioPowerLevelsIn,
00135                                     uint32_t            advConfigIntervalIn);
00136 
00137     /* When changing modes, we shutdown and init the BLE instance, so
00138      * this is needed to complete the initialisation task.
00139      */
00140     void bleInitComplete(BLE::InitializationCompleteCallbackContext* initContext);
00141 
00142     void swapAdvertisedFrame(void);
00143 
00144     void updateAdvertisementPacket(const uint8_t* rawFrame, size_t rawFrameLength);
00145 
00146     /* Helper function that calls user-defined functions to update Battery Voltage and Temperature (if available),
00147      * then updates the raw frame data and finally updates the actual advertised packet. This operation must be
00148      * done fairly often because the TLM frame TimeSinceBoot must have a 0.1 secs resolution according to the
00149      * Eddystone specification.
00150      */
00151     void updateRawTLMFrame(void);
00152 
00153     void setupBeaconService(void);
00154 
00155     void setupConfigService(void);
00156 
00157     void freeConfigCharacteristics(void);
00158 
00159     void freeBeaconFrames(void);
00160 
00161     void radioNotificationCallback(bool radioActive);
00162 
00163     /*
00164      * Internal helper function used to update the GATT database following any
00165      * change to the internal state of the service object.
00166      */
00167     void updateCharacteristicValues(void);
00168 
00169     void setupEddystoneConfigAdvertisements(void);
00170 
00171     void lockAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00172 
00173     void unlockAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00174 
00175     void urlDataWriteAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00176 
00177     void powerModeAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00178 
00179     template <typename T>
00180     void basicAuthorizationCallback(GattWriteAuthCallbackParams *authParams);
00181 
00182     /*
00183      * This callback is invoked when a GATT client attempts to modify any of the
00184      * characteristics of this service. Attempts to do so are also applied to
00185      * the internal state of this service object.
00186      */
00187     void onDataWrittenCallback(const GattWriteCallbackParams *writeParams);
00188 
00189     uint16_t correctAdvertisementPeriod(uint16_t beaconPeriodIn) const;
00190 
00191     BLE                                                             &ble;
00192     uint32_t                                                        advConfigInterval;
00193     uint8_t                                                         operationMode;
00194 
00195     URLFrame                                                        urlFrame;
00196     UIDFrame                                                        uidFrame;
00197     TLMFrame                                                        tlmFrame;
00198 
00199     PowerLevels_t                                                   radioPowerLevels;
00200     PowerLevels_t                                                   advPowerLevels;
00201     bool                                                            lockState;
00202     bool                                                            resetFlag;
00203     Lock_t                                                          lock;
00204     Lock_t                                                          unlock;
00205     uint8_t                                                         flags;
00206     uint8_t                                                         txPowerMode;
00207     uint16_t                                                        beaconPeriod;
00208 
00209     ReadOnlyGattCharacteristic<bool>                                *lockStateChar;
00210     WriteOnlyArrayGattCharacteristic<uint8_t, sizeof(Lock_t)>       *lockChar;
00211     WriteOnlyArrayGattCharacteristic<uint8_t, sizeof(Lock_t)>       *unlockChar;
00212     GattCharacteristic                                              *urlDataChar;
00213     ReadWriteGattCharacteristic<uint8_t>                            *flagsChar;
00214     ReadWriteArrayGattCharacteristic<int8_t, sizeof(PowerLevels_t)> *advPowerLevelsChar;
00215     ReadWriteGattCharacteristic<uint8_t>                            *txPowerModeChar;
00216     ReadWriteGattCharacteristic<uint16_t>                           *beaconPeriodChar;
00217     WriteOnlyGattCharacteristic<bool>                               *resetChar;
00218 
00219     uint8_t                                                         *rawUrlFrame;
00220     uint8_t                                                         *rawUidFrame;
00221     uint8_t                                                         *rawTlmFrame;
00222 
00223     uint16_t                                                        consecFrames[NUM_EDDYSTONE_FRAMES];
00224     uint16_t                                                        currentConsecFrames[NUM_EDDYSTONE_FRAMES];
00225     uint8_t                                                         currentAdvertisedFrame;
00226 
00227     TlmUpdateCallback_t                                             tlmBatteryVoltageCallback;
00228     TlmUpdateCallback_t                                             tlmBeaconTemperatureCallback;
00229 
00230     Timer                                                           timeSinceBootTimer;
00231 #ifndef YOTTA_CFG_MBED_OS
00232     Timeout                                                         swapAdvertisedFrameTimeout;
00233 #endif
00234 
00235     GattCharacteristic                                              *charTable[TOTAL_CHARACTERISTICS];
00236 };
00237 
00238 #endif  /* __EDDYSTONESERVICE_H__ */