BLE-Smart-LED-application-nRF52

Let’s face it…

One of the hardest things when working with BLE is simply getting started.

Whether it’s the setup of the IDE, the configuration of the project, or the implementation the BLE application.

I’ve been there… I’ve felt lost, not knowing where and how to start… This is especially true since I was trying to learn the technology itself (BLE) in addition to learning an SDK, platform, and IDE all at once! It just felt overwhelming and way too many things to learn at one time.

Lately, I’ve been focusing on one platform/chipset: Nordic’s nRF52. This is due to one main reason: I’ve found it to be the most developer-friendly platform out there. (It also helps that you get a FREE commercial license for a professional IDE: Segger Embedded Studio (SES)!)

There’s nothing wrong with the other platforms and chipsets, but it also helps if you stick to one platform that you feel comfortable with (at least for a given period of time, especially in the beginning of your journey in learning a technology).

Ok, enough with the rant, and let’s get into what this post is all about:

To guide you through setting up and developing the most basic BLE peripheral application: a smart BLE lightbulb application you can control from your smartphone.

In the previous blog post (The complete cross-platform nRF development tutorial), we went over how to set up the IDE of choice for developing nRF52 applications (Segger Embedded Studio) on any platform (macOS, Windows, Linux). In this post, we’ll focus on developing the BLE peripheral application, building it, debugging it, and finally testing it from a mobile phone application.

The simplest BLE Peripheral application

We’re going to build a very simple BLE lightbulb application that allows you to turn ON/OFF an LED on the nRF52840 development kit. The Peripheral application will also expose the battery level of a coin-cell battery installed in the development kit. The peripheral will notify the Central (mobile phone application in our case) when the battery level gets updated.

Keeping the example dead-simple is extremely important. You can always customize and expand your application once you’ve learned the basics.

But if you start with a complex application, you can get lost, and ultimately become frustrated before you get something working.

…which is why we’re keeping it simple in this application!

Prerequisites

To follow along with this example, you’ll need to know the basics of BLE. It does not require you to have in-depth knowledge of BLE. In fact, I recommend you do not spend too much time going through the theory and skip right into developing a BLE application and getting your hands dirty once you’ve gone through learning the basics.

If you’re looking to learn the basics, or simply need a refresher, I recommend checking out my FREE 7-day crash course on the Basics of Bluetooth Low Energy (BLE). Sign up by filling out the form in the bottom right-hand corner of the webpage:

Alternatively, you can sign up at the following link: FREE 7-day crash course on Bluetooth Low Energy (BLE).

So, what hardware & software do I need?

For this tutorial, you’ll need the following:

  • nRF52840 development kit (although any nRF5x development will work, with some modifications)
  • A PC running either Windows, Linux, or macOS (for development)
  • Segger Embedded Studio
  • nRF5 SDK (in our case, we’re using the latest SDK provided by Nordic: nRF5 SDK version 15.0.0)
  • A mobile phone
  • BLE client application running on the mobile phone (such as Nordic’s nRF Connect or LightBlue)

Getting Started

Installing the SDK

We’ve already covered how to install Segger Embedded Studio (the FREE License IDE used for nRF5x development) in a previous post. Here, we’ll focus on the steps that follow the installation.

Next, let’s download the latest nRF5 SDK (version 15.0.0) from Nordic’s website.

Once you have it downloaded, place it in a new folder. To make things easier, we’ll put it in a folder alongside the application we’ll be developing.

In my setup, I’ll be creating a new folder named “BLE Projects” which contains the SDK folder as well as another folder for the application.

Folder Structure Setup

Create a new folder to hold the SDK as well as the application (I named it “BLE Projects“):

  • Copy the SDK folder to the “BLE Projects” folder
  • [Optional] Rename the SDK folder to “nRF5_SDK_Current”. This way, if I need to migrate to a newer SDK, all I have to do is place it in that folder, and my current projects will not have to be updated (other than any changes needed for the APIs to work with the newer SDK)
  • Navigate to the folder examples/ble_peripheral/ and copy the folder ble_app_template to the BLE Projects folder
  • Copying the example application folder outside of the SDK makes it easier to keep it self-contained and independent of any changes you make to the SDK folder (such as installing a newer SDK)
  • Rename ble_app_template to another meaningful name that describes our simple application: ble_lightbulb

Now, it’s time for a little clean-up!

The example application folder contains a few unnecessary files and folders (related to other IDEs). I also find that it contains too many nested folders that make it harder to find important files. We’ll do the following:

  • Move the sdk_config.h file to the root folder of the application (located under pca10056/s140/config)
  • Move the SES Solution file (ble_app_template_pca10056_s140.emProject) along with the flash_placement.xml file to the root application folder (both of these files are located under pca10056/s140/ses).
  • You can also move the *.jlink and *.emSession files, but those are not necessary as SES will re-create them once you open the Solution.
  • Delete the ble_app_template.eww file
  • Delete the pca* folders (don’t forget to move the files listed above before you do this!)

