API documentation

BLE Controller

group ble_controller

The main APIs needed to configure, enable, and use the BLE Controller.

Defines

BLE_CONTROLLER_DEFAULT_RESOURCE_CFG_TAG

Default resource configuration tag.

BLE_CONTROLLER_DEFAULT_SLAVE_COUNT

Default maximum number of concurrent slave links.

BLE_CONTROLLER_DEFAULT_MASTER_COUNT

Default maximum number of concurrent master links.

BLE_CONTROLLER_DEFAULT_TX_PACKET_SIZE

Default maximum Link Layer TX packet size.

BLE_CONTROLLER_DEFAULT_RX_PACKET_SIZE

Default maximum Link Layer RX packet size.

BLE_CONTROLLER_DEFAULT_TX_PACKET_COUNT

Default maximum Link Layer TX packet count per connection.

With the default count, the application is able to refill the buffers during a connection event.

BLE_CONTROLLER_DEFAULT_RX_PACKET_COUNT

Default maximum Link Layer RX packet count per connection.

With the default count, the application is able to empty the buffers during a connection event.

BLE_CONTROLLER_DEFAULT_EVENT_LENGTH_US

Default connection event length.

BLE_CONTROLLER_BUILD_REVISION_SIZE

Size of build revision array in bytes.

Typedefs

typedef void (*ble_controller_fault_handler_t)(const char *file, const uint32_t line)

Function prototype for the fault handler.

Note

The BLE Controller will disable all interrupts prior to calling the fault handler. The BLE Controller will reset the chip if the application returns from this function.

Parameters
  • [in] file: The filename where the assertion occurred.

  • [in] line: The line number where the assertion occurred.

typedef void (*ble_controller_callback_t)(void)

Function prototype for the BLE Controller callback.

See

ble_controller_enable

Enums

enum BLE_CONTROLLER_CFG_TYPE

Values:

BLE_CONTROLLER_CFG_TYPE_NONE = 0

No configuration update.

BLE_CONTROLLER_CFG_TYPE_MASTER_COUNT = 1

Number of concurrent master roles.

See

ble_controller_cfg_t::master_count.

BLE_CONTROLLER_CFG_TYPE_SLAVE_COUNT = 2

Number of concurrent slave roles.

See

ble_controller_cfg_t::slave_count.

BLE_CONTROLLER_CFG_TYPE_BUFFER_CFG = 3

Buffer configuration per connection.

See

ble_controller_cfg_t::buffer_cfg.

BLE_CONTROLLER_CFG_TYPE_EVENT_LENGTH = 4

Maximum event length.

See

ble_controller_cfg_t::event_length.

Functions

int32_t ble_controller_init(ble_controller_fault_handler_t fault_handler)

Initialize the BLE Controller.

After this function is called, the application may use SoC APIs.

Parameters
  • [in] fault_handler: The fault handler will be executed when there is an internal error in the BLE Controller.

Return Value
  • 0: Success

  • -: NRF_EINVAL Invalid argument provided

  • -: NRF_EPERM Unable to initialize because

    • MPSL is not initialized

    • MPSL needs to be configured with a LFCLK accuracy of 500 ppm or better.

int32_t ble_controller_cfg_set(uint8_t config_tag, uint8_t config_type, ble_controller_cfg_t const *p_resource_cfg)

Change or add a BLE Controller configuration.

To change the default configuration, update BLE_CONTROLLER_DEFAULT_RESOURCE_CFG_TAG. To create or update a new configuration, provide another resource_cfg_tag.

Note

The application can set config_type to BLE_CONTROLLER_CFG_TYPE_NONE to obtain the required memory size for the current configuration in bytes.

Note

Resource configuration can only be performed prior to calling ble_controller_enable. However, the current configuration may be changed after enabling the BLE Controller.

See

BLE_CONTROLLER_CFG_TYPE.

Return

Required memory size for the current configuration in bytes.

Parameters
  • [in] config_tag: Configuration tag.

  • [in] config_type: Configuration type.

Parameters
  • [in] p_resource_cfg: Configuration to be changed.

Return Value
  • -: NRF_EOPNOTSUPP Unsupported configuration

  • -: NRF_EINVAL Invalid argument provided

int32_t ble_controller_enable(ble_controller_callback_t callback, uint8_t *p_mem)

Enable the BLE Controller.

After this function is called, the application may utilize HCI APIs.

See

hci_evt_get and hci_data_get.

Parameters
  • [in] callback: The callback will be executed when HCI data or and HCI event is available. The callback will be executed in the same context as mpsl_low_priority_process.

