Update documentation.

* Docuemnt HID device class.

* Add usage tips.

docs/Command_line_config.md

@@ -4,90 +4,89 @@
  
  If defined, NimBLE Client functions will not be included.  
 - Reduces flash size by approx. 7kB.  
-<br>
+<br/>
 
 `CONFIG_BT_NIMBLE_ROLE_OBSERVER_DISABLED`    
 
 If defined, NimBLE Scan functions will not be included.  
 - Reduces flash size by approx. 26kB.  
-<br>
+<br/>
 
 `CONFIG_BT_NIMBLE_ROLE_PERIPHERAL_DISABLED`   
 
 If defined NimBLE Server functions will not be included.  
 - Reduces flash size by approx. 16kB.  
-<br>
+<br/>
 
 `CONFIG_BT_NIMBLE_ROLE_BROADCASTER_DISABLED`    
 
 If defined, NimBLE Advertising functions will not be included.  
 - Reduces flash size by approx. 5kB.  
-<br>
+<br/>
 
 `CONFIG_BT_NIMBLE_DEBUG`   
 
 If defined, enables debug log messages from the NimBLE host  
 - Uses approx. 32kB of flash memory.  
-<br> 
+<br/>
 
 `CONFIG_NIMBLE_CPP_ENABLE_RETURN_CODE_TEXT`  
 
 If defined, NimBLE host return codes will be printed as text in debug log messages.  
 - Uses approx. 7kB of flash memory.  
-<br>  
+<br/>
 
 `CONFIG_NIMBLE_CPP_ENABLE_GAP_EVENT_CODE_TEXT`  
 
 If defined, GAP event codes will be printed as text in debug log messages.  
 - Uses approx. 1kB of flash memory.  
-<br>
+<br/>
 
 `CONFIG_NIMBLE_CPP_ENABLE_ADVERTISMENT_TYPE_TEXT`  
 
 If defined, advertisment types will be printed as text while scanning in debug log messages.  
 - Uses approx. 250 bytes of flash memory.  
-<br>  
+<br/>
 
 `CONFIG_BT_NIMBLE_PINNED_TO_CORE`  
 
 Sets the core the NimBLE host stack will run on   
 - Options: 0 or 1
-<br>
+<br/>
 
 `CONFIG_BT_NIMBLE_TASK_STACK_SIZE`  
 
 Set the task stack size for the NimBLE core.
 - Default is 4096  
-<br>
-
+<br/>
 
 `CONFIG_BT_NIMBLE_MEM_ALLOC_MODE_EXTERNAL`
 
 Sets the NimBLE stack to use external PSRAM will be loaded  
 - Must be defined with a value of 1; Default is CONFIG_BT_NIMBLE_MEM_ALLOC_MODE_INTERNAL 1  
-<br>
+<br/>
 
 `CONFIG_BT_NIMBLE_MAX_CONNECTIONS`
 
 Sets the number of simultaneous connections (esp controller max is 9)  
 - Default value is 3  
-<br>
+<br/>
  
 `CONFIG_BT_NIMBLE_MAX_BONDS`
 
 Sets the number of devices allowed to store/bond with  
 - Default value is 3  
-<br>
+<br/>
 
 `CONFIG_BT_NIMBLE_MAX_CCCDS` 
 
 Sets the maximum number of CCCD subscriptions to store  
 - Default value is 8  
-<br>
+<br/>
  
 `CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME`  
 
 Set the default device name  
 - Default value is "nimble"  
-<br>
+<br/>
 

docs/Improvements_and_updates.md

