CC256x TI Bluetooth Stack iBEACONDemo App

Return to CC256x MSP432 TI’s Bluetooth stack Basic Demo APPS

Return to CC256x STM32F4 TI’s Bluetooth stack Basic Demo APPS

Demo Overview

Note: The same instructions can be used to run this demo on the MSP432 or STM32F4 Platforms.

The iBEACON profile is used to provide a different way of location-based information and services. There are two roles defined in this profile, Server and the Client. Any time the Client is in range of the Server advertisements, it will be defined as iBEACON and with special applications it can trigger different behaviors.

This application allows the user to use a console to use Bluetooth Low Energy (BLE) to advertise specific data that can be read by the Client.

It is recommended that the user visits the kit setup Getting Started Guide for MSP432 or Getting Started Guide for STM32F4 pages before trying the application described on this page.

Running the Bluetooth Code

Once the code is flashed, Look at the Device manager for Communications Port (COM x) under Ports (COM & LPT). Attach a terminal program like PuTTY to the serial port (COM x) of the board, x means which COM is open for Communications Port in Device Manager. The serial parameter to use is 115200 Baud rate. Once connected, reset the device using Reset button and you should see the stack getting initialized on the terminal and the help screen will be displayed, which shows all of the commands. This device will become the Server.

Demo Application

The demo application provides a description on how to use the demo application in order to advertise a specific configuration and communicate over bluetoothLE.

Device 1 (Server) setup on the demo application

Note: If you enter values that the application doesn't support, it will show you an example.

a) This first square provides details about the FW, BTPS and Demo application versions for future use such as the Demo application name and the device BD address.
b) The next square provides the default values that the Server is configured to and advertising them.
c) The last square provides the help screen, which shows all of the commands.

Note: In order to change the default values, disabling the advertisement is mandatory.

d) To disable the advertisement you can issue the DisableAdvertiseIbeacon and you will get confirmation of the function.

e) To check which UUID is in use, you can issue the QueryIbeaconUUID command. .

f) To set new UUID, you can issue the SetIbeaconUUID [8 Hex digits]-[4 Hex digits]-[4 Hex digits]-[16 Hex digits]

g) In order to check which iBEACON Major is in use, you can issue the QueryIbeaconMajor command.

h) In order to set new iBEACON Major, you can issue the SetIbeaconMajor [Byte] [Byte]

i) In order to check which iBEACON Minor in use, you can issue the QueryIbeaconMinor command.

j) In order to set new iBEACON Minor, you can use the SetIbeaconMinor [Byte] [Byte] command

k) In order to check which iBEACON Tx Power in use, you can issue the QueryIbeaconTxPower command.

l) In order to set new iBEACON Tx Power, you can issue the SetIbeaconTxPower [up to ±255]

m) After configuring the new data, you can issue the AdvertiseIbeacon command in order to advertise the data.

Device 2 (Client) demonstration

n) When using application like iBeaconDetector from the Android market, you'll be able to see the new data.

Note: In the application you can see that the device in the yellow square is iBeacon and the data is the same as you configured.

Application Commands

TI’s Bluetooth stack is an implementation of the upper layers of the Bluetooth protocol stack. TI’s Bluetooth stack provides a robust and flexible software development tool that implements the Bluetooth Protocols and Profiles above the Host Controller Interface (HCI). TI’s Bluetooth stack's Application Programming Interface (API) provides access to the upper-layer protocols and profiles and can interface directly with a Bluetooth controller chip.

An overview of the application and other applications can be read at the Getting Started Guide for MSP432 and Getting Started Guide for STM32F4.

This page describes the various commands that a user of the application can use. Each command is a wrapper over a TI’s Bluetooth stack API which gets invoked with the parameters selected by the user. This is a subset of the APIs available to the user. TI’s Bluetooth stack API documentation (TI_Bluetooth_Stack_Version-Number\Documentation or for STM32F4, TI_Bluetooth_Stack_Version-Number\RTOS_VERSION\Documentation) describes all of the API's in detail.

GAP Commands

The Generic Access Profile defines standard procedures related to the discovery and connection of Bluetooth devices. It defines modes of operation that are generic to all devices and allows for procedures which use those modes to decide how a device can be interacted with by other Bluetooth devices. Discoverability, Connectability, Pairability, Bondable Modes, and Security Modes can all be changed using Generic Access Profile procedures. All of these modes affect the interaction two devices may have with one another. GAP also defines the procedures for how bond two Bluetooth devices.

Help (DisplayHelp)

Description
This command is responsible for displaying the app's command options. The input parameter to this command is completely ignored, and only needs to be passed in because all Commands that can be entered at the Prompt pass in the parsed information. This command displays the current Command Options that are available and always returns zero.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the command.

Possible Return Values
This command always returns 0

AdvertiseIbeacon

Description
The AdvertiseLE command is responsible for enabling LE Advertisements. This command returns zero on successful execution and a negative value on all errors.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the command.

Command Call Examples
“AdvertiseLE” Attempts to enable Low Energy Advertising on the local Bluetooth device.

