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

G.2 Commands

hciStatus_t HCI_EXT_AdvEventNoticeCmd ( uint8 taskID, uint16 taskEvent )

This command configures the device to set an event in the user task after each advertisement event completes. A non-zero taskEvent value is enable, while a zero valued taskEvent is disable.
Note

NOTE

This command fails to return any events but has a meaningful return status.

Parameters

taskID– task ID of the user

taskEvent – task event of the user (must be a single bit value)

Returns

SUCCESS: event configured correctly

LL_STATUS_ERROR_BAD_PARAMETER: more than one bit is set.

Example (code additions to SimpleBLEPeripheral.c):

  1. Define the event in the application.
    2. code_secVII_1__swru271.gif
  2. Configure the Bluetooth Low Energy protocol stack to return the event (in simpleBLEPeripheral_init())
    3. code_secVII_4__swru271.gif
  3. Check for and receive these events in the application (SimpleBLEPeripheral_ProcessEvent())
    4. code_secVII_5__swru271.gif

hciStatus_t HCI_EXT_BuildRevision( uint8 mode, uint16 userRevNum)

This command is used to either let the user set their own 16-bit revision number or read the build revision number of the Bluetooth Low Energy Stack library software. The default value of the user revision number is zero. When the user updates a Bluetooth Low Energy project by adding their own code, they may use this API to set their own revision number. When called with mode set to HCI_EXT_SET_APP_REVISION, the stack will save this value. No event will be returned from this API when used this way. TI intended this command to be called from within the target itself. This does not preclude this command from being received through the HCI but no event will be returned.
Parameters

Mode – HCI_EXT_SET_APP_REVISION, HCI_EXT_READ_BUILD_REVISION

userRevNum – Any 16-bit value

Returns (only when mode == HCI_EXT_SET_USER_REVISION)

SUCCESS: build revision set succesfully

LL_STATUS_ERROR_BAD_PARAMETER: an invalid mode

Corresponding Events (only when mode == HCI_EXT_SET_USER_REVISION)

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_ConnEventNoticeCmd ( uint8 taskID, uint16 taskEvent )

This command is used to configure the device to set an event in the user task after each connection event completes. A non-zero taskEvent value is enable, while a zero valued taskEvent is disable.
Note

NOTE

A slave with one connection is supported (this API only works when the device is configured as a slave and connected to one master). Send this command after establishing a connection.

This command fails to return any events but has a meaningful return status.

Parameters

taskID – task ID of the user

taskEvent – task event of the user

Returns

SUCCESS or FAILURE

LL_STATUS_ERROR_BAD_PARAMETER: more than one bit is set.

Example (code additions to SimpleBLEPeripheral.c):

  1. Define the event in the application.
    2. code_secVII_3__swru271.gif
  2. Configure the Bluetooth Low Energy protocol stack to return the event (in SimpleBLEPeripheral processStateChangeEbt()) after establishing the connection.
    3. code_secVII_4__swru271.gif
  3. Check for and receive these events in the application (SimpleBLEPeripheral_taskFxn()).
    4. code_secVII_5__swru271.gif

hciStatus_t HCI_EXT_DeclareNvUsageCmd ( uint8 mode)

This command informs the controller whether the host uses NV memory during Bluetooth Low Energy operations. The default system value for this feature is NV In Use. When the NV is unused during Bluetooth Low Energy operations, the controller can bypass internal checks that reduce overhead processing. This capability reduces average power consumption.
Note

NOTE

This command is allowed only when the Bluetooth Low Energy controller is idle.

If you use NV when declaring it is not in use, a hung Bluetooth Low Energy connection may occur.
Parameters

mode – one of…

HCI_EXT_NV_NOT_IN_USE

HCI_EXT_NV_IN_USE

Corresponding Events:

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_DecryptCmd ( uint8 *key, uint8 * encText)

This command decrypts encrypted data using the AES128 .
Note

NOTE

Only the application should use this command. Incoming encrypted Bluetooth Low Energy data is automatically decrypted by the stack and operates free of this API.
Parameters

mode – one of…

