ScStw/esp-nimble-cpp
2
0
Fork 0
mirror of https://github.com/h2zero/esp-nimble-cpp.git synced 2024-12-26 04:30:46 +01:00
Code Issues Projects Releases Packages Wiki Activity
esp-nimble-cpp/md_1_8x__to2_8x__migration__guide.html
h2zero 059364985d deploy: 275def333c
2024-12-17 01:50:27 +00:00

313 lines
30 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>esp-nimble-cpp: Migrating from 1.x to 2.x</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">esp-nimble-cpp<span id="projectnumber">&#160;2.0.1</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('md_1_8x__to2_8x__migration__guide.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Migrating from 1.x to 2.x</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="migrating-from-1x-to-2x"></a> Nearly all of the codebase has been updated and changed under the surface, which has greatly reduced the resource use of the library and improved it's performance. To be able to support these changes it required various API changes and additions.</p>
<p>This guide will help you migrate your application code to use the new API.</p>
<p>The changes listed here are only the required changes that must be made, and a short overview of options for migrating existing applications.</p>
<ul>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#general-changes">General changes</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#ble-device">BLE Device</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#ble-addresses">BLE Addresses</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#ble-uuids">BLE UUID's</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#server">Server</a><ul>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#services">Services</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#characteristics">Characteristics</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#characteristic-callbacks">Characteristic Callbacks</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#server">Security</a></li>
</ul>
</li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#client">Client</a><ul>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#client-callbacks">Client Callbacks</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#remote-services">Remote Services</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#remote-characteristics">Remote characteristics</a></li>
</ul>
</li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#scan">Scanning</a><ul>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#advertised-device">Advertise device</a></li>
</ul>
</li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#advertising">Advertising</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#beacons">Beacons</a></li>
<li><a class="el" href="md_1_8x__to2_8x__migration__guide.html#utilities">Utilities</a> <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="general-changes"></a>
General changes</h1>
<ul>
<li>All functions that take a time parameter now require the time in milliseconds instead of seconds, i.e. <code>NimBLEScan::start(10000); // 10 seconds</code></li>
<li><code>NimBLESecurity</code> class has been removed it's functionality has been merged into the <code><a class="el" href="class_nim_b_l_e_server.html" title="The model of a BLE server.">NimBLEServer</a></code> and <code><a class="el" href="class_nim_b_l_e_client.html" title="A model of a BLE client.">NimBLEClient</a></code> classes.</li>
<li>All connection oriented callbacks now receive a reference to <code><a class="el" href="class_nim_b_l_e_conn_info.html" title="Connection information.">NimBLEConnInfo</a></code> and the <code>ble_gap_conn_desc</code> parameter has been replaced with <code><a class="el" href="class_nim_b_l_e_conn_info.html" title="Connection information.">NimBLEConnInfo</a></code> in the functions that received it. <br />
For instance <code>onAuthenticationComplete(ble_gap_conn_desc* desc)</code> signature is now <code>onAuthenticationComplete(<a class="el" href="class_nim_b_l_e_conn_info.html" title="Connection information.">NimBLEConnInfo</a>&amp; connInfo)</code> and <br />
<code>NimBLEServerCallbacks::onConnect(NimBLEServer* pServer)</code> signature is now <code><a class="el" href="class_nim_b_l_e_server_callbacks.html#a11d48696c2121eb301a76301555df2c5" title="Handle a client connection. This is called when a client connects.">NimBLEServerCallbacks::onConnect</a>(NimBLEServer* pServer, <a class="el" href="class_nim_b_l_e_conn_info.html" title="Connection information.">NimBLEConnInfo</a>&amp; connInfo)</code>. <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="ble-device"></a>
BLE Device</h1>
<ul>
<li>Ignore list functions and vector have been removed, the application should implement this if desired. It was no longer used by the library.</li>
<li><code><a class="el" href="class_nim_b_l_e_device.html#a8b6b4bedfe37725ed9c20e91a3470005" title="Start the connection securing and authorization for this connection.">NimBLEDevice::startSecurity</a></code> now returns a <code>bool</code>, true on success, instead of an int to be consistent with the rest of the library.</li>
<li><code>NimBLEDevice::getInitialized</code> renamed to <code><a class="el" href="class_nim_b_l_e_device.html#a425561f1e23856756ab9c1c330da5737" title="Check if the initialization is complete.">NimBLEDevice::isInitialized</a></code>.</li>
<li><code><a class="el" href="class_nim_b_l_e_device.html#a2b45ce364bf3ee69959389c8cc70249c" title="Set the transmission power.">NimBLEDevice::setPower</a></code> no longer takes the <code>esp_power_level_t</code> and <code>esp_ble_power_type_t</code>, instead only an integer value in dbm units is accepted, so instead of <code>ESP_PWR_LVL_P9</code> an <code>int8_t</code> value of <code>9</code> would be used for the same result.</li>
<li><code><a class="el" href="class_nim_b_l_e_device.html#a31acb43c150014f06bad74b57c2335ff" title="Sets the address type to use.">NimBLEDevice::setOwnAddrType</a></code> no longer takes a <code>bool nrpa</code> parameter, the random address type will be determined by the bits the in the address instead. <br />
Note: If setting a custom address, it should be set with <code><a class="el" href="class_nim_b_l_e_device.html#a0f6521729222f9e55e40325824786070" title="Set the device address to use.">NimBLEDevice::setOwnAddr</a></code> first before calling <code><a class="el" href="class_nim_b_l_e_device.html#a31acb43c150014f06bad74b57c2335ff" title="Sets the address type to use.">NimBLEDevice::setOwnAddrType</a></code>.</li>
<li><code>NimBLEDevice::getClientListSize</code> replaced with <code><a class="el" href="class_nim_b_l_e_device.html#a0944f3f6eca16ed4b7fd96d88b2906d9" title="Get the number of created client objects.">NimBLEDevice::getCreatedClientCount</a></code>.</li>
<li><code>NimBLEDevice::getClientList</code> was removed and <code><a class="el" href="class_nim_b_l_e_device.html#acb098c56b7d08636e1745052eb184fb2" title="Get a list of connected clients.">NimBLEDevice::getConnectedClients</a></code> can be used instead which returns a <code>std::vector</code> of pointers to the connected client instances. This was done because internally the clients are managed in a <code>std::array</code> which replaced the 'std::list`. <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="ble-addresses"></a>
BLE Addresses</h1>
<p><a class="el" href="class_nim_b_l_e_address.html" title="A BLE device address.">NimBLEAddress</a> comparisons have changed to now consider the address type. If 2 address values are the same but the type is different then they are no longer considered equal. This is a correction to the 1.x version which did not consider the type, whereas the BLE specification states: </p><blockquote class="doxtable">
<p>&zwj;Whenever two device addresses are compared, the comparison shall include the device address type (i.e. if the two addresses have different types, they are different even if the two 48-bit addresses are the same). </p>
</blockquote>
<p>This means that if in your application you create a <a class="el" href="class_nim_b_l_e_address.html" title="A BLE device address.">NimBLEAddress</a> instance and are comparing a scan result or some other address created by the library and you did not define the address type then the comparison may fail. The default address type is public <code>0</code>, whereas many devices use a random <code>1</code> address type. If you experience this issue please create your address instances with the address type specified, i.e. <code><a class="el" href="class_nim_b_l_e_address.html" title="A BLE device address.">NimBLEAddress</a> address("11:22:33:44:55:66", TYPE_HERE)</code></p>
<p><code>NimBLEAddress::getNative</code> has been removed and replaced with <code><a class="el" href="class_nim_b_l_e_address.html#a31b466293f6cb752d5aba6b6ffb95351" title="Get the NimBLE base struct of the address.">NimBLEAddress::getBase</a></code>. This returns a pointer to <code>const ble_addr_t</code> instead of a pointer to the address value that <code>getNative</code> did. The value can be accessed through this struct via <code>ble_addr_t.value</code> and type is in <code>ble_addr_t.type</code>. <br />
<br />
</p>
<h1><a class="anchor" id="ble-uuids"></a>
BLE UUID's</h1>
<ul>
<li><code>NimBLEUUID::getNative</code> method replaced with <code><a class="el" href="class_nim_b_l_e_u_u_i_d.html#a68c61ae225675ac84d60f76058a5bdd4" title="Get a pointer to the NimBLE UUID base structure.">NimBLEUUID::getBase</a></code> which returns a read-only pointer to the underlying <code>ble_uuid_t</code> struct.</li>
<li><code><a class="el" href="class_nim_b_l_e_u_u_i_d.html" title="A model of a BLE UUID.">NimBLEUUID</a></code>; <code>msbFirst</code> parameter has been removed from constructor, caller should reverse the data first or call the new <code><a class="el" href="class_nim_b_l_e_u_u_i_d.html#a9b96d90463f02f6a21afbaebcc242dd9" title="Reverse the byte order of the UUID.">NimBLEUUID::reverseByteOrder</a></code> method after. <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="server"></a>
Server</h1>
<ul>
<li><code><a class="el" href="class_nim_b_l_e_server.html#ac79e828bcc3c45ae817bf51be914bfc0" title="Disconnect the specified client with optional reason.">NimBLEServer::disconnect</a></code> now returns <code>bool</code>, true = success, instead of <code>int</code> to be consistent with the rest of the library.</li>
<li><code>NimBLEServerCallbacks::onMTUChanged</code> renamed to <code><a class="el" href="class_nim_b_l_e_server_callbacks.html#ab702f73e739b4df72e191f47056c01ff" title="Called when the connection MTU changes.">NimBLEServerCallbacks::onMTUChange</a></code> to be consistent with the client callback.</li>
<li><code>NimBLEServer::getPeerIDInfo</code> renamed to <code><a class="el" href="class_nim_b_l_e_server.html#a08916d16ea00b4718bd6241bd407829f" title="Get the connection information of a connected peer by connection handle.">NimBLEServer::getPeerInfoByHandle</a></code> to better describe it's use. <br />
<br />
</li>
</ul>
<h2><a class="anchor" id="services"></a>
Services</h2>
<ul>
<li><code><a class="el" href="class_nim_b_l_e_service.html#a8219ccefd97180bee485b62572c62e58">NimBLEService::getCharacteristics</a></code> now returns a <code>const std::vector&lt;NimBLECharacteristic*&gt;&amp;</code> instead of a copy of the vector. <br />
<br />
</li>
</ul>
<h2><a class="anchor" id="characteristics"></a>
Characteristics</h2>
<ul>
<li><code><a class="el" href="class_nim_b_l_e_characteristic.html#ac4482e038124724d8bb6d147bcdb5481" title="Send a notification.">NimBLECharacteristic::notify</a></code> no longer takes a <code>bool is_notification</code> parameter, instead <code><a class="el" href="class_nim_b_l_e_characteristic.html#aabdc2745d2523239a9ab3f02e39aa3cf" title="Send an indication.">NimBLECharacteristic::indicate</a></code> should be called to send indications. <br />
<br />
</li>
</ul>
<h3><a class="anchor" id="characteristic-callbacks"></a>
Characteristic callbacks</h3>
<ul>
<li><code>NimBLECharacteristicCallbacks::onNotify</code> removed as unnecessary, the library does not call notify without app input.</li>
<li><code><a class="el" href="class_nim_b_l_e_characteristic_callbacks.html#a6f9b1f0f15492e3d47662e5e2ff0baee" title="Callback function to support a Notify/Indicate Status report.">NimBLECharacteristicCallbacks::onStatus</a></code> No longer takes a <code>status</code> parameter, refer to the return code parameter for success/failure. <br />
<br />
</li>
</ul>
<h2><a class="anchor" id="server-security"></a>
Server Security</h2>
<ul>
<li><code>NimBLEServerCallbacks::onPassKeyRequest</code> has been renamed to <code><a class="el" href="class_nim_b_l_e_server_callbacks.html#a45b5fc1c98b287a2ddeab8f2f5b63c4f" title="Called when a client requests a passkey for pairing (display).">NimBLEServerCallbacks::onPassKeyDisplay</a></code> as it is intended that the device should display the passkey for the client to enter.</li>
<li><code><a class="el" href="class_nim_b_l_e_server_callbacks.html#a7cbed42919678d9e8d40b351dec82523" title="Called when the pairing procedure is complete.">NimBLEServerCallbacks::onAuthenticationComplete</a></code> now takes a <code><a class="el" href="class_nim_b_l_e_conn_info.html" title="Connection information.">NimBLEConnInfo</a>&amp;</code> parameter. <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="client"></a>
Client</h1>
<ul>
<li><code><a class="el" href="class_nim_b_l_e_client.html#adefe48b87e8a814e1643cdb8c3759298" title="Get a pointer to the vector of found services.">NimBLEClient::getServices</a></code> now returns a const reference to std::vector&lt;NimBLERemoteService*&gt; instead of a pointer to the internal vector.</li>
<li><code>NimBLEClient::getConnId</code> has been renamed to <code>getConnHandle</code> to be consistent with bluetooth terminology.</li>
<li><code><a class="el" href="class_nim_b_l_e_client.html#a36b298b70a42d32b8d578869b0763140" title="Disconnect from the peer.">NimBLEClient::disconnect</a></code> now returns a <code>bool</code>, true on success, instead of an <code>int</code> to be consistent with the rest of the library. <br />
<br />
</li>
</ul>
<h2><a class="anchor" id="client-callbacks"></a>
Client callbacks</h2>
<ul>
<li><code>NimBLEClientCallbacks::onConfirmPIN</code> renamed to <code><a class="el" href="class_nim_b_l_e_client_callbacks.html#a6e7cfa81cd43420f78d6da727c67928b" title="Called when using numeric comparision for pairing.">NimBLEClientCallbacks::onConfirmPasskey</a></code>, takes a <code><a class="el" href="class_nim_b_l_e_conn_info.html" title="Connection information.">NimBLEConnInfo</a>&amp;</code> parameter and no longer returns a value. This should be used to prompt a user to confirm the pin on the display (YES/NO) after which the response should be sent with <code><a class="el" href="class_nim_b_l_e_device.html#aff35384524ab80a19ce1ef23fdcd970b" title="Inject the provided numeric comparison response into the Security Manager.">NimBLEDevice::injectConfirmPasskey</a></code>.</li>
<li><code>NimBLEClientCallbacks::onPassKeyRequest</code> has been changed to <code><a class="el" href="class_nim_b_l_e_client_callbacks.html#aacb0b757e6e7c7984d8389c83fe1937d" title="Called when server requests a passkey for pairing.">NimBLEClientCallbacks::onPassKeyEntry</a></code> which takes a <code><a class="el" href="class_nim_b_l_e_conn_info.html" title="Connection information.">NimBLEConnInfo</a>&amp;</code> parameter and no longer returns a value. Instead of returning a value this callback should prompt a user to enter a passkey number which is sent later via <code><a class="el" href="class_nim_b_l_e_device.html#a5071168b3bda69aa4457a43473ad7a96" title="Inject the provided passkey into the Security Manager.">NimBLEDevice::injectPassKey</a></code>. <br />
<br />
</li>
</ul>
<h2><a class="anchor" id="remote-services"></a>
Remote Services</h2>
<ul>
<li><code><a class="el" href="class_nim_b_l_e_remote_service.html#a5b07f0756c401d40396886e80d64b03b" title="Get a pointer to the vector of found characteristics.">NimBLERemoteService::getCharacteristics</a></code> now returns a <code>const std::vector&lt;NimBLERemoteCharacteristic*&gt;&amp;</code> instead of non-const <code>std::vector&lt;NimBLERemoteCharacteristic*&gt;*</code>. <br />
<br />
</li>
</ul>
<h2><a class="anchor" id="remote-characteristics"></a>
Remote Characteristics</h2>
<ul>
<li><code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#a1b3bbd1bcdde6dd952ee69ebad0ffc58" title="Get the remote service associated with this characteristic.">NimBLERemoteCharacteristic::getRemoteService</a></code> now returns a <code>const NimBLERemoteService*</code> instead of non-const.</li>
<li><code>NimBLERemoteCharacteristic::registerForNotify</code>, has been removed, the application should use <code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#adf445e6bd9dee047a61c708ae943304a" title="Subscribe for notifications or indications.">NimBLERemoteCharacteristic::subscribe</a></code> and <code>NimBLERemoteCharacteristic::unSubscribe</code>. <pre class="fragment"> `NimBLERemoteCharacteristic::readUInt32`
`NimBLERemoteCharacteristic::readUInt16`
`NimBLERemoteCharacteristic::readUInt8`
`NimBLERemoteCharacteristic::readFloat`
</pre> Have been removed, instead the application should use <code>NimBLERemoteCharacteristic::readValue&lt;type\&gt;</code>. <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="scan"></a>
Scan</h1>
<ul>
<li><code><a class="el" href="class_nim_b_l_e_scan.html#a68fa5cc715f62a9a97ac0dccfb8557c1" title="Stop an in progress scan.">NimBLEScan::stop</a></code> will no longer call the <code>onScanEnd</code> callback as the caller should know it has been stopped either by initiating a connection or calling this function itself.</li>
<li><code>NimBLEScan::clearDuplicateCache</code> has been removed as it was problematic and only for the original esp32. The application should stop and start the scanner for the same effect or call <code><a class="el" href="class_nim_b_l_e_scan.html#ac1307f30a881688d3a4d57bac7abe02c" title="Start scanning.">NimBLEScan::start</a></code> with the new <code>bool restart</code> parameter set to true.</li>
<li><code><a class="el" href="class_nim_b_l_e_scan_results.html#a98b106a3929919bf2c80cc0dfff59ba1" title="Return the specified device at the given index. The index should be between 0 and getCount()-1.">NimBLEScanResults::getDevice</a></code> methods now return <code>const NimBLEAdvertisedDevice*</code> instead of a non-const pointer.</li>
<li><code><a class="el" href="class_nim_b_l_e_scan_results.html" title="A class that contains and operates on the results of a BLE scan.">NimBLEScanResults</a></code> iterators are now <code>const_iterator</code>.</li>
<li><p class="startli">The callback parameter for <code><a class="el" href="class_nim_b_l_e_scan.html#ac1307f30a881688d3a4d57bac7abe02c" title="Start scanning.">NimBLEScan::start</a></code> has been removed and the blocking overload of <code><a class="el" href="class_nim_b_l_e_scan.html#ac1307f30a881688d3a4d57bac7abe02c" title="Start scanning.">NimBLEScan::start</a></code> has been replaced by an overload of <code><a class="el" href="class_nim_b_l_e_scan.html#a2ae53719546e2d410c816e12c56aad61" title="Get the results of the scan.">NimBLEScan::getResults</a></code> with the same parameters.</p>
<p class="startli">So if your code prior was this: </p><pre class="fragment">NimBLEScanResults results = pScan-&gt;start(10, false);
</pre><p> It should now be: </p><pre class="fragment">NimBLEScanResults results = pScan-&gt;getResults(10000, false); // note the time is now in milliseconds
</pre></li>
<li><code>NimBLEAdvertisedDeviceCallbacks</code> Has been replaced by <code><a class="el" href="class_nim_b_l_e_scan_callbacks.html" title="A callback handler for callbacks associated device scanning.">NimBLEScanCallbacks</a></code> which contains the following methods:</li>
<li>- <code><a class="el" href="class_nim_b_l_e_scan_callbacks.html#a962d8b08cf14ac3091e6fd6962d7e283" title="Called when a new scan result is complete, including scan response data (if applicable).">NimBLEScanCallbacks::onResult</a></code>, functions the same as the old <code>NimBLEAdvertisedDeviceCallbacks::onResult</code> but now takes aa <code>const NimBLEAdvertisedDevice*</code> instead of non-const.</li>
<li>- <code><a class="el" href="class_nim_b_l_e_scan_callbacks.html#a61c11db405e87ec847066ca3b6ad8375" title="Called when a scan operation ends.">NimBLEScanCallbacks::onScanEnd</a></code>, replaces the scanEnded callback passed to <code><a class="el" href="class_nim_b_l_e_scan.html#ac1307f30a881688d3a4d57bac7abe02c" title="Start scanning.">NimBLEScan::start</a></code> and now takes a <code>const <a class="el" href="class_nim_b_l_e_scan_results.html" title="A class that contains and operates on the results of a BLE scan.">NimBLEScanResults</a>&amp;</code> and <code>int reason</code> parameter.</li>
<li>- <code><a class="el" href="class_nim_b_l_e_scan_callbacks.html#a1f9b5eac5982340afbb84954a4c06277" title="Called when a new device is discovered, before the scan result is received (if applicable).">NimBLEScanCallbacks::onDiscovered</a></code>, This is called immediately when a device is first scanned, before any scan response data is available and takes a <code>const NimBLEAdvertisedDevice*</code> parameter. <br />
<br />
</li>
</ul>
<h2><a class="anchor" id="advertised-device"></a>
Advertised Device</h2>
<ul>
<li><code>NimBLEAdvertisedDevice::hasRSSI</code> removed as redundant, RSSI is always available.</li>
<li><code><a class="el" href="class_nim_b_l_e_advertised_device.html#a12971984cf749647c659b659bdfeda5d" title="Get the payload advertised by the device.">NimBLEAdvertisedDevice::getPayload</a></code> now returns <code>const std::vector&lt;uint8_t&gt;&amp;</code> instead of a pointer to internal memory.</li>
<li><code><a class="el" href="class_nim_b_l_e_advertised_device.html" title="A representation of a BLE advertised device found by a scan.">NimBLEAdvertisedDevice</a></code> Timestamp removed, if needed then the app should track the time from the callback. <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="advertising"></a>
Advertising</h1>
<ul>
<li><code>NimBLEAdvertising::setMinPreferred</code> and <code>NimBLEAdvertising::setMaxPreferred</code> have been removed and replaced by <code><a class="el" href="class_nim_b_l_e_advertising.html#a9dbb66ca66aa040731fcfd737f881469" title="Set the preferred min and max connection intervals to advertise.">NimBLEAdvertising::setPreferredParams</a></code> which takes both the min and max parameters.</li>
<li>Advertising the name and TX power of the device will no longer happen by default and should be set manually by the application using <code><a class="el" href="class_nim_b_l_e_advertising.html#a7fb4b74eb7acb1f46e57ff772baccd88" title="Set the advertised name of the device.">NimBLEAdvertising::setName</a></code> and <code><a class="el" href="class_nim_b_l_e_advertising.html#a0d3c5cb3a93416a4206abb1f8e443ebf" title="Add the transmission power level to the advertisement packet.">NimBLEAdvertising::addTxPower</a></code>.</li>
<li><code>NimBLEAdvertising::setAdvertisementType</code> has been renamed to <code><a class="el" href="class_nim_b_l_e_advertising.html#ae49d2bd91cabca46ec7c4bbd7fc49407" title="Set the type of connectable mode to advertise.">NimBLEAdvertising::setConnectableMode</a></code> to better reflect it's function.</li>
<li><code>NimBLEAdvertising::setScanResponse</code> has been renamed to <code><a class="el" href="class_nim_b_l_e_advertising.html#a6badd669ddf4ff8507561d5041d093d6" title="Enable scan response data.">NimBLEAdvertising::enableScanResponse</a></code> to better reflect it's function.</li>
<li><code><a class="el" href="class_nim_b_l_e_advertising.html" title="Perform and manage BLE advertising.">NimBLEAdvertising</a></code>; Scan response is no longer enabled by default.</li>
<li><code><a class="el" href="class_nim_b_l_e_advertising.html#a8a5c880ee36fd44e0c72c14c47c8e15e" title="Start advertising.">NimBLEAdvertising::start</a></code> No longer takes a callback pointer parameter, instead the new method <code><a class="el" href="class_nim_b_l_e_advertising.html#a3e81d7d3aa2b72b8db58427d4a42727b" title="Set the callback to be invoked when advertising stops.">NimBLEAdvertising::setAdvertisingCompleteCallback</a></code> should be used to set the callback function. <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="beacons"></a>
Beacons</h1>
<ul>
<li>Removed Eddystone URL as it has been shutdown by google since 2021.</li>
<li><code><a class="el" href="class_nim_b_l_e_eddystone_t_l_m.html#af5ff73359f3c7f7e76395d32f4efe575" title="Set the temperature to advertise.">NimBLEEddystoneTLM::setTemp</a></code> now takes an <code>int16_t</code> parameter instead of float to be friendly to devices without floating point support.</li>
<li><code><a class="el" href="class_nim_b_l_e_eddystone_t_l_m.html#a72589029e329c3939b05f9df5e8113ce" title="Get the temperature being advertised.">NimBLEEddystoneTLM::getTemp</a></code> now returns <code>int16_t</code> to work with devices that don't have floating point support.</li>
<li><code><a class="el" href="class_nim_b_l_e_eddystone_t_l_m.html#a05989cc6df5d5dc423c878d2317ddb89" title="Set the raw data for the beacon advertisement.">NimBLEEddystoneTLM::setData</a></code> now takes a reference to * <code>NimBLEEddystoneTLM::BeaconData</code> instead of <code>std::string</code>.</li>
<li><code><a class="el" href="class_nim_b_l_e_eddystone_t_l_m.html#a32c448f92ce2e61a9589d1cb0d149d07" title="Retrieve the data that is being advertised.">NimBLEEddystoneTLM::getData</a></code> now returns a reference to * <code>NimBLEEddystoneTLM::BeaconData</code> instead of <code>std::string</code>.</li>
<li><code><a class="el" href="class_nim_b_l_e_beacon.html#ab6475aaa5d8a93e24401da3b4b272496" title="Set the beacon data.">NimBLEBeacon::setData</a></code> now takes <code>const NimBLEBeacon::BeaconData&amp;</code> instead of <code>std::string</code>.</li>
<li><code><a class="el" href="class_nim_b_l_e_beacon.html#a8ac2cd99dd5a8a996f3556f9e5d20bbb" title="Retrieve the data that is being advertised.">NimBLEBeacon::getData</a></code> now returns <code>const NimBLEBeacon::BeaconData&amp;</code> instead of <code>std::string</code>. <br />
<br />
</li>
</ul>
<h1><a class="anchor" id="utilities"></a>
Utilities</h1>
<ul>
<li><code>NimBLEUtils::dumpGapEvent</code> function removed.</li>
<li><code>NimBLEUtils::buildHexData</code> replaced with <code><a class="el" href="class_nim_b_l_e_utils.html#a53f0b19687b0706ec48d6b630e209acb" title="Create a hexadecimal string representation of the input data.">NimBLEUtils::dataToHexString</a></code>, which returns a <code>std::string</code> containing the hex string. <br />
<br />
</li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8 </li>
</ul>
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink