Lab 2. Bluetooth Low Energy (BLE)

In this laboratory you will learn how to build a Bluetooth Low Energy (BLE) environmental service on your ESP32 Sparrow boards and to expose the measured sensor data to a Web application.

Bluetooth Smart, also known as Bluetooth Low Energy, abbreviated as BLE, is an energy-efficient iteration of Bluetooth designed to conserve power. Its main use involves transmitting small amounts of data over short distances with low bandwidth.

Unlike the constant activity of regular Bluetooth, BLE typically stays in sleep mode, only activating when a connection is established.

This results in significantly lower power consumption, approximately 100 times less than traditional Bluetooth, depending on the specific application. To explore the key distinctions between Bluetooth and Bluetooth Low Energy, refer to the detailed comparison here.

Within Bluetooth Low Energy, there exist two device types: the server (referred to as peripheral) and the client. The ESP32 is versatile, capable of functioning as either a client or a server.

The server actively broadcasts its presence, making it discoverable by other devices, and it holds data that the client can access. Meanwhile, the client conducts scans of nearby devices. Upon locating the desired server, it initiates a connection and awaits incoming data. This mode of communication is termed point-to-point, and it is the communication mode we will employ with the ESP32 Sparrow.

GATT, which stands for Generic Attributes, establishes a hierarchical data structure accessible to connected BLE devices. In essence, GATT outlines the protocol governing the exchange of standard messages between two BLE devices. Grasping this hierarchical arrangement is crucial as it facilitates a clearer comprehension of how to effectively employ BLE with the ESP32.

• Profile: standard collection of services for a specific use case;
• Service: collection of related information, like sensor readings, battery level, heart rate, etc. ;
• Characteristic: it is where the actual data is saved on the hierarchy (value);
• Descriptor: metadata about the data;
• Properties: describes how the characteristic value can be interacted with. For example: read, write, notify, broadcast, indicate, etc.

At the highest level of the hierarchy is a profile, consisting of one or more services. Typically, a BLE device encompasses multiple services.

Each service comprises at least one characteristic, and it may also reference other services. Essentially, a service serves as a repository of information, such as sensor readings.

The Bluetooth Special Interest Group (SIG) has established predefined services for various data types, including Battery Level, Blood Pressure, Heart Rate, Weight Scale, etc. Additional defined services can be explored here.

A characteristic is invariably associated with a service, serving as the location within the hierarchy where the actual data resides (value). It consistently consists of two attributes: the characteristic declaration, offering metadata about the data, and the characteristic value.

Furthermore, the characteristic value may be accompanied by descriptors, providing additional details about the metadata specified in the characteristic declaration.

The properties delineate the ways in which interaction with the characteristic value can occur. Essentially, these properties encompass the operations and procedures applicable to the characteristic:

• Broadcast
• Read
• Write without response
• Write
• Notify
• Indicate
• Authenticated Signed Writes
• Extended Properties

Every service, characteristic, and descriptor possesses a Universally Unique Identifier (UUID), which is a distinct 128-bit (16 bytes) number, for instance: 55072829-bc9e-4c53-938a-74a6d4c78776

Shortened UUIDs are available for all types, services, and profiles outlined in the Bluetooth Special Interest Group (SIG) specifications.

Should your application require a custom UUID, you can generate one using a UUID generator website, but for this lab assignment we will use the default UUID for an Environmental Sensing Service.

In essence, the UUID serves the purpose of uniquely identifying information. For example, it can distinguish a specific service provided by a Bluetooth device.

Build the example below, which advertises the board on BLE. Install on your phone an app that scans nearby Bluetooth devices, such as nRF Connect. Check if your device is in the list.

main.cpp

#include <Arduino.h>
#include <NimBLEDevice.h>
 
static const char* DEVICE_NAME = "ESP32-C6 Demo";
static NimBLEUUID SERVICE_UUID("6E400001-B5A3-F393-E0A9-E50E24DCCA9E");
static NimBLEUUID CHAR_UUID   ("6E400002-B5A3-F393-E0A9-E50E24DCCA9E");
 
NimBLEServer*         gServer = nullptr;
NimBLEService*        gService = nullptr;
NimBLECharacteristic* gChar = nullptr;
 
void startBLE() {
  NimBLEDevice::init(DEVICE_NAME);
 
  gServer  = NimBLEDevice::createServer();
  gService = gServer->createService(SERVICE_UUID);
 
  gChar = gService->createCharacteristic(
    CHAR_UUID,
    NIMBLE_PROPERTY::READ
  );
  gChar->setValue("Hello from ESP32-C6!");
  gService->start();
 
  NimBLEAdvertising* adv = NimBLEDevice::getAdvertising();
 
  // Advertise our service UUID
  adv->addServiceUUID(SERVICE_UUID);
 
  // (v2.x) Build advertising + scan-response payloads explicitly
  NimBLEAdvertisementData advData;
  advData.setFlags(0x06); // LE General Discoverable + BR/EDR Not Supported
 
  NimBLEAdvertisementData scanData;
  scanData.setName(DEVICE_NAME); // put the name in scan response
  // you can also add manufacturer data here if you want:
  // std::string mfg = "\x34\x12C6"; scanData.setManufacturerData(mfg);
 
  adv->setAdvertisementData(advData);
  adv->setScanResponseData(scanData);
 
  // Appearance is still supported
  adv->setAppearance(0x0200); // Generic Tag
 
  NimBLEDevice::startAdvertising();
}
 
void setup() {
  Serial.begin(115200);
  while (!Serial) { delay(10); }
  startBLE();
  Serial.println("Advertising as ESP32-C6 Demo. Open nRF Connect -> Scan.");
}
 
void loop() {
  delay(1000);
}

In our project, we will establish an Environmental Sensing Service featuring three distinct characteristics: one for temperature, another for humidity, and a third for pressure.

