<divclass="textblock"><p><b>Note:</b> If you are migrating an existing project from the original Bluedroid library please see the <aclass="el"href="md__migration_guide.html">Migration Guide.</a><br/>
<p>At the top of your application file add <code>#include <aclass="el"href="_nim_b_l_e_device_8h_source.html">NimBLEDevice.h</a></code>, this is the only header required and provides access to all classes. <br/>
<p>In order to perform any BLE tasks you must first initialize the library, this prepares the NimBLE stack to be ready for commands. <br/>
</p>
<p>To do this you must call <code><aclass="el"href="class_nim_b_l_e_device.html#a674d2e68d4ba0e3f84d7993f9da7d15b"title="Initialize the BLE environment.">NimBLEDevice::init</a>("your device name here")</code>, the parameter passed is a character string containing the name you want to advertise. <br/>
If you're not creating a server or do not want to advertise a name, simply pass an empty string for the parameter. <br/>
</p>
<p>This can be called any time you wish to use BLE functions and does not need to be called from app_main(IDF) or setup(Arduino) but usually is. <br/>
<p>BLE servers perform 2 tasks, they advertise their existance for clients to find them and they provide services which contain information for the connecting client. <br/>
</p>
<p>After initializing the NimBLE stack we create a server by calling <code><aclass="el"href="class_nim_b_l_e_device.html#a4d9780d0b5fafc279483822af802a508"title="Create a new instance of a server.">NimBLEDevice::createServer()</a></code>, this will create a server instance and return a pointer to it. <br/>
</p>
<p>Once we have created the server we need to tell it the services it hosts. <br/>
To do this we call <code><aclass="el"href="class_nim_b_l_e_server.html#aaeb58b4de85754d1aac6964e9248aa35"title="Create a BLE Service.">NimBLEServer::createService(const char* uuid)</a></code>. Which returns a pointer to an instance of <code><aclass="el"href="class_nim_b_l_e_service.html"title="The model of a BLE service.">NimBLEService</a></code>. <br/>
The <code>uuid</code> parameter is a hexadecimal string with the uuid we want to give the service, it can be 16, 32, or 128 bits. <br/>
</p>
<p>For this example we will keep it simple and use a 16 bit value: ABCD. <br/>
</div><!-- fragment --><p>Now we have NimBLE initialized, a server created and a service assigned to it. <br/>
We can't do much with this yet so now we should add a characteristic to the service to provide some data. <br/>
</p>
<p>Next we call <code><aclass="el"href="class_nim_b_l_e_service.html#adab5552c080b9cb88095af262d326309"title="Create a new BLE Characteristic associated with this service.">NimBLEService::createCharacteristic</a></code> which returns a pointer to an instance of <code><aclass="el"href="class_nim_b_l_e_characteristic.html"title="The model of a BLE Characteristic.">NimBLECharacteristic</a></code>, and takes two parameters: A <code>uuid</code> to specify the UUID of the characteristic and a bitmask of the properties we want applied to it. <br/>
</p>
<p>Just as with the service UUID we will use a simple 16 bit value: 1234. <br/>
The properties bitmask is a little more involved. It is a combination of NIMBLE_PROPERTY:: values. <br/>
</p>
<p>Here is the list of options: <br/>
</p><blockquoteclass="doxtable">
<p>NIMBLE_PROPERTY::READ <br/>
NIMBLE_PROPERTY::READ_ENC <br/>
NIMBLE_PROPERTY::READ_AUTHEN <br/>
NIMBLE_PROPERTY::READ_AUTHOR <br/>
NIMBLE_PROPERTY::WRITE <br/>
NIMBLE_PROPERTY::WRITE_NR <br/>
NIMBLE_PROPERTY::WRITE_ENC <br/>
NIMBLE_PROPERTY::WRITE_AUTHEN <br/>
NIMBLE_PROPERTY::WRITE_AUTHOR <br/>
NIMBLE_PROPERTY::BROADCAST <br/>
NIMBLE_PROPERTY::NOTIFY <br/>
NIMBLE_PROPERTY::INDICATE <br/>
</p>
</blockquote>
<p>For this example we won't need to specify these as the default value is <code>NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE</code><br/>
which will allow reading and writing values to the characteristic without encryption or security. <br/>
The function call will simply be <code>pService->createCharacteristic("1234");</code><br/>
</div><!-- fragment --><p>All that's left to do now is start the sevice, give the characteristic a value and start advertising for clients. <br/>
</p>
<p>Fist we start the service by calling <code><aclass="el"href="class_nim_b_l_e_service.html#ad37324ed0404d596923d6fdc0133b985"title="Builds the database of characteristics/descriptors for the service and registers it with the NimBLE s...">NimBLEService::start()</a></code>.</p>
<p>Next we need to call <code><aclass="el"href="class_nim_b_l_e_characteristic.html#a7cd211a8bb9a0c2ffaed57f2af273677"title="Set the value of the characteristic.">NimBLECharacteristic::setValue</a></code> to set the characteristic value that the client will read. <br/>
There are many different types you can send as parameters for the value but for this example we will use a simple string. <code>pCharacteristic->setValue("Hello BLE");</code><br/>
</p>
<p>Next we need to advertise for connections. <br/>
To do this we create an instance of <code><aclass="el"href="class_nim_b_l_e_advertising.html"title="Perform and manage BLE advertising.">NimBLEAdvertising</a></code> add our service to it (optional) and start advertisng. <br/>
</div><!-- fragment --><p> That's it, this will be enough to create a BLE server with a service and a characteristic and advertise for client connections. <br/>
</div><!-- fragment --><p>Now if you scan with your phone using nRFConnect or any other BLE app you should see a device named "NimBLE" with a service of "ABCD". <br/>
</p>
<p>For more advanced features and options please see the server examples in the examples folder. <br/>
<p>BLE clients perform 2 tasks, they scan for advertising servers and form connections to them to read and write to their characteristics/descriptors.</p>
<p>After initializing the NimBLE stack we create a scan instance by calling <code><aclass="el"href="class_nim_b_l_e_device.html#af93d92316454b051125460056368baec"title="Retrieve the Scan object that we use for scanning.">NimBLEDevice::getScan()</a></code>, this will create a <code><aclass="el"href="class_nim_b_l_e_scan.html"title="Perform and manage BLE scans.">NimBLEScan</a></code> instance and return a pointer to it. <br/>
</p>
<p>Once we have created the scan we can start looking for advertising servers. <br/>
</p>
<p>To do this we call <code>NimBLEScan::start(duration)</code>, the duration parameter is a uint32_t that specifies the number of seconds to scan for, <br/>
passing 0 will scan forever. <br/>
</p>
<p>In this example we will scan for 10 seconds. This is a blocking function (a non blocking overload is also available). <br/>
This call returns an instance of <code><aclass="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> when the scan completes which can be parsed for advertisers we are interested in. <br/>
<p>Now that we have scanned we need to check the results for any advertisers we are interested in connecting to. <br/>
</p>
<p>To do this we iterate through the results and check if any of the devices found are advertising the service we want <code>ABCD</code>. <br/>
Each result in <code><aclass="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> is a <code><aclass="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> instance that we can access data from.</p>
<p>We will check each device found for the <code>ABCD</code> service by calling <code><aclass="el"href="class_nim_b_l_e_advertised_device.html#a37ad095c066aa231a52a7259734c9bce"title="Check advertised services for existance of the required UUID.">NimBLEAdvertisedDevice::isAdvertisingService</a></code>. <br/>
This takes an instance of <code><aclass="el"href="class_nim_b_l_e_u_u_i_d.html"title="A model of a BLE UUID.">NimBLEUUID</a></code> as a parameter so we will need to create one. <br/>
</p>
<p><b>The code for this looks like:</b></p><divclass="fragment"><divclass="line">NimBLEUUID serviceUuid("ABCD");</div>
<divclass="line"></div>
<divclass="line">for(int i = 0; i < results.getCount(); i++) {</div>
<divclass="line"> if (device.isAdvertisingService(serviceUuid)) {</div>
<divclass="line"> // create a client and connect</div>
<divclass="line"> }</div>
<divclass="line">}</div>
</div><!-- fragment --><p><br/>
</p>
<p>Now that we can scan and parse advertisers we need to be able to create a <code><aclass="el"href="class_nim_b_l_e_client.html"title="A model of a BLE client.">NimBLEClient</a></code> instance and use it to connect. <br/>
</p>
<p>To do this we call <code><aclass="el"href="class_nim_b_l_e_device.html#af8142995252f486916dbb9de2a5b0c9e"title="Creates a new client object and maintains a list of all client objects each client can connect to 1 p...">NimBLEDevice::createClient</a></code> which creates the <code><aclass="el"href="class_nim_b_l_e_client.html"title="A model of a BLE client.">NimBLEClient</a></code> instance and returns a pointer to it. <br/>
</p>
<p>After this we call <code><aclass="el"href="class_nim_b_l_e_client.html#aab311f0a8af21fb63f78e7fbac29951a"title="Connect to an advertising device.">NimBLEClient::connect</a></code> to connect to the advertiser. <br/>
This takes a pointer to the <code><aclass="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> and returns <code>true</code> if successful.</p>
<p><b>Lets do that now:</b></p><divclass="fragment"><divclass="line">NimBLEUUID serviceUuid("ABCD");</div>
<divclass="line"></div>
<divclass="line">for(int i = 0; i < results.getCount(); i++) {</div>
</div><!-- fragment --><p> As shown, the call to <code><aclass="el"href="class_nim_b_l_e_client.html#aab311f0a8af21fb63f78e7fbac29951a"title="Connect to an advertising device.">NimBLEClient::connect</a></code> should have it's eturn value tested to make sure it succeeded before proceeding to get data. <br/>
<br/>
</p>
<p>Next we need to access the servers data by asking it for the service and the characteristic we are interested in, then read the characteristic value.</p>
<p>To do this we call <code><aclass="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></code>, which takes as a parameter the UUID of the service and returns <br/>
a pointer an instance to <code><aclass="el"href="class_nim_b_l_e_remote_service.html"title="A model of a remote BLE service.">NimBLERemoteService</a></code> or <code>nullptr</code> if the service was not found. <br/>
</p>
<p>Next we will call <code>NimBLERemoteService::getCharateristic</code> which takes as a parameter the UUID of the service and returns <br/>
a pointer to an instance of <code><aclass="el"href="class_nim_b_l_e_remote_characteristic.html"title="A model of a remote BLE characteristic.">NimBLERemoteCharacteristic</a></code> or <code>nullptr</code> if not found. <br/>
</p>
<p>Finally we will read the characteristic value with <code><aclass="el"href="class_nim_b_l_e_remote_characteristic.html#a7e10fa37095d7c80dc36c768fe783e67"title="Read the value of the remote characteristic.">NimBLERemoteCharacteristic::readValue()</a></code>. <br/>
</p>
<p><b>Here is what that looks like:</b></p><divclass="fragment"><divclass="line">NimBLEUUID serviceUuid("ABCD");</div>
<divclass="line"></div>
<divclass="line">for(int i = 0; i < results.getCount(); i++) {</div>
<divclass="line"> if (pCharacteristic != nullptr) {</div>
<divclass="line"> std::string value = pCharacteristic->readValue();</div>
<divclass="line"> // print or do whatever you need with the value</div>
<divclass="line"> }</div>
<divclass="line"> }</div>
<divclass="line"> } else {</div>
<divclass="line"> // failed to connect</div>
<divclass="line"> }</div>
<divclass="line"> }</div>
<divclass="line">}</div>
</div><!-- fragment --><p><br/>
</p>
<p>The last thing we should do is clean up once we are done with the connection. <br/>
Because multiple clients are supported and can be created we should delete them when finished with them to conserve resources. <br/>
This is done by calling <code><aclass="el"href="class_nim_b_l_e_device.html#a83aa0a3d9d57358d35082a442edf8549"title="Delete the client object and remove it from the list. Checks if it is connected or trying to connect ...">NimBLEDevice::deleteClient</a></code>.</p>
<p><b>Lets add that now:</b></p><divclass="fragment"><divclass="line">NimBLEUUID serviceUuid("ABCD");</div>
<divclass="line"></div>
<divclass="line">for(int i = 0; i < results.getCount(); i++) {</div>
<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.1 </li>
