API documentation

Bluetooth LE 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.

int32_t ble_controller_support_le_2m_phy(void)

Support LE 2M PHY.

After this API is called, the controller will support LE 2M PHY. That is:

  • All HCI APIs for obtaining or changing PHYs are supported.

  • The controller can use 2M PHY in both the connected and non-connected state.

  • LE 2M PHY is marked supported in the LL Feature Exchange procedure.

Return Value
  • 0: Success

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

int32_t ble_controller_support_le_coded_phy(void)

Support LE Coded PHY.

After this API is called, the controller will support LE Coded PHY. That is:

  • All HCI APIs for obtaining or changing PHYs are supported.

  • The controller can use LE Coded PHY in both the connected and non-connected state.

  • LE Coded PHY 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: LE Coded PHY 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.

Bluetooth LE 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

Bluetooth LE 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 Types

group HCI_TYPES

Enums

enum HCI_VS_OPCODE

HCI VS OpCode Field values.

Values:

HCI_VS_OPCODE_CMD_ZEPHYR_READ_VERSION_INFO = 0xfc01

See hci_vs_cmd_zephyr_read_version_info().

HCI_VS_OPCODE_CMD_ZEPHYR_READ_SUPPORTED_COMMANDS = 0xfc02

See hci_vs_cmd_zephyr_read_supported_commands().

HCI_VS_OPCODE_CMD_ZEPHYR_WRITE_BD_ADDR = 0xfc06

See hci_vs_cmd_zephyr_write_bd_addr().

HCI_VS_OPCODE_CMD_ZEPHYR_READ_STATIC_ADDRESSES = 0xfc09

See hci_vs_cmd_zephyr_read_static_addresses().

HCI_VS_OPCODE_CMD_ZEPHYR_WRITE_TX_POWER = 0xfc0e

See hci_vs_cmd_zephyr_write_tx_power().

HCI_VS_OPCODE_CMD_LLPM_MODE_SET = 0xfd01

See hci_vs_cmd_llpm_mode_set().

HCI_VS_OPCODE_CMD_CONN_UPDATE = 0xfd02

See hci_vs_cmd_conn_update().

HCI_VS_OPCODE_CMD_CONN_EVENT_EXTEND = 0xfd03

See hci_vs_cmd_conn_event_extend().

HCI_VS_OPCODE_CMD_QOS_CONN_EVENT_REPORT_ENABLE = 0xfd04

See hci_vs_cmd_qos_conn_event_report_enable().

HCI_VS_OPCODE_CMD_EVENT_LENGTH_SET = 0xfd05

See hci_vs_cmd_event_length_set().

enum HCI_VS_SUBEVENT

VS subevent Code values.

Values:

HCI_VS_SUBEVENT_QOS_CONN_EVENT_REPORT = 0x80

See hci_vs_subevent_qos_conn_event_report_t.

enum HCI_VS_TX_POWER_HANDLE_TYPE

TX power handle type.

Values:

HCI_VS_TX_POWER_HANDLE_TYPE_ADV = 0x00

Handle of type Advertiser.

HCI_VS_TX_POWER_HANDLE_TYPE_SCAN_INIT = 0x01

Handle of type Scanner or Initiator.

HCI_VS_TX_POWER_HANDLE_TYPE_CONN = 0x02

Handle of type Connection.

struct hci_vs_zephyr_static_address_t
#include <ble_controller_hci_vs.h>

Zephyr Static Adress type.

Public Members

uint8_t address[6]

Static device address.

uint8_t identity_root[16]

Identity root key (IR) for static device address. All zero parameter value indicates missing identity root key.

struct hci_vs_zephyr_supported_commands_t
#include <ble_controller_hci_vs.h>

Zephyr supported commands.

If the field is set to 1, it indicates that the underlying command and feature is supported by the controller.

Public Members

uint8_t read_version_info : 1

Read Version Information.

uint8_t read_supported_commands : 1

Read Supported Commands.

uint8_t read_supported_features : 1

Read Supported Features.

uint8_t set_event_mask : 1

Set Event Mask.

uint8_t reset : 1

Reset.

uint8_t write_bd_addr : 1

Write BD_ADDR.

uint8_t set_trace_enable : 1

Set Trace Enable.

uint8_t read_build_info : 1