The specific temperature, humidity, and pressure readings are stored within the values assigned to their respective characteristics. Each characteristic is configured with the notify property, ensuring that the client receives notifications whenever these values undergo a change.

We will adhere to the default UUIDs designated for the Environmental Sensing Profile and its associated characteristics.

To access the default assigned UUID numbers, visit this page and refer to the Assigned Numbers Document (PDF). By searching for the Environmental Sensing Service within the document, you can explore all the authorized characteristics applicable to this service. It's evident that the Environmental Sensing Service supports temperature, humidity, and pressure readings.

There’s a table with the UUIDs for all services. You can see that the UUID for the Environmental Sensing service is 0x181A.

Then, search for the temperature, humidity, and pressure characteristics UUIDs. You’ll find a table with the values for all characteristics. The UUIDs for the temperature, humidity, and pressure are:

• pressure: 0x2A6D
• temperature: 0x2A6E
• humidity: 0x246F

To verify the proper creation of the BLE Server and to receive notifications for temperature, humidity, and pressure, we'll utilize a smartphone application.

Most contemporary smartphones come equipped with BLE capabilities. You can check your smartphone's specifications to confirm its BLE compatibility.

Note: The smartphone can function as either a client or a server. In this context, it will act as the client, establishing a connection with the Sparrow BLE server.

For our testing purposes, we'll employ a free application named nRF Connect for Mobile, developed by Nordic Semi. This app is available on both Android ( Google Play Store) and iOS. To install the app, simply go to the Google Play Store or App Store, search for “nRF Connect for Mobile,” and proceed with the installation.

Here are the steps to create an BLE peripheral with an Environmental Sensing BLE service with temperature, humidity, and pressure, characteristics:

1. Create a BLE device (server) with a name of your choice (we’ll call it ESP32_BME680, but you can call it any other name).
2. Create an Environmental Sensing service (UUID: 0x181A).
3. Add characteristics to that service: pressure (0x2A6D), temperature (0x2A6E) and humidity (0x246F)
4. Add descriptors to the characteristics.
5. Start the BLE server.
6. Start advertising so BLE clients can connect and read the characteristics.
7. Once a connection is established with a client, it will write new values on the characteristics and will notify the client, every time there’s a change.

Copy the following code to the Arduino IDE, modify it and upload it to your board.

#include <Arduino.h>
#include <Wire.h>
#include <Adafruit_BME680.h>
#include <NimBLEDevice.h>
 
/* ============================
   User config
   ============================ */
static const char* DEVICE_NAME = "ESP32-C6 Env";
#define I2C_SDA_PIN 21
#define I2C_SCL_PIN 22
#define BME680_I2C_ADDR 0x77
static const uint32_t MEAS_INTERVAL_MS   = 2000;  // env update
static const uint32_t BATTERY_INTERVAL_MS = 60000; // battery update
 
/* Device Information strings */
static const char* DIS_MANUFACTURER = "YourBrand";
static const char* DIS_MODEL        = "ESP32-C6 EnvSense";
static const char* DIS_FW_REV       = "1.0.0";
static const char* DIS_SW_REV       = "1.0.0";
static const char* DIS_SN           = "SN-000001";
static const char* DIS_HW           = "RevA";
 
/* ============================
   UUIDs
   ============================ */
// Environmental Sensing
static NimBLEUUID ESS_UUID ((uint16_t)0x181A);
static NimBLEUUID TEMP_UUID((uint16_t)0x2A6E);
static NimBLEUUID PRES_UUID((uint16_t)0x2A6D);
static NimBLEUUID HUM_UUID ((uint16_t)0x2A6F);
 
// Battery Service
static NimBLEUUID BATT_SVC_UUID((uint16_t)0x180F);
static NimBLEUUID BATT_LVL_UUID((uint16_t)0x2A19);
 
// Device Information Service
static NimBLEUUID DIS_UUID      ((uint16_t)0x180A);
static NimBLEUUID DIS_MFR_UUID  ((uint16_t)0x2A29);
static NimBLEUUID DIS_MODEL_UUID((uint16_t)0x2A24);
static NimBLEUUID DIS_FW_UUID   ((uint16_t)0x2A26);
static NimBLEUUID DIS_SW_UUID   ((uint16_t)0x2A28);
static NimBLEUUID DIS_PNP_UUID  ((uint16_t)0x2A50);
 
/* ============================
   Globals
   ============================ */
Adafruit_BME680 bme; // I2C
 
NimBLEServer* gServer = nullptr;
 
/* Environmental Sensing */
NimBLEService*        gESS      = nullptr;
NimBLECharacteristic* gTempChar = nullptr;
NimBLECharacteristic* gPresChar = nullptr;
NimBLECharacteristic* gHumChar  = nullptr;
 
/* Battery */
NimBLEService*        gBattSvc  = nullptr;
NimBLECharacteristic* gBattChar = nullptr;
 
/* DIS */
NimBLEService*        gDIS      = nullptr;
 
uint32_t lastEnv = 0;
uint32_t lastBatt = 0;
 
/* ============================
   Helpers: GATT encoders
   ============================ */
static void setTempCentiDeg(NimBLECharacteristic* ch, float celsius) {
  int32_t raw = lroundf(celsius * 100.0f);      // sint16, 0.01 °C
  if (raw > 32767) raw = 32767;
  if (raw < -32768) raw = -32768;
  int16_t v = (int16_t)raw;
  uint8_t buf[2] = { (uint8_t)(v & 0xFF), (uint8_t)((v >> 8) & 0xFF) };
  ch->setValue(buf, sizeof(buf));
}
 
