Added methods + example to retrive local MAC for BT (espressif#7778)

* Added methods + example to retrive local MAC for BT

* Added .skip files in the new example folder

* Fixed typos and formatting + added doxygen comments

* changed std::string to String

* another std::string -> String

* Changed std::string to String

* chaged string type in example

Author: PilnyTomas

Diff for: libraries/BluetoothSerial/examples/GetLocalMAC/.skip.esp32c3

@@ -0,0 +1,46 @@
+// This example demonstrates usage of BluetoothSerial method to retrieve MAC address of local BT device in various formats.
+// By Tomas Pilny - 2023
+
+#include "BluetoothSerial.h"
+
+String device_name = "ESP32-example";
+
+#if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
+#error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
+#endif
+
+#if !defined(CONFIG_BT_SPP_ENABLED)
+#error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
+#endif
+
+BluetoothSerial SerialBT;
+
+void setup() {
+  Serial.begin(115200);
+  SerialBT.begin(device_name); //Bluetooth device name
+
+  uint8_t mac_arr[6]; // Byte array to hold the MAC address from getBtAddress()
+  BTAddress mac_obj; // Object holding instance of BTAddress with the MAC (for more details see libraries/BluetoothSerial/src/BTAddress.h)
+  String mac_str; // String holding the text version of MAC in format AA:BB:CC:DD:EE:FF
+
+  SerialBT.getBtAddress(mac_arr); // Fill in the array
+  mac_obj = SerialBT.getBtAddressObject(); // Instantiate the object
+  mac_str = SerialBT.getBtAddressString(); // Copy the string
+
+  Serial.print("This device is instantiated with name "); Serial.println(device_name);
+
+  Serial.print("The mac address using byte array: ");
+  for(int i = 0; i < ESP_BD_ADDR_LEN-1; i++){
+    Serial.print(mac_arr[i], HEX); Serial.print(":");
+  }
+  Serial.println(mac_arr[ESP_BD_ADDR_LEN-1], HEX);
+
+  Serial.print("The mac address using BTAddress object using default method `toString()`: "); Serial.println(mac_obj.toString().c_str());
+  Serial.print("The mac address using BTAddress object using method `toString(true)`\n\twhich prints the MAC with capital letters: "); Serial.println(mac_obj.toString(true).c_str()); // This actually what is used inside the getBtAddressString()
+
+  Serial.print("The mac address using string: "); Serial.println(mac_str.c_str());
+}
+
+void loop(){
+
+}

Diff for: libraries/BluetoothSerial/examples/GetLocalMAC/.skip.esp32s2

@@ -44,7 +44,7 @@ BTAddress::BTAddress() {
  *
  * @param [in] stringAddress The hex representation of the address.
  */
-BTAddress::BTAddress(std::string stringAddress) {
+BTAddress::BTAddress(String stringAddress) {
 	if (stringAddress.length() != 17) return;
 
 	int data[6];
@@ -86,20 +86,26 @@ esp_bd_addr_t *BTAddress::getNative() const {
 
 /**
  * @brief Convert a BT address to a string.
- *
- * A string representation of an address is in the format:
- *
+ * @param [in] capital changes the letter size
+ * By default the parameter `capital` == false and the string representation of an address is in the format:
  * ```
  * xx:xx:xx:xx:xx:xx
  * ```
- *
+ * When the parameter `capital` == true the format uses capital letters:
+ * ```
+ * XX:XX:XX:XX:XX:XX
+ * ```
  * @return The string representation of the address.
  */
-std::string BTAddress::toString() const {
+String BTAddress::toString(bool capital) const {
 	auto size = 18;
 	char *res = (char*)malloc(size);
-	snprintf(res, size, "%02x:%02x:%02x:%02x:%02x:%02x", m_address[0], m_address[1], m_address[2], m_address[3], m_address[4], m_address[5]);
-	std::string ret(res);
+	if(capital){
+		snprintf(res, size, "%02X:%02X:%02X:%02X:%02X:%02X", m_address[0], m_address[1], m_address[2], m_address[3], m_address[4], m_address[5]);
+	}else{
+		snprintf(res, size, "%02x:%02x:%02x:%02x:%02x:%02x", m_address[0], m_address[1], m_address[2], m_address[3], m_address[4], m_address[5]);
+	}
+	String ret(res);
 	free(res);
 	return ret;
 } // toString

Diff for: libraries/BluetoothSerial/examples/GetLocalMAC/.skip.esp32s3

@@ -12,7 +12,7 @@
 #include "sdkconfig.h"
 #if defined(CONFIG_BT_ENABLED) && defined(CONFIG_BLUEDROID_ENABLED)
 #include <esp_gap_bt_api.h> // ESP32 BT
-#include <string>
+#include <Arduino.h>
 
 
 /**
@@ -24,12 +24,12 @@ class BTAddress {
 public:
 	BTAddress();
 	BTAddress(esp_bd_addr_t address);
-	BTAddress(std::string stringAddress);
+	BTAddress(String stringAddress);
 	bool           equals(BTAddress otherAddress);
 	operator bool () const;
 
 	esp_bd_addr_t* getNative() const;
-	std::string    toString() const;
+	String         toString(bool capital = false) const;
 
 private:
 	esp_bd_addr_t m_address;

Diff for: libraries/BluetoothSerial/examples/GetLocalMAC/GetLocalMAC.ino

@@ -39,7 +39,7 @@ bool        BTAdvertisedDeviceSet::haveRSSI() const { return m_haveRSSI; }
  * @return A string representation of this device.
  */
 std::string BTAdvertisedDeviceSet::toString() {
-	std::string res = "Name: " + getName() + ", Address: " + getAddress().toString();
+	std::string res = "Name: " + getName() + ", Address: " + std::string(getAddress().toString().c_str(), getAddress().toString().length());
 	if (haveCOD()) {
 		char val[6];
 		snprintf(val, sizeof(val), "%d", getCOD());

Diff for: libraries/BluetoothSerial/src/BTAddress.cpp

@@ -84,7 +84,7 @@ void BTScanResultsSet::clear() {
 }
 
 bool BTScanResultsSet::add(BTAdvertisedDeviceSet advertisedDevice, bool unique) {
-	std::string key = advertisedDevice.getAddress().toString();
+	std::string key = std::string(advertisedDevice.getAddress().toString().c_str(), advertisedDevice.getAddress().toString().length());
 	if (!unique || m_vectorAdvertisedDevices.count(key) == 0) {
 		m_vectorAdvertisedDevices.insert(std::pair<std::string, BTAdvertisedDeviceSet>(key, advertisedDevice));
 		return true;

Diff for: libraries/BluetoothSerial/src/BTAddress.h

@@ -661,8 +661,6 @@ static bool _init_bt(const char *deviceName)
         }
     }
 
-    // Why only master need this?  Slave need this during pairing as well
-//    if (_isMaster && esp_bt_gap_register_callback(esp_bt_gap_cb) != ESP_OK) {
     if (esp_bt_gap_register_callback(esp_bt_gap_cb) != ESP_OK) {
         log_e("gap register failed");
         return false;
@@ -1183,4 +1181,31 @@ std::map<int, std::string> BluetoothSerial::getChannels(const BTAddress &remoteA
     return sdpRecords;
 }
 
+/**
+ * @brief      Gets the MAC address of local BT device in byte array.
+ *
+ * @param      mac [out]  The mac
+ */
+void BluetoothSerial::getBtAddress(uint8_t *mac) {
+    const uint8_t *dev_mac = esp_bt_dev_get_address();
+    memcpy(mac, dev_mac, ESP_BD_ADDR_LEN);
+}
+/**
+ * @brief      Gets the MAC address of local BT device as BTAddress object.
+ *
+ * @return     The BTAddress object.
+ */
+BTAddress BluetoothSerial::getBtAddressObject() {
+    uint8_t mac_arr[ESP_BD_ADDR_LEN];
+    getBtAddress(mac_arr);
+    return BTAddress(mac_arr);
+}
+/**
+ * @brief      Gets the MAC address of local BT device as string.
+ *
+ * @return     The BT MAC address string.
+ */
+String BluetoothSerial::getBtAddressString() {
+    return getBtAddressObject().toString(true);
+}
 #endif

Diff for: libraries/BluetoothSerial/src/BTAdvertisedDeviceSet.cpp

@@ -85,6 +85,9 @@ class BluetoothSerial: public Stream
         const int MAX_INQ_TIME = (ESP_BT_GAP_MAX_INQ_LEN * INQ_TIME);
 
         operator bool() const;
+        void getBtAddress(uint8_t *mac);
+        BTAddress getBtAddressObject();
+        String getBtAddressString();
     private:
         String local_name;
         int timeoutTicks=0;