This example demonstrates an implementation of a custom BLE service to toggle an LED on and off via the BLE communication stack.
NOTE: This application can be used with the entire NM1801xx series.
This exmaple requires an understanding of FreeRTOS and builds upon the nmapp2 application template. A rudimnentary knowledge of Bluetooth Low Energy is assumed. There are many resources available on the internet. Adafruit has a gentle introduction on BLE. The Bluetooth SIG has a detailed technical primer covering all aspects of BLE. The key concepts relevant to this example are attributes and characteristics that are essential to data exchanges between devices.
For a guide to build this reference application and flash the binary to the NM1801XX, follow along step by step in the Getting Started guide.
Bluetooth Low Energy (BLE) is a wireless technology that offers a low-power solution
for connecting devices over short distances (less than 100m). In this example, we demonstrate
how to develop a BLE application using the BLE protocol stack that is included in NMSDK2.
The following sections will guide you through the
necessary steps to develop a BLE firmware application including the custom service that will be used to control an LED on the development board.
ble_task.c provides OS interaction and control of the BLE application and stack.
ble_app_main.c is the BLE application, where services and profiles are instantiated and put into operation.
The custom light switch service has two characteristics:
- LED State Characteristic: This will notify and allow the client application (such as a mobile phone app) to read the state of the LED (ON/OFF).
- Control Characteristic: This will allow a client application to write the state (ON/OFF) to control the LED.
Unique UUIDs need to be defined for the service and its characteristics. In this example, they are defined in svc_custom.h as,
- Custom Service UUID: 87e790b9-c2fd-4b51-838d-4656a0603e45
- Custom Tx Characteristics UUID: 87e790b9-c2fd-4b51-838d-4656a0603e46
- Custom Rx Characteristics UUID: 87e790b9-c2fd-4b51-838d-4656a0603e47
The details of each characteristic, called attributes, are defined in svc_custom.c. Attributes are used to specify the value, size, permission of a characteristic.
Note: Adhere to good practices when deriving UUIDs to avoid inadvertent duplication and conflicting with reserved BLE UUIDs.
Once the characteristics are defined, we can implement the event handler for our
custom service. These APIs are defined in custom_api.h.
custom_main.c sets the callbacks for read and write events by issuing,
SvcCustomCbackRegister(customReadCback, customWriteCback)
customReadCback in this example, reads a byte from CustomTxBuffer and provides it to the BLE client for presentation.
The application task registers a callback for when a BLE write occurs by issuing the following,
CustomRegisterDecodeHandler(process_ble_write), and registers process_ble_write as custom_decode_handler.
When customWriteCback is called during a write event, it in turn calls, custom_decode_handler and leads to process_ble_write
Finally, with process_ble_write() the application interprets the data as a command to either turn on or off the LED, and sends the according message to the application task to take according action (LED on/off).
The LED can be toggled using button0 on the device or via a BLE client. Note that the method used by the button action to send LED control messages is the same as those used in the BLE write event.
When the appliation changes the state of the LED it needs to accordingly update the value in the BLE service by issuing a CustomUpdateAttribute.
Here are the steps to interact with the custom light service.
Once the NM1801xx is programmed and completes booting, it will start the BLE stack and begin advertising indicated by blue LED periodic blinking.
The device is advertised as "NM1801xx" definted in ble_app_scan_data_disc[]
If connected to the UART during boot, the CLI will show the following:
Use a BLE client like Infineon AIROC Bluetooh connect app to scan for and connect to the device.
Scan and connect to "NM1801xx" device by tapping on it.
Tap on "GATT DB" to choose a service.
Tap on the UUID of the custom light switch service.
Tap the desired charateristic ( Read / Write ).
Read the LED status
Write the LED status
Read the updated LED status