static void setHumidityCentiPct(NimBLECharacteristic* ch, float rh) {
  if (rh < 0) rh = 0; if (rh > 100) rh = 100;   // uint16, 0.01 %RH
  uint32_t raw = lroundf(rh * 100.0f);
  if (raw > 0xFFFF) raw = 0xFFFF;
  uint16_t v = (uint16_t)raw;
  uint8_t buf[2] = { (uint8_t)(v & 0xFF), (uint8_t)((v >> 8) & 0xFF) };
  ch->setValue(buf, sizeof(buf));
}
 
static void setPressureDeciPa(NimBLECharacteristic* ch, float pascals) {
  if (pascals < 0) pascals = 0;                 // uint32, 0.1 Pa
  uint64_t raw = llroundf(pascals * 10.0f);
  if (raw > 0xFFFFFFFFULL) raw = 0xFFFFFFFFULL;
  uint32_t v = (uint32_t)raw;
  uint8_t buf[4] = {
    (uint8_t)(v & 0xFF), (uint8_t)((v >> 8) & 0xFF),
    (uint8_t)((v >> 16) & 0xFF), (uint8_t)((v >> 24) & 0xFF)
  };
  ch->setValue(buf, sizeof(buf));
}
 
/* 0x2904 Presentation Format descriptor */
static void addCPF(NimBLECharacteristic* ch, uint8_t format, int8_t exponent, uint16_t unit) {
  // 7 bytes: format, exponent, unit(LE), namespace(1=1), description(2=0)
  uint8_t cpf[7] = {
    format, (uint8_t)exponent,
    (uint8_t)(unit & 0xFF), (uint8_t)((unit >> 8) & 0xFF),
    0x01, 0x00, 0x00
  };
  ch->createDescriptor("2904")->setValue(cpf, sizeof(cpf));
}
 
/* ============================
   Battery level source (stub)
   Replace with ADC/PMIC reading if available.
   ============================ */
static uint8_t getBatteryPercent() {
  // TODO: read your actual battery voltage & map to 0..100
  return 100; // placeholder
}
 
/* ============================
   BLE setup
   ============================ */
void startBLE() {
  NimBLEDevice::init(DEVICE_NAME);
  NimBLEDevice::setPower(ESP_PWR_LVL_P9);
  NimBLEDevice::setSecurityAuth(false, false, true); // no bonding; SC=true
 
  gServer = NimBLEDevice::createServer();
 
  /* --- Environmental Sensing Service --- */
  gESS = gServer->createService(ESS_UUID);
  auto propsRN = (NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::NOTIFY);
 
  gTempChar = gESS->createCharacteristic(TEMP_UUID, propsRN);
  gPresChar = gESS->createCharacteristic(PRES_UUID, propsRN);
  gHumChar  = gESS->createCharacteristic(HUM_UUID,  propsRN);
 
  // CPF descriptors for units
  const uint8_t GATT_FORMAT_SINT16 = 0x0E;
  const uint8_t GATT_FORMAT_UINT16 = 0x0D;
  const uint8_t GATT_FORMAT_UINT32 = 0x10;
  addCPF(gTempChar, GATT_FORMAT_SINT16, -2, 0x272F); // Celsius
  addCPF(gPresChar, GATT_FORMAT_UINT32, -1, 0x2724); // Pascal, 0.1
  addCPF(gHumChar,  GATT_FORMAT_UINT16, -2, 0x27AD); // %
 
  // Initial values
  setTempCentiDeg(gTempChar, 0.0f);
  setPressureDeciPa(gPresChar, 101325.0f);
  setHumidityCentiPct(gHumChar, 0.0f);
 
  gESS->start();
 
  /* --- Battery Service --- */
  gBattSvc  = gServer->createService(BATT_SVC_UUID);
  gBattChar = gBattSvc->createCharacteristic(BATT_LVL_UUID, propsRN);
  // Optional CPF for % (uint8, exponent 0)
  // format for uint8 = 0x04
  addCPF(gBattChar, 0x04, 0, 0x27AD);
  uint8_t lvl = getBatteryPercent();
  gBattChar->setValue(&lvl, 1);
  gBattSvc->start();
 
  /* --- Device Information Service (all READ-only) --- */
  gDIS = gServer->createService(DIS_UUID);
  gDIS->createCharacteristic(DIS_MFR_UUID,   NIMBLE_PROPERTY::READ)->setValue(DIS_MANUFACTURER);
  gDIS->createCharacteristic(DIS_MODEL_UUID, NIMBLE_PROPERTY::READ)->setValue(DIS_MODEL);
  gDIS->createCharacteristic(DIS_FW_UUID,    NIMBLE_PROPERTY::READ)->setValue(DIS_FW_REV);
  gDIS->createCharacteristic(DIS_SW_UUID,    NIMBLE_PROPERTY::READ)->setValue(DIS_SW_REV);
  gDIS->createCharacteristic((uint16_t)0x2A25, NIMBLE_PROPERTY::READ)->setValue(DIS_SN);  // Serial Number
  gDIS->createCharacteristic((uint16_t)0x2A27, NIMBLE_PROPERTY::READ)->setValue(DIS_HW);  // Hardware Rev
 
  // PnP ID (7 bytes): Vendor ID Source (1=Bluetooth, 2=USB), Vendor ID (LE16), Product ID (LE16), Product Version (LE16)
  uint8_t pnp[7] = { 0x02, 0x34, 0x12, 0x78, 0x56, 0x00, 0x01 }; // USB, VID 0x1234, PID 0x5678, ver 0x0100
  gDIS->createCharacteristic(DIS_PNP_UUID, NIMBLE_PROPERTY::READ)->setValue(pnp, sizeof(pnp));
 
  gDIS->start();
 
  /* --- Advertising (keeps your explicit payload approach) --- */
  NimBLEAdvertising* adv = NimBLEDevice::getAdvertising();
 
  // Advertise primary services (ESS + Battery). DIS is usually not advertised.
  adv->addServiceUUID(ESS_UUID);
  adv->addServiceUUID(BATT_SVC_UUID);
 
  NimBLEAdvertisementData advData;
  advData.setFlags(0x06); // LE General Discoverable + BR/EDR Not Supported
  adv->setAdvertisementData(advData);
 
  NimBLEAdvertisementData scanData;
  scanData.setName(DEVICE_NAME); // put name in scan response
  adv->setScanResponseData(scanData);
 
  // Appearance: Generic Thermometer (helps some UIs)
  adv->setAppearance(0x0300);
 
  NimBLEDevice::startAdvertising();
  Serial.println("Advertising: ESS + Battery + DIS (readable). Open nRF Connect -> Scan.");
}
 