Read Build Information.

uint8_t read_static_addresses : 1

Read Static Addresses.

uint8_t read_key_hierarchy_roots : 1

Read Key Hierarchy Roots.

uint8_t read_chip_temperature : 1

Read Chip Temperature.

uint8_t read_host_stack_commands : 1

Read Host Stack Commands.

uint8_t set_scan_request_reports : 1

Set Scan Request Reports.

uint8_t write_tx_power_level : 1

Write Tx Power Level (per Role/Connection).

uint8_t read_tx_power_level : 1

Read Tx Power Level (per Role/Connection).

HCI Events

group HCI_EVENTS
struct hci_vs_subevent_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 Commands

group HCI_COMMAND_PARAMETERS
struct hci_vs_cmd_zephyr_read_version_info_return_t
#include <ble_controller_hci_vs.h>

Zephyr Read Version Information return parameter(s).

Public Members

uint16_t hw_platform

Assigned hardware manufacturer. Always 0x0002 indicating Nordic Semiconductor.

uint16_t hw_variant

Assigned platform specific value. Set to 0x2 for nRF52, 0x3 for nRF53.

uint8_t fw_variant

Firmware Variant. 0 indicates a standard Bluetooth controller.

uint8_t fw_version

Firmware Version.

uint16_t fw_revision

Firmware Revision.

uint32_t fw_build

Firware build revision.

union hci_vs_cmd_zephyr_read_supported_commands_return_t
#include <ble_controller_hci_vs.h>

Zephyr Read Supported Commands return parameter(s).

Public Members

hci_vs_zephyr_supported_commands_t params

Bit mask for each vendor command. If a bit is 1, the Controller supports the corresponding command and the features required for the command, unsupported or undefined commands shall be set to 0.

uint8_t raw[64]
struct hci_vs_cmd_zephyr_write_bd_addr_t
#include <ble_controller_hci_vs.h>

Zephyr Write BD ADDR command parameter(s).

Public Members

uint8_t bd_addr[6]

BD_ADDR of the Device.

struct hci_vs_cmd_zephyr_read_static_addresses_return_t
#include <ble_controller_hci_vs.h>

Zephyr Read Static Addresses return parameter(s).

Public Members

uint8_t num_addresses

Number of static device addresses.

hci_vs_zephyr_static_address_t addresses[]

Zephyr Static Addresses. The number of addresses is specified in num_addresses.

struct hci_vs_cmd_zephyr_write_tx_power_t
#include <ble_controller_hci_vs.h>

Zephyr Write Tx Power Level (per Role/Connection) command parameter(s).

Public Members

uint8_t handle_type

Handle type. See HCI_VS_TX_POWER_HANDLE_TYPE.

uint16_t handle

Handle of the selected handle_type that identifies the instance to set the power of. In case of Extended Advertising, the handle specifies the advertising set. In case of a connection, it specifies a Connection Handle. Otherwise this parameter is ignored.

int8_t tx_power_level

The desired Tx_Power_Level in dBm in signed 1 octet integer format. If set to 127, this indicates that the controller shall revert to using its default setting for Tx power. If the selected power level is not supported, an error is returned.

struct hci_vs_cmd_zephyr_write_tx_power_return_t
#include <ble_controller_hci_vs.h>

Zephyr Write Tx Power Level (per Role/Connection) return parameter(s).

Public Members

uint8_t handle_type

Handle type. See HCI_VS_TX_POWER_HANDLE_TYPE.

uint16_t handle

See hci_vs_cmd_zephyr_write_tx_power_t.

int8_t selected_tx_power

The selected Tx Power in dBm.

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.

struct hci_vs_cmd_event_length_set_t
#include <ble_controller_hci_vs.h>

Set event length for connections command parameter(s).

Public Members

uint32_t event_length_us

Allocated event length in microseconds.

HCI VS API

group HCI_VS_API

Functions

uint8_t hci_vs_cmd_zephyr_read_version_info(hci_vs_cmd_zephyr_read_version_info_return_t *p_return)

Zephyr Read Version Information.

Reads the values for the vendor version information for the local Controller.

The Hardware_Platform information defines the hardware manufacturer information. The Hardware_Variant is manufacturer specific and defines the hardware platform from that manufacturer.

