> For the complete documentation index, see [llms.txt](https://cavedu.gitbook.io/linkit-7697/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cavedu.gitbook.io/linkit-7697/linkit-7697-development-guide-for-arduino-ide/developer-guide/using-bluetooth/peripheral-devices.md). # 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](https://www.bluetooth.com/specifications/generic-attributes-overview) or [this article](https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt#services-and-characteristics). 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 #include // 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); ``` * `19B1001`**`0`**`-E8F2-537E-4F6C-D104768A1214` is the service UUID, used by central device for service discovery. * `19B1001`**`1`**`-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](http://ai2.appinventor.mit.edu/) 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](https://github.com/MediaTek-Labs/Arduino-Add-On-for-LinkIt-SDK/raw/master/middleware/third_party/arduino/hardware/arduino/mt7697/libraries/LBLE/examples/SimplePeripheral/BLE_LED.aia). * Visit [AppInventor website](http://ai2.appinventor.mit.edu/) and log-in. You can log-in with your Google account. * From the web interface, select **`Projects > Import project (.aia) from my computer`** ![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FRXYllamMeNJKup4AdmhV%2Fimport_aia_project.png?alt=media\&token=c524bb7f-9c87-4dbd-9aa4-e1ea0db91054) * 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: ![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FS9SHKrxr7cCi5WcyQeS2%2Fble_device_address.png?alt=media\&token=5ae3f74d-772c-488a-b90d-1c88aabb1f06) * In **AppInventor**, switch to the **Blocks** view, and find the `addr` block as shown below: ![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FSJUhjtsgX59vl7687t5e%2Fappinventor_addr_block.png?alt=media\&token=2be471c2-72e3-4741-b485-13e11cad0b95) * 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. ![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2FCCPcDV4F0WxIX9xaK4Do%2Fappinventor_set_addr.png?alt=media\&token=07eada72-f110-4c49-9fec-1a04fc7ac9df) * From the **AppInventor** menu, select **`Build > App (provide QR code for .apk)`**: ![](https://3972650740-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY4gduUSLWOCI23CXUWej%2Fuploads%2F66mY5X1L6VeLHmNzWSfS%2Fappinventor_build.png?alt=media\&token=240c2be3-8a79-4be4-96ff-175bb2c96bc6) * 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](http://stackoverflow.com/questions/36212020/how-can-i-convert-a-bluetooth-16-bit-service-uuid-into-a-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.