/* ============================
   Sensor setup
   ============================ */
bool startBME680() {
  Wire.begin(I2C_SDA_PIN, I2C_SCL_PIN);
  if (!bme.begin(BME680_I2C_ADDR)) {
    Serial.println("[BME680] Not found on 0x77, trying 0x76...");
    if (!bme.begin(0x76)) {
      Serial.println("[BME680] Sensor not found. Check wiring/power.");
      return false;
    }
  }
  bme.setTemperatureOversampling(BME680_OS_8X);
  bme.setHumidityOversampling(BME680_OS_2X);
  bme.setPressureOversampling(BME680_OS_4X);
  bme.setIIRFilterSize(BME680_FILTER_SIZE_3);
  bme.setGasHeater(0, 0); // off
  return true;
}
 
/* ============================
   Updates
   ============================ */
void updateEnv() {
  if (!bme.performReading()) {
    Serial.println("[BME680] performReading() failed");
    return;
  }
  float c = bme.temperature;
  float h = bme.humidity;
  float p = bme.pressure;
 
  setTempCentiDeg(gTempChar, c);
  setHumidityCentiPct(gHumChar, h);
  setPressureDeciPa(gPresChar, p);
 
  gTempChar->notify();
  gHumChar->notify();
  gPresChar->notify();
 
  Serial.printf("[ENV] T=%.2f°C  RH=%.2f%%  P=%.1f Pa\n", c, h, p);
}
 
void updateBattery() {
  uint8_t lvl = getBatteryPercent();
  gBattChar->setValue(&lvl, 1);
  gBattChar->notify();
  Serial.printf("[BATT] %u%%\n", lvl);
}
 
/* ============================
   Arduino entry points
   ============================ */
void setup() {
  Serial.begin(115200);
  while (!Serial) { delay(10); }
 
  if (!startBME680()) {
    // Proceed with BLE even if sensor is missing, so you can still connect
  }
  startBLE();
}
 
void loop() {
  uint32_t now = millis();
 
  if (now - lastEnv >= MEAS_INTERVAL_MS) {
    lastEnv = now;
    updateEnv();
  }
 
  if (now - lastBatt >= BATTERY_INTERVAL_MS) {
    lastBatt = now;
    updateBattery();
  }
 
  delay(10);
}

Upload the code to your board. After uploading, open the Serial Monitor, and restart the Sparrow by pressing the RST/EN button.

You should get a data reading messages in the Serial Monitor.

Then, go to your smartphone, open the nRF Connect app from Nordic, and start scanning for new devices. You should find a device called ESP32-C6 Env, this is the BLE server name you defined earlier.

Connect to it. You’ll see that it displays the Environmental Sensing service with the temperature, humidity, and pressure characteristics. Click on the down arrows to activate the notifications.

Then, click on the second icon (the one that looks like a ” mark) at the left to change the format. You can change to unsigned int for all characteristics. You’ll start seeing the temperature, humidity, and pressure values being reported every 2 seconds.

You can also see a Battery Service and a Device Information Service. Battery is hardcoded for now at 100% and device information is also hardcoded.

The Bluetooth Low Energy (BLE) Current Time Service (CTS) is a standardized GATT (Generic Attribute Profile) service defined by the Bluetooth SIG. It allows a BLE peripheral (like a smartwatch or a clock) to expose the current date and time to another device (like a smartphone or computer).

Service UUID: 0x1805 Purpose: Provides the current time, including date, time, and time accuracy, to connected devices. Typical use case: A smartwatch, time server, or phone shares the correct time with another BLE device (like a sensor or display).

Characteristic UUID: 0x2A2B Properties: Read, Notify Value format (10 bytes total): here

Adjust Reason bitmask:

• A client (e.g., BLE thermometer) connects to a server (e.g., smartphone).
• The client reads the Current Time characteristic to get the date/time.
• The client may subscribe to notifications, so when the time updates (e.g., due to DST), it receives an update automatically.

1. Open nRF Connect → Menu ☰ → “Configure GATT server”.

• Tap Add service. From the list, pick Current Time Service (0x1805) (there’s a built-in preset).

2. Verify characteristics.

• Inside the service, you should see:
  • Current Time (0x2A2B) — properties typically Read, Notify, and Write (with response).
  • (Optional) Local Time Information (0x2A0F) and Reference Time Information (0x2A14).
• If something’s missing, add it manually with the correct 16-bit UUIDs.

3. (Optional) Set an initial value manually for testing:

  The Current Time value is 10 bytes. Example for **2025-10-06 14:32:10**, **Monday**, fractions=0, **AdjustReason=External ref update**:
  `E9 07 0A 06 0E 20 0A 01 00 02`  
  (Little-endian year 0x07E9, then month, day, hour, minute, second, day-of-week 1=Mon, fractions256, adjust-reason bitmask).

1. Go to “Advertiser” (tab at the bottom) and create a new set:

• Enable Connectable (so the client can connect).
• Add Service UUID 0x1805 to the advertising data (helps clients filter).
• Start advertising.

2. Start the server (if your app version separates server start from advertising).

• Make sure your created CTS config is the active one.

