The uGAP sits between the uLL and the application and is 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 provides the application with ub_getParameter() and ub_setParameter() functions to enable it to access the parameters used for implementing profile roles. For many of those parameters that are maintained and used by the uLL as listed in Application Parameters Relied On, ub_getParameter() and ub_getParameter() bypass the requests from the application to the uLL through ul_getParam() and ul_setParam(). However, there are some parameters that are maintained by the uGAP as follows:
- 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 UG_BCAST_STATE_INITIALIZED state once started unless it is requested to stop.
- ugbDutyOnTime: Time period during which the Broadcaster stays in UG_BCAST_STATE_ADVERTISING state. The uLL stays in Advertising State as well. When this time period ends, the Broadcaster state will transition to UG_BCAST_STATE_WAITING and the uLL will exit Advertising State. This parameter is effective only if Broadcaster Duty Control is enabled. If Broadcaster Duty Control is disabled, transition to other state from UG_BCAST_STATE_ADVERTISING is not affected by this parameter. A 100-ms time unit is used.
- ugbDutyOffTime: Time period during which the Broadcaster stays in UB_BCAST_STATE_WAITING state. The uLL cannot be in Advertising State during this period. When this time period ends, the Broadcaster state will transition to UG_BCAST_STATE_ADVERTISING and the uLL will enter Advertising State. This parameter is effective only if Broadcast Duty Control is enabled. If 0, Broadcaster Duty Control is disabled and the Broadcaster will not enter UG_BCAST_STATE_WAITING state. A 100-ms time unit is used.
The uGAP is the main interface to operate in various roles.
There are two distinct roles the uGAP supports:
The application must configure the uGAP to operate in the mode desired. This section goes over specifics of the individual roles.
If the application configures the uGAP to operate Broadcaster role, the uGAP lets the uLL send advertising events as described in Advertising State in accordance with the parameters listed in Application Parameters Relied On.
The Broadcaster Role has 4 states:
- UG_BCAST_STATE_INITIALIZED: Broadcaster is initialized but has never started. The corresponding state of the uLL can be anything but UL_STATE_ADVERTISING.
- UG_BCAST_STATE_ADVERTISING: Broadcaster is advertising in this state. The corresponding state of the uLL is UL_STATE_ADVERTISING. If Broadcaster Duty Control is enabled, the duty timer starts with the duration of BcastDutyOnTime when this state is entered. Then, the state switches to UG_BCAST_STATE_WAITING when the duty timer expires. If 0 was passed to NumAdvEvent when ug_bcastStart() is called, ugbNumAdvEvent won’t have any effect on this state. Otherwise, the state switches to UG_BCAST_STATE_IDLE if requested through ug_bcastStop() or the total number of Advertising Events since ug_bcastStart() was called reaches ugbNumAdvEvent. If ug_bcastSuspend() is called, the state switches to UG_BCAST_STATE_SUSPENDED, putting the duty timer on hold if Duty Control is enabled. The duty timer will resume when the state switches back to this state.
- UG_BCAST_STATE_WAITING: Broadcaster started but is not advertising in this state because it’s in DutyOffTime period. The corresponding state of the uLL is UL_STATE_STANDBY. If Broadcaster Duty Control is enabled, the duty timer starts with the duration of BcastDutyOffTime when this state is entered. Then, the state switches to UG_BCAST_STATE_ADVERTISING when the duty timer expires. The state switches to UG_BCAST_STATE_IDLE if requested through ug_bcastStop(). If ug_bcastSuspend() is called, the state switches to UG_BCAST_STATE_SUSPENDED, putting the duty timer on hold if Duty Control is enabled. The duty timer will resume when the state switches back to this state.
- UG_BCAST_STATE_SUSPENDED: Broadcaster started but is not advertising in this state. The corresponding state of the uLL can be anything but UL_STATE_ADVERTISING. The former state shall be recorded when this state is entered. If the suspension is lifted through ug_bcastResume(), the state will switch back to the former state. The state switches to UG_BCAST_STATE_IDLE if ug_bcastStop() is called.
The BLE specification doesn’t allow 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 BcastDutyOnTime and BcastDutyOffTime explained in Parameters Management. 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 81.
The Monitor Role is not an official BLE Specification role. This section is to describe how the uGAP operates when using the Monitor Feature.
This role is tested in stand alone condition only. No other uBLE Stack feature should be used in conjunction.
Monitor role is designed to follow an active BLE connection if given connection information such as access address, hop increment, and connection interval. With this information the Monitor role sets up uGAP and uBLE.
The Monitor Role has 3 States:
- UG_MONITOR_STATE_INITIALIZED: The monitor is initialized but is not monitoring.
- UG_MONITOR_STATE_IDLE: The monitor is not monitoring in this state. This corresponds to UL_STATE_STANDBY in the uLL.
- UG_MONITOR_STATE_MONITORING: The monitor is scanning. This corresponds to UL_STATE_MONITORING in the uLL.
When a packet is detected with the during a scan with the Connection Parameters passed in from the ‘uble.c’ source file a UGM_EVT_MONITOR_INDICATION event is generated.
When a scan is complete, a UGM_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 UGM_EVT_STATE_CHANGE event is generated.