Here is what the resulting folder looks like for me:

SES Project File Configuration

Now that we’ve got the folder structure set up, we need to update the SES project file to reflect these changes (this is something we’ll only have to do once).

First, rename the file “ble_app_template_pca10056_s140.emProject” to “”ble_lightbulb_pca10056_s140.emProject“.

Next, open the file in your text editor of choice.

Here are the modifications we’re going to make to the project file (I’ve already made all the changes and provided the full source code available for you to download if you want to skip these steps, at the end of this post):

  • Rename the Solution and Project names:

    to:
  • Replace any references to the SDK (since we copied the application folder outside the SDK).
    Replace “../../../../..” with “nRF5_SDK_current”
    E.g.:


    replaced with:

Next, open the Solution (*.emProject file) in SES.

Now, make the following changes to the Project and the source files:

  • In main.c, change the advertised name:
  • Also in main.c, add the following lines (highlighted):
  • Also, make sure you add the code to instantiate the LED Service object. This is done by calling a macro as following (macro will be defined later in led_service.h):
  • Remove any peer manager references (only needed for security features):
    • Change

      to:
    • Remove the following block of code:
    • Delete the following block:
    • Change

      to
    • Remove the highlighted line:
    • Change

      to
    • Modify the following (we are not using any buttons in our application, so we only need to initialize the LEDs):

      to
    • In main(), modify

      to
  • Change the debug print out for the main application:

    to
  • We need to add a write handler for the LED settings in main.c. This function will get used for the custom service and characteristic we’ll be implementing in our application.

BLE Lightbulb Application Design

Let’s talk about the design of our application, and what elements we need to add to implement our smart BLE-controlled lightbulb.

The application allows the user to:

  • Discover the BLE Peripheral named “BLE_Lightbulb” from a BLE Central application
  • Connect to the Peripheral and discover the Services and Characteristics exposed by the Peripheral
  • Turn ON/OFF LED2 on the nRF52840 development kit as well as read the status of the LED (whether ON or OFF)
  • Subscribe to Notifications to the Battery Level Characteristic exposed by the Peripheral inside the Battery Service

LED Service + LED 2 Characteristic

To be able to control the LED on the development kit from a BLE client (a smartphone application in our case), we’ll need to implement a custom service and characteristic for the LED.

