From bb3dd5f114177f5df8874244b718d07e79dbde34 Mon Sep 17 00:00:00 2001
From: h2zero <32826625+h2zero@users.noreply.github.com>
Date: Fri, 26 Aug 2022 19:32:01 -0600
Subject: [PATCH] [Breaking] Change all time input parameters to milliseconds.
(#78)
Changes all functions that accept a time parameter to use milliseconds instead of seconds.
* Adds duration input to NimBLEDevice::startAdvertising and NimBLEServer::startAdvertising.
---
docs/Migration_guide.md | 6 ++++++
docs/New_user_guide.md | 6 +++---
examples/Advanced/NimBLE_Client/main/main.cpp | 2 +-
.../Bluetooth_5/NimBLE_extended_client/main/main.cpp | 6 +++---
examples/basic/BLE_client/main/main.cpp | 12 ++++++------
examples/basic/BLE_scan/main/main.cpp | 2 +-
src/NimBLEAdvertising.cpp | 5 +----
src/NimBLEClient.cpp | 6 +++---
src/NimBLEClient.h | 2 +-
src/NimBLEDevice.cpp | 5 +++--
src/NimBLEDevice.h | 2 +-
src/NimBLEScan.cpp | 6 +-----
src/NimBLEServer.cpp | 9 +++++----
src/NimBLEServer.h | 2 +-
14 files changed, 36 insertions(+), 35 deletions(-)
diff --git a/docs/Migration_guide.md b/docs/Migration_guide.md
index 2ddc1b3..4283012 100644
--- a/docs/Migration_guide.md
+++ b/docs/Migration_guide.md
@@ -17,6 +17,7 @@ For more information on the improvements and additions please refer to the [clas
* [Remote Services](#remote-services)
* [Remote characteristics](#remote-characteristics)
* [Security](#client-security)
+* [Scanning](#scan-api)
* [General Security](#security-api)
* [Configuration](#arduino-configuration)
@@ -321,6 +322,11 @@ The client will automatically initiate security when the peripheral responds tha
The default configuration will use "just-works" pairing with no bonding, if you wish to enable bonding see below.
+
+### BLE Scan
+The scan API is mostly unchanged from the original except for `NimBLEScan::start`, in which the duration parameter is now in milliseconds instead of seconds.
+
+
## Security API
Security operations have been moved to `BLEDevice` (`NimBLEDevice`).
diff --git a/docs/New_user_guide.md b/docs/New_user_guide.md
index ce02efe..d5b8e6f 100644
--- a/docs/New_user_guide.md
+++ b/docs/New_user_guide.md
@@ -146,7 +146,7 @@ After initializing the NimBLE stack we create a scan instance by calling `NimBLE
Once we have created the scan we can start looking for advertising servers.
-To do this we call `NimBLEScan::start(duration)`, the duration parameter is a uint32_t that specifies the number of seconds to scan for,
+To do this we call `NimBLEScan::start(duration)`, the duration parameter is a uint32_t that specifies the number of milliseconds to scan for,
passing 0 will scan forever.
In this example we will scan for 10 seconds. This is a blocking function (a non blocking overload is also available).
@@ -162,7 +162,7 @@ void app_main(void)
NimBLEDevice::init("");
NimBLEScan *pScan = NimBLEDevice::getScan();
- NimBLEScanResults results = pScan->start(10);
+ NimBLEScanResults results = pScan->start(10 * 1000);
}
```
@@ -302,7 +302,7 @@ void app_main(void)
NimBLEDevice::init("");
NimBLEScan *pScan = NimBLEDevice::getScan();
- NimBLEScanResults results = pScan->start(10);
+ NimBLEScanResults results = pScan->start(10 * 1000);
NimBLEUUID serviceUuid("ABCD");
diff --git a/examples/Advanced/NimBLE_Client/main/main.cpp b/examples/Advanced/NimBLE_Client/main/main.cpp
index 1bf6ab1..f754b94 100644
--- a/examples/Advanced/NimBLE_Client/main/main.cpp
+++ b/examples/Advanced/NimBLE_Client/main/main.cpp
@@ -16,7 +16,7 @@ void scanEndedCB(NimBLEScanResults results);
static NimBLEAdvertisedDevice* advDevice;
static bool doConnect = false;
-static uint32_t scanTime = 0; /** 0 = scan forever */
+static uint32_t scanTime = 0; /** scan time in milliseconds, 0 = scan forever */
/** None of these are required as they will be handled by the library with defaults. **
diff --git a/examples/Bluetooth_5/NimBLE_extended_client/main/main.cpp b/examples/Bluetooth_5/NimBLE_extended_client/main/main.cpp
index 56881d0..4b37285 100644
--- a/examples/Bluetooth_5/NimBLE_extended_client/main/main.cpp
+++ b/examples/Bluetooth_5/NimBLE_extended_client/main/main.cpp
@@ -18,7 +18,7 @@ void scanEndedCB(NimBLEScanResults results);
static NimBLEAdvertisedDevice* advDevice;
static bool doConnect = false;
-static uint32_t scanTime = 10; /* 0 = scan forever */
+static uint32_t scanTime = 10 * 1000; // In milliseconds, 0 = scan forever
/* Define the PHY's to use when connecting to peer devices, can be 1, 2, or all 3 (default).*/
static uint8_t connectPhys = BLE_GAP_LE_PHY_CODED_MASK | BLE_GAP_LE_PHY_1M_MASK /*| BLE_GAP_LE_PHY_2M_MASK */ ;
@@ -79,8 +79,8 @@ bool connectToServer() {
*/
pClient->setConnectPhy(connectPhys);
- /** Set how long we are willing to wait for the connection to complete (seconds), default is 30. */
- pClient->setConnectTimeout(10);
+ /** Set how long we are willing to wait for the connection to complete (milliseconds), default is 30000. */
+ pClient->setConnectTimeout(10 * 1000);
if (!pClient->connect(advDevice)) {
/* Created a client but failed to connect, don't need to keep it as it has no data */
diff --git a/examples/basic/BLE_client/main/main.cpp b/examples/basic/BLE_client/main/main.cpp
index 49e8ad4..26862c1 100644
--- a/examples/basic/BLE_client/main/main.cpp
+++ b/examples/basic/BLE_client/main/main.cpp
@@ -5,7 +5,7 @@
* updated by chegewara
* updated for NimBLE by H2zero
*/
-
+
/** NimBLE differences highlighted in comment blocks **/
/*******original********
@@ -38,7 +38,7 @@ static void notifyCallback(
}
/** None of these are required as they will be handled by the library with defaults. **
- ** Remove as you see fit for your needs */
+ ** Remove as you see fit for your needs */
class MyClientCallback : public BLEClientCallbacks {
void onConnect(BLEClient* pclient) {
}
@@ -120,9 +120,9 @@ class MyAdvertisedDeviceCallbacks: public BLEAdvertisedDeviceCallbacks {
/**
* Called for each advertising BLE server.
*/
-
+
/*** Only a reference to the advertised device is passed now
- void onResult(BLEAdvertisedDevice advertisedDevice) { **/
+ void onResult(BLEAdvertisedDevice advertisedDevice) { **/
void onResult(BLEAdvertisedDevice* advertisedDevice) {
printf("BLE Advertised Device found: %s\n", advertisedDevice->toString().c_str());
@@ -171,7 +171,7 @@ void connectTask (void * parameter){
/*** Note: write value now returns true if successful, false otherwise - try again or disconnect ***/
pRemoteCharacteristic->writeValue((uint8_t*)buf, strlen(buf), false);
}else if(doScan){
- BLEDevice::getScan()->start(0); // this is just eample to start scan after disconnect, most likely there is better way to do it in arduino
+ BLEDevice::getScan()->start(0); // this is just eample to start scan after disconnect, most likely there is better way to do it
}
vTaskDelay(1000/portTICK_PERIOD_MS); // Delay a second between loops.
@@ -195,6 +195,6 @@ void app_main(void) {
pBLEScan->setActiveScan(true);
xTaskCreate(connectTask, "connectTask", 5000, NULL, 1, NULL);
- pBLEScan->start(5, false);
+ pBLEScan->start(5 * 1000, false);
} // End of setup.
diff --git a/examples/basic/BLE_scan/main/main.cpp b/examples/basic/BLE_scan/main/main.cpp
index 5686dd9..8a9e83b 100644
--- a/examples/basic/BLE_scan/main/main.cpp
+++ b/examples/basic/BLE_scan/main/main.cpp
@@ -17,7 +17,7 @@
extern "C"{void app_main(void);}
-int scanTime = 5; //In seconds
+int scanTime = 5 * 1000; // In milliseconds, 0 = scan forever
BLEScan* pBLEScan;
class MyAdvertisedDeviceCallbacks: public BLEAdvertisedDeviceCallbacks {
diff --git a/src/NimBLEAdvertising.cpp b/src/NimBLEAdvertising.cpp
index e45316d..4f2ea17 100644
--- a/src/NimBLEAdvertising.cpp
+++ b/src/NimBLEAdvertising.cpp
@@ -385,7 +385,7 @@ void NimBLEAdvertising::setScanResponseData(NimBLEAdvertisementData& advertiseme
/**
* @brief Start advertising.
- * @param [in] duration The duration, in seconds, to advertise, 0 == advertise forever.
+ * @param [in] duration The duration, in milliseconds, to advertise, 0 == advertise forever.
* @param [in] advCompleteCB A pointer to a callback to be invoked when advertising ends.
* @return True if advertising started successfully.
*/
@@ -423,9 +423,6 @@ bool NimBLEAdvertising::start(uint32_t duration, void (*advCompleteCB)(NimBLEAdv
if(duration == 0){
duration = BLE_HS_FOREVER;
}
- else{
- duration = duration*1000; // convert duration to milliseconds
- }
m_advCompCB = advCompleteCB;
diff --git a/src/NimBLEClient.cpp b/src/NimBLEClient.cpp
index bc255dc..2899323 100644
--- a/src/NimBLEClient.cpp
+++ b/src/NimBLEClient.cpp
@@ -533,10 +533,10 @@ NimBLEConnInfo NimBLEClient::getConnInfo() {
/**
* @brief Set the timeout to wait for connection attempt to complete.
- * @param [in] time The number of seconds before timeout.
+ * @param [in] time The number of milliseconds before timeout.
*/
-void NimBLEClient::setConnectTimeout(uint8_t time) {
- m_connectTimeout = (uint32_t)(time * 1000);
+void NimBLEClient::setConnectTimeout(uint32_t time) {
+ m_connectTimeout = time;
} // setConnectTimeout
diff --git a/src/NimBLEClient.h b/src/NimBLEClient.h
index d3c16b7..d4e349d 100644
--- a/src/NimBLEClient.h
+++ b/src/NimBLEClient.h
@@ -63,7 +63,7 @@ public:
uint16_t getConnId();
uint16_t getMTU();
bool secureConnection();
- void setConnectTimeout(uint8_t timeout);
+ void setConnectTimeout(uint32_t timeout);
void setConnectionParams(uint16_t minInterval, uint16_t maxInterval,
uint16_t latency, uint16_t timeout,
uint16_t scanInterval=16, uint16_t scanWindow=16);
diff --git a/src/NimBLEDevice.cpp b/src/NimBLEDevice.cpp
index 1504864..6563944 100644
--- a/src/NimBLEDevice.cpp
+++ b/src/NimBLEDevice.cpp
@@ -170,10 +170,11 @@ NimBLEAdvertising* NimBLEDevice::getAdvertising() {
/**
* @brief Convenience function to begin advertising.
+ * @param [in] duration The duration in milliseconds to advertise for, default = forever.
* @return True if advertising started successfully.
*/
-bool NimBLEDevice::startAdvertising() {
- return getAdvertising()->start();
+bool NimBLEDevice::startAdvertising(uint32_t duration) {
+ return getAdvertising()->start(duration);
} // startAdvertising
# endif
diff --git a/src/NimBLEDevice.h b/src/NimBLEDevice.h
index 1fa236d..7065775 100644
--- a/src/NimBLEDevice.h
+++ b/src/NimBLEDevice.h
@@ -151,7 +151,7 @@ public:
static bool stopAdvertising();
# else
static NimBLEAdvertising* getAdvertising();
- static bool startAdvertising();
+ static bool startAdvertising(uint32_t duration = 0);
static bool stopAdvertising();
# endif
#endif
diff --git a/src/NimBLEScan.cpp b/src/NimBLEScan.cpp
index d1c4879..1d4d239 100644
--- a/src/NimBLEScan.cpp
+++ b/src/NimBLEScan.cpp
@@ -302,7 +302,7 @@ bool NimBLEScan::isScanning() {
/**
* @brief Start scanning.
- * @param [in] duration The duration in seconds for which to scan.
+ * @param [in] duration The duration in milliseconds for which to scan.
* @param [in] scanCompleteCB A function to be called when scanning has completed.
* @param [in] is_continue Set to true to save previous scan results, false to clear them.
* @return True if scan started or false if there was an error.
@@ -319,10 +319,6 @@ bool NimBLEScan::start(uint32_t duration, void (*scanCompleteCB)(NimBLEScanResul
if(duration == 0){
duration = BLE_HS_FOREVER;
}
- else{
- // convert duration to milliseconds
- duration = duration * 1000;
- }
// Set the flag to ignore the results while we are deleting the vector
if(!is_continue) {
diff --git a/src/NimBLEServer.cpp b/src/NimBLEServer.cpp
index dff613a..607cc94 100644
--- a/src/NimBLEServer.cpp
+++ b/src/NimBLEServer.cpp
@@ -748,15 +748,16 @@ bool NimBLEServer::stopAdvertising(uint8_t inst_id) {
} // stopAdvertising
#endif
-#if !CONFIG_BT_NIMBLE_EXT_ADV|| defined(_DOXYGEN_)
+#if !CONFIG_BT_NIMBLE_EXT_ADV || defined(_DOXYGEN_)
/**
* @brief Start advertising.
+ * @param [in] duration The duration in milliseconds to advertise for, default = forever.
* @return True if advertising started successfully.
- * @details Start the server advertising its existence. This is a convenience function and is equivalent to
+ * @details Start the server advertising its existence. This is a convenience function and is equivalent to
* retrieving the advertising object and invoking start upon it.
*/
-bool NimBLEServer::startAdvertising() {
- return getAdvertising()->start();
+bool NimBLEServer::startAdvertising(uint32_t duration) {
+ return getAdvertising()->start(duration);
} // startAdvertising
#endif
diff --git a/src/NimBLEServer.h b/src/NimBLEServer.h
index 4cc2ed7..3242fef 100644
--- a/src/NimBLEServer.h
+++ b/src/NimBLEServer.h
@@ -59,7 +59,7 @@ public:
bool stopAdvertising(uint8_t inst_id);
#else
NimBLEAdvertising* getAdvertising();
- bool startAdvertising();
+ bool startAdvertising(uint32_t duration = 0);
#endif
bool stopAdvertising();
void start();