Parameters
  • [in] p_mem: Provide memory for the current resource configuration. If custom resource configurations are used, use the value returned from ble_controller_cfg_set.

Return Value
  • 0: Success

  • -: NRF_EINVAL Invalid argument provided

int32_t ble_controller_disable(void)

Disable the BLE Controller.

This call is synchronous. After the BLE Controller is disabled, BLE functionality is no longer available.

Return Value
  • 0: Success

int32_t ble_controller_build_revision_get(uint8_t *p_build_revision)

Obtain build revision string.

The application must provide a buffer that is at least BLE_CONTROLLER_BUILD_REVISION_SIZE bytes long. The BLE controller will copy the build revision string to the provided buffer.

Parameters
  • [inout] p_build_revision: Build revision.

Return Value
  • 0: Success

  • -: NRF_EINVAL Invalid argument provided

void ble_controller_RNG_IRQHandler(void)

BLE Controller RNG interrupt handler.

Note

This function should be called when a RNG interrupt occurs. The interrupt priority level should be lower than priority level 0, that is, a higher numerical priority value.

int32_t ble_controller_support_dle(void)

Support Data Length Extensions.

After this API is called, the controller will support data length extension. That is:

  • All DLE HCI APIs are supported.

  • The controller replies with LL_LENGTH_RSP when a LL_LENGTH_REQ is received.

  • DLE is marked supported in the LL Feature Exchange procedure.

Return Value
  • 0: Success

  • -: NRF_EPERM This API must be called before ble_controller_enable().

  • -: NRF_EOPNOTSUPP Data Length Extension is not supported.

struct ble_controller_cfg_role_count_t
#include <ble_controller.h>

Role count.

Public Members

uint8_t count

Max number of concurrent roles.

struct ble_controller_cfg_buffer_cfg_t
#include <ble_controller.h>

Buffer configuration.

Public Members

uint8_t tx_packet_size

Link Layer TX packet size. Valid range: 27-251.

uint8_t rx_packet_size

Link Layer RX packet size. Valid range: 27-251.

uint8_t tx_packet_count

Link Layer TX packet count per link.

uint8_t rx_packet_count

Link Layer RX packet count per link.

struct ble_controller_cfg_event_length_t
#include <ble_controller.h>

Connection event length configuration.

Public Members

uint32_t event_length_us

Maximum connection event length

union ble_controller_cfg_t
#include <ble_controller.h>

BLE controller configuration.

Public Members

ble_controller_cfg_role_count_t master_count

Max number of concurrent master connections. Default: BLE_CONTROLLER_DEFAULT_MASTER_COUNT.

ble_controller_cfg_role_count_t slave_count

Max number of concurrent slave connections. Default: BLE_CONTROLLER_DEFAULT_SLAVE_COUNT.

ble_controller_cfg_buffer_cfg_t buffer_cfg

Max number of concurrent slave connections. Default: BLE_CONTROLLER_DEFAULT_SLAVE_COUNT.

ble_controller_cfg_event_length_t event_length

Max connection event length. Default: BLE_CONTROLLER_DEFAULT_EVENT_LENGTH_US.

Memory requirement defines

group ble_controller_mem_defines

The BLE Controller memory requirement defines may be used to determine the dynamic memory usage at compile time. The defines specify an upper limit, therefore the actual memory required may be less.

Note

The values of the memory requirement defines may change between minor releases.

Defines

Maximum number of bytes required per master link for the default buffer configuration.

Maximum number of bytes required per slave link for the default buffer configuration.

BLE_CONTROLLER_MEM_BUFFER_OVERHEAD_SIZE

Memory overhead per LL packet buffer.

Maximum additional number of bytes required per link.

This macro will return the additional memory required per link if non-default buffer sizes are used.

Parameters
  • [in] tx_size: Link Layer TX packet size.

  • [in] rx_size: Link Layer RX packet size.

  • [in] tx_count: Link Layer TX packet count.

  • [in] rx_count: Link Layer RX packet count.

Maximum memory required per master link.

Parameters
  • [in] tx_size: Link Layer TX packet size.

  • [in] rx_size: Link Layer RX packet size.

  • [in] tx_count: Link Layer TX packet count.

  • [in] rx_count: Link Layer RX packet count.

Maximum memory required per slave link.

Parameters
  • [in] tx_size: Link Layer TX packet size.

  • [in] rx_size: Link Layer RX packet size.

  • [in] tx_count: Link Layer TX packet count.

  • [in] rx_count: Link Layer RX packet count.

Maximum shared memory required for master links.