HCI_EXT_NV_NOT_IN_USE

HCI_EXT_NV_IN_USE

Corresponding Events:

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_DelaySleepCmd (uint16 delay)

This command sets the delay before sleep occurs after reset or when waking from sleep to let the external 32-kHz crystal stabilize. If this command is always unused, the default delay is 400 ms on the CC254x. If the hardware of the customer requires a different delay or operates free of this delay, delay can be changed by calling this command during the OSAL task initialization of the application. A zero delay value eliminates the delay after reset and (unless changed again) all subsequent wakes from sleep. A non-zero delay value changes the delay after reset and (unless changed again) subsequent wakes from sleep. If this command is used after system initialization, the new delay value will be applied the next time the delay is used.
Note

NOTE

This delay applies only to reset and sleep. If a periodic timer is used or an active Bluetooth Low Energy operation and only sleep is used, this delay occurs only after reset.

No distinction exists between a hard and soft reset. The delay (if non-zero) is applied the same way in both cases.
Parameters

delay – 0x0000…0x003E8 in milliseconds

Corresponding Events:

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_DisconnectImmedCmd ( uint16 connHandle)

This command disconnects a connection immediately. When a connection must be ended without the latency associated with the normal Bluetooth Low Energy controller terminate control procedure, use this command.
Note

NOTE

The host issuing the command receives the HCI disconnection complete event with a reason status of 0x16 (that is, connection terminated by local host), followed by an HCI vendor specific event.

Parameters

connHandle– The handle of the connection.

Corresponding Events:

HCI_Disconnection_Complete

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_EnablePTMCmd ( void )

This command enables production test mode (PTM). The customer uses this command when assembling their product to allow limited access to the Bluetooth Low Energy Controller for testing and configuration. This mode remains enabled until the device is reset.
Note

NOTE

This commands resets the controller. To reenter the application, reset the device.

This command fails to return any events.

Return Values

HCI_SUCCESS: Successfully entered PTM

hciStatus_t HCI_EXT_EndModemTestCmd ( void )

This command shuts down a modem test. A complete link layer reset occurs.
Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_ExtendRfRangeCmd ( void )

This command configures the CC254x to automatically control the TI CC2590 2.4-GHz RF Front End device. Using the CC2590 allows a maximum Tx output power of 10 dBm (the specified Bluetooth Low Energy maximum) and increases Rx sensitivity. This capability extends the RF range of the CC254x. When using this command, the configuration fails to change unless the CC254x is reset. Automatic control of the CC2590 is achieved using the CC254x Observables, which take control of GPIO P1.2 and P1.3. The GPIO P1.1 controls RF gain. These GPIOs are unavailable when using this feature. You can use this command in combination with HCI_EXT_SetTxPowerCmd, resulting in a cumulative Tx output power. For the CC2540 only, attempting to set Tx output power to 4 dBm (that is, using HCI_EXT_TX_POWER_4_DBM) sets the Tx output power to 0 dBm. Use the command HCI_EXT_SetRxGainCmd to set the Rx gain. The CC254x Rx Standard/High gain setting is mirrored by the Bluetooth Low Energy controller to the CC2590 High Gain Mode (HGM) Low/High setting. When using this command, the CC254x Tx output power and Rx gain retain their previous values unless the previous Tx output power value was set to 4 dBm on the CC2540. In this case, the value is set to 0dBm.
Corresponding Events

HCI_Disconnection_Complete

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_GetConnInfoCmd (uint8 *numAllocConns, uint8 *numActiveConns, hciConnInfo_t *activeConnInfo)

This command gets the number of allocated connections and the number of active connections. For each active connection, this command gets the connection handle, the connection role, the peer device address, and peer device address type. The number of allocated connections is based on a default build value that can be changed in the project using MAX_NUM_BLE_CONNS. The number of active connections refers to active Bluetooth Low Energy connections. The information per connection is based on the structure hciConnInfo_t provided in hci.h. This command applies only to central devices for the CC254x as peripheral devices can only have one simultaneous connection. If all parameters are NULL, the call to this command is a network processor call through a transport layer and the results are provided by the host through a vendor specific command complete event. If any parameter is not NULL, the call to this command is a direct function call and the valid pointers store the result. Ensure sufficient memory is allocated. Obtain partial results by selective using pointers. If you want to know the number of active connections, do the following:
code_secVII_6__swru271.gif
Parameters