Possible Return Values
(0) Successful command
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-66) BTPS_ERROR_INSUFFICIENT_RESOURCES
(-107) BTPS_ERROR_INVALID_DEVICE_ROLE_MODE
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE

API Calls
Depending on the First Parameter Value
GAP_LE_Set_Advertising_Data(BluetoothStackID, (Advertisement_Data_Buffer.AdvertisingData.Advertising_Data[0] + 1), &(Advertisement_Data_Buffer.AdvertisingData));
GAP_LE_Advertising_Enable(BluetoothStackID, TRUE, &AdvertisingParameters, &ConnectabilityParameters, GAP_LE_Event_Callback, 0);

API Prototypes
int BTPSAPI GAP_LE_Advertising_Enable(unsigned int BluetoothStackID, Boolean_t EnableScanResponse, GAP_LE_Advertising_Parameters_t *GAP_LE_Advertising_Parameters, GAP_LE_Connectability_Parameters_t *GAP_LE_Connectability_Parameters, GAP_LE_Event_Callback_t GAP_LE_Event_Callback, unsigned long CallbackParameter)" int BTPSAPI GAP_LE_Set_Advertising_Data(unsigned int BluetoothStackID, unsigned int Length, Advertising_Data_t *Advertising_Data);

Description of API
The GAP_LE_Advertising_Enable provides a method of enabling advertising using the data written using GAP_LE_Set_Advertising_Data. This function takes as parameters the Bluetooth stack ID of the Bluetooth device, a boolean which specifies whether or not other devices may request scan response data (written with call to GAP_LE_Set_Advertising_Data() with Type set to dtScanResponse). The next parameter is a pointer to a structure containing advertising parameters. The next parameter is a pointer to a structure specifying the connectability mode and connectability mode parameters to use. The final two parameters are the GAP LE event callback and callback paramater to use when receiving events caused by advertising (like connection events). This function will return zero on success, or a negative return error code if there was an error. The GAP_LE_Set_Advertising_Data function is provided to allow the local host the ability to set the advertising data that is used during the advertising procedure (started via the GAP_LE_Advertising_Enable function). This function will return zero if successful or a negative return error code if there was an error condition.

DisableAdvertiseIbeacon

Description
The DisableAdvertiseIbeacon command is responsible for enabling LE Advertisements. This command returns zero on successful execution and a negative value on all errors.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the command.

Command Call Examples
“DisableAdvertiseIbeacon” Attempts to disable Low Energy Advertising on the local Bluetooth device.

Possible Return Values
(0) Successful command
(-4) FUNCTION_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE

API Calls
GAP_LE_Advertising_Disable(BluetoothStackID);

API Prototypes
int BTPSAPI GAP_LE_Advertising_Disable(unsigned int BluetoothStackID);

Description of API
The GAP_LE_Advertising_Disable function is provided to allow the local host the ability to cancel (stop) an on-going advertising procedure. This function will return zero if successful or a negative return error code if there was an error condition.

iBEACON Profile Commands

QueryIbeaconUUID

Description
This function is responsible for querying UUID parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the command.

Possible Return Values
(0) Successful command
(-8) INVALID_STACK_ID_ERROR

SetIbeaconUUID

Description
This function is responsible for setting new UUID parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
There is a special parameter needed for this command in the next format:
XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX
[8 Hex digits]-[4 Hex digits]-[4 Hex digits]-[16 Hex digits]

Possible Return Values
(0) Successful command
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

QueryIbeaconMinor

Description
This function is responsible for querying iBeacon Minor parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the command.

Possible Return Values
(0) Successful command
(-8) INVALID_STACK_ID_ERROR

SetIbeaconMinor

Description
This function is responsible for setting new iBeacon Minor parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
There are two parameters needed for this command in the next format: [Byte] [Byte]

Possible Return Values
(0) Successful command
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

QueryIbeaconMajor

Description
This function is responsible for querying iBeacon Major parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the command.

Possible Return Values
(0) Successful command
(-8) INVALID_STACK_ID_ERROR

SetIbeaconMajor

Description
This function is responsible for setting new iBeacon Major parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
There are two parameters needed for this command in the next format: [Byte] [Byte]

Possible Return Values
(0) Successful command
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

QueryIbeaconTxPower

Description
This function is responsible for querying iBeacon TxPower parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the command.

Possible Return Values
(0) Successful command
(-8) INVALID_STACK_ID_ERROR

SetIbeaconTxPower

Description
This function is responsible for setting new iBeacon TxPower parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
There is a one parameter needed for this command in the next format: [±byte]

Possible Return Values
(0) Successful command
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

QueryIbeaconUUID

Description
This function is responsible for querying UUID parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the command.

Possible Return Values
(0) Successful command
(-8) INVALID_STACK_ID_ERROR

SetIbeaconUUID

Description
This function is responsible for setting new UUID parameters. This function will return zero on successful execution and a negative value on errors.

Parameters
There is a special parameter needed for this command in the next format:
XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX
[8 Hex digits]-[4 Hex digits]-[4 Hex digits]-[16 Hex digits]

Possible Return Values
(0) Successful command
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR