Update documentation.

* Docuemnt HID device class.

* Add usage tips.
This commit is contained in:
h2zero 2021-01-17 10:19:58 -07:00
parent 559a6e6970
commit cf64169bc0
5 changed files with 127 additions and 55 deletions

View file

@ -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/>

View file

@ -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

41
docs/Usage_tips.md Normal file
View file

@ -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.

View file

@ -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

View file

@ -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;