iIn a previous post (Custom Services and Characteristics [BLE MIDI use case]), we described how to create custom services and characteristics, but here’s all you need to know:

  • We need to create one service. We’ll call it led_service.
  • In that service, we’ll add a single characteristic dedicated to LED 2 on our development kit (LED 1 will be used to indicate the state of the BLE peripheral: Advertising or Connected). Let’s call this characteristic: led_2_char.
  • For each (service and characteristic), we’ll need to choose a custom UUID (to learn more about custom/vendor-specific UUIDs and how to pick them, refer to this blog post (Creating custom UUIDs).
  • We’ll define the UUIDs as following:
    • LED Service UUID: E54B0001-67F5-479E-8711-B3B99198CE6C
    • LED 2 Characteristic UUID: E54B0002-67F5-479E-8711-B3B99198CE6C
  • The LED 2 Characteristic will have the following permissions:
    • Write-enabled
    • Read-enabled
    • NO Notifications or Indications enabled (since we’ll be controlling the LED from the BLE client)

Implementation

Instead of including the implementation of the LED service in the main.c file, we’ll be including them in a separate folder and files.

Let’s create two files: led_service.h & led_service.c.

We’ll be placing these in a separate folder named Services.

  • Create a folder named Services in the root folder of the application (from your Operating System’s file explorer)
  • Right-click on Project ‘ble_lightbulb’
  • Click New Folder
    Create new project folder SES
  • Rename New Folder to Services
  • Now you should have an empty Services folder
  • Right-click on Services and choose to Add New File
  • Choose C File (.c), and type led_service.c in the Name field
  • Under Location, click Browse and navigate to the Services folder
  • Select Services and click Choose

  • Click OK
  • Repeat the steps above but choose Header File (.h) instead and enter led_service.h in the Name field

Here are the contents of the source files. We’ll list the full source code first and then go through the content explaining it.

led_service.h

led_service.c

Let’s explain the most important elements of the implementation:

led_service.h

  • Lines 33-39: define a macro that will be used in main.c to instantiate the LED service data structure
  • Lines 41-53: define the UUIDs for the LED Service and the LED 2 Characteristic
  •  Lines 55-65: define the led write handler function prototype and the LED service initialization data structure
  • Lines 67-79: define the main LED service data structure that stores all the information relevant to the service
  • Lines 81-100: declare the functions needed for initializing the service as well as the event handler

led_service.c

  • Lines 18-23: include the necessary header files as well as define the string
  • Lines 25-44: define the functions for handling the connection and disconnection events
  • Lines 46-61: define the function for handling the BLE write event
  •  Lines 63-112: define the function for adding the LED 2 Characteristic
  • Lines 114-153: define the function used to initialize the LED Service
  • Lines 155-177: define the BLE event handler that gets called by the SoftDevice (to handle the different events such as connection, disconnection, and write events)

Battery Service

In addition to the custom Service and Characteristic, we’ll be using the Bluetooth SIG defined Battery Service, which includes a Battery Level Characteristic. (No need to create our own custom since we can reuse the SIG-defined Service).

Nordic’s SDK already has this Service implemented, so all we need to do is:

  • Enable the Battery Service in sdk_config.h. You can do so by setting the following macro to 1:
  • Add the ble_bas.c file:
    • Right-click on the folder named nRF_BLE under the Project in the Project Explorer window
    • Click on Add Existing File
    • Locate the ble_bas.c file under <SDK folder>/components/ble/ble_services/ble_bas
    • Click on ble_bas.c and hit Add
  • Update NRF_SDH_BLE_VS_UUID_COUNT in sdk_config.h to reflect the number of custom UUIDs (2 in our case: one for the LED Service and one for the LED 2 Characteristic)

Now that we have the Battery Service enabled, we need to implement the actual reading of the battery voltage level from the coin-cell battery installed in the development kit.

The good thing is we don’t have to implement this from scratch. In fact, one of the components within the nRF5 SDK provides exactly what we need!

The component we’ll be borrowing the code from is the Eddystone component (used for a beacon standard called Eddystone).

Navigate to the folder <SDK folder>/components/ble/ble_services/eddystone

There you will find the files:

es_battery_voltage.h
es_battery_voltage_saadc.c

We’ll copy these files into our project folder “ble_lightbulb” under a newly created folder named Battery Level.

Then rename them to “battery_voltage.c” and “battery_voltage.h“:

Now, you’ll need to add this folder to the Project in SES. Follow the same steps we did before with the LED Service files (creating a folder named Battery Level, but then using the Add Existing File option instead of creating a new one).

We’ll make a few slight modifications to functions names and such:

battery_voltage.h

battery_voltage.c

To be able to read the battery level, we have to set up a timer to trigger the reading of the battery voltage in the application’s main.c file.

Here are the changes we need to make to implement this functionality:

  • Define the battery timer and the battery level update period:
  • Declare two functions for handling the timeout and another for updating the battery level:

  • Next, we need to add the timer that triggers the battery level read operation. We add this to the timers_init() function:
  • Add a function to start the timer, and then call it from main()
  • Enable the SAADC (Analog to digital converter), needed for reading the battery voltage level. Open sdk_config.h and enable the SAADC in two locations:

  • Add the SAADC driver file. Right-click on “nRF_Drivers” and click on “Add Existing File“. Then navigate to “nRF5_SDK_current/modules/nrfx/drivers/src/” and select the file “nrfx_saadc.c“

Initializing the Services

Finally, we need to initialize the LED and Battery Services in the main file (main.c).

To do that, we implement the following function:

The function initializes both Services as well as defines the permissions of the Battery Service and Battery Level Characteristic.

This function already gets called from the main function main() :

Flashing and debugging

Before we build and flash our program to the development kit (nRF52840), we want to enable logging first so we can better follow the state of events and the state of our application.

To get this working:

  • Open sdk_config.h and make sure the following macros are set to the correct debug level (4). This level will enable all debug statements in the debug terminal within SES when you run your application.

Now, we can flash the application to the development kit.

To do this:

  • Right click on “Project ‘ble_lightbulb’“
  • Select “Build“
  • Right-click again on “Project ‘ble_lightbulb’“
  • Select “Debug → Start Debugging“
  • The application will start and stop at main() waiting for you to continue execution
  • You should now see the output in the debug terminal similar to the following:

Testing

Our next and final step is to test our application and make sure it’s working fine. For this, we will use a mobile phone app that acts as a BLE Central.

For this example, we’ll be using an app called LightBlue (available for iOS and Android).

Here’s a video showing the application running on the development kit:

Summary

In this post, we went over how to build a full BLE peripheral application that you can use as a starting point for developing any BLE application on the nRF52 platform. We went over:

  • Setting up the Project and Solution file for the application
  • Fully implementing a BLE application that allows you to turn ON/OFF an LED on the nRF52840 development kit
  • Building, flashing, and debugging the application on the nRF52840 development kit
  • Testing the application from a mobile phone app to make sure it is functioning correctly

To be notified when future blog posts are published here on the Novel Bits blog, be sure to enter your email address in the form below!

If you would like to download the code used in this post, please enter your email address in the form below. You’ll get a .zip containing all the source code, and I will also send you a FREE 9-page Report on the Essential Bluetooth Developer Tools. In addition to that, you will receive exclusive content, tips, and tricks that I don’t post to the blog!

Posted in BLE technology, Tutorials and tagged , , ,