Maximum shared memory required for slave links.

BLE Controller HCI

group ble_controller_hci

The BLE Controller HCI APIs are used to send HCI commands/data and receive events/data to and from the BLE Controller. The HCI packet format is described in the Bluetooth Core Specification, i.e. in Core v5. Vol 2, Part E. All APIs in this header file are expected to be called from the same execution priority as mpsl_low_priority_process. Not doing so will lead to undefined behavior.

Defines

HCI_CMD_HEADER_SIZE

The size of a command packet header.

HCI_DATA_HEADER_SIZE

The size of a data packet header.

HCI_EVENT_HEADER_SIZE

The size of an event packet header.

HCI_CMD_MAX_SIZE

The maximum size of a command.

HCI_DATA_MAX_SIZE

The maximum size of data.

HCI_EVENT_MAX_SIZE

The maximum size of an event.

HCI_CMD_PACKET_MAX_SIZE

The maximum size of an HCI command packet.

HCI_DATA_PACKET_MAX_SIZE

The maximum size of an HCI data packet.

HCI_EVENT_PACKET_MAX_SIZE

The maximum size of an HCI event packet.

HCI_MSG_BUFFER_MAX_SIZE

The maximum size of an HCI packet.

Functions

int32_t hci_cmd_put(uint8_t const *p_cmd_in)

Send an HCI command packet to the BLE Controller.

Parameters
  • [in] p_cmd_in: HCI Command packet. The first byte in the buffer should correspond to OpCode, as specified by the Bluetooth Core Specification.

Return Value
  • 0: Success

  • -: NRF_EINVAL Invalid input

int32_t hci_data_put(uint8_t const *p_data_in)

Send an HCI data packet to the BLE Controller.

Parameters
  • [in] p_data_in: HCI Data packet. The first byte in the buffer should correspond to Handle, as specified by the Bluetooth Core Specification.

Return Value
  • 0: Success

  • -: NRF_EINVAL Invalid input

int32_t hci_evt_get(uint8_t *p_evt_out)

Retrieve an HCI event packet from the BLE Controller.

This API is non-blocking.

Note

The application should ensure that the size of the provided buffer is at least HCI_EVENT_PACKET_MAX_SIZE bytes.

Parameters
  • [inout] p_evt_out: Buffer where the HCI event will be stored. If an event is retrieved, the first byte corresponds to Event Code, as specified by the Bluetooth Core Specification.

Return Value
  • 0: Success

  • -: NRF_EAGAIN No event available

  • -: NRF_EINVAL Invalid input

int32_t hci_data_get(uint8_t *p_data_out)

Retrieve an HCI data packet from the BLE Controller.

This API is non-blocking.

Note

The application should ensure that the size of the provided buffer is at least HCI_DATA_PACKET_MAX_SIZE bytes.

Parameters
  • [inout] p_data_out: Buffer where the HCI data packet will be stored. If an data packet is retrieved, the first byte corresponds to Handle, as specified by the Bluetooth Core Specification.

Return Value
  • 0: Success

  • -: NRF_EAGAIN No data available

  • -: NRF_EINVAL Invalid input

BLE Controller HCI VS

group ble_controller_hci_vs

The BLE Controller VS HCI APIs define additional functionality provided by the BLE controller library. All APIs in this header file are expected to be called from the same execution priority as mpsl_low_priority_process. Not doing so will lead to undefined behavior.

HCI VS Types

group HCI_VS_TYPES

Enums

enum HCI_VS_OPCODE

HCI OpCode Field values.

Values:

HCI_VS_OPCODE_CMD_LLPM_MODE_SET = 0xfc01

See hci_vs_cmd_llpm_mode_set().

HCI_VS_OPCODE_CMD_CONN_UPDATE = 0xfc02

See hci_vs_cmd_conn_update().

HCI_VS_OPCODE_CMD_CONN_EVENT_EXTEND = 0xfc03

See hci_vs_cmd_conn_event_extend().

HCI_VS_OPCODE_CMD_QOS_CONN_EVENT_REPORT_ENABLE = 0xfc04

See hci_vs_cmd_qos_conn_event_report_enable().

enum HCI_VS_SUBEVENT_CODE

Subevent Code values.

Values:

HCI_VS_SUBEVENT_CODE_QOS_CONN_EVENT_REPORT = 0x01

See hci_vs_evt_qos_conn_event_report_t.

HCI VS Events

group HCI_VS_EVENTS
struct hci_vs_evt_qos_conn_event_report_t
#include <ble_controller_hci_vs.h>

QoS Connection Event Report.

