Table of Content
Developing a Bluetooth Low Energy (BLE) enabled IoT product involves a critical intersection between embedded firmware and mobile application development. A common bottleneck in this process arises after the firmware engineer has defined the device’s GATT services and characteristics. To test and validate a custom communication protocol over BLE Service Characteristics, a mobile client is required. This often leads to a frustrating delay, as firmware developers must either wait for a mobile app to be built or spend valuable time creating a complex, throwaway test application for Android or iOS, complete with boilerplate code for permissions, scanning, and asynchronous callbacks.
This paper presents a more efficient, “no-code” approach to this problem using Silicon Labs’ Simplicity Studio and the Network Co-Processor (NCP) Commander tool. This methodology allows firmware engineers to decouple hardware testing from mobile app development, enabling them to immediately and thoroughly validate their device’s BLE functionality. By using the NCP Commander to implement a BLE device with a fully featured GATT Server, without coding any firmware, but instead using BGAPI commands to configure the hardware from a top level tool, so developers can directly send BGAPI commands to advertise the BLE device, allow clients to connect, as well as read, write, and notify characteristics that allows implementing a mobile application that can be used to test and verify the BLE device endpoints and custom communication protocols over BLE.
This guide will provide a step-by-step walkthrough of this process. We will begin by configuring a Silabs development board with an NCP target application. We will then demonstrate how to use the NCP Commander to set up the GATT Server, allowing you to test your device’s entire BLE communication protocol in real-time with a mobile app. By the end of this guide, you will be able to fully test and debug your BLE services and characteristics without writing a single line of firmware code, significantly accelerating your development cycle and improving debugging efficiency.
Tutorial Environment
This guide was developed and validated using the specific hardware and software versions listed below. While the workflow is generally applicable to other compatible hardware, the steps and screenshots reflect this exact configuration.
- IDE: Simplicity Studio v5 (SSv5)
- SDK: Simplicity SDK Suite v2024.12.0
- Mainboard: Wireless Starter Kit Mainboard (BRD4001A)
- Radio Board: xGM210P032 Wireless Gecko Module (BRD4308A Rev A01)
- Target Part: MGM210P032JIA
- Toolchain: GNU ARM v12.2.1
Bluetooth Low Energy (BLE)
More information about what is BLE, GATT, advertising, services and characteristics can be found at:
Building Secure IoT Networks with SiLabs BLE Mesh | Krasamo
BGAPI protocol
BlueGiga API Is a custom binary protocol specification used to externally control a BLE module. It is a collection of binary commands, responses and events.
It is lightweight, specifically designed for ease of implementation with host devices with limited resources, allowing to send and receive data packages, it can be used over UART or USB physical interfaces.
The BGAPI ANSI C host implementation is called BGLIB available with Silicon Labs BLE devices through Simplicity Studio.
https://www.silabs.com/documents/public/reference-manuals/Bluetooth_Smart_Software-BLE-1.3-API-RM.pdf
The full list of supported BGAPI message summary is available at:
https://docs.silabs.com/bluetooth/6.1.0/bluetooth-stack-api/md-doc-bgapi
NCP Commander
Bluetooth NCP Commander is a Simplicity Studio® 5 (SSv5) tool for sending BGAPI commands to an NCP target application during development.
Two versions of the tool are available in SSv5:
- Bluetooth NCP Commander Standalone (For custom hardware)
- Bluetooth NCP Commander (For Silicon Labs Dev Boards)
It’s required to have an NCP device supported by Silabs to use the Bluetooth NCP Commander tool, once the supported hardware is connected through UART, is possible to send BGAPI commands to setup a GATT (Generic Attribute Profile) Server that contains multiple services and characteristics, as well as Advertising the device for allowing clients to establish a connection.
More information about NCP commander is available at:
Prototyping a BLE Based Mobile Application
Before using NCP Commander the Gecko Dev Board, a mobile application needs to be developed for connecting to a BLE GATT Server, implement the native BLE library provided for iOS or Android, for more advanced features, like BLE mesh, Silabs provides their own libraries that can be included with native BLE libraries, by default it will require a class that handles device connection so you can keep a connection alive during the BLE connection session, as well as add your own business logic overriding the on read, on write and on notify event callbacks, so you can control the dataflow through the BLE channel, first, the class diagram for BLE Implementation:
Figure 1. Android BLE Class Diagram
The logic needed for developing all the required classes and interfaces can be found next, the BLE Connection Sequence that describes the process of scanning and finding nearby devices to connect is the following:
Figure 2. BLE Connection Sequence Diagram
Once the connection has been established to the BLE device will be needed to start the communication through the service characteristics read, write and notify:
Figure 3. BLE Characteristic Read/Write Sequence Diagram
Finally, the Notification Sequence Diagram describes the process to subscribe to the characteristic notification state, which allows your app to have an async communication with the BLE device, allowing the app to subscribe to the characteristic notify for on write event.
Figure 4. Characteristic Notification Sequence Diagram
Also is required to handle some specific errors when connecting, reading, writing or at characteristic notification as shown next:
Figure 5. Error Handling Sequence Diagram
To quickstart your BLE communication protocol development with the NCP Commander tool, it is needed to set the debug setpoints just before you write your characteristics, so you can control the flow and simulate request-response sequence, so Is needed to run the app in debug mode.
Advanced BLE Characteristics Communication Protocols
To continue make sure you install Simplicity Studio 5 from Silabs website: https://www.silabs.com/developer-tools/simplicity-studio
After installing SSv5 and opening the app, it’s required to plug the Silabs dev board, install the SDK libraries required for the current device and finally as shown in welcome screen click in start button to create the project used for working with NCP commander:
Image 1. Start Screen
Right away click on “Create New Project” button to start the project wizard:
Image 2. Dev board project screen
Search for NCP, for selecting Bluetooth – NCP example project, which has a fully developed BGLib for running BGAPI commands through NCP Commander:
Image 3. New Project Wizard
Set your project name, path and project files:
Image 4. New Project Wizard Project Configuration
Once the project has been created successfully you are going to be able to read the project documentation in readme.md.
Image 5. Successfully created project.
Some Wireless Gecko boards does not support bootloader application interface, so it’s required to uninstall it for running the project on the board, open the .slcp file to access to project details and then select “SOFTWARE COMPONENTS” tab:
Image 6. Project Overview.
Inside of software components tab, filter components by “Installed” and search for “bootloader”, in the results view select Bootloader Application Interface and click on “Uninstall”:
Image 7. Software Components – Uninstall Bootloader Application Interface.
Once the uninstall process it’s completed successfully a snack bar will popup.
Image 8. Software Components – Component successfully removed.
Finally, to run the project on the board, right click on the top of your current project root folder, select “Run As” and select the first option that appears shown in the image:
Image 9. Run As Silicon Labs ARM program.
The build and flash process is displayed in the bottom of the screen in the Console, wait until Build Finished message appears:
Image 10. Console – Build finished.
To start the NCP commander, go to the “Launcher” tab button found in the top right corner. Next, select in the new window “COMPATIBLE TOOLS” tab.
Image 11. Launcher tab
Inside of compatible tools tab are all the available tools that can be used with your Gecko board, for now we are going to launch “Bluetooth NCP Commander”
Image 12. Launcher Tab – Compatible tools
In order to allow the BLE device to be found by the mobile application, is going to be required to create a new advertisement set, so first click on the “+” button to create it
Image 13. NCP Commander – Create new advertise set
The advertisement set includes settings about how the device is broadcasting, to set an advertisement name, in “Advertising packets” click on the “Edit” button:
Image 14. NCP Commander – Advertise set
In the Advertising Data Creator window you can select all the advertising elements that you require it.
Image 15. NCP Commander – Advertising data creator
Select “Complete Local Name” for setting the advertising name for allowing the app to find the device by name.
Image 16. NCP Commander – Advertising Data Creator – Select complete local name element
Image 17. NCP Commander – Advertising Data Creator – Customize complete local name element
For reading, writing, and notifying through BLE it is required to set at least one service that contains the required characteristics for implementing the communication protocol that can be tested with your mobile device. Create as many services and characteristics required to accomplish your business logic.
Image 18. NCP Commander – Local GATT table
If the connection from the app to the board is successful, the connection will appear in “Ble Connection” with all the information sent from the client to the GATT Server:
Image 19. NCP Commander – BLE connections panel
Every time that the client write a characteristic, you are going to be able to read it through the NCP commander as a “Write Request Received”:
Image 20. NCP Commander – Characteristic write request received
Finally, if the client set up a listener as seen in Figure 4. Characteristic Notification Sequence Diagram, the NCP commander will display all the characteristics that the client has subscribed, so you can write the characteristic through the notification bell button:
Image 21. NCP Commander – Characteristic notification subscribed by the client
After the notification has been written, it will automatically notify the client listener, allowing you to develop over the BLE Gatt Channel more advanced communication protocols that you can continue developing seamlessly between your app and the Gecko board.
Image 22. NCP Commander – Characteristic notify message
Conclusion
By using tools like NCP Commander, developers are able to speed up IOT development by leveraging BLE firmware development to prioritize mobile application over a BLE architecture, particularly if the data structure is already defined as well as the protocol to be implemented over BLE, so every request or command sent through the BLE Service characteristics can be validated simultaneously during GATT Server / Mobile App Client communication in a debugging session that allows to controls the execution flow.
0 Comments