Secondary Channel Advertiser Command Handler

Introduction

The secondary channel advertiser command handler is a "special" handler meant for testing purposes that can be used for starting advertising on a secondary advertising channel. Unlike the advertiser handler, this command handler only supports extended advertising PDUs which use the secondary physical channel.

PDU Type	PDU Name	Physical Channel	LE 1M	LE 2M	LE Coded	Currently Supported
0b0111	AUX_ADV_IND	Secondary	*	*	*	*
0b0111	AUX_SCAN_RSP	Secondary	*	*	*
0b0111	AUX_SYNC_IND	Periodic	*	*	*
0b0111	AUX_CHAIN_IND	Secondary and Periodic	*	*	*	*
0b0111	AUX_SYNC_SUBEVENT_IND	Periodic	*	*	*
0b0111	AUX_SYNC_SUBEVENT_RSP	Periodic	*	*	*
0b1000	AUX_CONNECT_RSP	Secondary	*	*	*

Usage

How the secondary advertiser command handler is configured and used depends on the type of PDU that is supposed to be sent. Nevertheless, the following basic steps must have taken place before submitting the an advertiser command:

1. RCL has been initialized (See RCL_init) and a handle must exist (See RCL_open).
2. The RCL_CMD_BLE5_AUX_ADV_t command has been initialized and configured.
3. The necessary Tx buffer(s) have been initialized and configured.
4. If needed, the necessary Multibuffer for reception has been initialized and configured.

Once these steps have been completed, RCL_Command_submit and RCL_Command_pend are called to effectively send a packet and then wait for the command to conclude. Alternatively, callbacks can be used for post-processing and the submitting of new commands.

Command configuration and submitting is similar to the advertiser command handler, with the exception that the command handler requires the configuration of a channel to start the operation.

void runSecondaryAdvertiser(void)
{
    RCL_init();
    RCL_Handle h = RCL_open(&rclClient, &LRF_configBle);

    RCL_Buffer_TxBuffer *auxAdvTxBuffer = (RCL_Buffer_TxBuffer *)txBuffer;

    AuxPtr auxAdvAuxPtr;

    auxAdvCmd = RCL_CmdBle5AuxAdvertiser_DefaultRuntime();
    auxAdvCmd.channel = 25;
    auxAdvCmd.ctx = &auxAdvCtx;
    auxAdvCmd.stats = &auxAdvStats;
    auxAdvCmd.common.scheduling = RCL_Schedule_Now;
    auxAdvCmd.common.runtime.callback = advCallback;
    auxAdvCmd.common.runtime.lrfCallbackMask.value = 0;
    auxAdvCmd.common.runtime.rclCallbackMask.value = RCL_EventLastCmdDone.value |
                                                     RCL_EventTxBufferFinished.value;
    auxAdvCtx = RCL_CtxAdvertiser_DefaultRuntime();
    auxAdvStats = (RCL_StatsAdvScanInit) { 0 };
    auxAdvStats.config.accumulate = true;

    /* AuxPtr to be used for the AUX_ADV_IND indicating that the next auxiliary packet will be sent on:
     * BLE 2M PHY, channel 5, and in 1.2 [ms].
     */
    auxAdvAuxPtr.auxOffset = 4;
    auxAdvAuxPtr.offsetUnits = 1;
    auxAdvAuxPtr.auxPhy = 1;
    auxAdvAuxPtr.ca = 0;
    auxAdvAuxPtr.chIndex = 5;

    /* Populate Tx buffer used for the AUX_ADV_IND that will be sent on a secondary advertisement channel */
    setAuxAdvBuffer(auxAdvTxBuffer, &auxAdvAuxPtr, AUX_ADV_DATA_LEN);

    auxAdvTxBuffer->state = RCL_BufferStatePending;

    RCL_TxBuffer_put(&auxAdvCtx.txBuffers, auxAdvTxBuffer);

    RCL_Command_submit(h, &auxAdvCmd);
    /* Wait for command to conclude  */
    RCL_Command_pend(&auxAdvCmd);

    RCL_close(h);
}

Notice how the AuxPtr previously defined are used to populate the Tx Buffer with the help of a C struct.

typedef struct
{
    uint8_t   chIndex: 6;
    uint8_t   ca: 1;
    uint8_t   offsetUnits: 1;
    uint16_t  auxOffset: 13;
    uint16_t  auxPhy: 3;
} AuxPtr;

Architecture

The life cycle of the secondary advertiser command handler depends on the type advertising and more specifically the PDU type. The PDU type will determine aspects such as the number of Tx buffers needed for the operation, or whether the operation involves both Tx and Rx, or just Tx. It is the responsibility of the caller to provide a Tx Buffer containing a valid advertising physical channel PDU.

Furthermore, unlike the advertiser command handler, this command handler does not support the possibility to do PHY switching as this is meant to be handled during the primary channel advertising.

The following activity diagram illustrates the behavior of the secondary channel advertiser command handler.

RCL Event (In)	Description
RCL_EventSetup	Setup has been performed
RCL_EventTimerStart	Timer-based start signalled
RCL_EventGracefulStop	Graceful stop has been observed
RCL_EventHardStop	Hard stop has been observed
RCL_EventRxBufferUpdate	RX buffer has been updated

RCL Event (Out)	Description
RCL_EventLastCmdDone	The RCL is finished with the command
RCL_EventCmdStarted	Command handler has accepted and started executing
RCL_EventRxBufferFinished	An RX multi-buffer is finished
RCL_EventRxEntryAvail	An RX entry has been made available
RCL_EventTxBufferFinished	An TX buffer is finished

LRF Event	Description
LRF_EventOpDone	The PBE operation has finished
LRF_EventOpError	Something went wrong. Cause located in the PBE ENDCAUSE register
LRF_EventRxOk	Packet received with CRC OK and not to be ignored by the MCU
LRF_EventRxNok	Packet received with CRC error
LRF_EventRxIgnored	Packet received, but may be ignored by MCU