Add BLE Central support

README.md

@@ -4,7 +4,7 @@
 
 Enables BLE connectivity on the Arduino MKR WiFi 1010, Arduino UNO WiFi Rev.2, Arduino Nano 33 IoT, and Arduino Nano 33 BLE.
 
-This library currently supports creating a BLE peripheral.
+This library supports creating a BLE peripheral and BLE central mode.
 
 For the Arduino MKR WiFi 1010, Arduino UNO WiFi Rev.2, and Arduino Nano 33 IoT boards, it requires the NINA module to be running [Arduino NINA-W102 firmware](https://github.com/arduino/nina-fw) v1.2.0 or later.
 

examples/Central/LedControl/LedControl.ino

@@ -0,0 +1,128 @@
+/*
+  LED Control
+
+  This example scans for BLE peripherals until one with the advertised service
+  "19b10000-e8f2-537e-4f6c-d104768a1214" UUID is found. Once discovered and connected,
+  it will remotely control the BLE Peripheral's LED, when the button is pressed or released.
+
+  The circuit:
+  - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT,
+    Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board.
+  - Button with pull-up resistor connected to pin 2.
+
+  You can use it with another board that is compatible with this library and the
+  Peripherals -> LED example.
+
+  This example code is in the public domain.
+*/
+
+#include <ArduinoBLE.h>
+
+// variables for button
+const int buttonPin = 2;
+int oldButtonState = LOW;
+
+void setup() {
+  Serial.begin(9600);
+  while (!Serial);
+
+  // configure the button pin as input
+  pinMode(buttonPin, INPUT);
+
+  // initialize the BLE hardware
+  BLE.begin();
+
+  Serial.println("BLE Central - LED control");
+
+  // start scanning for peripherals
+  BLE.scanForUuid("19b10000-e8f2-537e-4f6c-d104768a1214");
+}
+
+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();
+
+    if (peripheral.localName() != "LED") {
+      return;
+    }
+
+    // stop scanning
+    BLE.stopScan();
+
+    controlLed(peripheral);
+
+    // peripheral disconnected, start scanning again
+    BLE.scanForUuid("19b10000-e8f2-537e-4f6c-d104768a1214");
+  }
+}
+
+void controlLed(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;
+  }
+
+  // retrieve the LED characteristic
+  BLECharacteristic ledCharacteristic = peripheral.characteristic("19b10001-e8f2-537e-4f6c-d104768a1214");
+
+  if (!ledCharacteristic) {
+    Serial.println("Peripheral does not have LED characteristic!");
+    peripheral.disconnect();
+    return;
+  } else if (!ledCharacteristic.canWrite()) {
+    Serial.println("Peripheral does not have a writable LED characteristic!");
+    peripheral.disconnect();
+    return;
+  }
+
+  while (peripheral.connected()) {
+    // while the peripheral is connected
+
+    // read the button pin
+    int buttonState = digitalRead(buttonPin);
+
+    if (oldButtonState != buttonState) {
+      // button changed
+      oldButtonState = buttonState;
+
+      if (buttonState) {
+        Serial.println("button pressed");
+
+        // button is pressed, write 0x01 to turn the LED on
+        ledCharacteristic.writeValue((byte)0x01);
+      } else {
+        Serial.println("button released");
+
+        // button is released, write 0x00 to turn the LED off
+        ledCharacteristic.writeValue((byte)0x00);
+      }
+    }
+  }
+
+  Serial.println("Peripheral disconnected");
+}

examples/Central/PeripheralExplorer/PeripheralExplorer.ino

@@ -0,0 +1,175 @@
+/*
+  Peripheral Explorer
+
+  This example scans for BLE peripherals until one with a particular name ("LED")
+  is found. Then connects, and discovers + prints all the peripheral's attributes.
+
+  The circuit:
+  - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT,
+    Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board.
+
+  You can use it with another board that is compatible with this library and the
+  Peripherals -> LED example.
+
+  This example code is in the public domain.
+*/
+
+#include <ArduinoBLE.h>
+
+void setup() {
+  Serial.begin(9600);
+  while (!Serial);
+
+  // begin initialization
+  if (!BLE.begin()) {
+    Serial.println("starting BLE failed!");
+
+    while (1);
+  }
+
+  Serial.println("BLE 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();
+
+    // see if peripheral is a LED
+    if (peripheral.localName() == "LED") {
+      // 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 properies 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);
+  }
+}

examples/Central/Scan/Scan.ino

@@ -0,0 +1,68 @@
+/*
+  Scan
+
+  This example scans for BLE peripherals and prints out their advertising details:
+  address, local name, adverised service UUID's.
+
+  The circuit:
+  - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT,
+    Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board.
+
+  This example code is in the public domain.
+*/
+
+#include <ArduinoBLE.h>
+
+void setup() {
+  Serial.begin(9600);
+  while (!Serial);
+
+  // begin initialization
+  if (!BLE.begin()) {
+    Serial.println("starting BLE failed!");
+
+    while (1);
+  }
+
+  Serial.println("BLE Central scan");
+
+  // start scanning for peripheral
+  BLE.scan();
+}
+
+void loop() {
+  // check if a peripheral has been discovered
+  BLEDevice peripheral = BLE.available();
+
+  if (peripheral) {
+    // discovered a peripheral
+    Serial.println("Discovered a peripheral");
+    Serial.println("-----------------------");
+
+    // print address
+    Serial.print("Address: ");
+    Serial.println(peripheral.address());
+
+    // print the local name, if present
+    if (peripheral.hasLocalName()) {
+      Serial.print("Local Name: ");
+      Serial.println(peripheral.localName());
+    }
+
+    // print the advertised service UUIDs, if present
+    if (peripheral.hasAdvertisedServiceUuid()) {
+      Serial.print("Service UUIDs: ");
+      for (int i = 0; i < peripheral.advertisedServiceUuidCount(); i++) {
+        Serial.print(peripheral.advertisedServiceUuid(i));
+        Serial.print(" ");
+      }
+      Serial.println();
+    }
+
+    // print the RSSI
+    Serial.print("RSSI: ");
+    Serial.println(peripheral.rssi());
+
+    Serial.println();
+  }
+}