The Firmware_Variant defines the type of firmware. It is possible to provide HCI firmware with limited functionality for example for bootloader operation. The Firmware_Version and Firmware_Revision define version information of the Firmware_Variant that is currently active. The Firmware_Build defines an additional counter for incremental builds.

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
  • [out] p_return: Extra return parameters.

Return Value
  • 0: if success.

uint8_t hci_vs_cmd_zephyr_read_supported_commands(hci_vs_cmd_zephyr_read_supported_commands_return_t *p_return)

Zephyr Read Supported Commands.

This command reads the list of vendor commands supported for the local Controller.

This command shall return the Supported_Commands configuration parameter. It is implied that if a command is listed as supported, the feature underlying that command is also supported.

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
  • [out] p_return: Extra return parameters.

Return Value
  • 0: if success.

uint8_t hci_vs_cmd_zephyr_write_bd_addr(const hci_vs_cmd_zephyr_write_bd_addr_t *p_params)

Zephyr Write BD ADDR.

This command writes the BD_ADDR (Bluetooth public device address) value to the volatile memory. The address does not change during an HCI Reset but is reset during a System Reset. The address can be read out using the Read_BD_ADDR command.

When the Write_BD_ADDR command has completed, a Command Complete event shall be generated.

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_zephyr_read_static_addresses(hci_vs_cmd_zephyr_read_static_addresses_return_t *p_return)

Zephyr Read Static Addresses.

This commands reads the controller specific static addresses.

This command shall return the static addresses programmed by the vendor at manufacturing time.

Each returned static address shall confirm to the Static Device Address definition. The two most significant bits of the address shall be equal to 1. At least one bit of the random part of the address shall be 0. At least one bit of the random part of the address shall be 1.

The Identity_Root parameter may be all zeros to indicate no identity root key being available for a given static address. The identity root key returned from Read_Key_Hierarchy_Roots command shall not be returned from this command.

Note: If no public address is provided and a static address is available, then it is recommended to return an identity root key (if available) from this command. In case a public address is provided, then it is recommended to use the Read_Key_Hierarchy_Roots command to return the identity root key (if only one is available).

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
  • [out] p_return: Extra return parameters.

Return Value
  • 0: if success.

uint8_t hci_vs_cmd_zephyr_write_tx_power(const hci_vs_cmd_zephyr_write_tx_power_t *p_params, hci_vs_cmd_zephyr_write_tx_power_return_t *p_return)

Zephyr Write Tx Power Level (per Role/Connection).

This command dynamically modifies BLE Tx power level given a handle and a handle type (advertiser, scanner, connection).

The Tx power of the BLE radio interface is modified for any low-level link by the controller with a high degree of flexibility. The BLE link whose power is set is identified based on a handle type (advertiser, scanner, connection) and handle pair.

The role/state defining input parameter is the Handle_Type, whereas its corresponding handle is provided by the Handle input parameter. Note that for Advertisements, the Handle input parameter is ignored in the case that Advertising Extensions are not configured, whereas Advertising Sets are to be identified by their corresponding Handle in case Advertising Extensions are enabled.

The desired transmitter power level for the selected link instance is inputted as Tx_Power_Level. The power setup and control can be performed dynamically without the need of restarting the advertiser and scanner role/states. In case of connections, the Tx power changes take effect only if the connections are in a connected state.

The inputs Handle_Type and Handle are passed through as outputs to aid the asynchronous service of the command as well. In addition, the command returns also with the Selected_Tx_Power by the controller which addresses and corrects the possible mismatches between the desired Tx_Power_Level and the achievable Tx powers given each individual controller capabilities.

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.

  • [out] p_return: Extra return parameters.

Return Value
  • 0: if success.

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 hci_vs_cmd_event_length_set(). 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_subevent_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.

uint8_t hci_vs_cmd_event_length_set(const hci_vs_cmd_event_length_set_t *p_params)

Set event length for connections.

Set the event length for new connections. This API must be called before starting a connectable advertiser or starting an initiator for the event length to applied to the connection once established.

The BLE controller will ensure that the anchor points of master link connections are spaced event_length_us apart.

The default event length is BLE_CONTROLLER_DEFAULT_EVENT_LENGTH_US.

See also hci_vs_cmd_conn_event_extend().

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.

Bluetooth LE 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