Overview¶
This section describes the high level design and functionality of the Micro BLE Stack (uBLE Stack). The uBLE Stack enables applications on the CC23xx to advertise, scan, or behave as a connection monitor.
Constraints and Requirements¶
The Micro BLE Stack has the following internal constraints and requirements:
This design optionally depends on partial integration of ICall to save system resources if there already is an application using ICall in the dual-mode use case. In the case of using the ICall module, ICall’s system heap management and RTOS service abstraction will be used.
There is no HCI because there is no separation between the controller and the host.
The privacy feature is not supported, but random address generation is supported.
To minimize the memory overhead and remove redundant context switching, the Micro BLE Stack doesn’t have a separate RTOS task. It is instead integrated in the application task.
The Micro BLE Stack requires the use of the MultiMode RF driver.
Devices using only the uBLE Stack can not be Bluetooth ® qualified.
System Architecture¶
The Micro BLE Stack consists of the Micro Radio Control Layer (RCL) Interface (Micro RCLI or uRCLI), the Micro Link Layer (Micro LL or uLL), and the Micro Generic Access Profile (Micro GAP or uGAP).
The Micro BLE Stack is not designed to run as a separate RTOS task, in order to save memory that would otherwise be required to maintain an additional task. Instead, it is integrated in the application from the RTOS context’s point of view. This way, all application callbacks that originate from RCL and Clock SWIs in the uBLE Stack (and might have lengthy operations such as command completion post processing and error handling) are called in the application task context.
How the Micro BLE Stack is integrated context-wise in the application is illustrated in Figure 106. Note that only the subcomponents directly relevant to the uBLE Stack in the application and the RCL driver are depicted.
Micro Radio Control Layer (RCL) Interface¶
The Micro RCLI is primarily used to initialize the Radio and allow Radio commands to be sent. Depending on the features enabled, the uRCLI will define the proper parameter structures for the uLL to reference in order to utilize the RCL driver.
The following RCL commands are used by the uBLE Stack:
RCL_CMD_BLE5_ADV
: Advertiser command, used by broadcaster
RCL_CMD_BLE5_SCANNER_t
: Scanner command, used by observer
RCL_CMD_BLE5_GENERIC_RX_t
: Generic RX command, used by monitor
Micro Link Layer¶
The Micro LL is mainly responsible for maintaining the device state and scheduling radio commands to perform advertising, scanning, or monitoring operations. The pre- and post-processing for each radio command execution are also done by the uLL. The uLL directly invokes the RCL Driver and will utilize the uRCLI to initialize the radio for the uBLE Stack features being exercised.
The Micro LL perfoms:
Radio management (scheduling radio activities)
Device state management (standby, advertising/scanning, or monitoring)
Pre- and post-processing
Note
The Filter Accept List without privacy is supported.
Radio Initialization¶
The Micro LL has a direct interface to the RCL Driver. It opens a connection to the
RCL Driver as an independent client using RCL_open()
with BLE PHY setup
parameters. The setup parameters used to interface with the RCL Driver are
defined in the Micro Radio Control Layer (RCL) Interface section. These parameters are
dependent on the features enabled in the uBLE Stack.
Application Parameters¶
The Micro LL maintains the parameters used for advertising, scanning, and monitoring. Most of these parameters can be accessed by the uGAP through uble_setParameter() and uble_getParameter() functions. These parameters are also dependent on the features enabled in the uBLE Stack.
Parameter |
Description |
Value Range |
Type |
---|---|---|---|
UBLE_PARAM_ADVINTERVAL |
Advertising Interval (0.625 ms unit) |
0x0020 to 0x4000 |
uint16 |
UBLE_PARAM_ADVCHANMAP |
Advertising Channel Map |
37: 0x01 38: 0x02 39: 0x04 |
uint8 |
UBLE_PARAM_ADVTYPE |
Advertising Type |
ADV_NONCONN_IND or ADV_SCAN_IND |
uint8 |
UBLE_PARAM_TIMETOADV |
How early to notify before the next advertisment (ms) |
0 to 255 |
uint8 |
UBLE_PARAM_ADVDATA |
Advertising Data (array) |
uint8[UBLE_MAX_ADVDATA_LEN] |
|
UBLE_PARAM_SCANRSPDATA* |
Scan Response Data (array) |
uint8[UBLE_MAX_ADVDATA_LEN] |
|
UBLE_PARAM_ADVFLTPOLICY* |
Advertising Filter Policy |
uint8 |
Note
*These parameters are also dependent on the Scan Response feature being enabled.
Parameter |
Description |
Value Range |
Type |
---|---|---|---|
UBLE_PARAM_SCANINTERVAL |
Scan Interval (0.625 ms unit) |
0x0004 to 0x4000 |
uint16 |
UBLE_PARAM_SCANWINDOW |
Scan Window (0.625 ms unit) |
0x0004 to 0x4000 |
uint16 |
UBLE_PARAM_SCANCHANMAP |
Scanning Channel Map |
37: 0x01 38: 0x02 39: 0x04 |
uint8 |
UBLE_PARAM_SCANTYPE |
Scanning Type |
SCAN_PASSIVE or SCAN_ACTIVE |
uint8 |
UBLE_PARAM_FLTDUPLICATE |
Whether to filter out duplicate advertising reports or not |
uint8 |
|
UBLE_PARAM_SCANFLTPOLICY |
Scan Filter Policy |
uint8 |
Parameter |
Description |
Value Range |
Type |
---|---|---|---|
UBLE_PARAM_SESSIONID |
Monitor Session Handle |
1 to CM_MAX_SESSIONS |
uint8 |
UBLE_PARAM_MONITOR_CHAN |
Monitor Channel |
0 to 39 |
uint8 |
UBLE_PARAM_MONITOR_DURATION |
Monitor Duration (0.625 ms unit) |
0x0004 to 0x4000 |
uint16 |
UBLE_PARAM_MONITOR_START_TIME |
Monitor Start Time (RAT ticks) |
uint32 |
|
UBLE_PARAM_MONITOR_ACCESS_ADDR |
Monitor Access Address |
uint32 |
|
UBLE_PARAM_MONITOR_CRC_INIT** |
Monitored connection’s CRC Initialization Value |
uint32 |
Note
**This parameter is not accessible to the application and is instead set
via calls to ugap_monitorRequest
.
Micro LL States¶
There are 4 states in the Micro LL: the Standby State, the Advertising State, the Scanning State, and the Monitoring State. The uLL changes the state from one to another at the uGAP’s request. Interfacing with the uBLE Stack should be done through uGAP APIs.
Standby State¶
This is the default state in the uLL. The uLL doesn’t do any radio activities in this state. The uLL may leave this state to enter any other state.
Advertising State¶
In this state, the uLL sends advertising PDUs in advertising events. Each advertising event is composed of 3 advertising PDUs sent on the advertising channels as the commands are chained together.
An advertising event is limited to the following type in this design version:
A non-connectable undirected event: ADV_NONCONN_IND PDU is used. No response PDU is expected.
Per each advertising event, the following notifications will be delivered to the uGAP before and after the event. Note that these notifications are conveyed based on the application task’s priority, since they are following the paths illustrated in Figure 106.
UGB_EVT_ADV_PREPARE
: This notification event is generatedUBLE_PARAM_TIMETOADV
ms prior to every advertising event. The purpose of this event is to let the application take time to update the advertising data with up-to-date information if necessary. IfUBLE_PARAM_TIMETOADV
is 0, this notification event won’t happen.You can change advertising data by using uble_setParameter().
UGB_EVT_ADV_POSTPROCESS
: This notification event is generated at the completion of every advertising event.UGB_EVT_STATE_CHANGE
: This notification event is generated when the state has changed.
Scanning State¶
In this state, the uLL scans for advertising PDUs in scanning events. Each scanning event is composed of a single scan, which will rotate through the advertising channels.
Per each scanning event, the following notifications will be delivered to the uGAP before and after the event. Note that these notifications are conveyed based on the application task’s priority, since they are following the paths illustrated in Figure 106.
UGAP_OBSERVER_EVT_SCAN_INDICATION
: This notification event is generated if an advertising packet is detected before the end of the scan duration. The uLL will call the callback that is registered for indications.UGAP_OBSERVER_EVT_SCAN_WINDOW_COMPLETE
: This notification event is generated once the scan duration is elapsed.If there are pending scans, the uGAP will automatically start the next one.
UGAP_OBSERVER_EVT_STATE_CHANGE
: This notification event is generated when the state has changed.
Monitoring State¶
In this state, the uLL will scan a particular channel with the specified scan
parameters. An access address filter is applied based on the accessAddr
parameter. The uGAP will supply all the necessary parameters and initialize the
scan. Each scan has an associated monitorHandle
which
maintains the session. The scan will be performed over the channels specified
by monitorChan
.
The monitor session currently scanning is determined by the
startTime
which accounts for when the next connection event of the
monitored connection should start. Furthermore, the crcInit
of the
connection to follow must be input.
Per each connection event, the following notifications will be delivered to the uGAP before and after the event. Note that these notifications are conveyed based on the application task’s priority, since they are following the paths illustrated in Figure 106.
UGAP_MONITOR_EVT_MONITOR_INDICATION
: This notification event is generated if a packet is detected before the end of the scan duration:monitorDuration
. The uLL will call the callback that is registered for indications.UGAP_MONITOR_EVT_MONITOR_COMPLETE
: This notification event is generated once the scan duration is elapsed.If there are pending scans, the uGAP will automatically start the next one.
UGAP_MONITOR_EVT_STATE_CHANGE
: This notification event is generated when the state has changed.
RCL Callbacks¶
Each RCL event is processed differently depending on the role the Micro BLE Stack is operating in (broadcaster, observer, or monitor). These RCL events are consumed through callbacks that are plugged to the RCL driver via the uLL. See the table below for a summary of how the RCL events are processed by the uLL.
Mode |
RCL Callback |
Events Processed |
Events Generated |
Broadcaster |
ull_advDoneCb |
RCL_EventLastCmdDone |
ULL_EVT_ADV_TX_SUCCESS |
RCL_EventCmdAborted, RCL_EventCmdStopped, RCL_EventCmdPreempted, RCL_EventCmdCancelled |
ULL_EVT_ADV_TX_FAILED |
||
Observer |
ull_scanDoneCb |
RCL_EventRxEntryDone |
ULL_EVT_SCAN_RX_SUCCESS |
RCL_EventLastCmdDone, RCL_EventInternalError |
ULL_EVT_SCAN_RX_FAILED or ULL_EVT_SCAN_RX_BUF_FULL (depending on status from RCL driver) |
||
Monitor |
ull_monitorDoneCb |
RCL_EventRxEntryDone |
ULL_EVT_MONITOR_RX_SUCCESS |
RCL_EventLastCmdDone |
ULL_EVT_MONITOR_RX_WINDOW_COMPLETE ULL_EVT_MONITOR_RX_BUF_FULL ULL_EVT_MONITOR_RX_FAILED (depending on status from RCL driver) |
||
RCL_EventInternalError |
ULL_EVT_MONITOR_RX_FAILED |
For more information regarding the RCL driver see the RCL Driver API: Driver API Reference.
Micro Generic Access Profile¶
The Micro GAP sits between the uLL and the application and is mainly responsible for controlling the uLL to set up and run profile roles. The application can indirectly configure the uLL through the uGAP and be notified of events from the uLL through uGAP callbacks. The uGAP needs an RTOS because the clock/timer service is used.
The Micro GAP performs:
Initialization and configuration of the uLL
State Management within the role
Interfacing with the application
Broadcaster, observer, and monitor roles
Parameter Management¶
The Micro GAP maintains the parameters used by the broadcaster, observer, and monitor roles. These parameters are also dependent on the features enabled in the uBLE Stack.
Broadcaster Parameters¶
These parameters are set by the uGAP through the ugap_bcastStart() and ugap_bcastSetDuty() functions:
ugbNumAdvEvent
: The number of advertising events to be done before the broadcaster stops its job. This is given when the application starts the broadcaster by callingug_bcastStart()
. If this parameter is set to 0, the broadcaster will not go to theUGAP_BCAST_STATE_INITIALIZED
state once started, unless it is requested to stop.ugbDutyOnTime
: Time period during which the broadcaster stays in theUGAP_BCAST_STATE_ADVERTISING
state. The uLL also stays in the advertising state. When this time period ends, the broadcaster’s state will transition to theUGAP_BCAST_STATE_WAITING
state and the uLL will exit the advertising state. A 100-ms time unit is used.This parameter is only effective if Broadcaster Duty Control is enabled. If Broadcaster Duty Control is disabled, transitions to other states from the
UGAP_BCAST_STATE_ADVERTISING
state are not affected by this parameter.
ugbDutyOffTime
: Time period during which the broadcaster stays in theUB_BCAST_STATE_WAITING
state. The uLL cannot be in the advertising state during this period. When this time period ends, the broadcaster’s state will transition to theUGAP_BCAST_STATE_ADVERTISING
state and the uLL will enter the advertising state. A 100-ms time unit is used.This parameter is only effective if Broadcaster Duty Control is enabled. If set to 0, Broadcaster Duty Control is disabled and the broadcaster will not enter the
UGAP_BCAST_STATE_WAITING
state.
Observer Parameters¶
These parameters are set by the uGAP through the ugap_scanRequest
and ugap_scanSuspend
functions:
ugoScanOnTime
: Time period during which the observer stays in theUGAP_SCAN_STATE_SCANNING
state. The uLL also stays in the scanning state. When this time period ends, the observer’s state will transition to theUGAP_SCAN_STATE_WAITING
state and the uLL will exit the scanning state. A 100-ms time unit is used.ugoScanOffTime
: Time period during which the observer stays in theUGAP_SCAN_STATE_WAITING
state. The uLL cannot be in the scanning state during this period. When this time period ends, the observer’s state will transition to theUGAP_SCAN_STATE_SCANNING
state and the uLL will enter the scanning state. A 100-ms time unit is used.ugoStatePrev
: The observer’s previous state. Used to determine whether the observer should enter theUGAP_SCAN_STATE_WAITING
orUGAP_SCAN_STATE_SCANNING
state upon leaving theUGAP_SCAN_STATE_SUSPENDED
state.ugoScanChanMap
: The map of the channels that the observer will request the uLL to scan.
Monitor Parameters¶
There are not currently any uGAP parameters specific to the monitor role.
Role Management¶
The uGAP is the main interface to operate in various roles.
There are three distinct roles the uGAP supports:
The application must configure the uGAP to operate in the desired role. This section goes over some specifics of the individual roles.
Broadcaster Role¶
If the application configures the uGAP to operate in the broadcaster role, the uGAP lets the uLL send advertising events as described in Advertising State.
The broadcaster role has 4 states:
UGAP_BCAST_STATE_INITIALIZED
: The broadcaster is initialized but has never started. The corresponding state of the uLL can be anything butULL_STATE_ADVERTISING
.UGAP_BCAST_STATE_ADVERTISING
: The broadcaster is advertising in this state. The corresponding state of the uLL isULL_STATE_ADVERTISING
. If Broadcaster Duty Control is enabled, the duty timer starts with the duration ofugbDutyOnTime
when this state is entered. Then, the state switches to theUGAP_BCAST_STATE_WAITING
state when the duty timer expires.If 0 was passed to
numAdvEvent
whenugap_bcastStart()
is called,ugbNumAdvEvent
won’t have any effect on this state. Otherwise, the broadcaster’s state will switch to theUGAP_BCAST_STATE_IDLE
state once the total number of advertising events sinceugap_bcastStart()
was called reachesugbNumAdvEvent
, or if requested throughugap_bcastStop()
.If
ugap_bcastSuspend()
is called, the broadcaster’s state will switch to theUGAP_BCAST_STATE_SUSPENDED
state, putting the duty timer on hold if Broadcaster Duty Control is enabled. The duty timer will resume when the broadcaster’s state switches back to theUGAP_BCAST_STATE_ADVERTISING
state.
UGAP_BCAST_STATE_WAITING
: The broadcaster has started but is not advertising in this state because it is in theugbDutyOffTime
period. The corresponding state of the uLL isULL_STATE_STANDBY
. If Broadcaster Duty Control is enabled, the duty timer starts with the duration ofugbDutyOffTime
when this state is entered. Then, the state switches to theUGAP_BCAST_STATE_ADVERTISING
state when the duty timer expires.The state switches to the
UGAP_BCAST_STATE_IDLE
state if requested throughugap_bcastStop()
. Ifugap_bcastSuspend()
is called, the state switches to theUGAP_BCAST_STATE_SUSPENDED
state, putting the duty timer on hold if Duty Control is enabled. The duty timer will resume when the broadcaster’s state switches back to theUGAP_BCAST_STATE_WAITING
state.
UGAP_BCAST_STATE_SUSPENDED
: The broadcaster has started but is not advertising in this state. The corresponding state of the uLL can be anything butULL_STATE_ADVERTISING
. The former state shall be recorded when this state is entered. If the suspension is lifted throughugap_bcastResume()
, the state will switch back to the former state. The state switches to theUGAP_BCAST_STATE_IDLE
ifugap_bcastStop()
is called.
The Bluetooth Core Specifications Version 5.3 doesn’t allow the broadcaster to have Limited Discoverable
Mode. However, the uGAP provides a duty control means similar to Limited
Discoverable Mode to save power consumption. The duty control can be
implemented with timers based on ugbDutyOnTime
and ugbDutyOffTime
,
explained in Parameter Management. The broadcaster’s
advertising state corresponds to the uLL’s advertising state.
The typical life cycle of the broadcasting function encompassing the application down to the uLL is illustrated in Figure 108.
Observer Role¶
If the application configures the uGAP to operate in the observer role, the uGAP lets the uLL scan for advertising events as described in Scanning State.
The observer role has 4 states:
UGAP_SCAN_STATE_INITIALIZED
: The observer is initialized but has never started. The corresponding state of the uLL can be anything butULL_STATE_SCANNING
.UGAP_SCAN_STATE_SCANNING
: The observer is scanning in this state. The corresponding state of the uLL isULL_STATE_SCANNING
. The duty timer starts with the duration ofugoScanOnTime
when this state is entered. Then, the state switches to theUGAP_SCAN_STATE_WAITING
state when the duty timer expires.Only one channel will be scanned during this state, determined by the value of
ugoScanChanMap
when this state is entered. The observer will updateugoScanChanMap
so that a new channel will be scanned the next time this state is entered, if possible.The state switches to the
UGAP_SCAN_STATE_IDLE
state if requested throughugap_scanStop()
. Ifugap_scanSuspend()
is called, the observer’s state will switch to theUGAP_SCAN_STATE_SUSPENDED
state, putting the duty timer on hold. The duty timer will resume when the observer’s state switches back to theUGAP_SCAN_STATE_SCANNING
state.
UGAP_SCAN_STATE_WAITING
: The observer has started but is not scanning in this state because it is in theugoScanOffTime
period. The corresponding state of the uLL isULL_STATE_STANDBY
. The duty timer starts with the duration ofugoScanOffTime
when this state is entered. Then, the state switches to theUGAP_SCAN_STATE_SCANNING
state when the duty timer expires.The state switches to the
UGAP_SCAN_STATE_IDLE
state if requested throughugap_scanStop()
. Ifugap_scanSuspend()
is called, the state switches to theUGAP_SCAN_STATE_SUSPENDED
state, putting the duty timer on hold. The duty timer will resume when the observer’s state switches back to theUGAP_SCAN_STATE_WAITING
state.
UGAP_SCAN_STATE_SUSPENDED
: The observer has started but is not advertising in this state. The corresponding state of the uLL can be anything butULL_STATE_ADVERTISING
. The former state shall be recorded when this state is entered. If the suspension is lifted throughugap_bcastResume()
, the state will switch back to the former state. The state switches to theUGAP_BCAST_STATE_IDLE
ifugap_bcastStop()
is called.
Monitor Role¶
The monitor role is not defined by the Bluetooth Core Specifications Version 5.3. This section is to describe how the uGAP operates when using the monitor feature.
Warning
This role is should only be used as stand alone condition only, which means no other uBLE Stack feature should be used in conjunction.
The monitor role is designed to follow an active BLE connection. It requires knowledge of the connection information, such as access address, hop increment, and connection interval. The monitor role uses this information to set up the uGAP and uBLE Stack.
The monitor role has 3 States:
UGAP_MONITOR_STATE_INITIALIZED
: The monitor is initialized but is not monitoring.UGAP_MONITOR_STATE_IDLE
: The monitor is not monitoring in this state. The corresponding state of the uLL isULL_STATE_STANDBY
.UGAP_MONITOR_STATE_MONITORING
: The monitor is scanning. The corresponding state of the uLL isULL_STATE_MONITORING
.
When a packet is detected during a scan of the connection specified by the
provided connection parameters, a UGAP_MONITOR_EVT_MONITOR_INDICATION
event is generated.
When a scan is complete, a UGAP_MONITOR_EVT_MONITOR_COMPLETE
event is
generated. If there are pending scans, the uGAP will start the next scheduled
scan.
Each time the monitor switches states, a UGAP_MONITOR_EVT_STATE_CHANGE
event is generated.
For more information regarding the monitor role and its application, please refer to the Connection Monitor (CM) Application section.