A QoS Connection Event report gives information about the connection event.

Public Members

uint16_t conn_handle

Connnection handle corresponding to the connection event report.

uint16_t event_counter

Connection event counter corresponding to the connection event report.

uint8_t channel_index

Data Channel Index used during the connection event (0-36).

uint16_t crc_ok_count

Number of packets received with good CRC during the connection event.

uint8_t crc_error_count

Number of packets received with bad CRC during the connection event.

uint8_t rx_timeout

Indicates that the connection event was closed because a packet was not received.

HCI VS Commands

group HCI_VS_COMMANDS
struct hci_vs_cmd_llpm_mode_set_t
#include <ble_controller_hci_vs.h>

Set Low Latency Packet Mode command parameter(s).

Public Members

uint8_t enable

Set to 1 to enable LLPM.

struct hci_vs_cmd_conn_update_t
#include <ble_controller_hci_vs.h>

Connection Update command parameter(s).

Public Members

uint16_t connection_handle

Connection Handle.

uint32_t conn_interval_us

Connection Interval in microseconds. Valid range is 7,500 us to 4,000,000 us in 1,250 us steps. If LLPM mode is enabled, parameters in the range 1,000 us to 7,000 us in 1,000 us steps are also accepted.

uint16_t conn_latency

Slave latency for the connection in number of connection events.

uint16_t supervision_timeout

Supervision timeout for the LE Link in 10 ms units. Range 100 ms to 32 ms.

struct hci_vs_cmd_conn_event_extend_t
#include <ble_controller_hci_vs.h>

Enable or Disable Extended Connection Events command parameter(s).

Public Members

uint8_t enable

Set to 0 for disabling, 1 for enabling, all other values are RFU.

struct hci_vs_cmd_qos_conn_event_report_enable_t
#include <ble_controller_hci_vs.h>

QoS Connection Event Reports enable command parameter(s).

Public Members

uint8_t enable

Set to 0 for disabling, 1 for enabling, all other values are RFU.

HCI VS API

group HCI_VS_API

Functions

uint8_t hci_vs_cmd_llpm_mode_set(const hci_vs_cmd_llpm_mode_set_t *p_params)

Set Low Latency Packet Mode.

This command enables or disables Low Latency Packet Mode support. When Low Latency Packet Mode is enabled, it is possible to switch to connection intervals in the range 1-7 ms. Switch to short connection intervals by calling hci_vs_cmd_conn_update().

After HCI Reset, this feature is disabled.

Return

Returns value between 0x01-0xFF in case of error. See Vol 2, Part D, Error for a list of error codes and descriptions.

Parameters
  • [in] p_params: Input parameters.

Return Value
  • 0: if success.

uint8_t hci_vs_cmd_conn_update(const hci_vs_cmd_conn_update_t *p_params)

Connection Update.

This vendor specific command is used to change the Link Layer Connection parameters of a connection. This command may be issued by the master only.

The Supervision_Timeout in milliseconds shall be larger than (1 + Conn_Latency) * Conn_Interval_Max * 2, where Conn_Interval_Max is given in milliseconds.

Return

Returns value between 0x01-0xFF in case of error. See Vol 2, Part D, Error for a list of error codes and descriptions.

Parameters
  • [in] p_params: Input parameters.

Return Value
  • 0: if success.

uint8_t hci_vs_cmd_conn_event_extend(const hci_vs_cmd_conn_event_extend_t *p_params)

Enable or Disable Extended Connection Events.

When Extended Connection Events are disabled, the maximum connection event length is set by ble_controller_cfg_event_length_t::event_length_us. When Extended Connection Events are enabled, the controller will extend the connection event as much as possible, if:

  • Either of the peers has more data to send. See also: Core v5.1, Vol 6, Part B, Section 4.5.6

  • There are no conflicts with other concurrent links.

A connection event can not be extended beyond the connection interval.

By default, that is after an HCI Reset, Extended Connection Events are enabled.

Return

Returns value between 0x01-0xFF in case of error. See Vol 2, Part D, Error for a list of error codes and descriptions.

Parameters
  • [in] p_params: Input parameters.

Return Value
  • 0: if success.

uint8_t hci_vs_cmd_qos_conn_event_report_enable(const hci_vs_cmd_qos_conn_event_report_enable_t *p_params)

QoS Connection Event Reports enable.

This vendor specific command is used to enable or disable generation of QoS Connection event reports. See hci_vs_evt_qos_conn_event_report_t. When enabled, one report will be generated every connection event.

Note

If the application does not pull a report in time, it will be overwritten.

Return

