mirror of
https://github.com/h2zero/esp-nimble-cpp.git
synced 2024-12-26 04:30:46 +01:00
206 lines
16 KiB
HTML
206 lines
16 KiB
HTML
<!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">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.9.1"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>esp-nimble-cpp: Improvements and updates</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 style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">esp-nimble-cpp
|
|
 <span id="projectnumber">1.4.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.1 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
var searchBox = new SearchBox("searchBox", "search",false,'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:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
$(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:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
$(document).ready(function(){initNavTree('md__improvements_and_updates.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">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<div class="PageDoc"><div class="header">
|
|
<div class="headertitle">
|
|
<div class="title">Improvements and updates </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p>Many improvements have been made to this library vs the original, this is a brief overview of the most significant changes. Refer to the <a href="https://h2zero.github.io/esp-nimble-cpp/annotated.html">class documentation</a> for further information on class specifics.</p>
|
|
<ul>
|
|
<li><a href="#server">Server</a></li>
|
|
<li><a href="#advertising">Advertising</a></li>
|
|
<li><a href="#client">Client</a></li>
|
|
<li><a href="#general">General</a> <br />
|
|
<br />
|
|
</li>
|
|
</ul>
|
|
<p><a class="anchor" id="server"></a> </p>
|
|
<h1><a class="anchor" id="autotoc_md37"></a>
|
|
Server</h1>
|
|
<p><code>NimBLEService::NimBLEService::createCharacteristic</code> takes a 3rd parameter to specify the maximum data size that can be stored by the characteristic. This allows for limiting the RAM use of the characteristic in cases where small amounts of data are expected. <br />
|
|
<br />
|
|
</p>
|
|
<p><code><a class="el" href="class_nim_b_l_e_characteristic.html#aba05898f446e31222fbe509fa357c730" title="Template to set the characteristic value to <type>val.">NimBLECharacteristic::setValue(const T &s)</a></code> <code><a class="el" href="class_nim_b_l_e_descriptor.html#a9136cc9e4b41110b3dd99d1c9553a477" title="Template to set the characteristic value to <type>val.">NimBLEDescriptor::setValue(const T &s)</a></code></p>
|
|
<p>Now use the <code>NimbleAttValue</code> class and templates to accommodate standard and custom types/values.</p>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line">struct my_struct {</div>
|
|
<div class="line"> uint8_t one;</div>
|
|
<div class="line"> uint16_t two;</div>
|
|
<div class="line"> uint32_t four;</div>
|
|
<div class="line"> uint64_t eight;</div>
|
|
<div class="line"> float flt;</div>
|
|
<div class="line">} myStruct;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> myStruct.one = 1;</div>
|
|
<div class="line"> myStruct.two = 2;</div>
|
|
<div class="line"> myStruct.four = 4;</div>
|
|
<div class="line"> myStruct.eight = 8;</div>
|
|
<div class="line"> myStruct.flt = 1234.56;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> pCharacteristic->setValue(myStruct);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> // Arduino String support</div>
|
|
<div class="line"> String myString = "Hello";</div>
|
|
<div class="line"> pCharacteristic->setValue(myString);</div>
|
|
</div><!-- fragment --><p> This will send the struct to the receiving client when read or a notification sent.</p>
|
|
<p><code><a class="el" href="class_nim_b_l_e_characteristic.html#a78484a01350300176033a09180f7207f" title="Retrieve the current value of the characteristic.">NimBLECharacteristic::getValue</a></code> now takes an optional timestamp parameter which will update it's value with the time the last value was received. In addition an overloaded template has been added to retrieve the value as a type specified by the user.</p>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line">time_t timestamp;</div>
|
|
<div class="line">myStruct = pCharacteristic->getValue<myStruct>(&timestamp); // timestamp optional</div>
|
|
</div><!-- fragment --><p> <br />
|
|
</p>
|
|
<p><b>Advertising will automatically start when a client disconnects.</b></p>
|
|
<p>A new method <code><a class="el" href="class_nim_b_l_e_server.html#a6bfd923ecd0ea06d5564343ab7209122" title="Set the server to automatically start advertising when a client disconnects.">NimBLEServer::advertiseOnDisconnect(bool)</a></code> has been implemented to control this, true(default) = enabled. <br />
|
|
<br />
|
|
</p>
|
|
<p><code><a class="el" href="class_nim_b_l_e_server.html#a00c92f62f41ec1c499dfaf042b487d75" title="Remove a service from the server.">NimBLEServer::removeService</a></code> takes an additional parameter <code>bool deleteSvc</code> that if true will delete the service and all characteristics / descriptors belonging to it and invalidating any pointers to them.</p>
|
|
<p>If false the service is only removed from visibility by clients. The pointers to the service and it's characteristics / descriptors will remain valid and the service can be re-added in the future using <code><a class="el" href="class_nim_b_l_e_server.html#a6eda4c9e0ac1dd031c678d4bf7da1d56" title="Adds a service which was either already created but removed from availability, or created and later a...">NimBLEServer::addService</a></code>. <br />
|
|
<br />
|
|
</p>
|
|
<p><a class="anchor" id="advertising"></a> </p>
|
|
<h1><a class="anchor" id="autotoc_md38"></a>
|
|
Advertising</h1>
|
|
<p><code><a class="el" href="class_nim_b_l_e_advertising.html#aeeee5a131b42a4f76010751f4c182e4f" title="Start advertising.">NimBLEAdvertising::start</a></code></p>
|
|
<p>Now takes 2 optional parameters, the first is the duration to advertise for (in seconds), the second is a callback that is invoked when advertising ends and takes a pointer to a <code><a class="el" href="class_nim_b_l_e_advertising.html" title="Perform and manage BLE advertising.">NimBLEAdvertising</a></code> object (similar to the <code><a class="el" href="class_nim_b_l_e_scan.html#a21b1e27816717b77533755f31dfaa820" title="Start scanning.">NimBLEScan::start</a></code> API).</p>
|
|
<p>This provides an opportunity to update the advertisement data if desired.</p>
|
|
<p>Also now returns a bool value to indicate if advertising successfully started or not. <br />
|
|
<br />
|
|
</p>
|
|
<p><a class="anchor" id="client"></a> </p>
|
|
<h1><a class="anchor" id="autotoc_md39"></a>
|
|
Client</h1>
|
|
<p><code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#a417bb44d000758535253488f4d77774a" title="Read the value of the remote characteristic.">NimBLERemoteCharacteristic::readValue</a>(time_t\*, bool)</code> <code><a class="el" href="class_nim_b_l_e_remote_descriptor.html#ac4e3a21818903b69ace41c36a58d3c46" title="Template to convert the remote descriptor data to <type>.">NimBLERemoteDescriptor::readValue(bool)</a></code></p>
|
|
<p>Have been added as templates to allow reading the values as any specified type.</p>
|
|
<p><b>Example</b> </p><div class="fragment"><div class="line">struct my_struct{</div>
|
|
<div class="line"> uint8_t one;</div>
|
|
<div class="line"> uint16_t two;</div>
|
|
<div class="line"> uint32_t four;</div>
|
|
<div class="line"> uint64_t eight;</div>
|
|
<div class="line"> float flt;</div>
|
|
<div class="line">}myStruct;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> time_t timestamp;</div>
|
|
<div class="line"> myStruct = pRemoteCharacteristic->readValue<myStruct>(&timestamp); // timestamp optional</div>
|
|
</div><!-- fragment --><p> <br />
|
|
</p>
|
|
<p><code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#ab4f54eabe90a416546b7b3fc3477f49c" title="backward-compatibility method for subscribe/unsubscribe notifications/indications">NimBLERemoteCharacteristic::registerForNotify</a></code> Has been <b>deprecated</b> as now the internally stored characteristic value is updated when notification/indication is received.</p>
|
|
<p><code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#ad2691a8ea85488c8270f78701352fbb2" title="Subscribe for notifications or indications.">NimBLERemoteCharacteristic::subscribe</a></code> and <code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#ae2791429ba4a8c310ffc24139a985da6" title="Unsubscribe for notifications or indications.">NimBLERemoteCharacteristic::unsubscribe</a></code> have been implemented to replace it. A callback is no longer required to get the most recent value unless timing is important. Instead, the application can call <code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#a6d0779ffe7e89449121428e7fd6083d8" title="Get the value of the remote characteristic.">NimBLERemoteCharacteristic::getValue</a></code> to get the last updated value any time. <br />
|
|
<br />
|
|
</p>
|
|
<p>The <code>notify_callback</code> function is now defined as a <code>std::function</code> to take advantage of using <code>std::bind</code> to specify a class member function for the callback.</p>
|
|
<p>Example: </p><div class="fragment"><div class="line">using namespace std::placeholders;</div>
|
|
<div class="line">notify_callback callback = std::bind(&<ClassName>::<memberFunctionCallbackName>, this, _1, _2, _3, _4);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><remoteCharacteristicInstance>->subscribe(true, callback);</div>
|
|
</div><!-- fragment --><p><code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#a417bb44d000758535253488f4d77774a" title="Read the value of the remote characteristic.">NimBLERemoteCharacteristic::readValue</a></code> and <code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#a6d0779ffe7e89449121428e7fd6083d8" title="Get the value of the remote characteristic.">NimBLERemoteCharacteristic::getValue</a></code> take an optional timestamp parameter which will update it's value with the time the last value was received.</p>
|
|
<blockquote class="doxtable">
|
|
<p><a class="el" href="class_nim_b_l_e_client.html#ae22379ab10bd82932d2303fb3753c366" title="Get the service BLE Remote Service instance corresponding to the uuid.">NimBLEClient::getService</a> <br />
|
|
<a class="el" href="class_nim_b_l_e_remote_service.html#ab12d195a2239a3808d60457184f0c487" title="Get the remote characteristic object for the characteristic UUID.">NimBLERemoteService::getCharacteristic</a> <br />
|
|
<a class="el" href="class_nim_b_l_e_remote_characteristic.html#a6178e1c58361b957be3c48548c1c4366" title="Get the descriptor instance with the given UUID that belongs to this characteristic.">NimBLERemoteCharacteristic::getDescriptor</a> </p>
|
|
</blockquote>
|
|
<p>These methods will now check the respective vectors for the attribute object and, if not found, will retrieve (only) the specified attribute from the peripheral.</p>
|
|
<p>These changes allow more control for the user to manage the resources used for the attributes. <br />
|
|
<br />
|
|
</p>
|
|
<p><code><a class="el" href="class_nim_b_l_e_client.html#ae9b3e8a9b47c7eaad040b485bda958a1" title="Connect to an advertising device.">NimBLEClient::connect()</a></code> can now be called without an address or advertised device parameter. This will connect to the device with the address previously set when last connected or set with <code>NimBLEDevice::setPeerAddress()</code>.</p>
|
|
<p><a class="anchor" id="general"></a> </p>
|
|
<h1><a class="anchor" id="autotoc_md40"></a>
|
|
General</h1>
|
|
<p>To reduce resource use all instances of <code>std::map</code> have been replaced with <code>std::vector</code>.</p>
|
|
<p>Use of <code>FreeRTOS::Semaphore</code> has been removed as it was consuming too much ram, the related files have been left in place to accomodate application use.</p>
|
|
<p>Operators <code>==</code>, <code>!=</code> and <code>std::string</code> have been added to <code><a class="el" href="class_nim_b_l_e_address.html" title="A BLE device address.">NimBLEAddress</a></code> and <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> for easier comparison and logging.</p>
|
|
<p>New constructor for <code><a class="el" href="class_nim_b_l_e_u_u_i_d.html" title="A model of a BLE UUID.">NimBLEUUID(uint32_t, uint16_t, uint16_t, uint64_t)</a></code> added to lower memory use vs string construction. See: <a href="https://github.com/h2zero/NimBLE-Arduino/pull/21">#21</a>.</p>
|
|
<p>Security/pairing operations are now handled in the respective <code><a class="el" href="class_nim_b_l_e_client_callbacks.html" title="Callbacks associated with a BLE client.">NimBLEClientCallbacks</a></code> and <code><a class="el" href="class_nim_b_l_e_server_callbacks.html" title="Callbacks associated with the operation of a BLE server.">NimBLEServerCallbacks</a></code> classes, <code><a class="el" href="class_nim_b_l_e_security.html" title="A class to handle BLE security operations. Deprecated - provided for backward compatibility only.">NimBLESecurity</a></code>(deprecated) remains for backward compatibility.</p>
|
|
<p>Configuration options have been added to add or remove debugging information, when disabled (default) significantly reduces binary size. In ESP-IDF the options are in menuconfig: <code>Main menu -> ESP-NimBLE-cpp configuration</code>. <br />
|
|
For Arduino the options must be commented / uncommented in <a class="el" href="nimconfig_8h.html">nimconfig.h</a>.</p>
|
|
<p>Characteristics and descriptors now use the <code><a class="el" href="class_nim_b_l_e_att_value.html" title="A specialized container class to hold BLE attribute values.">NimBLEAttValue</a></code> class to store their data. This is a polymorphic container class capable of converting to/from many different types efficiently. See: <a href="https://github.com/h2zero/NimBLE-Arduino/pull/286">#286</a> </p>
|
|
</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.1 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|