numAllocConns – pointer to number of build time connections allowed

numActiveConns - pointer to number of active Bluetooth Low Energy connections

activeConnInfo - pointer for the connection information for each active connection which consists of the following: Connection ID, Connection Role, Peer Device Address, and Peer Address Type, which requires (the number of active connections × 9 bytes) of memory:

code_secVII_7__swru271.gif
Corresponding Events:

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_HaltDuringRfCmd ( uint8 mode)

This command enables or disables the halting of the MCU while the radio is operating. When the MCU is not halted, the peak current is higher but the system is more responsive. When the MCU is halted, the peak current consumption is reduced but the system is less responsive. The default value is Enable.
Note

NOTE

If there are any active Bluetooth Low Energy connections, this command is disallowed.

If the halt during RF is disabled, the HCI_EXT_ClkDivOnHaltCmd is disallowed.

Parameters

mode – one of…

HCI_EXT_HALT_DURING_RF_DISABLE

HCI_EXT_HALT_DURING_RF_ENABLE

Corresponding Events:

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_MapPmIoPortCmd (uint8 ioPort, uint8 ioPin )

This command configures and maps a CC254x Input and Output Port as a General-Purpose Input and Output (GPIO) output signal that reflects the power management (PM) state of the CC254x device. The GPIO output is High on Wake and Low when entering Sleep. You can disable this feature by specifying HCI_EXT_PM_IO_PORT_NONE for the ioPort (ioPin is then ignored). The system default value when the hardware reset is disabled. You can use this command to control an external DC-DC converter (its intent) such has the TI TPS62730 (or any similar converter). Use this command with extreme care. This command overrides how the port or pin was previously configured, including the mapping of Port 0 pins to 32-kHz clock output, Analog Input and Output, UART, Timers,Port 1 pins to Observables, Digital Regulator status, UART, Timers, Port 2 pins to an external 32-kHz XOSC. The selected port or pin will be configured as an output GPIO with interrupts masked. Using this command carelessly can result in a reconfiguration that could disrupt the system. If a port or pin is used as part of the serial interface for the device, the pin or port is reconfigured from its original peripheral function to a GPIO, disrupting the serial port. Ensure the pin or port does not cause any conflicts in the system.
Note

NOTE

Only pins 0, 3 ,and 4 are valid for port 2 because pins 1 and 2 are mapped to debugger signals DD and DC.

A port or pin signal change occurs only when power savings is enabled.
Parameters

ioPort – one of the following:

  • HCI_EXT_PM_IO_PORT_P0
  • HCI_EXT_PM_IO_PORT_P1
  • HCI_EXT_PM_IO_PORT_P2
  • HCI_EXT_PM_IO_PORT_NONE

ioPin – one of the following:

  • HCI_EXT_PM_IO_PORT_PIN0
  • HCI_EXT_PM_IO_PORT_PIN1
  • HCI_EXT_PM_IO_PORT_PIN2
  • HCI_EXT_PM_IO_PORT_PIN3
  • HCI_EXT_PM_IO_PORT_PIN4
  • HCI_EXT_PM_IO_PORT_PIN5
  • HCI_EXT_PM_IO_PORT_PIN6
  • HCI_EXT_PM_IO_PORT_PIN7
Corresponding Events:

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_ModemHopTestTxCmd( void )

This API starts a continuous transmitter direct test mode test using a modulated carrier wave and transmitting a 37-byte packet of pseudo-random 9-bit data. A packet is transmitted on a different frequency (linearly stepping through all RF channels 0 through 39) every 625 µs. Use the HCI_EXT_EndModemTest command to end the test.
Note

NOTE

When the HCI_EXT_EndModemTest is issued to stop this test, a controller reset occurs.