Returns value between 0x01-0xFF in case of error. See Vol 2, Part D, Error for a list of error codes and descriptions.

Parameters
  • [in] p_params: Input parameters.

Return Value
  • 0: if success.

BLE Controller SoC

group ble_controller_soc

The BLE Controller SoC interface provides APIs for flash access, random number generation, and block encryption. While the BLE Controller is enabled, the application should only use the provided APIs to access NRF_NVMC, NRF_RNG, or NRF_ECB. Not doing so will lead to undefined behavior.

Typedefs

typedef void (*ble_controller_flash_callback_t)(uint32_t status)

Flash command callback.

The flash command callback will be called when a flash operation is completed. It will be executed in the same execution priority as mpsl_low_priority_process.

See

BLE_CONTROLLER_FLASH_CMD_STATUS.

Parameters
  • [in] status: The status of the flash operation.

Enums

enum BLE_CONTROLLER_FLASH_CMD_STATUS

Flash command status.

Values:

BLE_CONTROLLER_FLASH_CMD_STATUS_SUCCESS = 0
BLE_CONTROLLER_FLASH_CMD_STATUS_TIMEOUT = 1

Functions

int32_t ble_controller_flash_write(uint32_t addr, const void *p_src, uint32_t size, ble_controller_flash_callback_t on_complete)

Write data to flash.

This asynchronous API will ensure that the flash operation will not interfere with radio activity. The completion will be communicated to the application through the provided callback function.

Note

The data in the p_src buffer should not be modified before the completion callback has been executed.

Parameters
  • [in] addr: Flash location to be written.

  • [in] p_src: Pointer to buffer with data to be written.

  • [in] size: Number of 32-bit words to write. Maximum size is the number of words in one flash page. See the device’s Product Specification for details.

  • [in] on_complete: Callback to be called when flash is written. The callback will be executed in the context as mpsl_low_priority_process.

Return Value
  • 0: Success

  • -: NRF_EINVAL Either:

    • Tried to write to a non existing flash address

    • addr or p_src was not word aligned

    • Size was 0, or higher than the maximum allowed size

  • -: NRF_EINPROGRESS Previous flash operation is not yet completed

int32_t ble_controller_flash_page_erase(uint32_t addr, ble_controller_flash_callback_t on_complete)

Erase a flash page.

This asynchronous API will ensure that the flash operation will not interfere with radio activity. The completion will be communicated to the application through the provided callback function.

Parameters
  • [in] addr: Start address of the flash page to be erased. If the address is not aligned with the start of flash page, the page containing this address will be erased.

  • [in] on_complete: Function to be called when page is erased. The callback will be executed in the context as mpsl_low_priority_process.

Return Value
  • 0: Success

  • -: NRF_EINVAL Tried to erase a non existing flash page.

  • -: NRF_EINPROGRESS Previous flash operation is not yet completed

uint32_t ble_controller_rand_vector_get(uint8_t *p_dst, uint16_t length)

Get random bytes from the random pool.

The BLE Controller will use NRF_RNG to obtain the numbers. The function can be called from ISR context.

Note

If the function is repeatedly called from an execution priority higher than the RNG IRQ priority, no new bytes will be returned.

Parameters
  • [out] p_dst: Pointer to a buffer in RAM for storing the bytes.

  • [in] length: Number of random bytes to retrieve.

Return Value
  • Number: of bytes obtained

void ble_controller_rand_vector_get_blocking(uint8_t *p_dst, uint16_t length)

Get random bytes from the random pool synchronously.

The BLE Controller will use NRF_RNG to obtain the numbers. The function can be called from ISR context.

Note

This function works like ble_controller_rand_vector_get, except that instead of failing in the event of not enough numbers being available, it will block until it has filled the specified length with random number bytes. The time until completion will vary.

Parameters
  • [out] p_dst: Pointer to a buffer in RAM for storing the bytes.

  • [in] length: Number of random bytes to retrieve.

int32_t ble_controller_ecb_block_encrypt(const uint8_t key[16], const uint8_t cleartext[16], uint8_t ciphertext[16])

Encrypt a block according to the specified parameters.

The BLE Controller will use NRF_ECB encrypt the block. The encryption type is 128-bit AES.

Note

:

  • The application may set the SEVONPEND bit in the SCR to 1 to make the BLE Controller sleep while the ECB is running. The SEVONPEND bit should only be cleared from the current execution context or a lower priority execution context.

Parameters
  • [in] key: Encryption key

  • [in] cleartext: Cleartext data

  • [out] ciphertext: Encrypted data

Return Value
  • 0: Success