SWRU271I October   2010  – January 2020 CC2540 , CC2540T , CC2541 , CC2541-Q1 , CC2640R2F

 

  1.   Preface
    1.     Trademarks
    2.     Related Documentation
  2. 1Overview
    1. 1.1 Support Note
    2. 1.2 Introduction
    3. 1.3 Bluetooth Low Energy Protocol Stack Basics
  3. 2The TI Bluetooth Low Energy Software Development Platform
    1. 2.1 Overview
    2. 2.2 Configurations
    3. 2.3 Projects
    4. 2.4 Software Overview
  4. 3The Operating System Abstraction Layer (OSAL)
    1. 3.1 Overview
    2. 3.2 Task Initialization
    3. 3.3 Task Events and Event Processing
    4. 3.4 Heap Manager
    5. 3.5 OSAL Messages
  5. 4The Application and Profiles
    1. 4.1 Overview
    2. 4.2 Project Overview
    3. 4.3 Start-up in main()
    4. 4.4 Application Initialization
    5. 4.5 Event Processing
      1. 4.5.1 Periodic Event
      2. 4.5.2 OSAL Messages
    6. 4.6 Callbacks
    7. 4.7 Complete Attribute Table
    8. 4.8 Additional Sample Projects
  6. 5The Bluetooth Low Energy Protocol Stack
    1. 5.1 Overview
    2. 5.2 Generic Access Profile (GAP)
      1. 5.2.1 Overview
        1. 5.2.1.1 Connection Parameters
        2. 5.2.1.2 Effective Connection Interval
        3. 5.2.1.3 Connection Parameter Considerations
        4. 5.2.1.4 Connection Parameter Update
        5. 5.2.1.5 Connection Termination
      2. 5.2.2 GAP Abstraction
      3. 5.2.3 Configuring the GAP Layer
    3. 5.3 GAPRole Task
      1. 5.3.1 Peripheral Role
      2. 5.3.2 Central Role
    4. 5.4 Gap Bond Manager (GAPBondMgr)
      1. 5.4.1 Overview of Bluetooth Low Energy Security
      2. 5.4.2 Using the GapBondMgr Profile
      3. 5.4.3 GAPBondMgr Examples for Various Security Modes
        1. 5.4.3.1 Pairing Disabled
        2. 5.4.3.2 Just Works Pairing Without Bonding
        3. 5.4.3.3 Just Works Pairing With Bonding Enabled
        4. 5.4.3.4 Authenticated Pairing
        5. 5.4.3.5 Authenticated Pairing With Bonding Enabled
    5. 5.5 Generic Attribute Profile (GATT)
      1. 5.5.1 GATT Characteristics and Attributes
      2. 5.5.2 GATT Services and Profile
      3. 5.5.3 GATT Client Abstraction
        1. 5.5.3.1 Using the GATT Layer Directly
      4. 5.5.4 GATT Server Abstraction
        1. 5.5.4.1 GATTServApp Module
          1. 5.5.4.1.1 Building Up the Attribute Table
        2. 5.5.4.2 Profile Architecture
          1. 5.5.4.2.1 Attribute Table Definition
            1. 5.5.4.2.1.1 Service Declaration
            2. 5.5.4.2.1.2 Characteristic Declaration
            3. 5.5.4.2.1.3 Characteristic Value
            4. 5.5.4.2.1.4 Client Characteristic Configuration
          2. 5.5.4.2.2 Add Service Function
          3. 5.5.4.2.3 Register Application Callback Function
          4. 5.5.4.2.4 Read and Write Callback Functions
            1. 5.5.4.2.4.1 Read Request from A GATT Client
            2. 5.5.4.2.4.2 Write Request From Client
          5. 5.5.4.2.5 Get and Set Functions
    6. 5.6 L2CAP
    7. 5.7 HCI
      1. 5.7.1 HCI Extension Vendor-Specific Commands
      2. 5.7.2 Receiving HCI Extension Events in the Application
    8. 5.8 Library Files
  7. 6Drivers
    1. 6.1  Overview
    2. 6.2  ADC
    3. 6.3  AES
    4. 6.4  LCD
    5. 6.5  LED
    6. 6.6  KEY
    7. 6.7  DMA
    8. 6.8  UART and SPI
    9. 6.9  Other Peripherals
    10. 6.10 Simple NV (SNV)
  8. 7Creating a Custom Bluetooth Low Energy Application
    1. 7.1 Overview
    2. 7.2 Configuring the Bluetooth Low Energy Stack
    3. 7.3 Define Bluetooth Low Energy Behavior
    4. 7.4 Define Application Tasks
    5. 7.5 Configure Hardware Peripherals
    6. 7.6 Configuring Parameters for Custom Hardware
      1. 7.6.1 Board File
      2. 7.6.2 Adjusting for 32-MHz Crystal Stabilization Time
      3. 7.6.3 Setting the Sleep Clock Accuracy
    7. 7.7 Software Considerations
      1. 7.7.1 Memory Management for GATT Notifications and Indications
      2. 7.7.2 Limit Application Processing During Bluetooth Low Energy Activity
      3. 7.7.3 Global Interrupts
  9. 8Development and Debugging
    1. 8.1 Overview
    2. 8.2 IAR Overview
    3. 8.3 Using IAR Embedded Workbench
      1. 8.3.1 Open an Existing Project
      2. 8.3.2 Project Options, Configurations, and Defined Symbols
      3. 8.3.3 Building and Debugging a Project
      4. 8.3.4 Linker Map File
  10. 9General Information
    1. 9.1 Overview
    2. 9.2 Porting From BLE-Stack 1.5.0 to 1.5.1
    3. 9.3 Porting From BLE-Stack 1.4.2 to 1.5.0
    4. 9.4 Porting From Earlier BLE-Stack Versions
      1. 9.4.1 Porting BLEv1.4.1 Projects to BLEv1.4.2
      2. 9.4.2 Porting BLEv1.4.0 Projects to BLEv1.4.1
        1. 9.4.2.1 Project Porting Directions
        2. 9.4.2.2 API Changes
        3. 9.4.2.3 Typedef Changes
        4. 9.4.2.4 Structure Changes
          1. 9.4.2.4.1 Array Elements Changed to Pointers
          2. 9.4.2.4.2 Additional Fields in Key Distribution Strucutre
        5. 9.4.2.5 Default Value of HAL Components
        6. 9.4.2.6 Allocating Memory for Over-the-Air Messages
        7. 9.4.2.7 Allocation of Client Characteristic Configuration Table
      3. 9.4.3 Porting BLEv1.3.2 Projects to BLEv1.4.0
      4. 9.4.4 Porting BLEv1.2 Projects to BLEv1.3
      5. 9.4.5 Porting From CC2540 to CC2541 Project
    5. 9.5 Release Notes History
    6. 9.6 Document History
  11.   A GAP API
    1.     A.1 Commands
    2.     A.2 Configurable Parameters
    3.     A.3 Events
  12.   B GAPRole Peripheral Role API
    1.     B.1 Commands
    2.     B.2 Configurable Parameters
    3.     B.3 Callbacks
      1.      B.3.1 State Change Callback (pfnStateChange)
      2.      B.3.2 RSSI Callback (pfnRssiRead)
  13.   C GAPRole Central Role API
    1.     C.1 Commands
    2.     C.2 Configurable Parameters
    3.     C.3 Callbacks
      1.      C.3.1 RSSI Callback (rssiCB)
      2.      C.3.2 Central Event Callback (eventCB)
  14.   D GATT/ATT API
    1.     D.1 Overview
    2.     D.2 Server Commands
    3.     D.3 Client Commands
    4.     D.4 Return Values
    5.     D.5 Events
    6.     D.6 GATT Commands and Corresponding ATT Events
    7.     D.7 ATT_ERROR_RSP Error Codes
  15.   E GATTServApp API
    1.     E.1 Overview
    2.     E.2 Commands
  16.   F GAPBondMgr API
    1.     F.1 Overview
    2.     F.2 Commands
    3.     F.3 Configurable Parameters
    4.     F.4 Callbacks
      1.      F.4.1 Passcode Callback (passcodeCB)
      2.      F.4.2 Pairing State Callback (pairStateCB)
  17.   G HCI Extension API
    1.     G.1 Overview
    2.     G.2 Commands
    3.     G.3 Host Error Codes
  18.   Revision History

