TLMFrame.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 __TLMFRAME_H__
00018 #define __TLMFRAME_H__
00019 
00020 #include "EddystoneTypes.h"
00021 #include "aes_eax.h"
00022 
00023 /**
00024  * Class that encapsulates data that belongs to the Eddystone-TLM frame. For
00025  * more information refer to https://github.com/google/eddystone/tree/master/eddystone-tlm.
00026  */
00027 class TLMFrame
00028 {
00029 public:
00030     /**
00031      * Construct a new instance of this class.
00032      *
00033      * @param[in] tlmVersionIn
00034      *              Eddystone-TLM version number to use.
00035      * @param[in] tlmBatteryVoltageIn
00036      *              Initial value for the Eddystone-TLM Battery Voltage.
00037      * @param[in] tlmBeaconTemperatureIn
00038      *              Initial value for the Eddystone-TLM Beacon Temperature.
00039      * @param[in] tlmPduCountIn
00040      *              Initial value for the Eddystone-TLM Advertising PDU Count.
00041      * @param[in] tlmTimeSinceBootIn
00042      *              Intitial value for the Eddystone-TLM time since boot timer.
00043      8              This timer has a 0.1 second resolution.
00044      */
00045     TLMFrame(uint8_t  tlmVersionIn           = 0,
00046              uint16_t tlmBatteryVoltageIn    = 0,
00047              uint16_t tlmBeaconTemperatureIn = 0x8000,
00048              uint32_t tlmPduCountIn          = 0,
00049              uint32_t tlmTimeSinceBootIn     = 0);
00050 
00051     /**
00052      * Set the Eddystone-TLM version number.
00053      */
00054     void setTLMData(uint8_t tlmVersionIn = 0);
00055 
00056     /**
00057      * Construct the raw bytes of the Eddystone-TLM frame that will be directly
00058      * used in the advertising packets.
00059      *
00060      * @param[in] rawFrame
00061      *              Pointer to the location where the raw frame will be stored.
00062      */
00063     void setData(uint8_t *rawFrame);
00064     
00065     /**
00066      * Construct the encrypted bytes of the Eddystone-ETLM frame that will be directly
00067      * used in the advertising packets.
00068      *
00069      * @param[in] rawFrame
00070      *              Pointer to the location where the raw frame will be stored.
00071      * @param[in] eidIdentityKey
00072      *              Pointer to the eidIdentityKey in use
00073      * @param[in] rotationPeriodExp
00074      *              Rotation exponent for EID
00075      * @param[in] beaconTimeSecs
00076      *              Time in seconds since beacon boot.
00077      */
00078     void encryptData(uint8_t* rawFrame, uint8_t* eidIdentityKey, uint8_t rotationPeriodExp, uint32_t beaconTimeSecs);
00079 
00080     /**
00081      * Get the size of the Eddystone-TLM frame constructed with the
00082      * current state of the TLMFrame object.
00083      * 
00084      * @param[in] rawFrame
00085      *              Pointer to the location where the raw frame will be stored.
00086      *
00087      * @return The size in bytes of the Eddystone-TLM frame.
00088      */
00089     size_t getRawFrameSize(uint8_t* rawFrame);
00090     
00091     
00092     /**
00093      * Get the TLM frame data from the Eddystone-TLM frame.
00094      * 
00095      * @param[in] rawFrame
00096      *              Pointer to the location where the raw frame will be stored.
00097      *
00098      * @return A pointer to the bytes of the Eddystone-TLM frame data.
00099      */
00100     uint8_t* getData(uint8_t* rawFrame);
00101     
00102     /**
00103      * Get the length of the TLM frame data from the Eddystone-TLM frame.
00104      * 
00105      * @param[in] rawFrame
00106      *              Pointer to the location where the raw frame will be stored.
00107      *
00108      * @return The size in bytes of the Eddystone-TLM frame.
00109      */
00110     uint8_t  getDataLength(uint8_t* rawFrame);
00111     
00112     /**
00113      * Get the TLM Adv data from the Eddystone-TLMframe.
00114      * This is the full service data included in the BLE service data params
00115      * 
00116      * @param[in] rawFrame
00117      *              Pointer to the location where the raw frame will be stored.
00118      *
00119      * @return A pointer to the bytes of the Eddystone-TLM Adv frame data.
00120      */
00121     uint8_t* getAdvFrame(uint8_t* rawFrame);
00122     
00123     /**
00124      * Get the length of the TLM Adv data from the Eddystone-TLMframe.
00125      * 
00126      * @param[in] rawFrame
00127      *              Pointer to the location where the raw frame will be stored.
00128      *
00129      * @return The size in bytes of the Eddystone-TLM Adv frame data.
00130      */
00131     uint8_t getAdvFrameLength(uint8_t* rawFrame);
00132 
00133     /**
00134      * Update the time since boot.
00135      *
00136      * @param[in] nowInMillis
00137      *              The time since boot in milliseconds.
00138      */
00139     void updateTimeSinceBoot(uint32_t nowInMillis);
00140 
00141     /**
00142      * Update the Battery Voltage.
00143      *
00144      * @param[in] tlmBatteryVoltageIn
00145      *              The new Battery Voltage value.
00146      */
00147     void updateBatteryVoltage(uint16_t tlmBatteryVoltageIn);
00148 
00149     /**
00150      * Update the Beacon Temperature.
00151      *
00152      * @param[in] tlmBeaconTemperatureIn
00153      *              The new Beacon Temperature value.
00154      */
00155     void updateBeaconTemperature(uint16_t tlmBeaconTemperatureIn);
00156 
00157     /**
00158      * Increment the current PDU counter by 1.
00159      */
00160     void updatePduCount(void);
00161 
00162     /**
00163      * Get the current Battery Voltage.
00164      *
00165      * @return The Battery Voltage.
00166      */
00167     uint16_t getBatteryVoltage(void) const;
00168 
00169     /**
00170      * Get the current Beacon Temperature.
00171      *
00172      * @return The Beacon Temperature.
00173      */
00174     uint16_t getBeaconTemperature(void) const;
00175 
00176     /**
00177      * Get the current TLM Version number.
00178      *
00179      * @return The TLM Version number.
00180      */
00181     uint8_t getTLMVersion(void) const;
00182     
00183     /**
00184      * The byte ID of an Eddystone-TLM frame.
00185      */
00186     static const uint8_t FRAME_TYPE_TLM = 0x20;
00187     
00188     /**
00189     * The verison number of the Telemetry packets being used
00190     */
00191     static const uint8_t DEFAULT_TLM_VERSION = 0;
00192 
00193     /**
00194      * The size of an Eddystone-TLM frame.
00195      */
00196     static const uint8_t FRAME_SIZE_TLM = 14;
00197     /**
00198      * The size of an Eddystone-ETLM frame.
00199      */
00200     static const uint8_t FRAME_SIZE_ETLM = (FRAME_SIZE_TLM + 4);
00201 
00202     // Nonce
00203     static const uint8_t ETLM_NONCE_LEN = 6;
00204     // Version
00205     static const uint8_t VERSION_OFFSET = 4;
00206     static const uint8_t TLM_VERSION = 0x00;
00207     static const uint8_t ETLM_VERSION = 0x01;
00208     // Data
00209     static const uint8_t DATA_OFFSET = 5;
00210     static const uint8_t TLM_DATA_LEN = 12;
00211     static const uint8_t ETLM_DATA_LEN = 16;
00212     // Salt
00213     static const uint8_t SALT_OFFSET = 12;
00214     static const uint8_t SALT_LEN = 2;
00215     // Message Integrity Check
00216     static const uint8_t MIC_OFFSET = 14;
00217     static const uint8_t MIC_LEN = 2;
00218     // Return codes
00219     static const int ETLM_NONCE_INVALID_LEN = -1;
00220 
00221     /**
00222      * Constructs 6 byte (48-bit) Nonce from an empty array, rotationExp and beacon time (secs) 
00223      *
00224      * @param[in] nonce
00225      *              the input and target nonce[] array
00226      * @param[in] rotationPeriodExp
00227      *              Rotation exponent for EID
00228      * @param[in] beaconTimeSecs
00229      *              Time in seconds since beacon boot.
00230      * @return[out] return code (success = 0)
00231      */
00232     int generateEtlmNonce(uint8_t* nonce, uint8_t rotatePeriodExp, uint32_t beaconTimeSecs);
00233 
00234 
00235 private:
00236 
00237     /**
00238      * The size (in bytes) of an Eddystone-EID frame.
00239      * This is the some of the Eddystone UUID(2 bytes), FrameType, AdvTxPower,
00240      * EID Value
00241      */
00242     // static const uint8_t TLM_FRAME_LEN = 16;
00243     // static const uint8_t ETLM_FRAME_LEN = 20;
00244     static const uint8_t FRAME_LEN_OFFSET = 0;
00245     static const uint8_t EDDYSTONE_UUID_LEN = 2; 
00246     static const uint8_t TLM_DATA_OFFSET = 3;
00247     static const uint8_t ADV_FRAME_OFFSET = 1;
00248 
00249     /**
00250      * Eddystone-TLM version value.
00251      */
00252     uint8_t              tlmVersion;
00253     /**
00254      * Time since boot in milliseconds.
00255      */
00256     uint32_t             lastTimeSinceBootRead;
00257     /**
00258      * Eddystone-TLM Battery Voltage value.
00259      */
00260     uint16_t             tlmBatteryVoltage;
00261     /**
00262      * Eddystone-TLM Beacon temperature value.
00263      */
00264     uint16_t             tlmBeaconTemperature;
00265     /**
00266      * Eddystone-TLM Advertising PDU Count.
00267      */
00268     uint32_t             tlmPduCount;
00269     /**
00270      * Eddystone-TLM time since boot with 0.1 second resolution.
00271      */
00272     uint32_t             tlmTimeSinceBoot;
00273 
00274 
00275 };
00276 #endif  /* __TLMFRAME_H__ */