Bluetooth Low Energy Link Layer Metrics

A user application can enable or disable the tracking of metrics for Bluetooth Low Energy links. This is accomplished by calling the following function, with the en input parameter set to 0x1 or 0x0, respectively:

uint8_t BLE_Link_Metrics(uint8_t en, uint8_t actidx, struct ble_link_metrics *metricsPtr)

We recommend using this function to enable the link metrics tracking when a Bluetooth Low Energy link is established (i.e., when GAPC_CONNECTION_REQ_IND is received), and disable the tracking at Bluetooth Low Energy disconnection (i.e., when GAPC_DISCONNECT_IND is received).

Example code for the BLE_Link_Metrics() function:

struct ble_link_metrics bleLinkMetrics[APP_MAX_NB_CON];

...

 

/* At receiving GAPC_CONNECTION_REQ_IND */

memset(&bleLinkMetrics[conidx], 0, sizeof(struct ble_link_metrics));

ble_metrics_ret_val = BLE_Link_Metrics(1, p->conhdl, &bleLinkMetrics[conidx]);

...

 

/* At receiving GAPC_DISCONNECT_IND */

ble_metrics_ret_val = BLE_Link_Metrics(0, gap_env.connection[conidx].conhdl, &bleLinkMetrics[conidx]);

...

This example shows data structure ble_link_metrics used to track the metrics for a Bluetooth Low Energy link:

struct ble_link_metrics

{

uint8_t enable;

uint32_t noerr_pkt_non_empty_cnt;

uint32_t noerr_pkt_empty_cnt;

uint32_t sync_err_cnt;

uint32_t rxtime_err_cnt;

uint32_t len_err_cnt;

uint32_t crc_err_cnt;

uint32_t mic_err_cnt;

uint32_t llid_err_cnt;

uint32_t sn_err_cnt;

uint32_t nsen_err_cnt;

uint32_t rxcte_err_cnt;

};

The "ble_link_metrics Field Names and their Meanings" table shows the meaning of each field in the ble_link_metrics data structure:

Table: ble_link_metrics Field Names and their Meanings

Field Name

Contents

enable

Enable (0x1) or disable (0x0) the tracking of link metrics

noerr_pkt_non_empty_cnt

The number of received non-empty packets without any errors

noerr_pkt_empty_cnt

The number of received empty packets without any errors

sync_err_cnt

The number of received packets with Sync Word not correct or not detected

rxtime_err_cnt

The number of received packets with RX time greater than a threshold configured by the stack till the last CRC bit

len_err_cnt

The number of received packets with lengths greater than the maximum value allowed by the event configured by the stack

crc_err_cnt

The number of received packets with incorrect CRC

mic_err_cnt

The number of received packets with incorrect MIC

llid_err_cnt

The number of received packets with invalid LLID

sn_err_cnt

The number of received packets with incorrect sequence number (SN)

nsen_err_cnt

The number of received packets with incorrect next expected sequence number (NESN)

rxcte_err_cnt

The number of received packets with incomplete reception of CTE field to indicate an abort of the reception during the CTE field

When a packet is received at the link layer of the Bluetooth Low Energy stack, if the tracking of the associated link is enabled (whether the received packet is erroneous or not), the counters in ble_link_metrics data structure associated with the link are updated using the logic below:

if(rxstatus & EM_BLE_SYNC_ERR_BIT)

{

sync_err_cnt++;

}

else if(rxstatus & EM_BLE_RXTIME_ERR_BIT)

{

rxtime_err_cnt++;

}

else if(rxstatus & EM_BLE_LEN_ERR_BIT)

{

len_err_cnt++;

}

else if(rxstatus & EM_BLE_CRC_ERR_BIT)

{

crc_err_cnt++;

}

else if(rxstatus & EM_BLE_MIC_ERR_BIT)

{

mic_err_cnt++;

}

else if(rxstatus & EM_BLE_LLID_ERR_BIT)

{

llid_err_cnt++;

}

else if(rxstatus & EM_BLE_SN_ERR_BIT)

{

sn_err_cnt++;

}

else if(rxstatus & EM_BLE_NESN_ERR_BIT)

{

nsen_err_cnt++;

}

else if(rxstatus & EM_BLE_RXCTEERR_BIT)

{

rxcte_err_cnt++;

}

else

{

if(rxLength == 0)

{

noerr_pkt_empty_cnt++;

}

else

{

noerr_pkt_non_empty_cnt++;

}

}

BLE_Link_Metrics

uint8_t BLE_Link_Metrics(uint8_t en, uint8_t actidx, struct ble_link_metrics *metricsPtr)

Location: lld_con.c: 3643

This function enables or disables the tracking of Bluetooth Low Energy link metrics.

Returns:

Return value from this function indicates if the requested action (enable or disable) has been performed successfully.

Parameters:

Direction

Name

Description

in

en

0x1to enable the tracking of link metrics, 0x0 to disable it

in

actidx

Activity identifier of Bluetooth Low Energy link

in

metricsPtr

Pointer to the ble_link_metrics data structure, which maintains link metric counters

out

Return value

Returns status and indicates if requested action (enable/disable) has been performed successfully

  • 0x0 if requested action has been performed successfully
  • 0x1 if activity identifier of Bluetooth Low Energy link is invalid
  • 0x2 if the pointer to ble_link_metrics data structure is NULL