8.3.2 Project Options, Configurations, and Defined Symbols

Every project has a set of options, including settings for the compiler, linker, debugger, and so forth.

To view the project options, do the following:

  1. Right-click on the project name at the top of the file list.
  2. Select Options… (See Figure 8-2.)
    3. figure_22A_swru271.gifFigure 8-2 Project Configurations and Options

    After clicking Options…, a window will pop-up displaying the project options. You might need to have a few different configurations of options for different setups, like when using multiple hardware platforms. The IAR lets you create configurations. You can select these configurations through the drop-down menu in the top of the Workspace pane, see Figure 8-2.

    The default configuration in the SimpleBLEPeripheral project is the CC2540DK-MINI Keyfob configuration, which is targeted toward the keyfob hardware platform included with the CC2540/41DK mini development kit. Alternatively, CC2540 is optimized for the SmartRF05 + CC2540 EM included with the full development kit. Other configurations include a 128-KB part, an OAD, and so forth:

figure_22B_swru271.gifFigure 8-3 Project Configurations

Compiler preprocessor definitions or symbols are important settings when building a project, see Figure 8-4.

You can find and set these values by doing the following:

  1. Click the C/C++ Compiler category on the left.
  2. Click the Preprocessor tab on the right:
figure_23A_swru271.gifFigure 8-4 Preprocessor Defined Symbols Settings

