# 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_IN D 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