Bluetooth Smart C SDK Training - Silicon Labs · The added service will appear as Unknown service, if you write data to the characteristics you should be able to see it in the terminal

silabs.com | Smart. Connected. Energy-friendly Rev. 1.5

Bluetooth Smart C SDK Training

This document is the worksheet for the Blue Gecko training. These

exercises focus on the Simplicity Studio and AppBuilder based

workflow. The last exercise shows as alternative IAR based

workflow.

This worksheet expects that Simplicity Studio v3.3, Bluetooth Smart SDK and IAR Em-

bedded Workbench had been installed prior to the starting the exercises.

The first exercisel run through the factory demo project, then an Eddystone beacon is

being created. The second exercise demonstrating the Energy Profiler. The third section

focus on adding a new customer service to the same project. The fourth exercise is to

create HR monitor starting off with the AppBuilder and creating additional functionality by

adding user interaction to the code. The last exercise is same as third but uses the IAR

based workflow - leaves out Simplicity Studio from the development process.

KEY FEATURES

Four hands-on exercises based on Sim-

plicity Studio

Factory demo

Eddystone beacon

Battery service

Custom service

Customized HR monitor

One hands on exercise based on IAR

workflow

Worksheet for the Blue Gecko FAE training

Exercise 1 - Factory demo

silabs.com | Smart. Connected. Energy-friendly Rev. 1.5 | 1

1 Exercise 1 - Factory demo

This exercise will run the Factory demo and make some changes to the code.

1.1 Prerequisites

Supported kits: SLWSTK61010A (BGM111), SLWSTK6000A (EFR32MG), SLWSTK6020A (EFR32BG)

Silicon Labs Simplicity Studio + EFR32BG/MG support package needed

Silicon Labs Bluetooth Smart C-SDK GA – not the Beta

IAR Embedded Workbench for ARM 7.30 or later

Blue gecko app can be downloaded from Appstore or Playstore scan QR code for the link.

1.2 Running the factory demo

1. Make sure your kit discovered by Simplicity Studio

2. In the Simplicity perspective, select [Software Examples]




3. In the pop-up, select the correct kit, part number, and as SDK the Bluetooth Smart (Simplicity should recognize the kit and the

part), hit [Next]

4. Select ‘SOC demo for Smart Phone App’, and hit [Next]

5. Set project name, or use default, and hit [Next]

6. Make sure the selected build configuration is IAR.

7. From the AppBuilder-plugin (bleDemoSoc-smartphone.isc tab) hit [Generate] to create the project




8. Hit OK on the generation dialog

9. Press Debug to Build & Download

10. From the Debug view, hit the run button to run the demo

11. Check the WSTK screen it should be similar as below

1.2.1 Testing the factory demo

12. Start the Blue Gecko app

13. Tap the Health Thermometer

14. Select your device




15. Check the WSTK sensor data

16. Touch retail Beacon

17. Press PB0 button on the kit

18. Now you should see the beacon info like below

1.3 Changing the Beacon type to Eddystone

19. Exit from the debug perspective

20. Change the Beacon type to Eddystone and change the website address to site of your preference.




21. Generate the project

22. Build the project. Wait until Simplicity Studio flashes the kit.

23. Run the project

24. Check the beacon with the Blue Gecko as you did before

You can use the Blue Gecko app to see the Eddystone beacons, but possibly more power way of demoing Eddystone beacons is

to use native Android Eddystone notifications or on iOS using Chrome to notify of Eddystone beacons.




1.3.1 Adding a new profile to the project using the AppBuilder

25. Exit from the debug perspective

26. Run the Appbuilder-plugin (.isc) to add a new service to the project, add a Battery service by checking the tick box

27. Generate the project again to have new Bluetooth service added to your project.

28. Build the project. Wait until Simplicity Studio flashes the kit.

29. Run the project




1.3.2 Testing the added service with the Blue Gecko app

30. Tap the BLE Stack & Profile Test box

31. Connect to your device

32. Now you should see the new Battery service

Warning!

On IOS/Android the services are cached for a particular slave – it can happen that the new service not show up first

Try to switch on-off Bluetooth. If still not shows up quit from all apps which uses Bluetooth. Sometimes deleting the bonding on

the phone also helps.

If everything went fine you should see the battery level counting up.


Exercise 2 - Energy profiler


2 Exercise 2 - Energy profiler

In this exercise we will run our project as Simplicity Energy Profiler target to evaluate the project’s energy consumption.

33. Right-click on the project to open the toolbar, go to [Profile As] -> [2 Simplicity Energy Profiler Target]. The Energy profiler

starts automatically.




