Peripheral Devices

A BLE peripheral device provides data and services that can be connected by central devices.

To be connected by a BLE central device, you need to create a GATT server in your peripheral device. A GATT server contains a set of attributes that are organized logically as services and characteristics. A service, for example a heart rate measurement service, is identified by an UUID. A service may contain many characteristics that have values, for example a heart rate measurement service has a heart rate measurement value characteristic. A BLE central device can then request to read or write these values.

If you need to learn more about GATT attributes, you can refer to Bluetooth.com or this article.

To start a GATT server, you need to define the service and characteristics first. Since services and characteristics are persistent and can be read or written by the central device, you need to define them in global scope, for example:

#include <LBLE.h>
#include <LBLEPeriphral.h>

// Define a simple GATT service with only 1 characteristic
LBLEService ledService("19B10010-E8F2-537E-4F6C-D104768A1214");
LBLECharacteristicInt switchCharacteristic("19B10011-E8F2-537E-4F6C-D104768A1214", LBLE_READ | LBLE_WRITE);

• 19B10010-E8F2-537E-4F6C-D104768A1214 is the service UUID, used by central device for service discovery.

• 19B10011-E8F2-537E-4F6C-D104768A1214 is the characteristic UUID. The GATT protocol treats characteristics as a raw buffer with maximum length of 512 bytes. LBLECharacteristicInt provides a helper class that defines an integer characteristic that you can simply setValue() with integer parameter without having to operate directly on the raw data buffer.

After defining the service and characteristics, you need to define their relationships, and then add the services to the peripheral device, for example:

void setup() {
    // Add characteristics into ledService
    ledService.addAttribute(switchCharacteristic);

    // Add service to GATT server (peripheral)
    LBLEPeripheral.addService(ledService);

To start the GATT server, call the below function, for example:

 LBLEPeripheral.begin();

Note that once begin() is called, you cannot add more services, nor can you change the relationships between services and characteristics.

void loop() {
  delay(100);
  if (switchCharacteristic.isWritten()) {
    const char value = switchCharacteristic.getValue();
    switch (value) {
      case 1:
        digitalWrite(LED_BUILTIN, HIGH);
        break;
      case 0:
        digitalWrite(LED_BUILTIN, LOW);
        break;
      default:
        Serial.println("Unknown value written");
        break;
    }
  }
}

To demonstrate the entire scenario, a brief walkthrough of the SimplePeripheral example of in the LBLE library is provided in the next section.

SimplePeripheral Example

To use this example, open the IDE menu File > Examples > LBLE > SimplePeripheral and upload it. This example waits for central device to write the value to 1 or 0, and change the on-board LED status accordingly. You'll learn how to create an Android app that act as the central device with AppInventor in the next section.

Import AppInventor Example Project

You can use GATT APIs on iOS or Android devices to connect to the peripheral. In this section, you'll learn how to connect to the device with AppInventor, a graphical programming environment for Android application development. To do so, follow the steps below:

• Download the example AppInventor project file BLE_LED.aia from this link.
• Visit AppInventor website and log-in. You can log-in with your Google account.
• From the web interface, select Projects > Import project (.aia) from my computer

• Select and upload the downloaded BLE_LED.aia file

Connecting to BLE Peripheral

This example project connects to the BLE peripheral device by specifying the BLE device address, which is different on each LinkIt 7697 board. The SimplePeripheral example shows device address on the Serial Monitor.

• Open the Serial Monitor with baud rate 9600, and look for the device address, for example:

• In AppInventor, switch to the Blocks view, and find the addr block as shown below:

• Copy and paste the device address from the Serial Monitor to the addr block. Note that AppInventor requires the address in capital hexadecimal letters, for example: D7:00:00:2B:88:8C. It will fail to connect if lower-case letters are given.

• From the AppInventor menu, select Build > App (provide QR code for .apk):

• Wait for a few minutes (it may take some time even after the progress bar have reached 100%), scan the QRCode with your Android device.

• Download and install the apk file BLE_LED.apk. It's an application named BLE Light.

• Launch the app BLE Light, and tap Connect.

• If everything is OK, the ON and OFF buttons becomes enabled.

• Click ON, and the on-board LED turns on.

• Click OFF, and the on-board LED turns off.

Limitations on Bluetooth Library

The known limitations of the LBLE library is as follows, suggestions or feature implementation requests are welcome, please post your comments in our forum.

• LBLEPeripheral only supports 128-bit UUID. To use 16-bit UUID, you need to convert it to 128-bit UUID with the Bluetooth base UUID.
• Cannot define descriptors.

• Cannot dynamically add new services and characteristics after begin().

• Cannot adjust TX power for advertisements.