Do not delete client instances unless necessary or unused</h1>
<p>When a client instance has been created and has connected to a peer device and it has retrieved service/characteristic information it will store that data for the life of the client instance. <br/>
If you are periodically connecting to the same devices and you have deleted the client instance or the services when connecting again it will cause a retrieval of that information from the peer again. <br/>
This results in significant energy drain on the battery of the devices, fragments heap, and reduces connection performance. <br/>
<p>Client instances in this library use approximately 20% of the original bluedroid library, deleting them will provide much less gain than it did before. <br/>
<p>As a client the use of <code>NimBLEClient::getServices</code> or <code>NimBLERemoteService::getCharacteristics</code> and using <code>true</code> for the parameter should be limited to devices that are not known. <br/>
Instead <code>NimBLEClient::getService(NimBLEUUID)</code> or <code>NimBLERemoteService::getCharacteristic(NimBLEUUID)</code> should be used to access certain attributes that are useful to the application. <br/>
This reduces energy consumed, heap allocated, connection time and improves overall efficiency. <br/>
<p>Many user issues can be avoided by checking if a function returned successfully, by either testing for true/false such as when calling <code>NimBLEClient::connect</code>, <br/>
or nullptr such as when calling <code>NimBLEClient::getService</code>. The latter being a must, as calling a method on a nullptr will surely result in a crash. <br/>
Persisted bonds can be lost due to low MAX_CCCDS</h1>
<p>The symptom: CONFIG_BT_NIMBLE_MAX_BONDS is set to N, but a smaller number of bonds is preserved, perhaps even a single bond. The limitation of persisted bonds can be observed via NimBLEDevice::getNumBonds(). The number may not reach CONFIG_BT_NIMBLE_MAX_BONDS.</p>
<p>Cause: For each bond, NimBLE persists each of the CCCD (client characteristic configuration descriptor) values that have been subscribed to by the client. If CONFIG_BT_NIMBLE_MAX_CCCDS is too low, the older CCCD values are overwritten by the newer ones. The loss of the older CCCDs values results in those bonds being lost.</p>
<p>Fix: Increase CONFIG_BT_NIMBLE_MAX_CCCDS. These take approximately 40 bytes in NVS, 2 bytes for the CCCD value and the NVS metadata overhead. The value of CONFIG_BT_NIMBLE_MAX_CCCDS should conservatively be no less than (CONFIG_BT_NIMBLE_MAX_BONDS * {maximum number of characteristics that can be subscribed to}).</p>
<h1><aclass="anchor"id="device-local-name"></a>
Device 'Local Name'</h1>
<p>'Local name' refers to how the device is seen and displayed.</p>
<p>A devices 'Local name' can be thought of as coming from two places, the <em>Advertising "Local name"</em> and the <em>the GATT Device Name</em>.</p>
<p>Field found in the advertising data payload. Value is set via <aclass="el"href="class_nim_b_l_e_advertising.html#a7fb4b74eb7acb1f46e57ff772baccd88"title="Set the advertised name of the device.">NimBLEAdvertising::setName()</a>.</p>
<h2><aclass="anchor"id="gatt-device-name"></a>
GATT Device Name</h2>
<p>Characteristic UUID 0x2A00 in the Generic Access service. Set via <aclass="el"href="class_nim_b_l_e_device.html#a2e8bb71daabbffd9eab8787493a45ce7"title="Initialize the BLE environment.">NimBLEDevice::init()</a> or <aclass="el"href="class_nim_b_l_e_device.html#aaa64b6baff54c010eb8b4d0ba338cc01"title="Set the BLEDevice name.">NimBLEDevice::setDeviceName()</a>.</p>
<p>This characteristic is read <b>after</b> connecting to the device.</p>
<li>OSes cache the <em>'GATT Device Name'</em>.</li>
<li>OSes update the device name based on the <em>'GATT Device Name'</em> after connecting to a device. This means that if you set the <em>Advertising 'Local name'</em> to "ABCD" but the <em>'GATT Device Name'</em> to "12345", the device will be seen as "ABCD" until connecting to the device, at which time the devices name will change to "12345".</li>
<li>If no <em>'Advertising "Local name"'</em> is set, OSes, such as iOS, may display the devices name as 'Unnamed' until the device is connected to, at which time the <em>'GATT Device Name'</em> is read and used instead.</li>
</ul>
<p>It is recommended that both <em>'Advertising "Local name"'</em><b>and</b><em>'GATT Device Name'</em> be set appropriately, after considering the above described behavior.</p>
<p>No code is bug free and unit testing will not find them all on it's own. If you encounter a bug, please report it along with any logs and decoded backtrace if applicable. <br/>
Best efforts will be made to correct any errors ASAP. <br/>
</p>
<p>Bug reports can be made at <ahref="https://github.com/h2zero/NimBLE-Arduino/issues">https://github.com/h2zero/NimBLE-Arduino/issues</a> or <ahref="https://github.com/h2zero/esp-nimble-cpp/issues">https://github.com/h2zero/esp-nimble-cpp/issues</a>. <br/>
Questions and suggestions will be happily accepted there as well. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<divid="nav-path"class="navpath"><!-- id is needed for treeview function! -->
<liclass="footer">Generated by <ahref="https://www.doxygen.org/index.html"><imgclass="footer"src="doxygen.svg"width="104"height="31"alt="doxygen"/></a> 1.9.8 </li>
