Kenji Arai / mbed-os_TYBLE16

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.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/FEATURE_BLE/ble/gap/AdvertisingDataSimpleBuilder.h@0:5b88d5760320, 2019-12-17 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 17 23:23:45 2019 +0000
Revision:
0:5b88d5760320
mbed-os5 only for TYBLE16

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kenjiArai 0:5b88d5760320 1 /* mbed Microcontroller Library
kenjiArai 0:5b88d5760320 2 * Copyright (c) 2006-2013 ARM Limited
kenjiArai 0:5b88d5760320 3 *
kenjiArai 0:5b88d5760320 4 * Licensed under the Apache License, Version 2.0 (the "License");
kenjiArai 0:5b88d5760320 5 * you may not use this file except in compliance with the License.
kenjiArai 0:5b88d5760320 6 * You may obtain a copy of the License at
kenjiArai 0:5b88d5760320 7 *
kenjiArai 0:5b88d5760320 8 * http://www.apache.org/licenses/LICENSE-2.0
kenjiArai 0:5b88d5760320 9 *
kenjiArai 0:5b88d5760320 10 * Unless required by applicable law or agreed to in writing, software
kenjiArai 0:5b88d5760320 11 * distributed under the License is distributed on an "AS IS" BASIS,
kenjiArai 0:5b88d5760320 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
kenjiArai 0:5b88d5760320 13 * See the License for the specific language governing permissions and
kenjiArai 0:5b88d5760320 14 * limitations under the License.
kenjiArai 0:5b88d5760320 15 */
kenjiArai 0:5b88d5760320 16
kenjiArai 0:5b88d5760320 17 #ifndef BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
kenjiArai 0:5b88d5760320 18 #define BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
kenjiArai 0:5b88d5760320 19
kenjiArai 0:5b88d5760320 20 #include "ble/gap/AdvertisingDataBuilder.h"
kenjiArai 0:5b88d5760320 21
kenjiArai 0:5b88d5760320 22 namespace ble {
kenjiArai 0:5b88d5760320 23
kenjiArai 0:5b88d5760320 24 /**
kenjiArai 0:5b88d5760320 25 * @addtogroup ble
kenjiArai 0:5b88d5760320 26 * @{
kenjiArai 0:5b88d5760320 27 * @addtogroup gap
kenjiArai 0:5b88d5760320 28 * @{
kenjiArai 0:5b88d5760320 29 */
kenjiArai 0:5b88d5760320 30
kenjiArai 0:5b88d5760320 31 /**
kenjiArai 0:5b88d5760320 32 * Build advertising data.
kenjiArai 0:5b88d5760320 33 *
kenjiArai 0:5b88d5760320 34 * It is a simplified version of AdvertisingDataBuilder that can generate
kenjiArai 0:5b88d5760320 35 * advertising data "inline".
kenjiArai 0:5b88d5760320 36 *
kenjiArai 0:5b88d5760320 37 * It differs from AdvertisingDataBuilder on the following points:
kenjiArai 0:5b88d5760320 38 * - The buffer used to build the advertising data is embedded in the object.
kenjiArai 0:5b88d5760320 39 * - If insertion fails, an assertion is raised. Outside of debug mode, if an
kenjiArai 0:5b88d5760320 40 * insertion fails, the buffer is not modified.
kenjiArai 0:5b88d5760320 41 * - The API is fluent.
kenjiArai 0:5b88d5760320 42 * - It hides advanced functions.
kenjiArai 0:5b88d5760320 43 *
kenjiArai 0:5b88d5760320 44 * @code
kenjiArai 0:5b88d5760320 45 void setupAdvertisingData(ble::Gap& gap)
kenjiArai 0:5b88d5760320 46 {
kenjiArai 0:5b88d5760320 47 using namespace ble;
kenjiArai 0:5b88d5760320 48 gap.setAdvertisingPayload(
kenjiArai 0:5b88d5760320 49 LEGACY_ADVERTISING_HANDLE,
kenjiArai 0:5b88d5760320 50 AdvertisingDataSimpleBuilder<LEGACY_ADVERTISING_MAX_SIZE>()
kenjiArai 0:5b88d5760320 51 .setFlags()
kenjiArai 0:5b88d5760320 52 .setName("My device", true)
kenjiArai 0:5b88d5760320 53 .setAppearance(adv_data_appearance_t::GENERIC_HEART_RATE_SENSOR)
kenjiArai 0:5b88d5760320 54 .setLocalService(ATT_UUID_HEART_RATE_SERVICE)
kenjiArai 0:5b88d5760320 55 .getAdvertisingData()
kenjiArai 0:5b88d5760320 56 );
kenjiArai 0:5b88d5760320 57 }
kenjiArai 0:5b88d5760320 58 * @endcode
kenjiArai 0:5b88d5760320 59 */
kenjiArai 0:5b88d5760320 60 template<size_t DataSize>
kenjiArai 0:5b88d5760320 61 class AdvertisingDataSimpleBuilder {
kenjiArai 0:5b88d5760320 62 public:
kenjiArai 0:5b88d5760320 63 /**
kenjiArai 0:5b88d5760320 64 * Construct a AdvertisingDataSimpleBuilder
kenjiArai 0:5b88d5760320 65 */
kenjiArai 0:5b88d5760320 66 AdvertisingDataSimpleBuilder() : _builder(_buffer)
kenjiArai 0:5b88d5760320 67 {
kenjiArai 0:5b88d5760320 68 }
kenjiArai 0:5b88d5760320 69
kenjiArai 0:5b88d5760320 70 /**
kenjiArai 0:5b88d5760320 71 * Add device appearance in the advertising payload.
kenjiArai 0:5b88d5760320 72 *
kenjiArai 0:5b88d5760320 73 * @param[in] appearance The appearance to advertise.
kenjiArai 0:5b88d5760320 74 *
kenjiArai 0:5b88d5760320 75 * @return A reference to this object.
kenjiArai 0:5b88d5760320 76 *
kenjiArai 0:5b88d5760320 77 * @note If the field is already present in the payload, it is replaced.
kenjiArai 0:5b88d5760320 78 */
kenjiArai 0:5b88d5760320 79 AdvertisingDataSimpleBuilder &setAppearance(adv_data_appearance_t appearance)
kenjiArai 0:5b88d5760320 80 {
kenjiArai 0:5b88d5760320 81 ble_error_t res = _builder.setAppearance(appearance);
kenjiArai 0:5b88d5760320 82 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 83 return *this;
kenjiArai 0:5b88d5760320 84 }
kenjiArai 0:5b88d5760320 85
kenjiArai 0:5b88d5760320 86 /**
kenjiArai 0:5b88d5760320 87 * Add BLE flags in the advertising payload.
kenjiArai 0:5b88d5760320 88 *
kenjiArai 0:5b88d5760320 89 * @param[in] flags Bitfield describing the capability of the device. See
kenjiArai 0:5b88d5760320 90 * allowed flags in Flags_t.
kenjiArai 0:5b88d5760320 91 *
kenjiArai 0:5b88d5760320 92 * @return A reference to this object.
kenjiArai 0:5b88d5760320 93 *
kenjiArai 0:5b88d5760320 94 * @note If the field is already present in the payload, it is replaced.
kenjiArai 0:5b88d5760320 95 */
kenjiArai 0:5b88d5760320 96 AdvertisingDataSimpleBuilder &setFlags(
kenjiArai 0:5b88d5760320 97 adv_data_flags_t flags = adv_data_flags_t::default_flags
kenjiArai 0:5b88d5760320 98 )
kenjiArai 0:5b88d5760320 99 {
kenjiArai 0:5b88d5760320 100 ble_error_t res = _builder.setFlags(flags);
kenjiArai 0:5b88d5760320 101 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 102 return *this;
kenjiArai 0:5b88d5760320 103 }
kenjiArai 0:5b88d5760320 104
kenjiArai 0:5b88d5760320 105 /**
kenjiArai 0:5b88d5760320 106 * Add the advertising TX in the advertising payload.
kenjiArai 0:5b88d5760320 107 *
kenjiArai 0:5b88d5760320 108 * @param[in] txPower Transmission power level in dB.
kenjiArai 0:5b88d5760320 109 *
kenjiArai 0:5b88d5760320 110 * @return A reference to this object.
kenjiArai 0:5b88d5760320 111 *
kenjiArai 0:5b88d5760320 112 * @note If the field is already present in the payload, it is replaced.
kenjiArai 0:5b88d5760320 113 */
kenjiArai 0:5b88d5760320 114 AdvertisingDataSimpleBuilder &setTxPowerAdvertised(advertising_power_t txPower)
kenjiArai 0:5b88d5760320 115 {
kenjiArai 0:5b88d5760320 116 ble_error_t res = _builder.setTxPowerAdvertised(txPower);
kenjiArai 0:5b88d5760320 117 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 118 return *this;
kenjiArai 0:5b88d5760320 119 }
kenjiArai 0:5b88d5760320 120
kenjiArai 0:5b88d5760320 121 /**
kenjiArai 0:5b88d5760320 122 * Add device name to the advertising payload.
kenjiArai 0:5b88d5760320 123 *
kenjiArai 0:5b88d5760320 124 * @note Data size for individual types cannot exceed 255 bytes.
kenjiArai 0:5b88d5760320 125 *
kenjiArai 0:5b88d5760320 126 * @param[in] name Null terminated string containing the name.
kenjiArai 0:5b88d5760320 127 * @param[in] complete Complete local name if true, otherwise
kenjiArai 0:5b88d5760320 128 *
kenjiArai 0:5b88d5760320 129 * @return A reference to this object.
kenjiArai 0:5b88d5760320 130 *
kenjiArai 0:5b88d5760320 131 * @note If the field is already present in the payload, it is replaced.
kenjiArai 0:5b88d5760320 132 */
kenjiArai 0:5b88d5760320 133 AdvertisingDataSimpleBuilder &setName(const char *name, bool complete = true)
kenjiArai 0:5b88d5760320 134 {
kenjiArai 0:5b88d5760320 135 ble_error_t res = _builder.setName(name, complete);
kenjiArai 0:5b88d5760320 136 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 137 return *this;
kenjiArai 0:5b88d5760320 138 }
kenjiArai 0:5b88d5760320 139
kenjiArai 0:5b88d5760320 140 /**
kenjiArai 0:5b88d5760320 141 * Add manufacturer specific data to the advertising payload.
kenjiArai 0:5b88d5760320 142 *
kenjiArai 0:5b88d5760320 143 * @note Data size for individual types cannot exceed 255 bytes.
kenjiArai 0:5b88d5760320 144 *
kenjiArai 0:5b88d5760320 145 * @param[in] data New data to be added.
kenjiArai 0:5b88d5760320 146 *
kenjiArai 0:5b88d5760320 147 * @return a reference to this object.
kenjiArai 0:5b88d5760320 148 */
kenjiArai 0:5b88d5760320 149 AdvertisingDataSimpleBuilder &setManufacturerSpecificData(mbed::Span<const uint8_t> data)
kenjiArai 0:5b88d5760320 150 {
kenjiArai 0:5b88d5760320 151 ble_error_t res = _builder.setManufacturerSpecificData(data);
kenjiArai 0:5b88d5760320 152 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 153 return *this;
kenjiArai 0:5b88d5760320 154 }
kenjiArai 0:5b88d5760320 155
kenjiArai 0:5b88d5760320 156 /**
kenjiArai 0:5b88d5760320 157 * Add advertising interval to the payload. This field can only carry 2 bytes.
kenjiArai 0:5b88d5760320 158 *
kenjiArai 0:5b88d5760320 159 * @param interval Interval to advertise. Cannot be larger than 0xFFFF.
kenjiArai 0:5b88d5760320 160 *
kenjiArai 0:5b88d5760320 161 * @return a reference to this object.
kenjiArai 0:5b88d5760320 162 */
kenjiArai 0:5b88d5760320 163 AdvertisingDataSimpleBuilder &setAdvertisingInterval(adv_interval_t interval)
kenjiArai 0:5b88d5760320 164 {
kenjiArai 0:5b88d5760320 165 ble_error_t res = _builder.setAdvertisingInterval(interval);
kenjiArai 0:5b88d5760320 166 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 167 return *this;
kenjiArai 0:5b88d5760320 168 }
kenjiArai 0:5b88d5760320 169
kenjiArai 0:5b88d5760320 170 /**
kenjiArai 0:5b88d5760320 171 * Add connection interval preferences to the payload
kenjiArai 0:5b88d5760320 172 *
kenjiArai 0:5b88d5760320 173 * @param min Minimum connection interval to advertise.
kenjiArai 0:5b88d5760320 174 * @param max Maximum connection interval to advertise.
kenjiArai 0:5b88d5760320 175 *
kenjiArai 0:5b88d5760320 176 * @return a reference to this object.
kenjiArai 0:5b88d5760320 177 */
kenjiArai 0:5b88d5760320 178 AdvertisingDataSimpleBuilder &setConnectionIntervalPreference(
kenjiArai 0:5b88d5760320 179 conn_interval_t min,
kenjiArai 0:5b88d5760320 180 conn_interval_t max
kenjiArai 0:5b88d5760320 181 )
kenjiArai 0:5b88d5760320 182 {
kenjiArai 0:5b88d5760320 183 ble_error_t res = _builder.setConnectionIntervalPreference(min, max);
kenjiArai 0:5b88d5760320 184 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 185 return *this;
kenjiArai 0:5b88d5760320 186 }
kenjiArai 0:5b88d5760320 187
kenjiArai 0:5b88d5760320 188 /**
kenjiArai 0:5b88d5760320 189 * Add service data to the advertising payload.
kenjiArai 0:5b88d5760320 190 *
kenjiArai 0:5b88d5760320 191 * @note Data size for individual types cannot exceed 255 bytes.
kenjiArai 0:5b88d5760320 192 *
kenjiArai 0:5b88d5760320 193 * @param[in] service UUID of the service.
kenjiArai 0:5b88d5760320 194 * @param[in] data New data to be added.
kenjiArai 0:5b88d5760320 195 *
kenjiArai 0:5b88d5760320 196 * @return A reference to this object.
kenjiArai 0:5b88d5760320 197 */
kenjiArai 0:5b88d5760320 198 AdvertisingDataSimpleBuilder &setServiceData(UUID service, mbed::Span<const uint8_t> data)
kenjiArai 0:5b88d5760320 199 {
kenjiArai 0:5b88d5760320 200 ble_error_t res = _builder.setServiceData(service, data);
kenjiArai 0:5b88d5760320 201 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 202 return *this;
kenjiArai 0:5b88d5760320 203 }
kenjiArai 0:5b88d5760320 204
kenjiArai 0:5b88d5760320 205 /**
kenjiArai 0:5b88d5760320 206 * Add local service ID to the advertising payload. If the data can't fit,
kenjiArai 0:5b88d5760320 207 * no modification will take place.
kenjiArai 0:5b88d5760320 208 *
kenjiArai 0:5b88d5760320 209 * @note Data size for individual types cannot exceed 255 bytes.
kenjiArai 0:5b88d5760320 210 *
kenjiArai 0:5b88d5760320 211 * @param[in] data New data to be added.
kenjiArai 0:5b88d5760320 212 * @param[in] complete True if this is a complete list.
kenjiArai 0:5b88d5760320 213 *
kenjiArai 0:5b88d5760320 214 * @return A reference to this object.
kenjiArai 0:5b88d5760320 215 */
kenjiArai 0:5b88d5760320 216 AdvertisingDataSimpleBuilder &setLocalService(
kenjiArai 0:5b88d5760320 217 const UUID& data,
kenjiArai 0:5b88d5760320 218 bool complete = true
kenjiArai 0:5b88d5760320 219 )
kenjiArai 0:5b88d5760320 220 {
kenjiArai 0:5b88d5760320 221 ble_error_t res = _builder.setLocalServiceList(
kenjiArai 0:5b88d5760320 222 mbed::make_Span(&data, 1), complete
kenjiArai 0:5b88d5760320 223 );
kenjiArai 0:5b88d5760320 224 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 225 return *this;
kenjiArai 0:5b88d5760320 226 }
kenjiArai 0:5b88d5760320 227
kenjiArai 0:5b88d5760320 228
kenjiArai 0:5b88d5760320 229 /**
kenjiArai 0:5b88d5760320 230 * Add local service IDs to the advertising payload. If the data can't fit,
kenjiArai 0:5b88d5760320 231 * no modification will take place.
kenjiArai 0:5b88d5760320 232 *
kenjiArai 0:5b88d5760320 233 * @note Data size for individual types cannot exceed 255 bytes.
kenjiArai 0:5b88d5760320 234 *
kenjiArai 0:5b88d5760320 235 * @param[in] data New data to be added.
kenjiArai 0:5b88d5760320 236 * @param[in] complete True if this is a complete list.
kenjiArai 0:5b88d5760320 237 *
kenjiArai 0:5b88d5760320 238 * @return A reference to this object.
kenjiArai 0:5b88d5760320 239 */
kenjiArai 0:5b88d5760320 240 AdvertisingDataSimpleBuilder &setLocalServiceList(
kenjiArai 0:5b88d5760320 241 mbed::Span<const UUID> data,
kenjiArai 0:5b88d5760320 242 bool complete = true
kenjiArai 0:5b88d5760320 243 )
kenjiArai 0:5b88d5760320 244 {
kenjiArai 0:5b88d5760320 245 ble_error_t res = _builder.setLocalServiceList(data, complete);
kenjiArai 0:5b88d5760320 246 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 247 return *this;
kenjiArai 0:5b88d5760320 248 }
kenjiArai 0:5b88d5760320 249
kenjiArai 0:5b88d5760320 250 /**
kenjiArai 0:5b88d5760320 251 * Add a UUID of a solicited service.
kenjiArai 0:5b88d5760320 252 *
kenjiArai 0:5b88d5760320 253 * @note Data size for individual types cannot exceed 255 bytes.
kenjiArai 0:5b88d5760320 254 *
kenjiArai 0:5b88d5760320 255 * @param[in] data List of 128 or 16 bit service UUIDs.
kenjiArai 0:5b88d5760320 256 *
kenjiArai 0:5b88d5760320 257 * @return A reference to this object.
kenjiArai 0:5b88d5760320 258 */
kenjiArai 0:5b88d5760320 259 AdvertisingDataSimpleBuilder &setRequestedService(const UUID& data)
kenjiArai 0:5b88d5760320 260 {
kenjiArai 0:5b88d5760320 261 ble_error_t res = _builder.setRequestedServiceList(mbed::make_Span(&data, 1));
kenjiArai 0:5b88d5760320 262 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 263 return *this;
kenjiArai 0:5b88d5760320 264 }
kenjiArai 0:5b88d5760320 265
kenjiArai 0:5b88d5760320 266 /**
kenjiArai 0:5b88d5760320 267 * Add a list of UUIDs of solicited services.
kenjiArai 0:5b88d5760320 268 *
kenjiArai 0:5b88d5760320 269 * @note Data size for individual types cannot exceed 255 bytes.
kenjiArai 0:5b88d5760320 270 *
kenjiArai 0:5b88d5760320 271 * @param[in] data List of 128 or 16 bit service UUIDs.
kenjiArai 0:5b88d5760320 272 *
kenjiArai 0:5b88d5760320 273 * @return A reference to this object.
kenjiArai 0:5b88d5760320 274 */
kenjiArai 0:5b88d5760320 275 AdvertisingDataSimpleBuilder &setRequestedServiceList(mbed::Span<const UUID> data)
kenjiArai 0:5b88d5760320 276 {
kenjiArai 0:5b88d5760320 277 ble_error_t res = _builder.setRequestedServiceList(data);
kenjiArai 0:5b88d5760320 278 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 279 return *this;
kenjiArai 0:5b88d5760320 280 }
kenjiArai 0:5b88d5760320 281
kenjiArai 0:5b88d5760320 282 /**
kenjiArai 0:5b88d5760320 283 * Add a new field into the payload. The operation fails if type is already present.
kenjiArai 0:5b88d5760320 284 *
kenjiArai 0:5b88d5760320 285 * @note Data size for individual types cannot exceed 255 bytes.
kenjiArai 0:5b88d5760320 286 *
kenjiArai 0:5b88d5760320 287 * @param[in] advDataType The type of the field to add.
kenjiArai 0:5b88d5760320 288 * @param[in] fieldData Span of data to add.
kenjiArai 0:5b88d5760320 289 *
kenjiArai 0:5b88d5760320 290 * @return A reference to this object.
kenjiArai 0:5b88d5760320 291 */
kenjiArai 0:5b88d5760320 292 AdvertisingDataSimpleBuilder& addData(
kenjiArai 0:5b88d5760320 293 adv_data_type_t advDataType,
kenjiArai 0:5b88d5760320 294 mbed::Span<const uint8_t> fieldData
kenjiArai 0:5b88d5760320 295 )
kenjiArai 0:5b88d5760320 296 {
kenjiArai 0:5b88d5760320 297 ble_error_t res = _builder.addData(advDataType, fieldData);
kenjiArai 0:5b88d5760320 298 MBED_ASSERT(res == BLE_ERROR_NONE);
kenjiArai 0:5b88d5760320 299 return *this;
kenjiArai 0:5b88d5760320 300 }
kenjiArai 0:5b88d5760320 301
kenjiArai 0:5b88d5760320 302 /**
kenjiArai 0:5b88d5760320 303 * Get the subspan of the buffer containing valid data.
kenjiArai 0:5b88d5760320 304 *
kenjiArai 0:5b88d5760320 305 * @return A Span containing the payload.
kenjiArai 0:5b88d5760320 306 */
kenjiArai 0:5b88d5760320 307 mbed::Span<const uint8_t> getAdvertisingData() const
kenjiArai 0:5b88d5760320 308 {
kenjiArai 0:5b88d5760320 309 return _builder.getAdvertisingData();
kenjiArai 0:5b88d5760320 310 }
kenjiArai 0:5b88d5760320 311
kenjiArai 0:5b88d5760320 312 private:
kenjiArai 0:5b88d5760320 313 uint8_t _buffer[DataSize];
kenjiArai 0:5b88d5760320 314 AdvertisingDataBuilder _builder;
kenjiArai 0:5b88d5760320 315 };
kenjiArai 0:5b88d5760320 316
kenjiArai 0:5b88d5760320 317 /**
kenjiArai 0:5b88d5760320 318 * @}
kenjiArai 0:5b88d5760320 319 * @}
kenjiArai 0:5b88d5760320 320 */
kenjiArai 0:5b88d5760320 321
kenjiArai 0:5b88d5760320 322 } // namespace ble
kenjiArai 0:5b88d5760320 323
kenjiArai 0:5b88d5760320 324
kenjiArai 0:5b88d5760320 325 #endif //BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H