Merge pull request #1451 from arduino/Hannes7eicher/R4-BLE-Examples

[HWU4M-71] Add BLE example

Author: karlsoderby

content/hardware/02.hero/boards/uno-r4-wifi/tutorials/cheat-sheet/cheat-sheet.md

@@ -622,6 +622,172 @@ To learn more about the Wi-Fi® capabilities of the UNO R4 WiFi, try out the [Ne
 
 Thanks to the ESP32 module, the UNO R4 WiFi has Bluetooth® LE and Bluetooth® 5 capabilities, at a speed of up to 2 Mbps. The ESP32 module has a built in trace-antenna, meaning that you do not need an external one to use the connectivity features of the board. However, this trace antenna is shared with the Bluetooth® module, which means that you cannot use Bluetooth® and Wi-Fi® at the same time.
 
+Below is an example sketch scans for bluetooth devices:
+
+```arduino
+#include <ArduinoBLE.h>
+
+void setup() {
+  Serial.begin(9600);
+  while (!Serial);
+
+  // begin initialization
+  if (!BLE.begin()) {
+    Serial.println("starting Bluetooth® Low Energy module failed!");
+
+    while (1);
+  }
+
+  Serial.println("Bluetooth® Low Energy Central - Peripheral Explorer");
+
+  // start scanning for peripherals
+  BLE.scan();
+}
+
+void loop() {
+  // check if a peripheral has been discovered
+  BLEDevice peripheral = BLE.available();
+
+  if (peripheral) {
+    // discovered a peripheral, print out address, local name, and advertised service
+    Serial.print("Found ");
+    Serial.print(peripheral.address());
+    Serial.print(" '");
+    Serial.print(peripheral.localName());
+    Serial.print("' ");
+    Serial.print(peripheral.advertisedServiceUuid());
+    Serial.println();
+
+    // check for peripheral's name
+    if (peripheral.localName() == "<PERIPHERAL_NAME>") {
+      // stop scanning
+      BLE.stopScan();
+
+      explorerPeripheral(peripheral);
+
+      // peripheral disconnected, we are done
+      while (1) {
+        // do nothing
+      }
+    }
+  }
+}
+
+void explorerPeripheral(BLEDevice peripheral) {
+  // connect to the peripheral
+  Serial.println("Connecting ...");
+
+  if (peripheral.connect()) {
+    Serial.println("Connected");
+  } else {
+    Serial.println("Failed to connect!");
+    return;
+  }
+
+  // discover peripheral attributes
+  Serial.println("Discovering attributes ...");
+  if (peripheral.discoverAttributes()) {
+    Serial.println("Attributes discovered");
+  } else {
+    Serial.println("Attribute discovery failed!");
+    peripheral.disconnect();
+    return;
+  }
+
+  // read and print device name of peripheral
+  Serial.println();
+  Serial.print("Device name: ");
+  Serial.println(peripheral.deviceName());
+  Serial.print("Appearance: 0x");
+  Serial.println(peripheral.appearance(), HEX);
+  Serial.println();
+
+  // loop the services of the peripheral and explore each
+  for (int i = 0; i < peripheral.serviceCount(); i++) {
+    BLEService service = peripheral.service(i);
+
+    exploreService(service);
+  }
+
+  Serial.println();
+
+  // we are done exploring, disconnect
+  Serial.println("Disconnecting ...");
+  peripheral.disconnect();
+  Serial.println("Disconnected");
+}
+
+void exploreService(BLEService service) {
+  // print the UUID of the service
+  Serial.print("Service ");
+  Serial.println(service.uuid());
+
+  // loop the characteristics of the service and explore each
+  for (int i = 0; i < service.characteristicCount(); i++) {
+    BLECharacteristic characteristic = service.characteristic(i);
+
+    exploreCharacteristic(characteristic);
+  }
+}
+
+void exploreCharacteristic(BLECharacteristic characteristic) {
+  // print the UUID and properties of the characteristic
+  Serial.print("\tCharacteristic ");
+  Serial.print(characteristic.uuid());
+  Serial.print(", properties 0x");
+  Serial.print(characteristic.properties(), HEX);
+
+  // check if the characteristic is readable
+  if (characteristic.canRead()) {
+    // read the characteristic value
+    characteristic.read();
+
+    if (characteristic.valueLength() > 0) {
+      // print out the value of the characteristic
+      Serial.print(", value 0x");
+      printData(characteristic.value(), characteristic.valueLength());
+    }
+  }
+  Serial.println();
+
+  // loop the descriptors of the characteristic and explore each
+  for (int i = 0; i < characteristic.descriptorCount(); i++) {
+    BLEDescriptor descriptor = characteristic.descriptor(i);
+
+    exploreDescriptor(descriptor);
+  }
+}
+
+void exploreDescriptor(BLEDescriptor descriptor) {
+  // print the UUID of the descriptor
+  Serial.print("\t\tDescriptor ");
+  Serial.print(descriptor.uuid());
+
+  // read the descriptor value
+  descriptor.read();
+
+  // print out the value of the descriptor
+  Serial.print(", value 0x");
+  printData(descriptor.value(), descriptor.valueLength());
+
+  Serial.println();
+}
+
+void printData(const unsigned char data[], int length) {
+  for (int i = 0; i < length; i++) {
+    unsigned char b = data[i];
+
+    if (b < 16) {
+      Serial.print("0");
+    }
+
+    Serial.print(b, HEX);
+  }
+}
+```
+
+If you want to learn more about Bluetooth LE check out our article [here](/learn/communication/bluetooth).
+
 ### Programming the ESP32 (Advanced)
 
 The ESP32 module and the Renesas RA4M1-chip are part of a sophisticated USB-Serial system that is highly flexible and adaptive to allow for HID features while still keeping the ability to program both the main MCU, and the ESP32, if you so wish. By default, the ESP32's is used mainly as a radio module using Wi-Fi® and Bluetooth®.