Merge ServerDev branch into master.

API_DIFFERENCES.md

@@ -0,0 +1,207 @@
+# Server API differnces:
+
+### Characteristics:
+When creating a characteristic the properties are now set with `NIMBLE_PROPERTY::XXXX` instead of `BLECharacteristic::XXXX`.
+
+#### Previous:
+```
+BLECharacteristic::PROPERTY_READ |
+BLECharacteristic::PROPERTY_WRITE
+```
+
+#### Changed to:
+```
+NIMBLE_PROPERTY::READ | 
+NIMBLE_PROPERTY::WRITE
+```    
+
+#### The full list of properties:
+```
+NIMBLE_PROPERTY::READ
+NIMBLE_PROPERTY::READ_ENC
+NIMBLE_PROPERTY::READ_AUTHEN
+NIMBLE_PROPERTY::READ_AUTHOR
+NIMBLE_PROPERTY::WRITE
+NIMBLE_PROPERTY::WRITE_NR
+NIMBLE_PROPERTY::WRITE_ENC
+NIMBLE_PROPERTY::WRITE_AUTHEN
+NIMBLE_PROPERTY::WRITE_AUTHOR
+NIMBLE_PROPERTY::BROADCAST
+NIMBLE_PROPERTY::NOTIFY 
+NIMBLE_PROPERTY::INDICATE
+```
+
+### Descriptors:
+Descriptors are now created using the NimBLEcharacteristic method `createDescriptor()`.
+
+The previous method `addDescriptor()` is now a private function in the library.
+
+This was done because the NimBLE host automatically creates a 0x2902 descriptor if a characteristic has notify or indicate properties applied.   
+Due to this fact, this library also creates one automatically for your application.    
+The only reason to manually create this descriptor now is to assign callback functions.   
+If you do not require this functionality you can safely exclude the manual creation of that descriptor.   
+
+
+For any other descriptor, (except 0x2904, see below) it should now be created just as characteristics are    
+by invoking the `NimBLECharacteristic::createDescriptor` methods.   
+Which are defined as:
+```
+NimBLEDescriptor* createDescriptor(const char* uuid, 
+						uint32_t properties = NIMBLE_PROPERTY::READ | 
+											  NIMBLE_PROPERTY::WRITE,
+                                     uint16_t max_len = 100);
+
+NimBLEDescriptor* createDescriptor(NimBLEUUID uuid,
+						uint32_t properties = NIMBLE_PROPERTY::READ | 
+											  NIMBLE_PROPERTY::WRITE,
+                                     uint16_t max_len = 100);
+```
+##### Example:
+```
+pDescriptor = pCharacteristic->createDescriptor("ABCD", 
+                            NIMBLE_PROPERTY::READ | 
+                            NIMBLE_PROPERTY::WRITE |
+                            NIMBLE_PROPERTY::WRITE_ENC,
+                            25);`
+```
+Would create a descriptor with the UUID 0xABCD, publicly readable but only writable if paired/bonded (encrypted) and has a max value length of 25 bytes.
+
+For the 0x2904 descriptor, there is a special class that is created when you call `createDescriptor("2904")`.
+
+The pointer returned is of the base class `NimBLEDescriptor` but the call will create the derived class of `NimBLE2904` so you must cast the returned pointer to `NimBLE2904*` to access the specific class methods.
+
+##### Example:
+```
+p2904 = (NimBLE2904*)pCharacteristic->createDescriptor("2904");
+```
+
+#### Server Security:
+Security is set on the characteristic or descriptor properties by applying one of the following:
+```
+NIMBLE_PROPERTY::READ_ENC
+NIMBLE_PROPERTY::READ_AUTHEN
+NIMBLE_PROPERTY::READ_AUTHOR
+NIMBLE_PROPERTY::WRITE_ENC
+NIMBLE_PROPERTY::WRITE_AUTHEN
+NIMBLE_PROPERTY::WRITE_AUTHOR
+```
+When a peer wants to read or write a characteristic or descriptor with any of these properties applied    
+it will trigger the pairing process. By default the "just-works" pairing will be performed automatically.   
+This can be changed to use passkey authentication or numeric confirmation. See below for details.
+
+
+# Client API Differences:
+The `BLEAdvertisedDeviceCallbacks` class `onResult()` method now receives a pointer to the    
+`NimBLEAdvertisedDevice` object instead of a copy.
+
+`NimBLEClient::connect()` now takes an extra parameter to indicate if the client should download the services   
+ database from the peripheral, default value is true. 
+
+Defined as:
+```
+bool connect(NimBLEAdvertisedDevice* device, bool refreshServices = true);
+bool connect(NimBLEAddress address, uint8_t type = BLE_ADDR_TYPE_PUBLIC, bool refreshServices = true);
+```
+If set to false the client will use the services database it retrieved from the peripheral last time it connected.    
+This allows for faster connections and power saving if the devices just dropped connection and want to reconnect.
+
+```
+NimBLERemoteCharacteristic::writeValue();
+NimBLERemoteCharacteristic::registerForNotify();
+```
+Now return true or false to indicate success or failure so you can choose to disconnect or try again.
+
+#### Client Security:
+The client will automatically initiate security when the peripheral responds that it's required.    
+The default configuration will use "just-works" pairing with no bonding, if you wish to enable bonding see below.
+
+
+# Security:
+Security callback functions are now incorporated in the client/server Callbacks class.   
+However backward compatibility with the `BLESecurity` class is retained to minimize app code changes.
+
+The relevent server callbacks are defined as:
+```
+bool    onConfirmPIN(uint32_t pin); // accept or reject the passkey
+void    onAuthenticationComplete(ble_gap_conn_desc* desc); // auth complete - details in desc 
+bool    onPassKeyNotify(uint32_t pass_key); // receive the passkey sent by the client, accept or reject
+```
+The relevent client callbacks are defined as:
+```
+bool     onConfirmPIN(uint32_t pin); // accept or reject the passkey
+void     onAuthenticationComplete(ble_gap_conn_desc* desc); // auth complete - details in desc 
+uint32_t onPassKeyRequest(); // return the passkey to send to the server
+```
+
+Security settings and IO capabilities are now set by the corresponding method of `NimBLEDevice::`.
+```
+static void             setSecurityAuth(bool bonding, bool mitm, bool sc);
+static void             setSecurityAuth(uint8_t auth_req);
+static void             setSecurityIOCap(uint8_t iocap);
+static void             setSecurityInitKey(uint8_t init_key);
+static void             setSecurityRespKey(uint8_t init_key);
+
+
+/**
+ * @brief Set the authorization mode for this device.
+ * @param bonding, if true we allow bonding, false no bonding will be performed.
+ * @param mitm, if true we are capable of man in the middle protection, false if not.
+ * @param sc, if true we will perform secure connection pairing, false we will use legacy pairing.
+ */   
+void NimBLEDevice::setSecuityAuth(bool bonding, bool mitm, bool sc) 
+
+
+
+/**
+ * @brief Set the authorization mode for this device.
+ * @param A bitmap indicating what modes are supported.
+ * The bits are defined as follows:
+ ** 0x01 BLE_SM_PAIR_AUTHREQ_BOND                
+ ** 0x04 BLE_SM_PAIR_AUTHREQ_MITM                
+ ** 0x08 BLE_SM_PAIR_AUTHREQ_SC                  
+ ** 0x10 BLE_SM_PAIR_AUTHREQ_KEYPRESS  - not yet supported.         
+ ** 0xe2 BLE_SM_PAIR_AUTHREQ_RESERVED  - for reference only.
+ */ 
+void NimBLEDevice::setSecuityAuth(uint8_t auth_req) 
+
+
+
+/**
+ * @brief Set the Input/Output capabilities of this device.
+ * @param One of the following:
+ ** 0x00 BLE_HS_IO_DISPLAY_ONLY         DisplayOnly IO capability
+ ** 0x01 BLE_HS_IO_DISPLAY_YESNO        DisplayYesNo IO capability
+ ** 0x02 BLE_HS_IO_KEYBOARD_ONLY        KeyboardOnly IO capability 
+ ** 0x03 BLE_HS_IO_NO_INPUT_OUTPUT      NoInputNoOutput IO capability 
+ ** 0x04 BLE_HS_IO_KEYBOARD_DISPLAY     KeyboardDisplay Only IO capability
+ */
+void NimBLEDevice::setSecurityIOCap(uint8_t iocap) 
+
+
+
+/**
+ * @brief If we are the initiator of the security procedure this sets the keys we will distribute.
+ * @param A bitmap indicating which keys to distribute during pairing.
+ * The bits are defined as follows:           
+ ** 0x01: BLE_SM_PAIR_KEY_DIST_ENC  - Distribute the encryption key.
+ ** 0x02: BLE_SM_PAIR_KEY_DIST_ID   - Distribute the ID key (IRK).
+ ** 0x04: BLE_SM_PAIR_KEY_DIST_SIGN
+ ** 0x08: BLE_SM_PAIR_KEY_DIST_LINK
+ */
+void NimBLEDevice::setSecurityInitKey(uint8_t init_key) 
+
+
+/**
+ * @brief Set the keys we are willing to accept during pairing.
+ * @param A bitmap indicating which keys to accept during pairing.
+ * The bits are defined as follows:           
+ ** 0x01: BLE_SM_PAIR_KEY_DIST_ENC  -  Accept the encryption key.
+ ** 0x02: BLE_SM_PAIR_KEY_DIST_ID   -  Accept the ID key (IRK).
+ ** 0x04: BLE_SM_PAIR_KEY_DIST_SIGN
+ ** 0x08: BLE_SM_PAIR_KEY_DIST_LINK
+ */
+void NimBLEDevice::setSecurityRespKey(uint8_t init_key) 
+```
+
+ I'm sure there are more things I have forgotten but this is all the majors.   
+ I will update this document as necessary.

LICENSE

@@ -1,4 +1,4 @@
-                                 Apache License
+                             Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 
@@ -178,15 +178,15 @@
    APPENDIX: How to apply the Apache License to your work.
 
       To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
+      boilerplate notice, with the fields enclosed by brackets "{}"
       replaced with your own identifying information. (Don't include
       the brackets!)  The text should be enclosed in the appropriate
       comment syntax for the file format. We also recommend that a
       file or class name and description of purpose be included on the
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright {2020} {Ryan Powell}
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -199,3 +199,21 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+
+This product bundles queue.h 8.5, which is available under the "3-clause BSD"
+license.  For details, see porting/nimble/include/os/queue.h
+
+This product partly derives from FreeBSD, which is available under the
+"3-clause BSD" license.  For details, see:
+    * porting/nimble/src/os_mbuf.c
+
+This product bundles Gary S. Brown's CRC32 implementation, which is available
+under the following license:
+    COPYRIGHT (C) 1986 Gary S. Brown.  You may use this program, or
+    code or tables extracted from it, as desired without restriction.
+
+This product bundles tinycrypt, which is available under the "3-clause BSD"
+license. For details, and bundled files see:
+    * ext/tinycrypt/LICENSE
+
+This product partly derives from esp32-snippets; Copyright 2017 Neil Kolban.

README.md

@@ -1,40 +1,78 @@
 # *** UPDATE ***
 
-Server code nearing readiness, checkout the ServerDev branch if you would like to assist with testing.
+This library is now ready with (mostly)all original Arduino BLE library compatiblity.   
+Check the examples and API_DIFFERENCES document for details of using this library.
+
+3 simultaneous connections tested stable so far on both client and server.
 
-Client code working with all functionality.
 
-# ****************
+# NimBLE-Arduino
+A fork of the NimBLE stack restructured for compilation in the Ardruino IDE with a CPP library for use with ESP32.
+
+Why? Because the Bluedroid library is too bulky. 
+
+Initial client code testing has resulted in code size reduction of ~115k and reduced ram consumption of ~37k.
+
+Server code testing results from @beegee-toyo [from the project here](https://github.com/beegee-tokyo/ESP32WiFiBLE-NimBLE):
+
+
+### Memory usage (compilation output)
+#### Arduino BLE library
+```log
+RAM:   [==        ]  17.7% (used 58156 bytes from 327680 bytes)    
+Flash: [========  ]  76.0% (used 1345630 bytes from 1769472 bytes)    
+```
+#### NimBLE-Arduino library
+```log
+RAM:   [=         ]  14.5% (used 47476 bytes from 327680 bytes)    
+Flash: [=======   ]  69.5% (used 911378 bytes from 1310720 bytes)    
+```
+### Memory usage after **`setup()`** function
+#### Arduino BLE library
+**`Internal Total heap 259104, internal Free Heap 91660`**    
+#### NimBLE-Arduino library
+**`Internal Total heap 290288, internal Free Heap 182344`** 
+
+
+# Installation:
 
+Download as .zip and extract to Arduino/libraries folder, or in Arduino IDE from Sketch menu -> Include library -> Add .Zip library.
 
-# NimBLE-Arduino
-A fork of the NimBLE library structured for compilation with Ardruino, designed for use with ESP32.
+`#include "NimBLEDevice.h"` at the beginning of your sketch.
 