The device transmits at the default output power (0 dBm) unless changed by HCI_EXT_SetTxPowerCmd.

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_ModemTestRxCmd( uint8 rxFreq )

This API starts a continuous receiver modem test using a modulated carrier wave tone, at the frequency that corresponds to the specific RF channel. Any received data is discarded. Receiver gain may be adjusted using the HCI_EXT_SetRxGain command. RSSI may be read during this test by using the HCI_ReadRssi command. Use HCI_EXT_EndModemTest command to end the test.
Note

NOTE

The RF channel not the Bluetooth Low Energy frequency is specified. You can obtain the RF channel from the Bluetooth Low Energy frequency as follows: RF Channel = (Bluetooth Low Energy Frequency – 2402) ÷ 2.

When the HCI_EXT_EndModemTest is issued to stop this test, the controller resets.

Parameters

rxFreq- selects which channel [0 to 39] on which to receive

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_NumComplPktsLimitCmd ( uint8 limit, uint8 flushOnEvt )

This command sets the limit on the minimum number of complete packets before the controller returns a control number of completed packets event . If the limit is not reached by the end of a connection event, the number of completed packets event is returned based on the flushOnEvt flag if nonzero. You can set the limit rom one to the maximum number of HCI buffers (see the LE Read Buffer Size command in (16)). The default limit is one; the default flushOnEvt flag is FALSE.
Note

NOTE

The purpose of this command is to minimize the overhead of sending multiple number of completed packet events. Minimizing this number of events maximizes the processing available to increase wireless throughput. This command is often used in conjunction with HCI_EXT_OverlappedProcessingCmd.
Parameters

limit – From 1 to HCI_MAX_NUM_DATA_BUFFERS (returned by HCI_LE_ReadBufSizeCmd).

flushOnEvt –

  • HCI_EXT_DISABLE_NUM_COMPL_PKTS_ON_EVENT: only return a number of completed packets event when the number of completed packets is greater than or equal to the limit
  • HCI_EXT_ENABLE_NUM_COMPL_PKTS_ON_EVENT: return the number of completed packets event at the end of every connection event
Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_OnePacketPerEventCmd ( uint8 control )

This command configures the link layer to only allow one packet per connection event. The default system value for this feature is disabled. This command can tradeoff throughput and power consumption during a connection. When enabled, power can be conserved during a connection by limiting the number of packets per connection event to one at the expense of more limited throughput. When disabled, the number of packets transferred during a connection event is not limited at the expense of higher power consumption per connection event.
Note

NOTE

Perform a power analysis of the system before determining whether this command will save power. Transferring multiple packets per connection event, may be more power efficient.
Parameters

control – HCI_EXT_DISABLE_ONE_PKT_PER_EVT, HCI_EXT_ENABLE_ONE_PKT_PER_EVT

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent: this event is returned only if the setting is changing from enable to disable or disable to enable

hciStatus_t HCI_EXT_OverlappedProcessingCmd ( uint8 mode )

This command enables or disables overlapped processing. The default is disabled.
Parameters

mode – one of the following:

  • HCI_EXT_DISABLE_OVERLAPPED_PROCESSING,
  • HCI_EXT_ENABLE_OVERLAPPED_PROCESSING
Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent: this event is returned only if the setting is changing from enable to disable or disable to enable

hciStatus_t HCI_EXT_PacketErrorRateCmd ( uint16 connHandle, uint8 command )

This command resets or reads the packet error rate counters for a connection. When resetting, the counters are cleared. When reading the total number of packets received, the number of packets received with a CRC error, the number of events, the number of missed events are returned.
Note

NOTE

The counters are only 16 bits. At the shortest connection interval, this command allows for a little over eight minutes of data.
Parameters

connId– The connection ID to perform the command

command- HCI_EXT_PER_RESET, HCI_EXT_PER_READ

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_PERbyChanCmd ( uint16 connHandle, perByChan_t *perByChan )

