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.

Figure 106. System Context Diagram¶

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.

Table 25. Advertising Parameters (uStack/uble.h)¶
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.

Table 26. Scanning Parameters (uStack/uble.h)¶
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

Table 27. Monitoring Parameters (uStack/uble.h)¶
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 generated UBLE_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. If UBLE_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.

Table 28. RCL Driver Event processing by the Micro BLE-Stack¶
Mode	RCL Callback	Events Processed	Events Generated
Broadcaster	ull_advDoneCb	RCL_EventLastCmdDone	ULL_EVT_ADV_TX_SUCCESS
Broadcaster	ull_advDoneCb	RCL_EventCmdAborted, RCL_EventCmdStopped, RCL_EventCmdPreempted, RCL_EventCmdCancelled	ULL_EVT_ADV_TX_FAILED
Observer	ull_scanDoneCb	RCL_EventRxEntryDone	ULL_EVT_SCAN_RX_SUCCESS
Observer	ull_scanDoneCb	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 calling ug_bcastStart(). If this parameter is set to 0, the broadcaster will not go to the UGAP_BCAST_STATE_INITIALIZED state once started, unless it is requested to stop.
ugbDutyOnTime: Time period during which the broadcaster stays in the UGAP_BCAST_STATE_ADVERTISING state. The uLL also stays in the advertising state. When this time period ends, the broadcaster’s state will transition to the UGAP_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 the UB_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 the UGAP_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 the UGAP_SCAN_STATE_SCANNING state. The uLL also stays in the scanning state. When this time period ends, the observer’s state will transition to the UGAP_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 the UGAP_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 the UGAP_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 the UGAP_SCAN_STATE_WAITING or UGAP_SCAN_STATE_SCANNING state upon leaving the UGAP_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:

Broadcaster Role
Observer Role
Monitor Role

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 but ULL_STATE_ADVERTISING.
UGAP_BCAST_STATE_ADVERTISING: The broadcaster is advertising in this state. The corresponding state of the uLL is ULL_STATE_ADVERTISING. If Broadcaster Duty Control is enabled, the duty timer starts with the duration of ugbDutyOnTime when this state is entered. Then, the state switches to the UGAP_BCAST_STATE_WAITING state when the duty timer expires.
- If 0 was passed to numAdvEvent when ugap_bcastStart() is called, ugbNumAdvEvent won’t have any effect on this state. Otherwise, the broadcaster’s state will switch to the UGAP_BCAST_STATE_IDLE state once the total number of advertising events since ugap_bcastStart() was called reaches ugbNumAdvEvent, or if requested through ugap_bcastStop().
- If ugap_bcastSuspend() is called, the broadcaster’s state will switch to the UGAP_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 the UGAP_BCAST_STATE_ADVERTISING state.
UGAP_BCAST_STATE_WAITING: The broadcaster has started but is not advertising in this state because it is in the ugbDutyOffTime period. The corresponding state of the uLL is ULL_STATE_STANDBY. If Broadcaster Duty Control is enabled, the duty timer starts with the duration of ugbDutyOffTime when this state is entered. Then, the state switches to the UGAP_BCAST_STATE_ADVERTISING state when the duty timer expires.
- The state switches to the UGAP_BCAST_STATE_IDLE state if requested through ugap_bcastStop(). If ugap_bcastSuspend() is called, the state switches to the UGAP_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 the UGAP_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 but ULL_STATE_ADVERTISING. The former state shall be recorded when this state is entered. If the suspension is lifted through ugap_bcastResume(), the state will switch back to the former state. The state switches to the UGAP_BCAST_STATE_IDLE if ugap_bcastStop() is called.

Figure 107. Broadcaster States¶

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.

Figure 108. Life Cycle of Broadcaster Function¶

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 but ULL_STATE_SCANNING.
UGAP_SCAN_STATE_SCANNING: The observer is scanning in this state. The corresponding state of the uLL is ULL_STATE_SCANNING. The duty timer starts with the duration of ugoScanOnTime when this state is entered. Then, the state switches to the UGAP_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 update ugoScanChanMap 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 through ugap_scanStop(). If ugap_scanSuspend() is called, the observer’s state will switch to the UGAP_SCAN_STATE_SUSPENDED state, putting the duty timer on hold. The duty timer will resume when the observer’s state switches back to the UGAP_SCAN_STATE_SCANNING state.
UGAP_SCAN_STATE_WAITING: The observer has started but is not scanning in this state because it is in the ugoScanOffTime period. The corresponding state of the uLL is ULL_STATE_STANDBY. The duty timer starts with the duration of ugoScanOffTime when this state is entered. Then, the state switches to the UGAP_SCAN_STATE_SCANNING state when the duty timer expires.
- The state switches to the UGAP_SCAN_STATE_IDLE state if requested through ugap_scanStop(). If ugap_scanSuspend() is called, the state switches to the UGAP_SCAN_STATE_SUSPENDED state, putting the duty timer on hold. The duty timer will resume when the observer’s state switches back to the UGAP_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 but ULL_STATE_ADVERTISING. The former state shall be recorded when this state is entered. If the suspension is lifted through ugap_bcastResume(), the state will switch back to the former state. The state switches to the UGAP_BCAST_STATE_IDLE if ugap_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 is ULL_STATE_STANDBY.
UGAP_MONITOR_STATE_MONITORING: The monitor is scanning. The corresponding state of the uLL is ULL_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.