1. Connect from your BLE client.

• Many CTS clients will read 0x2A2B on connect and may subscribe to notifications.
• Some stacks require bonding before allowing CTS writes/reads; accept pairing if prompted.

2. Confirm it works.

• On the client, you should see Service 0x1805 with Characteristic 0x2A2B.
• A read should return your current time payload; enabling notifications will push updates when you modify it.

Here is an example of a NimBLE client that discovers a peripheral advertising the Current Time Service, connects, reads characteristic 0x2A2B, and prints the decoded timestamp. Run it on your Sparrow node after setting up a CTS GATT Server.

main.cpp

#include <Arduino.h>
#include <NimBLEDevice.h>
#include <Wire.h>
#include <Adafruit_SSD1306.h>
 
namespace {
 
const NimBLEUUID CTS_SERVICE_UUID((uint16_t)0x1805);
const NimBLEUUID CTS_CHARACTERISTIC_UUID((uint16_t)0x2A2B);
constexpr uint32_t CTS_READ_INTERVAL_MS = 10000; // 10 seconds
 
const NimBLEAdvertisedDevice* g_targetDevice = nullptr;
NimBLEClient* g_client = nullptr;
NimBLERemoteCharacteristic* g_ctsChar = nullptr;
bool g_doConnect = false;
uint32_t g_lastReadMillis = 0;
 
constexpr uint8_t OLED_WIDTH = 128;
constexpr uint8_t OLED_HEIGHT = 64;
constexpr uint8_t OLED_RESET_PIN = -1;
constexpr uint8_t OLED_I2C_ADDR = 0x3C;
constexpr uint8_t OLED_LINE_HEIGHT = 10;
constexpr uint8_t OLED_TOP_MARGIN = 12;
 
Adafruit_SSD1306 g_display(OLED_WIDTH, OLED_HEIGHT, &Wire, OLED_RESET_PIN);
 
struct CurrentTime {
  uint16_t year;
  uint8_t month;
  uint8_t day;
  uint8_t hours;
  uint8_t minutes;
  uint8_t seconds;
  uint8_t dayOfWeek;
  uint8_t fractions256;
  uint8_t adjustReason;
};
 
void printCurrentTime(const CurrentTime& time) {
  static const char* kDays[] = {"Unknown", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"};
  const char* dow = (time.dayOfWeek >= 1 && time.dayOfWeek <= 7) ? kDays[time.dayOfWeek] : kDays[0];
 
  Serial.printf("[CTS] %04u-%02u-%02u %02u:%02u:%02u (%s) adj=0x%02X frac=%u\n",
                time.year,
                time.month,
                time.day,
                time.hours,
                time.minutes,
                time.seconds,
                dow,
                time.adjustReason,
                time.fractions256);
}
 
bool parseCurrentTime(const uint8_t* buffer, size_t length, CurrentTime& out) {
  if (length < 10) {
    Serial.printf("[CTS] Expected 10 bytes, got %u\n", static_cast<unsigned>(length));
    return false;
  }
 
  out.year = static_cast<uint16_t>(buffer[0] | (buffer[1] << 8));
  out.month = buffer[2];
  out.day = buffer[3];
  out.hours = buffer[4];
  out.minutes = buffer[5];
  out.seconds = buffer[6];
  out.dayOfWeek = buffer[7];
  out.fractions256 = buffer[8];
  out.adjustReason = buffer[9];
  return true;
}
 
void displayStatusMessage(const char* message) {
  g_display.clearDisplay();
  g_display.setCursor(0, OLED_TOP_MARGIN);
  g_display.println(message);
  g_display.display();
}
 
void displayCurrentTime(const CurrentTime& time) {
  g_display.clearDisplay();
  g_display.setCursor(0, OLED_TOP_MARGIN);
 
  char line[24];
  snprintf(line, sizeof(line), "%04u-%02u-%02u", time.year, time.month, time.day);
  g_display.println(line);
 
  snprintf(line, sizeof(line), "%02u:%02u:%02u", time.hours, time.minutes, time.seconds);
  g_display.println(line);
 
  static const char* kDays[] = {"", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"};
  const char* dow = (time.dayOfWeek >= 1 && time.dayOfWeek <= 7) ? kDays[time.dayOfWeek] : "";
  g_display.println(dow);
 
  g_display.display();
}
 
class ClientCallbacks : public NimBLEClientCallbacks {
  void onConnect(NimBLEClient* client) override {
    Serial.printf("[BLE] Connected to %s\n", client->getPeerAddress().toString().c_str());
    displayStatusMessage("Connected");
  }
 
  void onDisconnect(NimBLEClient* client, int reason) override {
    Serial.printf("[BLE] Disconnected (reason %d), restarting scan\n", reason);
    g_ctsChar = nullptr;
    g_lastReadMillis = 0;
    NimBLEDevice::deleteClient(client);
    g_client = nullptr;
    displayStatusMessage("Disconnected");
    NimBLEDevice::getScan()->start(0, false, true);
  }
};
 
class ScanCallbacks : public NimBLEScanCallbacks {
  void onResult(const NimBLEAdvertisedDevice* advertisedDevice) override {
    if (!advertisedDevice->isAdvertisingService(CTS_SERVICE_UUID)) {
      return;
    }
 
    Serial.printf("[BLE] Found CTS peripheral: %s\n", advertisedDevice->toString().c_str());
    NimBLEDevice::getScan()->stop();
 
    g_targetDevice = advertisedDevice;
    g_doConnect = true;
  }
 
  void onScanEnd(const NimBLEScanResults& results, int reason) override {
    Serial.printf("[BLE] Scan ended (reason %d, %d devices)\n", reason, results.getCount());
    if (!g_doConnect && g_ctsChar == nullptr) {
      NimBLEDevice::getScan()->start(0, false, true);
    }
  }
};
 
ClientCallbacks g_clientCallbacks;
ScanCallbacks g_scanCallbacks;
 
void startScan() {
  NimBLEScan* scan = NimBLEDevice::getScan();
  scan->setScanCallbacks(&g_scanCallbacks, false);
  scan->setActiveScan(true);
  scan->setInterval(160);
  scan->setWindow(120);
  scan->start(0, false, true);
  Serial.println("[BLE] Scanning for Current Time Service peripherals...");
  displayStatusMessage("Scanning...");
}
 
bool connectToCurrentTimeService() {
  if (!g_doConnect || g_targetDevice == nullptr) {
    return false;
  }
 
  g_doConnect = false;
 
  if (g_client == nullptr) {
    g_client = NimBLEDevice::createClient();
    g_client->setClientCallbacks(&g_clientCallbacks, false);
    g_client->setConnectionParams(12, 12, 0, 200);
    g_client->setConnectTimeout(5000);
  }
 
  Serial.println("[BLE] Connecting to peripheral...");
  if (!g_client->connect(g_targetDevice)) {
    Serial.println("[BLE] Connection failed, restarting scan");
    NimBLEDevice::deleteClient(g_client);
    g_client = nullptr;
    g_ctsChar = nullptr;
    g_targetDevice = nullptr;
    NimBLEDevice::getScan()->start(0, false, true);
    return false;
  }
 
  NimBLERemoteService* service = g_client->getService(CTS_SERVICE_UUID);
  if (service == nullptr) {
    Serial.println("[BLE] Current Time Service not found on peripheral");
    g_client->disconnect();
    NimBLEDevice::deleteClient(g_client);
    g_client = nullptr;
    g_ctsChar = nullptr;
    g_targetDevice = nullptr;
    NimBLEDevice::getScan()->start(0, false, true);
    return false;
  }
 
  NimBLERemoteCharacteristic* characteristic = service->getCharacteristic(CTS_CHARACTERISTIC_UUID);
  if (characteristic == nullptr) {
    Serial.println("[BLE] Current Time characteristic missing");
    g_client->disconnect();
    NimBLEDevice::deleteClient(g_client);
    g_client = nullptr;
    g_ctsChar = nullptr;
    g_targetDevice = nullptr;
    NimBLEDevice::getScan()->start(0, false, true);
    return false;
  }
 
  if (!characteristic->canRead()) {
    Serial.println("[BLE] Current Time characteristic is not readable");
    g_client->disconnect();
    NimBLEDevice::deleteClient(g_client);
    g_client = nullptr;
    g_ctsChar = nullptr;
    g_targetDevice = nullptr;
    NimBLEDevice::getScan()->start(0, false, true);
    return false;
  }
 
  g_ctsChar = characteristic;
  g_lastReadMillis = 0;
  g_targetDevice = nullptr;
 
  Serial.println("[BLE] Ready to read current time");
  displayStatusMessage("CTS ready");
  return true;
}
 
void readAndPrintCurrentTime() {
  if (g_ctsChar == nullptr || g_client == nullptr) {
    return;
  }
 
  if (!g_client->isConnected()) {
    return;
  }
 
  const uint32_t now = millis();
  if (now - g_lastReadMillis < CTS_READ_INTERVAL_MS) {
    return;
  }
  g_lastReadMillis = now;
 
  Serial.println("[CTS] Reading current time...");
  NimBLEAttValue value = g_ctsChar->readValue();
  if (value.length() == 0) {
    Serial.println("[CTS] Read returned empty value");
    return;
  }
 
  CurrentTime time{};
  if (!parseCurrentTime(value.data(), value.length(), time)) {
    return;
  }
 
  printCurrentTime(time);
  displayCurrentTime(time);
}
 
} // namespace
 
void setup() {
  Serial.begin(115200);
  while (!Serial) {
    delay(10);
  }
 
  Serial.println();
  Serial.println("[BOOT] BLE Current Time Service client");
 
  NimBLEDevice::init("ESP32C6-CTS-Client");
  NimBLEDevice::setPower(ESP_PWR_LVL_P9);
  NimBLEDevice::setSecurityAuth(false, false, true);
 
  Wire.begin(21, 22);
  if (!g_display.begin(SSD1306_SWITCHCAPVCC, OLED_I2C_ADDR)) {
    Serial.println("[OLED] SSD1306 allocation failed");
    while (true) {
      delay(1000);
    }
  }
  g_display.clearDisplay();
  g_display.setTextColor(SSD1306_WHITE);
  g_display.setTextSize(2);
  g_display.setCursor(0, OLED_TOP_MARGIN);
  g_display.println("BLE CTS Client");
  g_display.display();
 
  startScan();
}
 
void loop() {
  connectToCurrentTimeService();
  readAndPrintCurrentTime();
  delay(100);
}

All BLE connections done so far in this lab have been without any authentication/encryption. For applications where this is necessary, BLE offers multiple security modes and a bonding scheme which establishes and encrypted connection between devices.

A typical pairing scenarion over BLE goes through these steps:

1. Pairing Request/Response: Devices agree on IO capabilities (keyboard, display, none). 2. Key Exchange: Exchange temporary keys (STK, LTK, IRK, etc.). 3. Encryption Setup: Link is encrypted using generated keys. 4. Bonding (optional): Keys are stored persistently for future use.

We can test pairing with the nRF Connect mobile app.

1. Flash your ESP32-C6 firmware with the code below, which has security-enabled GATT characteristics.
2. Open nRF Connect → Scan → Connect to your ESP32-C6.
3. Try to read a protected characteristic — expect something like:

   Error 0x05: Insufficient Authentication

4. Tap ⋮ → Bond to start pairing.
5. Depending on setup:
   • Just Works: automatic pairing.
   • Passkey Entry: app prompts for a 6-digit PIN.
   • Numeric Comparison: both sides show a code for confirmation.
6. After pairing, retry read — it should succeed.

main.cpp

#include <Arduino.h>
#include <Wire.h>
#include <cmath>
#include <Adafruit_BME680.h>
#include <NimBLEDevice.h>
#include <NimBLEAdvertisementData.h>
 
 
 
namespace {
 
#define I2C_SDA_PIN 21
#define I2C_SCL_PIN 22
#define BME680_I2C_ADDR 0x77
 
constexpr char kDeviceName[] = "ESP32C6 ESS";
const NimBLEUUID kEnvironmentalServiceUUID((uint16_t)0x181A);
const NimBLEUUID kTemperatureCharUUID((uint16_t)0x2A6E);
const NimBLEUUID kHumidityCharUUID((uint16_t)0x2A6F);
const NimBLEUUID kPressureCharUUID((uint16_t)0x2A6D);
constexpr uint32_t kSecurityPasskey = 654321; // 6-digit static passkey for pairing
constexpr uint32_t kNotifyIntervalMs = 5000;  // send notify every 5 seconds
 
Adafruit_BME680 g_bme;
bool g_bmeReady = false;
NimBLECharacteristic* g_temperatureCharacteristic = nullptr;
NimBLECharacteristic* g_humidityCharacteristic = nullptr;
NimBLECharacteristic* g_pressureCharacteristic = nullptr;
volatile bool g_isConnected = false;
uint32_t g_lastNotify = 0;
 
class ServerCallbacks : public NimBLEServerCallbacks {
  void onConnect(NimBLEServer* server, NimBLEConnInfo& connInfo) override {
    g_isConnected = true;
    Serial.printf("[BLE] Central connected: %s\n", connInfo.getAddress().toString().c_str());
  }
 
  void onDisconnect(NimBLEServer* server, NimBLEConnInfo& connInfo, int reason) override {
    g_isConnected = false;
    Serial.printf("[BLE] Central disconnected (reason %d)\n", reason);
    if (!NimBLEDevice::startAdvertising()) {
      Serial.println("[BLE] Failed to restart advertising");
    }
  }
 
  uint32_t onPassKeyDisplay() override {
    Serial.printf("[BLE] Displaying passkey: %06u\n", kSecurityPasskey);
    return kSecurityPasskey;
  }
 
  void onConfirmPassKey(NimBLEConnInfo& connInfo, uint32_t pin) override {
    Serial.printf("[BLE] Confirm passkey %06u for %s\n", pin, connInfo.getAddress().toString().c_str());
    NimBLEDevice::injectConfirmPasskey(connInfo, true);
  }
 
  void onAuthenticationComplete(NimBLEConnInfo& connInfo) override {
    if (connInfo.isEncrypted()) {
      Serial.printf("[BLE] Link encrypted; bonded=%s, authenticated=%s\n",
                    connInfo.isBonded() ? "yes" : "no",
                    connInfo.isAuthenticated() ? "yes" : "no");
    } else {
      Serial.printf("[BLE] Authentication failed; disconnecting %s\n", connInfo.getAddress().toString().c_str());
      NimBLEDevice::getServer()->disconnect(connInfo.getConnHandle());
    }
  }
};
 
class ValueCallbacks : public NimBLECharacteristicCallbacks {
  void onRead(NimBLECharacteristic* characteristic, NimBLEConnInfo& connInfo) override {
    Serial.printf("[GATT] Read from %s on characteristic %s\n",
                  connInfo.getAddress().toString().c_str(),
                  characteristic->getUUID().toString().c_str());
  }
 
  void onWrite(NimBLECharacteristic* characteristic, NimBLEConnInfo& connInfo) override {
    std::string value = characteristic->getValue();
    Serial.printf("[GATT] Write to %s from %s, %zu bytes\n",
                  characteristic->getUUID().toString().c_str(),
                  connInfo.getAddress().toString().c_str(),
                  value.size());
  }
};
 
ServerCallbacks g_serverCallbacks;
ValueCallbacks g_valueCallbacks;
 
bool initBME680() {
  if (!g_bme.begin(BME680_I2C_ADDR)) {
    Serial.println("[BME680] Not found on 0x77, trying 0x76...");
    if (!g_bme.begin(0x76)) {
      Serial.println("[BME680] Sensor not found. Check wiring/power.");
      return false;
    }
  }
 
  g_bme.setTemperatureOversampling(BME680_OS_8X);
  g_bme.setHumidityOversampling(BME680_OS_2X);
  g_bme.setPressureOversampling(BME680_OS_4X);
  g_bme.setIIRFilterSize(BME680_FILTER_SIZE_3);
  g_bme.setGasHeater(0, 0); // Disable gas heater for periodic environmental sampling
 
  Serial.println("[BME680] Sensor initialized");
  return true;
}
 
bool readBME680(float& temperatureC, float& humidityPct, float& pressurePa) {
  if (!g_bme.performReading()) {
    Serial.println("[BME680] Failed to perform reading");
    return false;
  }
 
  temperatureC = g_bme.temperature;
  humidityPct = g_bme.humidity;
  pressurePa = g_bme.pressure; // Library returns Pascals
  return true;
}
 
void setupSecurity() {
  NimBLEDevice::setSecurityAuth(true, true, true); // bonding, MITM, secure connections
  NimBLEDevice::setSecurityIOCap(BLE_HS_IO_DISPLAY_YESNO);
  NimBLEDevice::setSecurityPasskey(kSecurityPasskey);
  NimBLEDevice::setPower(ESP_PWR_LVL_P9);
}
 
void setupGattServer() {
  NimBLEServer* server = NimBLEDevice::createServer();
  server->setCallbacks(&g_serverCallbacks, false);
 
  NimBLEService* environmentalService = server->createService(kEnvironmentalServiceUUID);
 
  g_temperatureCharacteristic = environmentalService->createCharacteristic(
      kTemperatureCharUUID,
      NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::READ_ENC |
          NIMBLE_PROPERTY::READ_AUTHEN |
          NIMBLE_PROPERTY::NOTIFY);
  g_temperatureCharacteristic->setCallbacks(&g_valueCallbacks);
  uint8_t tempPlaceholder[2] = {0xFF, 0x7F}; // NaN equivalent (0x7FFF)
  g_temperatureCharacteristic->setValue(tempPlaceholder, sizeof(tempPlaceholder));
 
  g_humidityCharacteristic = environmentalService->createCharacteristic(
      kHumidityCharUUID,
      NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::READ_ENC |
          NIMBLE_PROPERTY::READ_AUTHEN |
          NIMBLE_PROPERTY::NOTIFY);
  g_humidityCharacteristic->setCallbacks(&g_valueCallbacks);
  uint8_t humidityPlaceholder[2] = {0xFF, 0xFF};
  g_humidityCharacteristic->setValue(humidityPlaceholder, sizeof(humidityPlaceholder));
 
  g_pressureCharacteristic = environmentalService->createCharacteristic(
      kPressureCharUUID,
      NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::READ_ENC |
          NIMBLE_PROPERTY::READ_AUTHEN |
          NIMBLE_PROPERTY::NOTIFY);
  g_pressureCharacteristic->setCallbacks(&g_valueCallbacks);
  uint8_t pressurePlaceholder[4] = {0xFF, 0xFF, 0xFF, 0xFF};
  g_pressureCharacteristic->setValue(pressurePlaceholder, sizeof(pressurePlaceholder));
 
  environmentalService->start();
 
  NimBLEAdvertising* advertising = NimBLEDevice::getAdvertising();
  NimBLEAdvertisementData advData;
  advData.setName(kDeviceName);
  advData.addServiceUUID(kEnvironmentalServiceUUID);
  advData.setAppearance(0x0341); // Thermometer
  advertising->setAdvertisementData(advData);
 
  NimBLEAdvertisementData scanData;
  scanData.setName("Env Sensing", false);
  advertising->setScanResponseData(scanData);
 
  advertising->setConnectableMode(BLE_GAP_CONN_MODE_UND);
  advertising->setDiscoverableMode(BLE_GAP_DISC_MODE_GEN);
 
  if (advertising->start()) {
    Serial.println("[BLE] Advertising environmental sensing service");
  } else {
    Serial.println("[BLE] Failed to start advertising");
  }
}
 
void updateEnvironmentalMeasurements() {
  if (!g_isConnected || !g_bmeReady ||
      g_temperatureCharacteristic == nullptr ||
      g_humidityCharacteristic == nullptr ||
      g_pressureCharacteristic == nullptr) {
    return;
  }
 
  const uint32_t now = millis();
  if (now - g_lastNotify < kNotifyIntervalMs) {
    return;
  }
  g_lastNotify = now;
 
  float temperatureC = 0.0f;
  float humidityPct = 0.0f;
  float pressurePa = 0.0f;
  if (!readBME680(temperatureC, humidityPct, pressurePa)) {
    return;
  }
 
  const int16_t temperatureHundredths =
      static_cast<int16_t>(std::lround(temperatureC * 100.0));
  const uint16_t humidityHundredths =
      static_cast<uint16_t>(std::lround(humidityPct * 100.0));
  const uint32_t pressureValue = static_cast<uint32_t>(std::lround(pressurePa));
 
  uint8_t temperaturePayload[2] = {
      static_cast<uint8_t>(temperatureHundredths & 0xFF),
      static_cast<uint8_t>((temperatureHundredths >> 8) & 0xFF),
  };
  g_temperatureCharacteristic->setValue(temperaturePayload, sizeof(temperaturePayload));
  g_temperatureCharacteristic->notify();
 
  uint8_t humidityPayload[2] = {
      static_cast<uint8_t>(humidityHundredths & 0xFF),
      static_cast<uint8_t>((humidityHundredths >> 8) & 0xFF),
  };
  g_humidityCharacteristic->setValue(humidityPayload, sizeof(humidityPayload));
  g_humidityCharacteristic->notify();
 
  uint8_t pressurePayload[4] = {
      static_cast<uint8_t>(pressureValue & 0xFF),
      static_cast<uint8_t>((pressureValue >> 8) & 0xFF),
      static_cast<uint8_t>((pressureValue >> 16) & 0xFF),
      static_cast<uint8_t>((pressureValue >> 24) & 0xFF),
  };
  g_pressureCharacteristic->setValue(pressurePayload, sizeof(pressurePayload));
  g_pressureCharacteristic->notify();
 
  Serial.printf("[ESS] Notified T=%.2fC H=%.2f%% P=%.2fhPa\n",
                temperatureC,
                humidityPct,
                pressurePa / 100.0f);
}
 
} // namespace
 
void setup() {
  Serial.begin(115200);
  while (!Serial) {
    delay(10);
  }
  delay(1000);
  Serial.println();
  Serial.println("[BOOT] ESP32-C6 Environmental Sensing Server");
 
  Wire.begin(I2C_SDA_PIN, I2C_SCL_PIN);
  g_bmeReady = initBME680();
  if (!g_bmeReady) {
    Serial.println("[BOOT] BME680 not ready; characteristics will remain invalid");
  }
 
  NimBLEDevice::init(kDeviceName);
  setupSecurity();
  setupGattServer();
}
 
void loop() {
  updateEnvironmentalMeasurements();
  delay(100);
}

Follow the tutorial here to learn how to create a Web application that connects directly to your Sparrow ESP32 board. You can use the web app just like a normal phone application to send and receive information over BLE from your device.

Build the application in the tutorial and deploy the web page in your GitHub account.