This command starts or ends the packet error rate by accumulating channel counters for a connection and can be used by an application to make coexistence assessments. Based on the results, an application can perform an update channel classification command to limit channel interference from other wireless standards. If *perByChan is NULL, counter accumulation discontinues. If *perByChan is not NULL, sufficient memory is assumed to exist at this location for the PER data based on the following type definition perByChan_t located in ll.h:
code_secVII_8__swru271.gif
Note

NOTE

You must ensure there is sufficient memory allocated in the perByChan structure. You must also maintain the counters by clearing them if required before starting accumulation.

The counters are 16 bits. At the shortest connection interval, this provides a bit over 8 minutes of data.

This command can be used combined with HCI_EXT_PacketErrorRateCmd.
Parameters

connHandle – The connection ID to accumulate the data

perByChan- Pointer to PER by channel data or NULL

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_ResetSystemCmd ( uint8 mode )

This command issues a hard or soft system reset. A watchdog timer timeout causes a hard reset. Resetting the PC to zero causes a soft reset.
Note

NOTE

The reset occurs after a 100 ms delay to let the correspond event to be returned to the application.
Parameters

mode – HCI_EXT_RESET_SYSTEM_HARD

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SaveFreqTuneCmd ( void )

This PTM-only command saves this device’s the tuning setting of this device in non-volatile memory. The Bluetooth Low Energy Controller uses this setting when resetting and waking from sleep.
Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetBDADDRCmd( uint8 *bdAddr )

This command sets the Bluetooth Low Energy address (BDADDR) of the device. This address overrides the address of the device determined at reset. To restore the initialized address of the device stored in flash, issue this command with an invalid address (0xFFFFFFFFFFFF).
Note

NOTE

This command is allowed only when the controller is in the standby state. TI intends this command to be used only during initialization. Changing the BDADDR of the device after active Bluetooth Low Energy operations (i.e. Tx and Rx) have occurred may cause undefined behavior.
Parameters

bdAddr – A pointer to a buffer to hold this address of the device. An invalid address (that is, all FFs) restores the address of this device to the address set at initialization.

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetFastTxResponseTimeCmd ( uint8 control )

This command configures the link layer fast transmit response time feature. The default system value for this feature is enabled.
Note

NOTE

This command is valid only for a slave controller.

When the host transmits data, the controller ensures the packet is sent over the LL connection with minimal delay even when the connection is configured to use slave latency by default. The transmit response time is no longer than the connection interval, instead of waiting for the next effective connection interval due to slave latency. The result is lower power savings because the LL may need to wake to transmit during connection events that would have been skipped due to slave latency. If saving power is more critical than fast transmit response time, you can disable this feature using this command. When disabled, the transmit response time will be no longer than the effective connection interval (slave latency + 1 × the connection interval).

Parameters

control – HCI_EXT_ENABLE_FAST_TX_RESP_TIME, HCI_EXT_DISABLE_FAST_TX_RESP_TIME

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetFreqTuneCmd (uint8 step )

This PTM-only command sets the frequency tuning of the device either up one step or down one step. When the current setting is at its maximum value, stepping up has no effect. When the current setting is at its mininimum value, stepping down has no effect. This setting remain only in effect until the device is reset unless you use HCI_EXT_SaveFreqTuneCmd to save it in nonvolatile memory.
Parameters

step – HCI_PTM_SET_FREQ_TUNE_UP, HCI_PTM_SET_FREQ_TUNE_DOWN

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetLocalSupportedFeaturesCmd ( uint8 * localFeatures)

This command sets the local supported features of the controller.
Note

NOTE

This command can be issued either before or after one or more connections are formed. The local features set are only effective if performed before a feature exchange procedure has been initiated by the master. When this control procedure has been completed for a connection, only the exchanged feature set for that connection will be used. Because the link layer may initiate the feature exchange procedure autonomously, TI recommends using this command before the connection is formed.

The features are initialized by the controller when starting up. You might not need this command. Refer to ll.h for a description of the local features.
Parameters

localFeatures – A pointer to the feature set where each bit where each bit corresponds to a feature 0: feature shall not be used

0: Feature shall not be used

1: Feature can be used

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetMaxDtmTxPowerCmd ( uint8 txPower )

