mirror of
https://github.com/h2zero/esp-nimble-cpp.git
synced 2024-11-23 13:40:55 +01:00
239 lines
16 KiB
HTML
239 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.0"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>esp-nimble-cpp / NimBLE-Arduino: 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 / NimBLE-Arduino
|
|
 <span id="projectnumber">1.3.1</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.0 -->
|
|
<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_docs__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. <br />
|
|
Refer to the <a href="https://h2zero.github.io/esp-nimble-cpp/annotated.html">class documentation</a> for futher information on class specifics. <br />
|
|
</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_md24"></a>
|
|
Server</h1>
|
|
<p><code><a class="el" href="class_nim_b_l_e_characteristic.html#aba05898f446e31222fbe509fa357c730" title="Convenience template to set the characteristic value to <type>val.">NimBLECharacteristic::setValue(const T &s)</a></code> <br />
|
|
<code><a class="el" href="class_nim_b_l_e_descriptor.html#a9136cc9e4b41110b3dd99d1c9553a477" title="Convenience template to set the descriptor value to <type>val.">NimBLEDescriptor::setValue(const T &s)</a></code> <br />
|
|
</p>
|
|
<p>Now use a template to accomodate standard and custom types/values. <br />
|
|
</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><!-- fragment --><p> This will send the struct to the recieving client when read or a notification sent. <br />
|
|
</p>
|
|
<p><code><a class="el" href="class_nim_b_l_e_characteristic.html#a37e908d114f6ad2b4bf19c7cc4db9c54" 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 <br />
|
|
the time the last value was recieved. In addition an overloaded template has been added to retrieve the value <br />
|
|
as a type specified by the user. <br />
|
|
</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> <br />
|
|
</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 <br />
|
|
and all characteristics / descriptors belonging to it and invalidating any pointers to them. <br />
|
|
</p>
|
|
<p>If false the service is only removed from visibility by clients. The pointers to the service and <br />
|
|
it's characteristics / descriptors will remain valid and the service can be re-added in the future <br />
|
|
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_md25"></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 <br />
|
|
that is invoked when advertsing 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). <br />
|
|
</p>
|
|
<p>This provides an opportunity to update the advertisment data if desired. <br />
|
|
</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_md26"></a>
|
|
Client</h1>
|
|
<p><code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#a7e10fa37095d7c80dc36c768fe783e67" title="Read the value of the remote characteristic.">NimBLERemoteCharacteristic::readValue</a>(time_t\*, bool)</code> <br />
|
|
<code><a class="el" href="class_nim_b_l_e_remote_descriptor.html#ac4e3a21818903b69ace41c36a58d3c46" title="A template to convert the remote descriptor data to <type>.">NimBLERemoteDescriptor::readValue(bool)</a></code> <br />
|
|
</p>
|
|
<p>Have been added as templates to allow reading the values as any specified type. <br />
|
|
</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> <br />
|
|
Has been <b>deprecated</b> as now the internally stored characteristic value is updated when notification/indication is recieved. <br />
|
|
</p>
|
|
<p><code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#aa08b2f62376568e1fc833e4ff91e8aa7" title="Subscribe for notifications or indications.">NimBLERemoteCharacteristic::subscribe</a></code> and <code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#a6e331afdbdbc32bf461c9866236a97aa" title="Unsubscribe for notifications or indications.">NimBLERemoteCharacteristic::unsubscribe</a></code> have been implemented to replace it. <br />
|
|
A callback is no longer requred 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#add1a1daed14b5f3e729e284dbd369257" title="Get the value of the remote characteristic.">NimBLERemoteCharacteristic::getValue</a></code> to <br />
|
|
get the last updated value any time. <br />
|
|
<br />
|
|
<br />
|
|
</p>
|
|
<p>The <code>notifiy_callback</code> function is now defined as a <code>std::function</code> to take advantage of using <code>std::bind</code> to specifiy a class member function for the callback. <br />
|
|
</p>
|
|
<p>Example: <br />
|
|
</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"><remoteCharacteristicInstance>->subscribe(true, callback);</div>
|
|
</div><!-- fragment --><p><code><a class="el" href="class_nim_b_l_e_remote_characteristic.html#a7e10fa37095d7c80dc36c768fe783e67" 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#add1a1daed14b5f3e729e284dbd369257" title="Get the value of the remote characteristic.">NimBLERemoteCharacteristic::getValue</a></code> take an optional timestamp parameter which will update it's value with <br />
|
|
the time the last value was recieved. <br />
|
|
</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> <br />
|
|
</p>
|
|
</blockquote>
|
|
<p>These methods will now check the respective vectors for the attribute object and, if not found, will retrieve (only) <br />
|
|
the specified attribute from the peripheral. <br />
|
|
</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#aab311f0a8af21fb63f78e7fbac29951a" 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 <br />
|
|
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_md27"></a>
|
|
General</h1>
|
|
<p>To reduce resource use all instances of <code>std::map</code> have been replaced with <code>std::vector</code>. <br />
|
|
</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. <br />
|
|
</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. <br />
|
|
</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>. <br />
|
|
</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. <br />
|
|
</p>
|
|
<p>Configuration options have been added to add or remove debugging information, when disabled (default) significatly reduces binary size. <br />
|
|
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>. <br />
|
|
<br />
|
|
<br />
|
|
</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.0 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|