@@ -69,7 +69,9 @@ Now takes 2 optional parameters, the first is the duration to advertise for (in
 that is invoked when advertsing ends and takes a pointer to a `NimBLEAdvertising` object (similar to the `NimBLEScan::start` API).  
 
 This provides an opportunity to update the advertisment data if desired.  
-<br/>
+
+Also now returns a bool value to indicate if advertising successfully started or not.
+<br/>  
 
 <a name="client"></a>
 # Client  
@@ -100,8 +102,18 @@ Has been **deprecated** as now the internally stored characteristic value is upd
 `NimBLERemoteCharacteristic::subscribe` and `NimBLERemoteCharacteristic::unsubscribe` have been implemented to replace it.  
 A callback is no longer requred to get the most recent value unless timing is important. Instead, the application can call `NimBLERemoteCharacteristic::getValue` to  
 get the last updated value any time.  
+<br/>  
 
-In addition `NimBLERemoteCharacteristic::readValue` and `NimBLERemoteCharacteristic::getValue` take an optional timestamp parameter which will update it's value with  
+The `notifiy_callback` function is now defined as a `std::function` to take advantage of using `std::bind` to specifiy a class member function for the callback.  
+
+Example:  
+```
+using namespace std::placeholders;
+notify_callback callback = std::bind(&<ClassName>::<memberFunctionCallbackName>, this, _1, _2, _3, _4);
+<remoteCharacteristicInstance>->subscribe(true, callback);
+```
+
+`NimBLERemoteCharacteristic::readValue` and `NimBLERemoteCharacteristic::getValue` take an optional timestamp parameter which will update it's value with  
 the time the last value was recieved.  
 
 > NimBLEClient::getService  

docs/Usage_tips.md

@@ -0,0 +1,41 @@
+# Usage Tips
+
+## Put BLE functions in a task running on the NimBLE stack core
+
+When commands are sent to the stack from a differnt core they can experience delays in execution.  
+This library detects this and invokes the esp32 IPC to reroute these commands through the correct core but this also increases overhead.  
+Therefore it is highly recommended to create tasks for BLE to run on the same core, the macro `CONFIG_BT_NIMBLE_PINNED_TO_CORE` can be used to set the core.
+<br/>  
+
+## Do not delete client instances unless necessary or unused
+
+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.  
+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.  
+This results in significant energy drain on the battery of the devices, fragments heap, and reduces connection performance.  
+  
+Client instances in this library use approximately 20% of the original bluedroid library, deleteing them will provide much less gain than it did before.  
+
+It is recommended to retain the client instance in cases where the time between connecting to the same device is less than 5 minutes.  
+<br/>  
+
+## Only retrieve the services and characteriscs needed
+
+As a client the use of `NimBLEClient::getServices` or `NimBLERemoteService::getCharacteristics` and using `true` for the parameter should be limited to devices that are not known.  
+Instead `NimBLEClient::getService(NimBLEUUID)` or `NimBLERemoteService::getCharacteristic(NimBLEUUID)` should be used to access certain attributes that are useful to the application.  
+This reduces energy consumed, heap allocated, connection time and improves overall efficiency.  
+<br/>  
+
+## Check return values
+
+Many user issues can be avoided by checking if a function returned successfully, by either testing for true/false such as when calling `NimBLEClient::connect`,  
+or nullptr such as when  calling `NimBLEClient::getService`. The latter being a must, as calling a method on a nullptr will surely result in a crash.  
+Most of the functions in this library return something that should be checked before proceeding.  
+<br/>  
+
+## There will be bugs - please report them
+
+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.  
+Best efforts will be made to correct any errors ASAP.  
+
+Bug reports can be made at https://github.com/h2zero/NimBLE-Arduino/issues or https://github.com/h2zero/esp-nimble-cpp/issues.  
+Questions and suggestions will be happily accepted there as well.

docs/index.md

@@ -48,7 +48,9 @@ If you have not used the original Bluedroid library please refer to the [New use
 
 If you are familiar with the original library, see: [The migration guide](Migration_guide.md) for details.  
 
-Also see [Improvements_and_updates](Improvements_and_updates.md) for information about non-breaking changes.  
+Also see [Improvements and updates](Improvements_and_updates.md) for information about non-breaking changes.  
+
+For more advanced usage see [Usage tips](Usage_tips.md) for more performance and optimization.
 
 ### Arduino specific
 See the Refactored_original_examples in the examples folder for highlights of the differences with the original library.  
@@ -61,7 +63,7 @@ Change the settings in the nimconfig.h file to customize NimBLE to your project,
 <br/>  
 
 ### Command line and platformio
-See the command line configuration options available in [Command_line_config](Command_line_config.md).  
+See the command line configuration options available in [Command line config](Command_line_config.md).  
 <br/>  
 
 # Acknowledgments

src/NimBLEHIDDevice.cpp

@@ -20,6 +20,10 @@
 #include "NimBLEHIDDevice.h"
 #include "NimBLE2904.h"
 
+/**
+ * @brief Construct a default NimBLEHIDDevice object.
+ * @param [in] server A pointer to the server instance this HID Device will use.
+ */
 NimBLEHIDDevice::NimBLEHIDDevice(NimBLEServer* server) {
 	/*
 	 * Here we create mandatory services described in bluetooth specification
@@ -61,15 +65,18 @@ NimBLEHIDDevice::NimBLEHIDDevice(NimBLEServer* server) {
 NimBLEHIDDevice::~NimBLEHIDDevice() {
 }
 
-/*
- * @brief
+/**
+ * @brief Set the report map data formatting information.
+ * @param [in] map A pointer to an array with the values to set.
+ * @param [in] size The number of values in the array.
  */
 void NimBLEHIDDevice::reportMap(uint8_t* map, uint16_t size) {
 	m_reportMapCharacteristic->setValue(map, size);
 }
 
-/*
- * @brief This function suppose to be called at the end, when we have created all characteristics we need to build HID service
+/**
+ * @brief Start the HID device services.\n
+ * This function called when all the services have been created.
  */
 void NimBLEHIDDevice::startServices() {
 	m_deviceInfoService->start();
@@ -77,41 +84,47 @@ void NimBLEHIDDevice::startServices() {
 	m_batteryService->start();
 }
 
-/*
- * @brief Create manufacturer characteristic (this characteristic is optional)
+/**
+ * @brief Create a manufacturer characteristic (this characteristic is optional).
  */
 NimBLECharacteristic* NimBLEHIDDevice::manufacturer() {
 	m_manufacturerCharacteristic = m_deviceInfoService->createCharacteristic((uint16_t) 0x2a29, NIMBLE_PROPERTY::READ);
 	return m_manufacturerCharacteristic;
 }
 
-/*
+/**
  * @brief Set manufacturer name
- * @param [in] name manufacturer name
+ * @param [in] name The manufacturer name of this HID device.
  */
 void NimBLEHIDDevice::manufacturer(std::string name) {
 	m_manufacturerCharacteristic->setValue(name);
 }
 
-/*
- * @brief
+/**
+ * @brief Sets the Plug n Play characterisc value.
+ * @param [in] sig The vendor ID source number.
+ * @param [in[ vid The vendor ID number.
+ * @param [in] pid The product ID number.
+ * @param [in] version The produce version number.
  */
 void NimBLEHIDDevice::pnp(uint8_t sig, uint16_t vid, uint16_t pid, uint16_t version) {
 	uint8_t pnp[] = { sig, (uint8_t) (vid >> 8), (uint8_t) vid, (uint8_t) (pid >> 8), (uint8_t) pid, (uint8_t) (version >> 8), (uint8_t) version };
 	m_pnpCharacteristic->setValue(pnp, sizeof(pnp));
 }
 
-/*
- * @brief
+/**
+ * @brief Sets the HID Information characteristic value.
+ * @param [in] country The country code for the device.
+ * @param [in] flags The HID Class Specification release number to use.
  */
 void NimBLEHIDDevice::hidInfo(uint8_t country, uint8_t flags) {
 	uint8_t info[] = { 0x11, 0x1, country, flags };
 	m_hidInfoCharacteristic->setValue(info, sizeof(info));
 }
 
-/*
- * @brief Create input report characteristic that need to be saved as new characteristic object so can be further used
- * @param [in] reportID input report ID, the same as in report map for input object related to created characteristic
+/**
+ * @brief Create input report characteristic
+ * @param [in] reportID input report ID, the same as in report map for input object related to the characteristic
  * @return pointer to new input report characteristic
  */
 NimBLECharacteristic* NimBLEHIDDevice::inputReport(uint8_t reportID) {
@@ -124,9 +137,9 @@ NimBLECharacteristic* NimBLEHIDDevice::inputReport(uint8_t reportID) {
 	return inputReportCharacteristic;
 }
 
-/*
- * @brief Create output report characteristic that need to be saved as new characteristic object so can be further used
- * @param [in] reportID Output report ID, the same as in report map for output object related to created characteristic
+/**
+ * @brief Create output report characteristic
+ * @param [in] reportID Output report ID, the same as in report map for output object related to the characteristic
  * @return Pointer to new output report characteristic
  */
 NimBLECharacteristic* NimBLEHIDDevice::outputReport(uint8_t reportID) {
@@ -139,9 +152,9 @@ NimBLECharacteristic* NimBLEHIDDevice::outputReport(uint8_t reportID) {
 	return outputReportCharacteristic;
 }
 
-/*
- * @brief Create feature report characteristic that need to be saved as new characteristic object so can be further used
- * @param [in] reportID Feature report ID, the same as in report map for feature object related to created characteristic
+/**
+ * @brief Create feature report characteristic.
+ * @param [in] reportID Feature report ID, the same as in report map for feature object related to the characteristic
  * @return Pointer to new feature report characteristic
  */
 NimBLECharacteristic* NimBLEHIDDevice::featureReport(uint8_t reportID) {
@@ -154,34 +167,38 @@ NimBLECharacteristic* NimBLEHIDDevice::featureReport(uint8_t reportID) {
 	return featureReportCharacteristic;
 }
 
-/*
- * @brief
+/**
+ * @brief Creates a keyboard boot input report characteristic
  */
 NimBLECharacteristic* NimBLEHIDDevice::bootInput() {
 	return m_hidService->createCharacteristic((uint16_t) 0x2a22, NIMBLE_PROPERTY::NOTIFY);
 }
 
-/*
- * @brief
+/**
+ * @brief Create a keyboard boot output report characteristic
  */
 NimBLECharacteristic* NimBLEHIDDevice::bootOutput() {
 	return m_hidService->createCharacteristic((uint16_t) 0x2a32, NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE | NIMBLE_PROPERTY::WRITE_NR);
 }
 
-/*
- * @brief
+/**
+ * @brief Returns a pointer to the HID control point characteristic.
  */
 NimBLECharacteristic* NimBLEHIDDevice::hidControl() {
 	return m_hidControlCharacteristic;
 }
 
-/*
- * @brief
+/**
+ * @brief Returns a pointer to the protocol mode characteristic.
  */
 NimBLECharacteristic* NimBLEHIDDevice::protocolMode() {
 	return m_protocolModeCharacteristic;
 }
 
+/**
+ * @brief Set the battery level characteristic value.
+ * @param [in] level The battery level value.
+ */
 void NimBLEHIDDevice::setBatteryLevel(uint8_t level) {
 	m_batteryLevelCharacteristic->setValue(&level, 1);
 }
@@ -208,22 +225,23 @@ BLECharacteristic*	BLEHIDDevice::hidInfo() {
 	return m_hidInfoCharacteristic;
 }
 */
-/*
- * @brief
+
+/**
+ * @brief Returns a pointer to the device information service.
  */
 NimBLEService* NimBLEHIDDevice::deviceInfo() {
 	return m_deviceInfoService;
 }
 
-/*
- * @brief
+/**
+ * @brief Returns a pointer to the HID service.
  */
 NimBLEService* NimBLEHIDDevice::hidService() {
 	return m_hidService;
 }
 
-/*
- * @brief
+/**
+ * @brief @brief Returns a pointer to the battery service.
  */
 NimBLEService* NimBLEHIDDevice::batteryService() {
 	return m_batteryService;