-Why? Because the Bluedroid library is too bulky, In testing I have found an initial code size reduction of ~115k and reduced ram usage by ~37k.
+Tested and working with esp32-arduino v1.0.2 and 1.0.4 in Arduino IDE v1.8.12 and platform IO.
 
 
-# Installation:
+# Usage: 
+
+This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes.
+
+Check 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 are in examples/ BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon, BLE_EddystoneURL_Beacon.   
 
-Download .zip 
-Extract to Arduino/libraries folder or in Arduino IDE from Sketch menu -> Include library -> Add .Zip library.
+Change the settings in the `nimconfig.h` file to customize NimBLE to your project, such as increasing max connections, default is 3.
 
 
-# Use: 
+# Continuing development:
 
-This library is intended to be compatible with the current BLE library classes, functions and types with minor changes. 
+This Library is tracking the esp-nimble repo, nimble-1.2.0-idf master branch, currently [@c4af628.](https://github.com/espressif/esp-nimble)
 
-At this time only the client code has been (nearly) fully implemented and work has started on the server code.
+Also tracking the NimBLE related changes in esp-idf, master branch, currently [@48bd2d7.](https://github.com/espressif/esp-idf/tree/master/components/bt/host/nimble)
 
 
-# Features:
+# Acknowledgments:
 
-Multiple clients are supported, up to 3 presently.
+* @nkolban and @chegewara for the [original esp32 BLE library](https://github.com/nkolban/esp32-snippets) this project was derived from.
+* @beegee-tokyo for contributing your time to test/debug and contributing the beacon examples.
 
 
 # Todo:
 
-1. Complete server implementation.
-2. Code cleanup.
-3. Create documentation.
-4. Examples.
+1. Code cleanup.
+2. Create documentation.
+3. Expose more NimBLE features.
+4. Add BLE Mesh code.