From 559a6e69701691fe67afdd6e2a61c3ec303bffae Mon Sep 17 00:00:00 2001 From: h2zero Date: Fri, 15 Jan 2021 21:51:49 -0700 Subject: [PATCH] Update documentation. --- docs/Command_line_config.md | 93 +++++++++++++++++++++++++++++++++++++ docs/index.md | 21 ++------- src/NimBLEClient.cpp | 1 + src/NimBLEDevice.cpp | 3 +- src/nimconfig.h | 9 +++- 5 files changed, 108 insertions(+), 19 deletions(-) create mode 100644 docs/Command_line_config.md diff --git a/docs/Command_line_config.md b/docs/Command_line_config.md new file mode 100644 index 0000000..813156f --- /dev/null +++ b/docs/Command_line_config.md @@ -0,0 +1,93 @@ +# Arduino command line and platformio config options + +`CONFIG_BT_NIMBLE_ROLE_CENTRAL_DISABLED` + + If defined, NimBLE Client functions will not be included. +- Reduces flash size by approx. 7kB. +
+ +`CONFIG_BT_NIMBLE_ROLE_OBSERVER_DISABLED` + +If defined, NimBLE Scan functions will not be included. +- Reduces flash size by approx. 26kB. +
+ +`CONFIG_BT_NIMBLE_ROLE_PERIPHERAL_DISABLED` + +If defined NimBLE Server functions will not be included. +- Reduces flash size by approx. 16kB. +
+ +`CONFIG_BT_NIMBLE_ROLE_BROADCASTER_DISABLED` + +If defined, NimBLE Advertising functions will not be included. +- Reduces flash size by approx. 5kB. +
+ +`CONFIG_BT_NIMBLE_DEBUG` + +If defined, enables debug log messages from the NimBLE host +- Uses approx. 32kB of flash memory. +
+ +`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. +
+ +`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. +
+ +`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. +
+ +`CONFIG_BT_NIMBLE_PINNED_TO_CORE` + +Sets the core the NimBLE host stack will run on +- Options: 0 or 1 +
+ +`CONFIG_BT_NIMBLE_TASK_STACK_SIZE` + +Set the task stack size for the NimBLE core. +- Default is 4096 +
+ + +`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 +
+ +`CONFIG_BT_NIMBLE_MAX_CONNECTIONS` + +Sets the number of simultaneous connections (esp controller max is 9) +- Default value is 3 +
+ +`CONFIG_BT_NIMBLE_MAX_BONDS` + +Sets the number of devices allowed to store/bond with +- Default value is 3 +
+ +`CONFIG_BT_NIMBLE_MAX_CCCDS` + +Sets the maximum number of CCCD subscriptions to store +- Default value is 8 +
+ +`CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME` + +Set the default device name +- Default value is "nimble" +
+ diff --git a/docs/index.md b/docs/index.md index 81381fc..edd67ab 100644 --- a/docs/index.md +++ b/docs/index.md @@ -50,29 +50,18 @@ If you are familiar with the original library, see: [The migration guide](Migrat Also see [Improvements_and_updates](Improvements_and_updates.md) for information about non-breaking changes. -### Arduino specific: +### Arduino specific See the Refactored_original_examples in the examples folder for highlights of the differences with the original library. More advanced examples highlighting many available features are in examples/NimBLE_Server, NimBLE_Client. Beacon examples provided by [beegee-tokyo](https://github.com/beegee-tokyo) are in examples/BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon, BLE_EddystoneURL_Beacon. -Change the settings in the nimconfig.h file to customize NimBLE to your project, such as increasing max connections (default == 3). +Change the settings in the nimconfig.h file to customize NimBLE to your project, such as increasing max connections (default is 3). +
-**Note To increase max connections in Arduino it is also required to change the controller max connections defined in sdkconfig.h.** - -This is located in your Arduino/hardware/espressif/esp32/tools/sdk/include/config folder. - -The values in `sdkconfig.h` you will need to change are: -``` -#define CONFIG_BTDM_CONTROLLER_BLE_MAX_CONN 3 -#define CONFIG_BTDM_CONTROLLER_BLE_MAX_CONN_EFF 3 -``` -In `nimconfig.h` the value is: -``` -#define CONFIG_BT_NIMBLE_MAX_CONNECTIONS 3 -``` -Espressif has stated the hard maximum connections is 9. +### Command line and platformio +See the command line configuration options available in [Command_line_config](Command_line_config.md).
# Acknowledgments diff --git a/src/NimBLEClient.cpp b/src/NimBLEClient.cpp index 70dfc7c..ddd3abe 100644 --- a/src/NimBLEClient.cpp +++ b/src/NimBLEClient.cpp @@ -704,6 +704,7 @@ std::string NimBLEClient::getValue(const NimBLEUUID &serviceUUID, const NimBLEUU * @param [in] serviceUUID The service that owns the characteristic. * @param [in] characteristicUUID The characteristic whose value we wish to write. * @param [in] value The value to write to the characteristic. + * @param [in] response If true, uses write with response operation. * @returns true if successful otherwise false */ bool NimBLEClient::setValue(const NimBLEUUID &serviceUUID, const NimBLEUUID &characteristicUUID, diff --git a/src/NimBLEDevice.cpp b/src/NimBLEDevice.cpp index f7532a0..f34a522 100644 --- a/src/NimBLEDevice.cpp +++ b/src/NimBLEDevice.cpp @@ -702,12 +702,13 @@ void NimBLEDevice::setSecurityCallbacks(NimBLESecurityCallbacks* callbacks) { /** * @brief Set the own address type. - * @param own_addr_type Own Bluetooth Device address type.\n + * @param [in] own_addr_type Own Bluetooth Device address type.\n * The available bits are defined as: * * 0x00: BLE_OWN_ADDR_PUBLIC * * 0x01: BLE_OWN_ADDR_RANDOM * * 0x02: BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT * * 0x03: BLE_OWN_ADDR_RPA_RANDOM_DEFAULT + * @param [in] useNRPA If true, and address type is random, uses a non-resolvable random address. */ void NimBLEDevice::setOwnAddrType(uint8_t own_addr_type, bool useNRPA) { m_own_addr_type = own_addr_type; diff --git a/src/nimconfig.h b/src/nimconfig.h index 4eb48b8..d90921f 100644 --- a/src/nimconfig.h +++ b/src/nimconfig.h @@ -15,8 +15,13 @@ * This converts them to "CONFIG_BT_NIMBLE_" format used in the latest IDF. */ -/* Detect if using ESP-IDF or Arduino (Arduino won't have these defines in sdkconfig) */ -#if defined(CONFIG_BT_NIMBLE_TASK_STACK_SIZE) || defined(CONFIG_NIMBLE_TASK_STACK_SIZE) +/* Detect if using ESP-IDF or Arduino (Arduino won't have these defines in sdkconfig) + * + * Note: We do not use #ifdef CONFIG_BT_NIMBLE_ENABLED since we cannot enable NimBLE when using + * Arduino as a component and the esp-nimble-compnent, so we check if other config options are defined. + * We also need to use a config parameter that must be present and not likely defined in the command line. + */ +#if defined(CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN) || defined(CONFIG_NIMBLE_GAP_DEVICE_NAME_MAX_LEN) #if defined(CONFIG_NIMBLE_ENABLED) && !defined(CONFIG_BT_NIMBLE_ENABLED) #define CONFIG_BT_NIMBLE_ENABLED