Lesson 5 – WICED Bluetooth: Bluetooth Designer – Turn up the Radio!

WICED Bluetooth Using the CYW20719

# Title Comment
0 A Two Hour WICED Bluetooth Class WICED Bluetooth Using the CYW20719 in all its glory
1 Resources Links to all of the Cypress WICED information including videos, application notes etc.
2 Your First Project Making Hello World & the Blinky LED
3 The Super Mux Tool Learning about platforms and the Super Mux Tool
4 Snips Using the example projects to learn Bluetooth
5 Bluetooth Designer Using the tool to customize a project and get going fast
6 The CCCD & Notification Writing back to the Central
7 Advertising  Beacon Building a beacon project to advertise your custom information 
8 Scanner Viewing the world around you
9 Bluetooth Classic SPP Using the Serial Port Profile to Transmit Lots of Data

Source code: 

  • git@github.com:iotexpert/wiced_bt_intro.git
  • https://github.com/iotexpert/wiced_bt_intro

 

Summary

In this lesson we are going to build the simplest project that I could think of… turning an LED on/off with Bluetooth Low Energy.

The important BLE concepts are

  1. What is a Central / Peripheral
  2. What is Advertising
  3. What is a GATT Database

The important WICED Bluetooth Concepts are:

  1. How do you run WICED Bluetooth Designer
  2. What is the structure of a WICED Bluetooth Project
  3. What is a Callback
  4. How is the GATT Database Implemented
  5. How to run CySmart

The steps that we will follow are:

  1. Run BT Designer
  2. Create a project called L5_BluetoothLED
  3. Go to the characteristics page
  4. Add a vendor specific service
  5. Name the Service L5Service
  6. Add an optional characteristic that is vendor specific
  7. Name it RED
  8. Make it 1 byte with an initial value of 01
  9. Set it up for host write
  10. Add a user description to the characteristic
  11. Generate the code
  12. Move the folder to the wiced_bt_class folder
  13. Fix the three include problems
  14. Reset the debug UART to PUART
  15. When there is a write, change the value of the WICED_LED_1 GPIO
  16. Test

BLE Concepts

In the world of BLE there are two sides of every connection

  • The Central – typically a cellphone
  • The Peripheral – your WICED device

Centrals listen for Peripherals that are Advertising.  Advertising is a periodic packet of up to 31 bytes of information that a Peripheral will send out to make it presence known.  When a Central hears the Advertising packets of a Peripheral that is “interesting” it can initiate a connection.

Once a connection is made, how do you exchange information?  The answer is that a Peripheral has a database running inside of it.  The database is called a “GATT database”.   A Central can perform “Service Discovery” to find all of the legal stuff in the database.  The GATT database is organized into one or more “Services” that have one or more “Characteristics”.  For instance a Heart Rate Monitor might have a “Heart Rate Service” with two characteristics, one for heart rate and one for battery level.

There are two types of Services.  Ones that are specified by the Bluetooth SIG, like heartrate.  And vendor specific custom services.

Run Bluetooth Designer

The Bluetooth Designer is a GUI tool that we built into Eclipse.  It allows you to configure some of the fundamental Bluetooth feature (like the GATT Database) and then automatically generate the code.  Start Bluetooth Designer by running File->New->WICED Bluetooth Designer.

Since this is Lesson 5 and we are going to write and LED… call the project “L5_BluetoothLED”

Once you start BT Designer, you screen should look like this.  The project is going to be a BLE only project.

The Characteristics button lets you setup the GATT database.

Add a service by selecting vendor specific service and then hitting the “+”

I’ll call the service “L5Service”

Next add a characteristic by selecting “vendor specific characteristic” and pressing “+”

Change the name to “RED”, Make the device role “Host write to or reads from service”.  Make the size 1 byte and set the initial value to 01 (it must be 01 not 1 or 001)

When we are looking at this remotely you would like to be able to see the user description.  So click that tab and give it a description.

Press Generate Code button.  You will end up with a folder in the top level apps directory.  I don’t like this, so lets move it into our class projects folder.  You can do this by dragging the folder to the wiced_bt_class folder.  Now it should look like this:

Unfortunately, there are three little issues that this creates which need to be fixed.  First, you need to fix L5_BluetoothLED.c as this include is wrong.

And change it to:

Next edit L5_BluetoothLED_db.h and add the #include “wiced.h”

Finally edit the L5_BluetoothLED_db.c to fix the same include problem.

It should be like this.

Now edit the make target that was created by the BT Designer and change it to:

Remember in the earlier lesson I showed you about the WICED HCI UART and the WICED PUART.  Well by default the WICED_BT_TRACE is setup to go to the HCI UART.  So, lets fix the output of BT_TRACE to go to the PUART by changing the file “L5_BluetoothLED.c”

The last thing that we want to do is fix it so that when the Central writes a new value into the RED LED characteristic we should write the GPIO to the new value.  In L5_BluetoothLED.c make this change.

Now build the project and see what happens.  The first testing step will be to open CySmart.  You can see that a device called “L5_BluetoothLED” is advertising.

When I click it, you can see that there is a GattDB.

When I click on the database, I can see that there is only one service (which makes sense as we setup only one)

Click on the Service and you can see that there is only one characteristic in the service… and its value is 01.

When you click the descriptor button you can see that there is a Characteristic User Description

 

And finally the value is “Red LED Value”.  That is what we setup.

When you click back … then click on the write it will bring up this window where I can send a new value.

Now the value is 0x00 and the RED LED is on (remember from earlier that it is active low so that makes sense)

 

And when I look at the terminal I can see two writes (I wrote again before I took this screen shot)

A Tour of the Source Code

The GATT Database is in the file L5_BluetoothLED_db.c

Each row in the Database table has a unique “Handle” that is defined in the L5_BluetoothLED_db.h

Each characteristic value is held in one of the uint8_t arrays found in “L5_BluetoothLED.c”