This command overrides the RF transmitter output power used by the direct test mode (DTM). Typically, the maximum transmitter output power setting used by DTM is the maximum transmitter output power setting for the device (that is, 5 dBm ). This command changes the value used by DTM.
Note

NOTE

When DTM is ended by a call to HCI_LE_TestEndCmd or a HCI_Reset is used, the transmitter output power setting is restored to the default value of 0 dBm.
Parameters

txPower – one of:

  • HCI_EXT_TX_POWER_MINUS_21_DBM
  • HCI_EXT_TX_POWER_MINUS_18_DBM
  • HCI_EXT_TX_POWER_MINUS_15_DBM
  • HCI_EXT_TX_POWER_MINUS_12_DBM
  • HCI_EXT_TX_POWER_MINUS_9_DBM
  • HCI_EXT_TX_POWER_MINUS_6_DBM
  • HCI_EXT_TX_POWER_MINUS_3_DBM
  • HCI_EXT_TX_POWER_0_DBM
  • HCI_EXT_TX_POWER_1_DBM
  • HCI_EXT_TX_POWER_2_DBM
  • HCI_EXT_TX_POWER_3_DBM
  • HCI_EXT_TX_POWER_4_DBM
  • HCI_EXT_TX_POWER_5_DBM
Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetRxGainCmd( uint8 rxGain )

This command sets the RF receiver gain. The default system value for this feature is standard receiver gain.
Note

NOTE

When DTM is ended by a call to HCI_LE_TestEndCmd or a HCI_Reset is used, the transmitter output power setting is restored to the default value of 0 dBm.
Parameters

rxGain– one of:

  • HCI_EXT_RX_GAIN_STD
  • HCI_EXT_RX_GAIN_HIGH
Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetSCACmd ( uint16 scaInPPM )

This command sets the sleep clock accuracy (SCA) value of the device in parts per million (PPM), from 0 to 500. For a master device, the value is converted to one of eight ordinal values representing a SCA range per (15), which is used when a connection is created. For a slave device, the value is used directly. The system default value for a master and slave device is 50 ppm and 40 ppm, respectively.
Note

NOTE

This command is allowed only when the device is disconnected.

The SCA value of the device remains unaffected by an HCI reset.
Parameters

scaInPPM – The SCA of the device in PPM from 0 to 500.

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetSlaveLatencyOverrideCmd ( uint8 mode)

This command enables or disables the slave latency override letting the user temporarily suspend slave latency even though it is active for the connection. When enabled, the device wakes up for every connection until slave latency override is disabled again. The default value is disable.
Note

NOTE

This command applies only to devices in the slave role.

This command can help when the slave application will soon receive something that must be handled immediately. This command fails to change the slave latency connection parameter: the device wakes up for each connection event.
Parameters

control – HCI_EXT_ENABLE_SL_OVERRIDE, HCI_EXT_DISABLE_SL_OVERRIDE

Corresponding Events

HCI_VendorSpecifcCommandCompleteEvent

hciStatus_t HCI_EXT_SetTxPowerCmd( uint8 txPower )

This command sets the RF transmitter output power. The default system value for this feature is 0 dBm.
Parameters

txPower– Device's transmit power, one of the following:

Corresponding Events:

HCI_VendorSpecifcCommandCompleteEvent:

  • HCI_EXT_TX_POWER_MINUS_21_DBM
  • HCI_EXT_TX_POWER_MINUS_18_DBM
  • HCI_EXT_TX_POWER_MINUS_15_DBM
  • HCI_EXT_TX_POWER_MINUS_12_DBM
  • HCI_EXT_TX_POWER_MINUS_9_DBM
  • HCI_EXT_TX_POWER_MINUS_6_DBM
  • HCI_EXT_TX_POWER_MINUS_3_DBM
  • HCI_EXT_TX_POWER_0_DBM
  • HCI_EXT_TX_POWER_1_DBM
  • HCI_EXT_TX_POWER_2_DBM
  • HCI_EXT_TX_POWER_3_DBM
  • HCI_EXT_TX_POWER_4_DBM
  • HCI_EXT_TX_POWER_5_DBM