.. _sec-uBLE-overview-cc23xx:

Overview
========

This section describes the high level design and functionality of the Micro BLE
Stack (uBLE Stack). The uBLE Stack enables applications on the |DEVICE| 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* |reg| qualified.


.. _system-architecture-cc23xx:

System Architecture
===================

The Micro BLE Stack consists of the :ref:`sec-urcli-cc23xx`
(Micro RCLI or uRCLI), the :ref:`sec-ull-cc23xx` (Micro LL or uLL), and the
:ref:`sec-ugap-cc23xx` (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 :numref:`system_context_diagram-cc23xx` Note
that only the subcomponents directly relevant to the uBLE Stack in the
application and the RCL driver are depicted.

.. _system_context_diagram-cc23xx:
.. figure:: /u-stack/resources/system_context_diagram.jpg
    :align: center
    :alt: alternate text

    System Context Diagram


.. _sec-urcli-cc23xx:

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


.. _sec-ull-cc23xx:

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 :term:`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 :ref:`sec-urcli-cc23xx` section. These parameters are
dependent on the features enabled in the uBLE Stack.


.. _parameters-to-rely-on-cc23xx:

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 :ble_api:`uble_setParameter` and :ble_api:`uble_getParameter`
functions. These parameters are also dependent on the features
enabled in the uBLE Stack.

.. table:: 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             | uint8                       |
   |                                |                                      | 38: 0x02             |                             |
   |                                |                                      | 39: 0x04             |                             |
   +--------------------------------+--------------------------------------+----------------------+-----------------------------+
   | UBLE_PARAM_ADVTYPE             | Advertising Type                     | ADV_NONCONN_IND or   | uint8                       |
   |                                |                                      | ADV_SCAN_IND         |                             |
   +--------------------------------+--------------------------------------+----------------------+-----------------------------+
   | UBLE_PARAM_TIMETOADV           | How early to notify before the next  | 0 to 255             | uint8                       |
   |                                | advertisment (ms)                    |                      |                             |
   +--------------------------------+--------------------------------------+----------------------+-----------------------------+
   | 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:: 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             | uint8                       |
   |                                |                                      | 38: 0x02             |                             |
   |                                |                                      | 39: 0x04             |                             |
   +--------------------------------+--------------------------------------+----------------------+-----------------------------+
   | UBLE_PARAM_SCANTYPE            | Scanning Type                        | SCAN_PASSIVE or      | uint8                       |
   |                                |                                      | SCAN_ACTIVE          |                             |
   +--------------------------------+--------------------------------------+----------------------+-----------------------------+
   | UBLE_PARAM_FLTDUPLICATE        | Whether to filter out duplicate      |                      | uint8                       |
   |                                | advertising reports or not           |                      |                             |
   +--------------------------------+--------------------------------------+----------------------+-----------------------------+
   | UBLE_PARAM_SCANFLTPOLICY       | Scan Filter Policy                   |                      | uint8                       |
   +--------------------------------+--------------------------------------+----------------------+-----------------------------+

.. table:: 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           |                      | uint32                      |
   |                                | Initialization Value                 |                      |                             |
   +--------------------------------+--------------------------------------+----------------------+-----------------------------+

.. note::
   \*\*This parameter is not accessible to the application and is instead set
   via calls to ``ugap_monitorRequest``.


.. _ull-states-cc23xx:

Micro LL States
---------------

There are 4 states in the Micro LL: the :ref:`ustack-standby-state-cc23xx`,
the :ref:`ustack-advertising-state-cc23xx`, the
:ref:`ustack-scanning-state-cc23xx`, and the
:ref:`ustack-monitoring-state-cc23xx`. 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.


.. _ustack-standby-state-cc23xx:

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.


.. _ustack-advertising-state-cc23xx:

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.

.. .. code-block:: c
..   :caption: uStack/urcli.c: Chaining advertising command
..   :linenos:

..    urfiAdvCmd[0].pNextOp                  = (rfc_radioOp_t*) &urfiAdvCmd[1];
..    urfiAdvCmd[1].pNextOp                  = (rfc_radioOp_t*) &urfiAdvCmd[2];
..    urfiAdvCmd[2].pNextOp                  = NULL;

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 :numref:`system_context_diagram-cc23xx`

-  ``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 :ble_api:`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.


.. _ustack-scanning-state-cc23xx:

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 :numref:`system_context_diagram-cc23xx`

-  ``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.


.. _ustack-monitoring-state-cc23xx:

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 :numref:`system_context_diagram-cc23xx`

-  ``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.

.. _tbl-ustack-rf-event-processing-cc23xx:

.. table:: 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                             |
   +                    +                   +----------------------------------------------+----------------------------------------------------+
   |                    |                   | RCL_EventCmdAborted, RCL_EventCmdStopped,    | ULL_EVT_ADV_TX_FAILED                              |
   |                    |                   | RCL_EventCmdPreempted, RCL_EventCmdCancelled |                                                    |
   +--------------------+-------------------+----------------------------------------------+----------------------------------------------------+
   | 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:
:ref:`ti_driver_reference`.


.. _sec-ugap-cc23xx:

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-cc23xx:

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 :ble_api:`ugap_bcastStart` and
:ble_api:`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:

- :ref:`ustack-broadcaster-role-cc23xx`
- :ref:`ustack-observer-role-cc23xx`
- :ref:`ustack-monitor-role-cc23xx`

The application must configure the uGAP to operate in the
desired role. This section goes over some specifics of the
individual roles.


.. _ustack-broadcaster-role-cc23xx:

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
:ref:`ustack-advertising-state-cc23xx`.

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.

.. _broadcaster_states-cc23xx:
.. figure:: /u-stack/resources/broadcaster_states.jpg
    :align: center
    :alt: alternate text

    Broadcaster States

The |CORESPEC| 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 :ref:`parameter-management-cc23xx`. 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 :numref:`life_cycle_broadcaster_function-cc23xx`

.. _life_cycle_broadcaster_function-cc23xx:
.. figure:: /u-stack/resources/life_cycle_broadcaster_function.jpg
    :align: center
    :alt: alternate text

    Life Cycle of Broadcaster Function


.. _ustack-observer-role-cc23xx:

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
:ref:`ustack-scanning-state-cc23xx`.

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.

.. .. _observer_states-cc23xx:
.. .. figure:: /u-stack/resources/observer_states.jpg
..     :align: center
..     :alt: alternate text

..     Observer States

.. _ustack-monitor-role-cc23xx:

Monitor Role
^^^^^^^^^^^^

The monitor role is not defined by the |CORESPEC|.
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 :ref:`sec-cm-app-cc23xx` section.