Sarah Marsh / Mbed OS EddystoneBeacon

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

source/TLMFrame.h@0:1c7da5f83647, 2016-11-29 (annotated)

Committer:
sarahmarshy
Date:
Tue Nov 29 06:29:10 2016 +0000
Revision:
0:1c7da5f83647
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
sarahmarshy 0:1c7da5f83647 1 /*
sarahmarshy 0:1c7da5f83647 2 * Copyright (c) 2006-2016 Google Inc, All Rights Reserved
sarahmarshy 0:1c7da5f83647 3 *
sarahmarshy 0:1c7da5f83647 4 * Licensed under the Apache License, Version 2.0 (the "License");
sarahmarshy 0:1c7da5f83647 5 * you may not use this file except in compliance with the License.
sarahmarshy 0:1c7da5f83647 6 * You may obtain a copy of the License at
sarahmarshy 0:1c7da5f83647 7 *
sarahmarshy 0:1c7da5f83647 8 * http://www.apache.org/licenses/LICENSE-2.0
sarahmarshy 0:1c7da5f83647 9 *
sarahmarshy 0:1c7da5f83647 10 * Unless required by applicable law or agreed to in writing, software
sarahmarshy 0:1c7da5f83647 11 * distributed under the License is distributed on an "AS IS" BASIS,
sarahmarshy 0:1c7da5f83647 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
sarahmarshy 0:1c7da5f83647 13 * See the License for the specific language governing permissions and
sarahmarshy 0:1c7da5f83647 14 * limitations under the License.
sarahmarshy 0:1c7da5f83647 15 */
sarahmarshy 0:1c7da5f83647 16
sarahmarshy 0:1c7da5f83647 17 #ifndef __TLMFRAME_H__
sarahmarshy 0:1c7da5f83647 18 #define __TLMFRAME_H__
sarahmarshy 0:1c7da5f83647 19
sarahmarshy 0:1c7da5f83647 20 #include "EddystoneTypes.h"
sarahmarshy 0:1c7da5f83647 21 #include "aes_eax.h"
sarahmarshy 0:1c7da5f83647 22
sarahmarshy 0:1c7da5f83647 23 /**
sarahmarshy 0:1c7da5f83647 24 * Class that encapsulates data that belongs to the Eddystone-TLM frame. For
sarahmarshy 0:1c7da5f83647 25 * more information refer to https://github.com/google/eddystone/tree/master/eddystone-tlm.
sarahmarshy 0:1c7da5f83647 26 */
sarahmarshy 0:1c7da5f83647 27 class TLMFrame
sarahmarshy 0:1c7da5f83647 28 {
sarahmarshy 0:1c7da5f83647 29 public:
sarahmarshy 0:1c7da5f83647 30 /**
sarahmarshy 0:1c7da5f83647 31 * Construct a new instance of this class.
sarahmarshy 0:1c7da5f83647 32 *
sarahmarshy 0:1c7da5f83647 33 * @param[in] tlmVersionIn
sarahmarshy 0:1c7da5f83647 34 * Eddystone-TLM version number to use.
sarahmarshy 0:1c7da5f83647 35 * @param[in] tlmBatteryVoltageIn
sarahmarshy 0:1c7da5f83647 36 * Initial value for the Eddystone-TLM Battery Voltage.
sarahmarshy 0:1c7da5f83647 37 * @param[in] tlmBeaconTemperatureIn
sarahmarshy 0:1c7da5f83647 38 * Initial value for the Eddystone-TLM Beacon Temperature.
sarahmarshy 0:1c7da5f83647 39 * @param[in] tlmPduCountIn
sarahmarshy 0:1c7da5f83647 40 * Initial value for the Eddystone-TLM Advertising PDU Count.
sarahmarshy 0:1c7da5f83647 41 * @param[in] tlmTimeSinceBootIn
sarahmarshy 0:1c7da5f83647 42 * Intitial value for the Eddystone-TLM time since boot timer.
sarahmarshy 0:1c7da5f83647 43 8 This timer has a 0.1 second resolution.
sarahmarshy 0:1c7da5f83647 44 */
sarahmarshy 0:1c7da5f83647 45 TLMFrame(uint8_t tlmVersionIn = 0,
sarahmarshy 0:1c7da5f83647 46 uint16_t tlmBatteryVoltageIn = 0,
sarahmarshy 0:1c7da5f83647 47 uint16_t tlmBeaconTemperatureIn = 0x8000,
sarahmarshy 0:1c7da5f83647 48 uint32_t tlmPduCountIn = 0,
sarahmarshy 0:1c7da5f83647 49 uint32_t tlmTimeSinceBootIn = 0);
sarahmarshy 0:1c7da5f83647 50
sarahmarshy 0:1c7da5f83647 51 /**
sarahmarshy 0:1c7da5f83647 52 * Set the Eddystone-TLM version number.
sarahmarshy 0:1c7da5f83647 53 */
sarahmarshy 0:1c7da5f83647 54 void setTLMData(uint8_t tlmVersionIn = 0);
sarahmarshy 0:1c7da5f83647 55
sarahmarshy 0:1c7da5f83647 56 /**
sarahmarshy 0:1c7da5f83647 57 * Construct the raw bytes of the Eddystone-TLM frame that will be directly
sarahmarshy 0:1c7da5f83647 58 * used in the advertising packets.
sarahmarshy 0:1c7da5f83647 59 *
sarahmarshy 0:1c7da5f83647 60 * @param[in] rawFrame
sarahmarshy 0:1c7da5f83647 61 * Pointer to the location where the raw frame will be stored.
sarahmarshy 0:1c7da5f83647 62 */
sarahmarshy 0:1c7da5f83647 63 void setData(uint8_t *rawFrame);
sarahmarshy 0:1c7da5f83647 64
sarahmarshy 0:1c7da5f83647 65 /**
sarahmarshy 0:1c7da5f83647 66 * Construct the encrypted bytes of the Eddystone-ETLM frame that will be directly
sarahmarshy 0:1c7da5f83647 67 * used in the advertising packets.
sarahmarshy 0:1c7da5f83647 68 *
sarahmarshy 0:1c7da5f83647 69 * @param[in] rawFrame
sarahmarshy 0:1c7da5f83647 70 * Pointer to the location where the raw frame will be stored.
sarahmarshy 0:1c7da5f83647 71 * @param[in] eidIdentityKey
sarahmarshy 0:1c7da5f83647 72 * Pointer to the eidIdentityKey in use
sarahmarshy 0:1c7da5f83647 73 * @param[in] rotationPeriodExp
sarahmarshy 0:1c7da5f83647 74 * Rotation exponent for EID
sarahmarshy 0:1c7da5f83647 75 * @param[in] beaconTimeSecs
sarahmarshy 0:1c7da5f83647 76 * Time in seconds since beacon boot.
sarahmarshy 0:1c7da5f83647 77 */
sarahmarshy 0:1c7da5f83647 78 void encryptData(uint8_t* rawFrame, uint8_t* eidIdentityKey, uint8_t rotationPeriodExp, uint32_t beaconTimeSecs);
sarahmarshy 0:1c7da5f83647 79
sarahmarshy 0:1c7da5f83647 80 /**
sarahmarshy 0:1c7da5f83647 81 * Get the size of the Eddystone-TLM frame constructed with the
sarahmarshy 0:1c7da5f83647 82 * current state of the TLMFrame object.
sarahmarshy 0:1c7da5f83647 83 *
sarahmarshy 0:1c7da5f83647 84 * @param[in] rawFrame
sarahmarshy 0:1c7da5f83647 85 * Pointer to the location where the raw frame will be stored.
sarahmarshy 0:1c7da5f83647 86 *
sarahmarshy 0:1c7da5f83647 87 * @return The size in bytes of the Eddystone-TLM frame.
sarahmarshy 0:1c7da5f83647 88 */
sarahmarshy 0:1c7da5f83647 89 size_t getRawFrameSize(uint8_t* rawFrame);
sarahmarshy 0:1c7da5f83647 90
sarahmarshy 0:1c7da5f83647 91
sarahmarshy 0:1c7da5f83647 92 /**
sarahmarshy 0:1c7da5f83647 93 * Get the TLM frame data from the Eddystone-TLM frame.
sarahmarshy 0:1c7da5f83647 94 *
sarahmarshy 0:1c7da5f83647 95 * @param[in] rawFrame
sarahmarshy 0:1c7da5f83647 96 * Pointer to the location where the raw frame will be stored.
sarahmarshy 0:1c7da5f83647 97 *
sarahmarshy 0:1c7da5f83647 98 * @return A pointer to the bytes of the Eddystone-TLM frame data.
sarahmarshy 0:1c7da5f83647 99 */
sarahmarshy 0:1c7da5f83647 100 uint8_t* getData(uint8_t* rawFrame);
sarahmarshy 0:1c7da5f83647 101
sarahmarshy 0:1c7da5f83647 102 /**
sarahmarshy 0:1c7da5f83647 103 * Get the length of the TLM frame data from the Eddystone-TLM frame.
sarahmarshy 0:1c7da5f83647 104 *
sarahmarshy 0:1c7da5f83647 105 * @param[in] rawFrame
sarahmarshy 0:1c7da5f83647 106 * Pointer to the location where the raw frame will be stored.
sarahmarshy 0:1c7da5f83647 107 *
sarahmarshy 0:1c7da5f83647 108 * @return The size in bytes of the Eddystone-TLM frame.
sarahmarshy 0:1c7da5f83647 109 */
sarahmarshy 0:1c7da5f83647 110 uint8_t getDataLength(uint8_t* rawFrame);
sarahmarshy 0:1c7da5f83647 111
sarahmarshy 0:1c7da5f83647 112 /**
sarahmarshy 0:1c7da5f83647 113 * Get the TLM Adv data from the Eddystone-TLMframe.
sarahmarshy 0:1c7da5f83647 114 * This is the full service data included in the BLE service data params
sarahmarshy 0:1c7da5f83647 115 *
sarahmarshy 0:1c7da5f83647 116 * @param[in] rawFrame
sarahmarshy 0:1c7da5f83647 117 * Pointer to the location where the raw frame will be stored.
sarahmarshy 0:1c7da5f83647 118 *
sarahmarshy 0:1c7da5f83647 119 * @return A pointer to the bytes of the Eddystone-TLM Adv frame data.
sarahmarshy 0:1c7da5f83647 120 */
sarahmarshy 0:1c7da5f83647 121 uint8_t* getAdvFrame(uint8_t* rawFrame);
sarahmarshy 0:1c7da5f83647 122
sarahmarshy 0:1c7da5f83647 123 /**
sarahmarshy 0:1c7da5f83647 124 * Get the length of the TLM Adv data from the Eddystone-TLMframe.
sarahmarshy 0:1c7da5f83647 125 *
sarahmarshy 0:1c7da5f83647 126 * @param[in] rawFrame
sarahmarshy 0:1c7da5f83647 127 * Pointer to the location where the raw frame will be stored.
sarahmarshy 0:1c7da5f83647 128 *
sarahmarshy 0:1c7da5f83647 129 * @return The size in bytes of the Eddystone-TLM Adv frame data.
sarahmarshy 0:1c7da5f83647 130 */
sarahmarshy 0:1c7da5f83647 131 uint8_t getAdvFrameLength(uint8_t* rawFrame);
sarahmarshy 0:1c7da5f83647 132
sarahmarshy 0:1c7da5f83647 133 /**
sarahmarshy 0:1c7da5f83647 134 * Update the time since last boot.
sarahmarshy 0:1c7da5f83647 135 *
sarahmarshy 0:1c7da5f83647 136 * @param[in] nowInMillis
sarahmarshy 0:1c7da5f83647 137 * The time since boot in milliseconds.
sarahmarshy 0:1c7da5f83647 138 */
sarahmarshy 0:1c7da5f83647 139 void updateTimeSinceLastBoot(uint32_t nowInMillis);
sarahmarshy 0:1c7da5f83647 140
sarahmarshy 0:1c7da5f83647 141 /**
sarahmarshy 0:1c7da5f83647 142 * Update the Battery Voltage.
sarahmarshy 0:1c7da5f83647 143 *
sarahmarshy 0:1c7da5f83647 144 * @param[in] tlmBatteryVoltageIn
sarahmarshy 0:1c7da5f83647 145 * The new Battery Voltage value.
sarahmarshy 0:1c7da5f83647 146 */
sarahmarshy 0:1c7da5f83647 147 void updateBatteryVoltage(uint16_t tlmBatteryVoltageIn);
sarahmarshy 0:1c7da5f83647 148
sarahmarshy 0:1c7da5f83647 149 /**
sarahmarshy 0:1c7da5f83647 150 * Update the Beacon Temperature.
sarahmarshy 0:1c7da5f83647 151 *
sarahmarshy 0:1c7da5f83647 152 * @param[in] tlmBeaconTemperatureIn
sarahmarshy 0:1c7da5f83647 153 * The new Beacon Temperature value.
sarahmarshy 0:1c7da5f83647 154 */
sarahmarshy 0:1c7da5f83647 155 void updateBeaconTemperature(uint16_t tlmBeaconTemperatureIn);
sarahmarshy 0:1c7da5f83647 156
sarahmarshy 0:1c7da5f83647 157 /**
sarahmarshy 0:1c7da5f83647 158 * Increment the current PDU counter by 1.
sarahmarshy 0:1c7da5f83647 159 */
sarahmarshy 0:1c7da5f83647 160 void updatePduCount(void);
sarahmarshy 0:1c7da5f83647 161
sarahmarshy 0:1c7da5f83647 162 /**
sarahmarshy 0:1c7da5f83647 163 * Get the current Battery Voltage.
sarahmarshy 0:1c7da5f83647 164 *
sarahmarshy 0:1c7da5f83647 165 * @return The Battery Voltage.
sarahmarshy 0:1c7da5f83647 166 */
sarahmarshy 0:1c7da5f83647 167 uint16_t getBatteryVoltage(void) const;
sarahmarshy 0:1c7da5f83647 168
sarahmarshy 0:1c7da5f83647 169 /**
sarahmarshy 0:1c7da5f83647 170 * Get the current Beacon Temperature.
sarahmarshy 0:1c7da5f83647 171 *
sarahmarshy 0:1c7da5f83647 172 * @return The Beacon Temperature.
sarahmarshy 0:1c7da5f83647 173 */
sarahmarshy 0:1c7da5f83647 174 uint16_t getBeaconTemperature(void) const;
sarahmarshy 0:1c7da5f83647 175
sarahmarshy 0:1c7da5f83647 176 /**
sarahmarshy 0:1c7da5f83647 177 * Get the current TLM Version number.
sarahmarshy 0:1c7da5f83647 178 *
sarahmarshy 0:1c7da5f83647 179 * @return The TLM Version number.
sarahmarshy 0:1c7da5f83647 180 */
sarahmarshy 0:1c7da5f83647 181 uint8_t getTLMVersion(void) const;
sarahmarshy 0:1c7da5f83647 182
sarahmarshy 0:1c7da5f83647 183 /**
sarahmarshy 0:1c7da5f83647 184 * The byte ID of an Eddystone-TLM frame.
sarahmarshy 0:1c7da5f83647 185 */
sarahmarshy 0:1c7da5f83647 186 static const uint8_t FRAME_TYPE_TLM = 0x20;
sarahmarshy 0:1c7da5f83647 187
sarahmarshy 0:1c7da5f83647 188 /**
sarahmarshy 0:1c7da5f83647 189 * The verison number of the Telemetry packets being used
sarahmarshy 0:1c7da5f83647 190 */
sarahmarshy 0:1c7da5f83647 191 static const uint8_t DEFAULT_TLM_VERSION = 0;
sarahmarshy 0:1c7da5f83647 192
sarahmarshy 0:1c7da5f83647 193 /**
sarahmarshy 0:1c7da5f83647 194 * The size of an Eddystone-TLM frame.
sarahmarshy 0:1c7da5f83647 195 */
sarahmarshy 0:1c7da5f83647 196 static const uint8_t FRAME_SIZE_TLM = 14;
sarahmarshy 0:1c7da5f83647 197 /**
sarahmarshy 0:1c7da5f83647 198 * The size of an Eddystone-ETLM frame.
sarahmarshy 0:1c7da5f83647 199 */
sarahmarshy 0:1c7da5f83647 200 static const uint8_t FRAME_SIZE_ETLM = (FRAME_SIZE_TLM + 4);
sarahmarshy 0:1c7da5f83647 201
sarahmarshy 0:1c7da5f83647 202 // Nonce
sarahmarshy 0:1c7da5f83647 203 static const uint8_t ETLM_NONCE_LEN = 6;
sarahmarshy 0:1c7da5f83647 204 // Version
sarahmarshy 0:1c7da5f83647 205 static const uint8_t VERSION_OFFSET = 4;
sarahmarshy 0:1c7da5f83647 206 static const uint8_t TLM_VERSION = 0x00;
sarahmarshy 0:1c7da5f83647 207 static const uint8_t ETLM_VERSION = 0x01;
sarahmarshy 0:1c7da5f83647 208 // Data
sarahmarshy 0:1c7da5f83647 209 static const uint8_t DATA_OFFSET = 5;
sarahmarshy 0:1c7da5f83647 210 static const uint8_t TLM_DATA_LEN = 12;
sarahmarshy 0:1c7da5f83647 211 static const uint8_t ETLM_DATA_LEN = 16;
sarahmarshy 0:1c7da5f83647 212 // Salt
sarahmarshy 0:1c7da5f83647 213 static const uint8_t SALT_OFFSET = 12;
sarahmarshy 0:1c7da5f83647 214 static const uint8_t SALT_LEN = 2;
sarahmarshy 0:1c7da5f83647 215 // Message Integrity Check
sarahmarshy 0:1c7da5f83647 216 static const uint8_t MIC_OFFSET = 14;
sarahmarshy 0:1c7da5f83647 217 static const uint8_t MIC_LEN = 2;
sarahmarshy 0:1c7da5f83647 218 // Return codes
sarahmarshy 0:1c7da5f83647 219 static const int ETLM_NONCE_INVALID_LEN = -1;
sarahmarshy 0:1c7da5f83647 220
sarahmarshy 0:1c7da5f83647 221 /**
sarahmarshy 0:1c7da5f83647 222 * Constructs 6 byte (48-bit) Nonce from an empty array, rotationExp and beacon time (secs)
sarahmarshy 0:1c7da5f83647 223 *
sarahmarshy 0:1c7da5f83647 224 * @param[in] nonce
sarahmarshy 0:1c7da5f83647 225 * the input and target nonce[] array
sarahmarshy 0:1c7da5f83647 226 * @param[in] rotationPeriodExp
sarahmarshy 0:1c7da5f83647 227 * Rotation exponent for EID
sarahmarshy 0:1c7da5f83647 228 * @param[in] beaconTimeSecs
sarahmarshy 0:1c7da5f83647 229 * Time in seconds since beacon boot.
sarahmarshy 0:1c7da5f83647 230 * @return[out] return code (success = 0)
sarahmarshy 0:1c7da5f83647 231 */
sarahmarshy 0:1c7da5f83647 232 int generateEtlmNonce(uint8_t* nonce, uint8_t rotatePeriodExp, uint32_t beaconTimeSecs);
sarahmarshy 0:1c7da5f83647 233
sarahmarshy 0:1c7da5f83647 234
sarahmarshy 0:1c7da5f83647 235 private:
sarahmarshy 0:1c7da5f83647 236
sarahmarshy 0:1c7da5f83647 237 /**
sarahmarshy 0:1c7da5f83647 238 * The size (in bytes) of an Eddystone-EID frame.
sarahmarshy 0:1c7da5f83647 239 * This is the some of the Eddystone UUID(2 bytes), FrameType, AdvTxPower,
sarahmarshy 0:1c7da5f83647 240 * EID Value
sarahmarshy 0:1c7da5f83647 241 */
sarahmarshy 0:1c7da5f83647 242 // static const uint8_t TLM_FRAME_LEN = 16;
sarahmarshy 0:1c7da5f83647 243 // static const uint8_t ETLM_FRAME_LEN = 20;
sarahmarshy 0:1c7da5f83647 244 static const uint8_t FRAME_LEN_OFFSET = 0;
sarahmarshy 0:1c7da5f83647 245 static const uint8_t EDDYSTONE_UUID_LEN = 2;
sarahmarshy 0:1c7da5f83647 246 static const uint8_t TLM_DATA_OFFSET = 3;
sarahmarshy 0:1c7da5f83647 247 static const uint8_t ADV_FRAME_OFFSET = 1;
sarahmarshy 0:1c7da5f83647 248
sarahmarshy 0:1c7da5f83647 249 /**
sarahmarshy 0:1c7da5f83647 250 * Eddystone-TLM version value.
sarahmarshy 0:1c7da5f83647 251 */
sarahmarshy 0:1c7da5f83647 252 uint8_t tlmVersion;
sarahmarshy 0:1c7da5f83647 253 /**
sarahmarshy 0:1c7da5f83647 254 * Time since boot in milliseconds.
sarahmarshy 0:1c7da5f83647 255 */
sarahmarshy 0:1c7da5f83647 256 uint32_t lastTimeSinceBootRead;
sarahmarshy 0:1c7da5f83647 257 /**
sarahmarshy 0:1c7da5f83647 258 * Eddystone-TLM Battery Voltage value.
sarahmarshy 0:1c7da5f83647 259 */
sarahmarshy 0:1c7da5f83647 260 uint16_t tlmBatteryVoltage;
sarahmarshy 0:1c7da5f83647 261 /**
sarahmarshy 0:1c7da5f83647 262 * Eddystone-TLM Beacon temperature value.
sarahmarshy 0:1c7da5f83647 263 */
sarahmarshy 0:1c7da5f83647 264 uint16_t tlmBeaconTemperature;
sarahmarshy 0:1c7da5f83647 265 /**
sarahmarshy 0:1c7da5f83647 266 * Eddystone-TLM Advertising PDU Count.
sarahmarshy 0:1c7da5f83647 267 */
sarahmarshy 0:1c7da5f83647 268 uint32_t tlmPduCount;
sarahmarshy 0:1c7da5f83647 269 /**
sarahmarshy 0:1c7da5f83647 270 * Eddystone-TLM time since boot with 0.1 second resolution.
sarahmarshy 0:1c7da5f83647 271 */
sarahmarshy 0:1c7da5f83647 272 uint32_t tlmTimeSinceBoot;
sarahmarshy 0:1c7da5f83647 273
sarahmarshy 0:1c7da5f83647 274
sarahmarshy 0:1c7da5f83647 275 };
sarahmarshy 0:1c7da5f83647 276 #endif /* __TLMFRAME_H__ */