The energy consumption profile changes after a while. This is because or advertisement settings.

34. Go back to the app builder UI and set up different advertisement timing and check the difference in energy consumption with

profiler




35. Generate the project again to have your changes added to your project.

35. Right-click on the project to open the toolbar, go to [Profile As] -> [2 Simplicity Energy Profiler Target].

The project rebuild then the Energy profiler starts automatically. You will see how your changes effected the energy consump-

tion.


Exercise 3 - Adding a custom service


3 Exercise 3 - Adding a custom service

This example will add a custom service which will have a characteristic to receive data. When the master device (tablet/phone) writes

this characteristic the slave (WSTK) will print out the actual data to the VCOM.

36. To add a new service you need to define it in the ble-soc-gattdb.bgproj file. This file is used as an input the for the studio

(bgbuild.exe) and will produce the gatt_db.c and gatt_db.h.

So double click on the ble-soc-gattdb.bgproj file from the Project Navigator.

To edit the xml source of the bgproj file switch the view to source mode

37. Add the new service definition to the file. You can copy paste it from the .bgproj file which is in the provided training material

folder.



<service uuid="f6ec37db-bda1-46ec-a43a-6d86de88561d" advertise="true">

<description>My Service</description>

<characteristic uuid="af20fbac-2518-4998-9af7-af42540731b3" id="my_data">



<properties write="true" indicate="true" />

<value type="hex" length="20" />

</characteristic>

</service>

The bgproj syntax can be found in the UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer User's Guide)

38. Don’t forget to save your modification (Ctrl +S)

39. Delete the gatt_db.c and gatt_db.h files from your project. These file will be regenerated during the build.

40. Drag and drop the service implementation code to the project. So the my_service.c/.h files should be in the project as below

These files can be found in the provided training material folder.




The service implementation - void AttrValueChanged_my_data(uint8array *value) -is only a simple print function

in this case. This function should be called whenever the my_data characteristic changed in the GATT. The stack generates

events for every GATT access. You should register your service callback to the right stack event. The stack events are docu-

mented in the BluetoothSmart_APIRefMan which is located in the SDK installation folder.

41. Edit the app_cfg.c to register the printing callback.

Warning! This file is referenced from the SDK and you are going to edit this.

When you try to write something to it Simplicity Studio offers to make a copy of it to avoid ovewritting the SDK source.

Please choose the default Make a Copy option.




42. Register the callback as below.

With this registration whenever the gattdb_my_data is written by the GATT client (phone/tablet) the AttrValueChanged_my_data

function will be called which will print out the actual data to the console.

43. #include "my_service.h" in to the app_cfg.c.

44. Warning! In this case we do not have to regenerate the project because we edited the configuration manually. Regeneration

could overwrite the bgproj file and the your newly defined service will lost

45. Debug (F11) the project.

46. Run the project




3.1.1 Testing the changes

47. Start a terminal program (PuTTY, teraterm, realterm, ect.) and connect the terminal to the WSTK’s virtual COM (JLink) 115200

8N1 no flow control

48. Run the Blue Gecko app on your Smartphone. In the app, go to section ‘BLE Stack & Profile Test’ and connect to your device.

The added service will appear as Unknown service, if you write data to the characteristics you should be able to see it in the

terminal program.

NOTE: Smartphone’s cache the GATT data so your changes do not necessarily appear in the list of services. To update

the cache, you might need to first close the app and turn off the Bluetooth adapter.

49. Type something to characteristic and save it. The same data should appear on terminal.


Exercise 4 - Customizing a built in profile


4 Exercise 4 - Customizing a built in profile

This exercise will walk you through creating a standard profile using the AppBuilder and modify the code after. Task is to familiarize with

the possible customer workflow and find your way around the code.

So let’s create a Heart Rate measurement device. The heart rate should increase/decrease whenever the PB0/PB1 button pressed.

50. Close the previous project – to make sure you edit the right files. To do this right click on the project then select Close Project

51. Create a new project by selecting the [Software Examples] in the main Simplicity perspective

52. Follow the same steps as in the factory demo, but chose the [SOC Demo - Heart Rate Profile – Server Role] as the project base




53. Generate the project


55. Run the project

56. First you can the run the example and see how the example works with the Blue Gecko App. So open the Blue Gecko app and

browse the GATT.

NOTE: Smartphone’s cache the GATT data so your changes do not necessarily appear in the list of services. To update

the cache, you might need to first close the app and turn off the Bluetooth adapter.

57. Drag and Drop the the my_hr_driver.c/h file files to the workspace. The files can be found in the provided training material folder.

The my_hr_driver.c driver contains 3 functios:

uint16_t my_hr_read(void); void my_button_0_cbk(void); void my_button_1_cbk(void);

These functions have to be connected with the right stack events. The my_hr_read should be connected with the actual heart

rate reading function.

58. So locate the appHwReadHr function in app_hw.c. This is the code which is increasing the heart monitor characteristic value by

one every second by default. You need to overwrite this function.




59. Edit the app_hw.c.

Warning! This file is referenced from the SDK and you are going to edit this.

When you try to write something to it Simplicity Studio offers to make a copy of it to avoid ovewritting the SDK source.

Please choose the default Make a Copy option.

60. Now add the my_hr_read to this function. One possible implementation is below.

61. Include the my_hr_driver.h in app_hw.c




62. The my_button_0_cbk and my_button_0_cbk callbacks should be connected with the button pressed events. Now let’s

register the button callbacks in app_cfg.c.

Warning! This file is referenced from the SDK and you going to edit this. Simplicity Studio offers to make a copy of it to avoid

ovewritting the SDK source. Lets choose the Make a Copy option

The callback registration is below

63. Now include the my_hr_driver.h to the app_cfg.c


65. Run the project




66. Test the app with the Blue Gecko app.

The Heart Rate Measurement Value should incremented/decremented.


IAR workflow


5 IAR workflow

5.1 Prerequisites

IAR 7.30 or later

IAR EFR32 device files - The support files in the shared provided training material folder. (These files may not needed for future

IAR releases)

5.2 Running the factory demo

The Bluetooth Smart SDK contains IAR Embedded Workbench workspace files (*.eww). These can be found in the sdk/iar-ew folder.

There are two types of examples: SoC and NCP. The bleDemo-soc-41xx.eww supports the BRD4100A, BRD4151A, and the BRD4153A

radio boards. The bleDemo-soc-4300.eww supports the BRD4300A radio board only.

67. Copy the device files to IAR

c:\Program Files (x86)\IAR Systems\Embedded Workbench 7.3\arm\config\devices\SiliconLaboratories\

c:\Program Files (x86)\IAR Systems\Embedded Workbench 7.3\arm\config\debugger\SiliconLaboratories\

c:\Program Files (x86)\IAR Systems\Embedded Workbench 7.3\arm\config\linker\SiliconLaboratories\

c:\Program Files (x86)\IAR Systems\Embedded Workbench 7.3\arm\config\flashloader\SiliconLaboratories\

68. Open IAR Embedded Workbench

69. Open the SoC example which is compatible with your kit. If you have MG kits open the c:\SiliconLabs\BluetoothSmartSDK\1.0.0.0-GA\sdk\iar-ew\bleDemo-soc-41xx.eww

70. Compile and run it (Ctrl +D)

71. Test with the Blue Gecko application. Same flow as exercise 1.


IAR workflow


5.3 Adding a new profile to the IAR factory demo

Let’s create the same my_service you already have at chapter 3. The workflow is similar.

72. Edit the bgproj file and add the service definition

73. Go to c:\SiliconLabs\BluetoothSmartSDK\1.0.0.0-GA\sdk\iar-ew\bleDemo-soc\services\

and create a new folder called my_service

Copy the my_service.c/h files to the my_service folder

74. Create a new group in IAR under service group. - Right click on the services group and click on Add then select Add group...

75. Add the files to the IAR workspace - Right click on the my_service group and click on Add then select Add Files…

76. Because the new header file is in a new folder you need to update the include paths -Goto Project-Options (Alt+F7) and

Add $PROJ_DIR$\..\services\beacon to the end of the list as below


IAR workflow


77. Edit the app.c. to call your service callbacks.

/* Value of attribute changed from the local database by remote GATT client */

case gecko_evt_gatt_server_attribute_value_id:

if ( gattdb_alert_level == evt->data.evt_gatt_server_attribute_value.attribute)

{

iaImmediateAlertWrite(&evt->data.evt_gatt_server_attribute_value.value);

}

/* Check if the event is because “my_data” changed by the remote GATT client */

else if ( gattdb_my_data == evt->data.evt_gatt_server_attribute_value.attribute )

{

/* Call my handler */

AttrValueChanged_my_data(&(evt->data.evt_gatt_server_attribute_value.value));

}

break;

78. include my_service.h int to the app.c

79. Download and Debug

80. Open a terminal program and select your WSTK J-Link USB CDC Virtual COM port

81. Write the new characteristic in the Blue Gecko App. Check the output on the terminal window.

Documents

Bluetooth Smart C SDK Training - Silicon Labs · The added service will appear as Unknown service, if you write data to the characteristics you should be able to see it in the terminal