When preceded by an x, the symbol has no valid definition and can be considered disabled. Removing the preceding x to restore the proper name of the symbol reenables the feature or definition.

Symbols can be defined in configuration files, which are included when compiling. The Extra Options tab under the compiler settings let you set up the configuration files to be included. You must include the config.cfg file with every build because it defines some required universal constants. The buildConfig.h file included with the software development kit defines the appropriate symbols for the project, see Figure 8-5.

figure_23B_swru271.gifFigure 8-5 The buildConfig.h File

Select the Use command line option box through the Extra Options tab shown in Figure 8-6 to supply the compiler with additional options.

figure_24_swru271.gifFigure 8-6 Configuration File Setup

The Bluetooth Low Energy protocol stack and software uses the following symbols. You can find them in the sample project:

Symbols Mandatory for Bluetooth Low Energy Stack

  • INT_HEAP_LEN – This symbol defines the size of the heap used by the OSAL Memory Manager in bytes, see Section 3.4. The default value in the sample project is 3072. You can increase this value if the application requires additional heap memory. If this value is increased too much, you may exceed the RAM limit. If the application requires additional memory for local variables, you may need to increase this value. The memory set aside for the heap shows up in the map file under the OSAL_Memory module. For more information on the map file, see section Section 8.3.4.
  • HALNODEBUG – Define this symbol for all projects to disable HAL assertions.
  • OSAL_CBTIMER_NUM_TASKS – This symbol defines the number of OSAL callback timers that you can use. The Bluetooth Low Energy protocol stack uses the OSAL callback timer. You must define this value as either 1 or 2 (a maximum of two callback timers are allowed). For applications without any callback timers such as the sample application, define this value as 1.
  • HAL_AES_DMA – Define this symbol as TRUE because the Bluetooth Low Energy stack uses DMA for AES encryption.
  • HAL_DMA – This value must be defined as TRUE for all Bluetooth Low Energy projects, as the DMA controller is used by the stack when reading and writing to flash.

Optional Symbols

  • POWER_SAVING – When defined, this symbol configures the system to go into sleep mode when free of any pending tasks.
  • PLUS_BROADCASTER – This symbol indicates that the device is using the GAP Peripheral/Broadcaster multirole profile rather than the single GAP Peripheral role profile. The default option in the simpleBLEPeripheral project is undefined.
  • HAL_LCD – This symbol indicates whether to include and use the LCD driver when set to TRUE. If not defined, it is set to TRUE.
  • HAL_LED – This symbol indicates whether to include the LED driver when set to TRUE. If not defined, it is set to TRUE.
  • HAL_KEY – This symbol indicates whether to include the KEY driver when set to TRUE. If not defined, it is set to TRUE.
  • HAL_UART – This symbol indicates whether to include the UART driver when set to TRUE. If not defined, it is set to FALSE.
  • CC2540_MINIDK – Define this symbol when using the keyfob board in the CC2540/41DK-MINI development kit. This symbol configures the hardware based on the keyfob board layout.
  • HAL_UART_DMA – This symbol sets the UART interface to use DMA mode when set to 1. When HAL_UART is defined, set either HAL_UART_DMA or HAL_UART_ISR to 1.
  • HAL_UART_ISR – This symbol sets the UART interface to use ISR mode when set to 1. When HAL_UART is defined, set either HAL_UART_DMA or HAL_UART_ISR to 1.
  • HAL_UART_SPI – This symbol indicates whether to include the SPI driver.
  • GAP_BOND_MGR – The HostTestRelease network processor project uses this symbol. When this symbol is defined for slave and peripheral configurations, use the GAP peripheral bond manager security profile to manage bonds and handle keys. For more information on the peripheral bond manager, see Section 5.4.
  • GATT_DB_OFF_CHIP – The HostTestRelease network processor project uses this symbol. This symbol sets a GATT client in a network processor configuration to manage the attributes in the application processor instead of the CC2540/41.

Other definitions relating to specific use cases such as the serial bootloader, OAD, and so forth are defined in the documentation.