API documentation

SoftDevice Controller
- Memory requirement defines
SoftDevice Controller HCI
SoftDevice Controller HCI VS
SoftDevice Controller SoC

SoftDevice Controller 

group sdc

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

Defines

SDC_DEFAULT_RESOURCE_CFG_TAG: Default resource configuration tag.

SDC_DEFAULT_ADV_COUNT: Default maximum number of concurrent advertisers.

SDC_DEFAULT_PERIODIC_ADV_COUNT: Default maximum number of concurrent periodic advertisers.

SDC_DEFAULT_PERIODIC_SYNC_COUNT: Default maximum number of concurrent synchronizations to periodic advertisers.

SDC_DEFAULT_SLAVE_COUNT: Default maximum number of concurrent slave links.

SDC_DEFAULT_MASTER_COUNT: Default maximum number of concurrent master links.

SDC_DEFAULT_TX_PACKET_SIZE: Default maximum Link Layer TX packet size.

SDC_DEFAULT_RX_PACKET_SIZE: Default maximum Link Layer RX packet size.

SDC_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.

SDC_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.

SDC_DEFAULT_SCAN_BUFFER_COUNT

Default maximum number of advertising reports available in the scanner.

The default buffer configuration allows the scanner to continue scanning with a pending advertising and scan response report.

SDC_DEFAULT_PERIODIC_SYNC_BUFFER_COUNT: Default maximum number of periodic advertising reports available.

SDC_DEFAULT_ADV_BUF_SIZE: Default advertising data size when legacy advertising is supported.

SDC_DEFAULT_PERIODIC_ADV_LIST_SIZE: Default number of devices that can be added to the periodic advertiser list.

SDC_DEFAULT_EVENT_LENGTH_US: Default connection event length.

SDC_BUILD_REVISION_SIZE: Size of build revision array in bytes.

Typedefs

typedef void (*sdc_fault_handler_t)(const char *file, const uint32_t line)

Function prototype for the fault handler.

Note

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

Param file: [in] The filename where the assertion occurred.
Param line: [in] The line number where the assertion occurred.

typedef void (*sdc_callback_t)(void)

Function prototype for the SoftDevice Controller callback.

The SoftDevice 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

SDC_MEM_PER_MASTER_LINK(tx_size, rx_size, tx_count, rx_count)

Maximum memory required per master link.

Parameters

tx_size – [in] Link Layer TX packet size.
rx_size – [in] Link Layer RX packet size.
tx_count – [in] Link Layer TX packet count.
rx_count – [in] Link Layer RX packet count.

SDC_MEM_PER_SLAVE_LINK(tx_size, rx_size, tx_count, rx_count)

Maximum memory required per slave link.

Parameters

tx_size – [in] Link Layer TX packet size.
rx_size – [in] Link Layer RX packet size.
tx_count – [in] Link Layer TX packet count.
rx_count – [in] Link Layer RX packet count.

SDC_MEM_MASTER_LINKS_SHARED: Maximum shared memory required for master links.

SDC_MEM_SLAVE_LINKS_SHARED: Maximum shared memory required for slave links.

SDC_MEM_SCAN_BUFFER(buffer_count): Memory required for scanner buffers when only supporting legacy scanning.

SDC_MEM_SCAN_BUFFER_EXT(buffer_count): Memory required for scanner buffers when supporting extended scanning.

SDC_MEM_PER_ADV_SET(max_adv_data)

Maximum required memory for a given advertising buffer size.

Parameters

max_adv_data – [in] The desired advertising data size.

SDC_MEM_PER_PERIODIC_ADV_SET(max_adv_data)

Additional memory required for periodic advertising, if configured.

Note

The max_adv_data must be the same as for advertising in SDC_MEM_PER_ADV_SET.

Parameters

max_adv_data – [in] The desired periodic advertising data size.

SDC_MEM_PER_PERIODIC_SYNC(buffer_count)

Memory required per periodic sync

Parameters

buffer_count – [in] The number of periodic synchronization receive buffers.

SDC_MEM_PERIODIC_ADV_LIST(list_size)

Memory required for the periodic adv list.

Parameters

list_size – [in] The number of entries the list can fit.

SoftDevice Controller HCI 

group sdc_hci

The SoftDevice Controller HCI APIs are used to send HCI commands/data and receive events/data to and from the SoftDevice 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 sdc_hci_cmd_put(uint8_t const *p_cmd_in)

Send an HCI command packet to the SoftDevice Controller.

Parameters

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

Return values

0 – Success
-NRF_EINVAL – Invalid input

int32_t sdc_hci_data_put(uint8_t const *p_data_in)

Send an HCI data packet to the SoftDevice Controller.

Parameters

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

Return values

0 – Success
-NRF_EINVAL – Invalid input

int32_t sdc_hci_evt_get(uint8_t *p_evt_out)

Retrieve an HCI event packet from the SoftDevice 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

p_evt_out – [inout] 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 values

0 – Success
-NRF_EAGAIN – No event available
-NRF_EINVAL – Invalid input

int32_t sdc_hci_data_get(uint8_t *p_data_out)

Retrieve an HCI data packet from the SoftDevice 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

p_data_out – [inout] 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 values

0 – Success
-NRF_EAGAIN – No data available
-NRF_EINVAL – Invalid input

SoftDevice Controller HCI VS 

group sdc_hci_vs: The SoftDevice Controller VS HCI APIs define additional functionality provided by the SoftDevice 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 sdc_hci_opcode_cb

HCI CB OpCode Field values.

Values:

enumerator SDC_HCI_OPCODE_CMD_CB_SET_EVENT_MASK: See sdc_hci_cmd_cb_set_event_mask().

enumerator SDC_HCI_OPCODE_CMD_CB_RESET: See sdc_hci_cmd_cb_reset().

enumerator SDC_HCI_OPCODE_CMD_CB_READ_TRANSMIT_POWER_LEVEL: See sdc_hci_cmd_cb_read_transmit_power_level().

enumerator SDC_HCI_OPCODE_CMD_CB_SET_CONTROLLER_TO_HOST_FLOW_CONTROL: See sdc_hci_cmd_cb_set_controller_to_host_flow_control().

enumerator SDC_HCI_OPCODE_CMD_CB_HOST_BUFFER_SIZE: See sdc_hci_cmd_cb_host_buffer_size().

enumerator SDC_HCI_OPCODE_CMD_CB_HOST_NUMBER_OF_COMPLETED_PACKETS: See sdc_hci_cmd_cb_host_number_of_completed_packets().

enumerator SDC_HCI_OPCODE_CMD_CB_SET_EVENT_MASK_PAGE_2: See sdc_hci_cmd_cb_set_event_mask_page_2().

enumerator SDC_HCI_OPCODE_CMD_CB_READ_AUTHENTICATED_PAYLOAD_TIMEOUT: See sdc_hci_cmd_cb_read_authenticated_payload_timeout().

enumerator SDC_HCI_OPCODE_CMD_CB_WRITE_AUTHENTICATED_PAYLOAD_TIMEOUT: See sdc_hci_cmd_cb_write_authenticated_payload_timeout().

enum sdc_hci_opcode_ip

HCI IP OpCode Field values.

Values:

enumerator SDC_HCI_OPCODE_CMD_IP_READ_LOCAL_VERSION_INFORMATION: See sdc_hci_cmd_ip_read_local_version_information().

enumerator SDC_HCI_OPCODE_CMD_IP_READ_LOCAL_SUPPORTED_COMMANDS: See sdc_hci_cmd_ip_read_local_supported_commands().

enumerator SDC_HCI_OPCODE_CMD_IP_READ_LOCAL_SUPPORTED_FEATURES: See sdc_hci_cmd_ip_read_local_supported_features().

enumerator SDC_HCI_OPCODE_CMD_IP_READ_BD_ADDR: See sdc_hci_cmd_ip_read_bd_addr().

enum sdc_hci_opcode_le

HCI LE OpCode Field values.

Values:

enumerator SDC_HCI_OPCODE_CMD_LE_SET_EVENT_MASK: See sdc_hci_cmd_le_set_event_mask().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_BUFFER_SIZE: See sdc_hci_cmd_le_read_buffer_size().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_LOCAL_SUPPORTED_FEATURES: See sdc_hci_cmd_le_read_local_supported_features().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_RANDOM_ADDRESS: See sdc_hci_cmd_le_set_random_address().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_ADV_PARAMS: See sdc_hci_cmd_le_set_adv_params().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_ADV_PHYSICAL_CHANNEL_TX_POWER: See sdc_hci_cmd_le_read_adv_physical_channel_tx_power().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_ADV_DATA: See sdc_hci_cmd_le_set_adv_data().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_SCAN_RESPONSE_DATA: See sdc_hci_cmd_le_set_scan_response_data().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_ADV_ENABLE: See sdc_hci_cmd_le_set_adv_enable().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_SCAN_PARAMS: See sdc_hci_cmd_le_set_scan_params().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_SCAN_ENABLE: See sdc_hci_cmd_le_set_scan_enable().

enumerator SDC_HCI_OPCODE_CMD_LE_CREATE_CONN: See sdc_hci_cmd_le_create_conn().

enumerator SDC_HCI_OPCODE_CMD_LE_CREATE_CONN_CANCEL: See sdc_hci_cmd_le_create_conn_cancel().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_WHITE_LIST_SIZE: See sdc_hci_cmd_le_read_white_list_size().

enumerator SDC_HCI_OPCODE_CMD_LE_CLEAR_WHITE_LIST: See sdc_hci_cmd_le_clear_white_list().

enumerator SDC_HCI_OPCODE_CMD_LE_ADD_DEVICE_TO_WHITE_LIST: See sdc_hci_cmd_le_add_device_to_white_list().

enumerator SDC_HCI_OPCODE_CMD_LE_REMOVE_DEVICE_FROM_WHITE_LIST: See sdc_hci_cmd_le_remove_device_from_white_list().

enumerator SDC_HCI_OPCODE_CMD_LE_CONN_UPDATE: See sdc_hci_cmd_le_conn_update().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_HOST_CHANNEL_CLASSIFICATION: See sdc_hci_cmd_le_set_host_channel_classification().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_CHANNEL_MAP: See sdc_hci_cmd_le_read_channel_map().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_REMOTE_FEATURES: See sdc_hci_cmd_le_read_remote_features().

enumerator SDC_HCI_OPCODE_CMD_LE_ENCRYPT: See sdc_hci_cmd_le_encrypt().

enumerator SDC_HCI_OPCODE_CMD_LE_RAND: See sdc_hci_cmd_le_rand().

enumerator SDC_HCI_OPCODE_CMD_LE_ENABLE_ENCRYPTION: See sdc_hci_cmd_le_enable_encryption().

enumerator SDC_HCI_OPCODE_CMD_LE_LONG_TERM_KEY_REQUEST_REPLY: See sdc_hci_cmd_le_long_term_key_request_reply().

enumerator SDC_HCI_OPCODE_CMD_LE_LONG_TERM_KEY_REQUEST_NEGATIVE_REPLY: See sdc_hci_cmd_le_long_term_key_request_negative_reply().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_SUPPORTED_STATES: See sdc_hci_cmd_le_read_supported_states().

enumerator SDC_HCI_OPCODE_CMD_LE_TEST_END: See sdc_hci_cmd_le_test_end().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_DATA_LENGTH: See sdc_hci_cmd_le_set_data_length().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH: See sdc_hci_cmd_le_read_suggested_default_data_length().

enumerator SDC_HCI_OPCODE_CMD_LE_WRITE_SUGGESTED_DEFAULT_DATA_LENGTH: See sdc_hci_cmd_le_write_suggested_default_data_length().

enumerator SDC_HCI_OPCODE_CMD_LE_ADD_DEVICE_TO_RESOLVING_LIST: See sdc_hci_cmd_le_add_device_to_resolving_list().

enumerator SDC_HCI_OPCODE_CMD_LE_REMOVE_DEVICE_FROM_RESOLVING_LIST: See sdc_hci_cmd_le_remove_device_from_resolving_list().

enumerator SDC_HCI_OPCODE_CMD_LE_CLEAR_RESOLVING_LIST: See sdc_hci_cmd_le_clear_resolving_list().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_RESOLVING_LIST_SIZE: See sdc_hci_cmd_le_read_resolving_list_size().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_ADDRESS_RESOLUTION_ENABLE: See sdc_hci_cmd_le_set_address_resolution_enable().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_RESOLVABLE_PRIVATE_ADDRESS_TIMEOUT: See sdc_hci_cmd_le_set_resolvable_private_address_timeout().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_MAX_DATA_LENGTH: See sdc_hci_cmd_le_read_max_data_length().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_PHY: See sdc_hci_cmd_le_read_phy().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_DEFAULT_PHY: See sdc_hci_cmd_le_set_default_phy().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_PHY: See sdc_hci_cmd_le_set_phy().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_ADV_SET_RANDOM_ADDRESS: See sdc_hci_cmd_le_set_adv_set_random_address().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_EXT_ADV_PARAMS: See sdc_hci_cmd_le_set_ext_adv_params().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_EXT_ADV_DATA: See sdc_hci_cmd_le_set_ext_adv_data().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_EXT_SCAN_RESPONSE_DATA: See sdc_hci_cmd_le_set_ext_scan_response_data().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_EXT_ADV_ENABLE: See sdc_hci_cmd_le_set_ext_adv_enable().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_MAX_ADV_DATA_LENGTH: See sdc_hci_cmd_le_read_max_adv_data_length().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_NUMBER_OF_SUPPORTED_ADV_SETS: See sdc_hci_cmd_le_read_number_of_supported_adv_sets().

enumerator SDC_HCI_OPCODE_CMD_LE_REMOVE_ADV_SET: See sdc_hci_cmd_le_remove_adv_set().

enumerator SDC_HCI_OPCODE_CMD_LE_CLEAR_ADV_SETS: See sdc_hci_cmd_le_clear_adv_sets().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_PERIODIC_ADV_PARAMS: See sdc_hci_cmd_le_set_periodic_adv_params().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_PERIODIC_ADV_DATA: See sdc_hci_cmd_le_set_periodic_adv_data().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_PERIODIC_ADV_ENABLE: See sdc_hci_cmd_le_set_periodic_adv_enable().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_EXT_SCAN_PARAMS: See sdc_hci_cmd_le_set_ext_scan_params().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_EXT_SCAN_ENABLE: See sdc_hci_cmd_le_set_ext_scan_enable().

enumerator SDC_HCI_OPCODE_CMD_LE_EXT_CREATE_CONN: See sdc_hci_cmd_le_ext_create_conn().

enumerator SDC_HCI_OPCODE_CMD_LE_PERIODIC_ADV_CREATE_SYNC: See sdc_hci_cmd_le_periodic_adv_create_sync().

enumerator SDC_HCI_OPCODE_CMD_LE_PERIODIC_ADV_CREATE_SYNC_CANCEL: See sdc_hci_cmd_le_periodic_adv_create_sync_cancel().

enumerator SDC_HCI_OPCODE_CMD_LE_PERIODIC_ADV_TERMINATE_SYNC: See sdc_hci_cmd_le_periodic_adv_terminate_sync().

enumerator SDC_HCI_OPCODE_CMD_LE_ADD_DEVICE_TO_PERIODIC_ADV_LIST: See sdc_hci_cmd_le_add_device_to_periodic_adv_list().

enumerator SDC_HCI_OPCODE_CMD_LE_REMOVE_DEVICE_FROM_PERIODIC_ADV_LIST: See sdc_hci_cmd_le_remove_device_from_periodic_adv_list().

enumerator SDC_HCI_OPCODE_CMD_LE_CLEAR_PERIODIC_ADV_LIST: See sdc_hci_cmd_le_clear_periodic_adv_list().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_PERIODIC_ADV_LIST_SIZE: See sdc_hci_cmd_le_read_periodic_adv_list_size().

enumerator SDC_HCI_OPCODE_CMD_LE_READ_TRANSMIT_POWER: See sdc_hci_cmd_le_read_transmit_power().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_PRIVACY_MODE: See sdc_hci_cmd_le_set_privacy_mode().

enumerator SDC_HCI_OPCODE_CMD_LE_SET_PERIODIC_ADV_RECEIVE_ENABLE: See sdc_hci_cmd_le_set_periodic_adv_receive_enable().

enum sdc_hci_opcode_lc

HCI LC OpCode Field values.

Values:

enumerator SDC_HCI_OPCODE_CMD_LC_DISCONNECT: See sdc_hci_cmd_lc_disconnect().

enumerator SDC_HCI_OPCODE_CMD_LC_READ_REMOTE_VERSION_INFORMATION: See sdc_hci_cmd_lc_read_remote_version_information().

enum sdc_hci_opcode_sp

HCI SP OpCode Field values.

Values:

enumerator SDC_HCI_OPCODE_CMD_SP_READ_RSSI: See sdc_hci_cmd_sp_read_rssi().

enum sdc_hci_opcode_vs

HCI VS OpCode Field values.

Values:

enumerator SDC_HCI_OPCODE_CMD_VS_ZEPHYR_READ_VERSION_INFO: See sdc_hci_cmd_vs_zephyr_read_version_info().

enumerator SDC_HCI_OPCODE_CMD_VS_ZEPHYR_READ_SUPPORTED_COMMANDS: See sdc_hci_cmd_vs_zephyr_read_supported_commands().

enumerator SDC_HCI_OPCODE_CMD_VS_ZEPHYR_WRITE_BD_ADDR: See sdc_hci_cmd_vs_zephyr_write_bd_addr().

enumerator SDC_HCI_OPCODE_CMD_VS_ZEPHYR_READ_STATIC_ADDRESSES: See sdc_hci_cmd_vs_zephyr_read_static_addresses().

enumerator SDC_HCI_OPCODE_CMD_VS_ZEPHYR_READ_KEY_HIERARCHY_ROOTS: See sdc_hci_cmd_vs_zephyr_read_key_hierarchy_roots().

enumerator SDC_HCI_OPCODE_CMD_VS_ZEPHYR_READ_CHIP_TEMP: See sdc_hci_cmd_vs_zephyr_read_chip_temp().

enumerator SDC_HCI_OPCODE_CMD_VS_ZEPHYR_WRITE_TX_POWER: See sdc_hci_cmd_vs_zephyr_write_tx_power().

enumerator SDC_HCI_OPCODE_CMD_VS_ZEPHYR_READ_TX_POWER: See sdc_hci_cmd_vs_zephyr_read_tx_power().

enumerator SDC_HCI_OPCODE_CMD_VS_READ_SUPPORTED_VS_COMMANDS: See sdc_hci_cmd_vs_read_supported_vs_commands().

enumerator SDC_HCI_OPCODE_CMD_VS_LLPM_MODE_SET: See sdc_hci_cmd_vs_llpm_mode_set().

enumerator SDC_HCI_OPCODE_CMD_VS_CONN_UPDATE: See sdc_hci_cmd_vs_conn_update().

enumerator SDC_HCI_OPCODE_CMD_VS_CONN_EVENT_EXTEND: See sdc_hci_cmd_vs_conn_event_extend().

enumerator SDC_HCI_OPCODE_CMD_VS_QOS_CONN_EVENT_REPORT_ENABLE: See sdc_hci_cmd_vs_qos_conn_event_report_enable().

enumerator SDC_HCI_OPCODE_CMD_VS_EVENT_LENGTH_SET: See sdc_hci_cmd_vs_event_length_set().

enumerator SDC_HCI_OPCODE_CMD_VS_PERIODIC_ADV_EVENT_LENGTH_SET: See sdc_hci_cmd_vs_periodic_adv_event_length_set().

enum sdc_hci_subevent_vs

VS subevent Code values.

Values:

enumerator SDC_HCI_SUBEVENT_VS_QOS_CONN_EVENT_REPORT: See sdc_hci_subevent_vs_qos_conn_event_report_t.

enum sdc_hci_vs_tx_power_handle_type

TX power handle type.

Values:

enumerator SDC_HCI_VS_TX_POWER_HANDLE_TYPE_ADV: Handle of type Advertiser.

enumerator SDC_HCI_VS_TX_POWER_HANDLE_TYPE_SCAN_INIT: Handle of type Scanner or Initiator.

enumerator SDC_HCI_VS_TX_POWER_HANDLE_TYPE_CONN: Handle of type Connection.

struct sdc_hci_cb_event_mask_t

#include <sdc_hci_cmd_controller_baseband.h>

Event Mask.

If the bit in the Event_Mask is set to a one, then the event associated with that bit will be enabled.

struct sdc_hci_cb_event_mask_page_2_t

#include <sdc_hci_cmd_controller_baseband.h>

Event mask page 2.

If the bit in the Event_Mask is set to a one, then the event associated with that bit will be enabled.

struct sdc_hci_cb_host_number_of_completed_packets_array_params_t: #include <sdc_hci_cmd_controller_baseband.h>

Host Number Of Completed Packets array parameters.

struct sdc_hci_ip_lmp_features_t

#include <sdc_hci_cmd_info_params.h>

LMP features.

See Core_v5.2, Vol 2, Part C, Section 3.3

struct sdc_hci_ip_supported_commands_t

#include <sdc_hci_cmd_info_params.h>

Supported HCI commands.

See Core_v5.2, Vol 4, Part E, Section 6.27

struct sdc_hci_le_ext_create_conn_array_params_t: #include <sdc_hci_cmd_le.h>

LE Extended Create Connection array parameters.

struct sdc_hci_le_le_event_mask_t

#include <sdc_hci_cmd_le.h>

LE event mask.

If the bit in the Event_Mask is set to a one, then the event associated with that bit will be enabled.

struct sdc_hci_le_le_features_t

#include <sdc_hci_cmd_le.h>

LE features.

See Core_v5.2, Vol 6, Part B, Section 4.6

struct sdc_hci_le_set_ext_adv_enable_array_params_t: #include <sdc_hci_cmd_le.h>

LE Set Extended Advertising Enable array parameters.

struct sdc_hci_le_set_ext_scan_params_array_params_t: #include <sdc_hci_cmd_le.h>

LE Set Extended Scan Parameters array parameters.

struct sdc_hci_vs_supported_vs_commands_t: #include <sdc_hci_vs.h>

Supported Vendor Specific HCI Commands.

struct sdc_hci_vs_zephyr_static_address_t

#include <sdc_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 sdc_hci_vs_zephyr_supported_commands_t

#include <sdc_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: Read Version Information.

uint8_t read_supported_commands: Read Supported Commands.

uint8_t read_supported_features: Read Supported Features.

uint8_t set_event_mask: Set Event Mask.

uint8_t reset: Reset.

uint8_t write_bd_addr: Write BD_ADDR.

uint8_t set_trace_enable: Set Trace Enable.

uint8_t read_build_info: Read Build Information.

uint8_t read_static_addresses: Read Static Addresses.

uint8_t read_key_hierarchy_roots: Read Key Hierarchy Roots.

uint8_t read_chip_temperature: Read Chip Temperature.

uint8_t read_host_stack_commands: Read Host Stack Commands.

uint8_t set_scan_request_reports: Set Scan Request Reports.

uint8_t write_tx_power_level: Write Tx Power Level (per Role/Connection).

uint8_t read_tx_power_level: Read Tx Power Level (per Role/Connection).

HCI Events 

group HCI_EVENTS

struct sdc_hci_subevent_vs_qos_conn_event_report_t

#include <sdc_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

union sdc_hci_cmd_cb_set_event_mask_t

#include <sdc_hci_cmd_controller_baseband.h>

Set Event Mask command parameter(s).

Public Members

sdc_hci_cb_event_mask_t params

uint8_t raw[8]

struct sdc_hci_cmd_cb_read_transmit_power_level_t: #include <sdc_hci_cmd_controller_baseband.h>

Read Transmit Power Level command parameter(s).

struct sdc_hci_cmd_cb_read_transmit_power_level_return_t: #include <sdc_hci_cmd_controller_baseband.h>

Read Transmit Power Level return parameter(s).

struct sdc_hci_cmd_cb_set_controller_to_host_flow_control_t: #include <sdc_hci_cmd_controller_baseband.h>

Set Controller To Host Flow Control command parameter(s).

struct sdc_hci_cmd_cb_host_buffer_size_t: #include <sdc_hci_cmd_controller_baseband.h>

Host Buffer Size command parameter(s).

struct sdc_hci_cmd_cb_host_number_of_completed_packets_t: #include <sdc_hci_cmd_controller_baseband.h>

Host Number Of Completed Packets command parameter(s).

union sdc_hci_cmd_cb_set_event_mask_page_2_t

#include <sdc_hci_cmd_controller_baseband.h>

Set Event Mask Page 2 command parameter(s).

Public Members

sdc_hci_cb_event_mask_page_2_t params

uint8_t raw[8]

struct sdc_hci_cmd_cb_read_authenticated_payload_timeout_t: #include <sdc_hci_cmd_controller_baseband.h>

Read Authenticated Payload Timeout command parameter(s).

struct sdc_hci_cmd_cb_read_authenticated_payload_timeout_return_t: #include <sdc_hci_cmd_controller_baseband.h>

Read Authenticated Payload Timeout return parameter(s).

struct sdc_hci_cmd_cb_write_authenticated_payload_timeout_t: #include <sdc_hci_cmd_controller_baseband.h>

Write Authenticated Payload Timeout command parameter(s).

struct sdc_hci_cmd_cb_write_authenticated_payload_timeout_return_t: #include <sdc_hci_cmd_controller_baseband.h>

Write Authenticated Payload Timeout return parameter(s).

struct sdc_hci_cmd_ip_read_local_version_information_return_t: #include <sdc_hci_cmd_info_params.h>

Read Local Version Information return parameter(s).

union sdc_hci_cmd_ip_read_local_supported_commands_return_t

#include <sdc_hci_cmd_info_params.h>

Read Local Supported Commands return parameter(s).

Public Members

sdc_hci_ip_supported_commands_t params

uint8_t raw[64]

union sdc_hci_cmd_ip_read_local_supported_features_return_t

#include <sdc_hci_cmd_info_params.h>

Read Local Supported Features return parameter(s).

Public Members

sdc_hci_ip_lmp_features_t params

uint8_t raw[8]

struct sdc_hci_cmd_ip_read_bd_addr_return_t: #include <sdc_hci_cmd_info_params.h>

Read BD_ADDR return parameter(s).

union sdc_hci_cmd_le_set_event_mask_t

#include <sdc_hci_cmd_le.h>

LE Set Event Mask command parameter(s).

Public Members

sdc_hci_le_le_event_mask_t params

uint8_t raw[8]

struct sdc_hci_cmd_le_read_buffer_size_return_t: #include <sdc_hci_cmd_le.h>

LE Read Buffer Size [v1] return parameter(s).

union sdc_hci_cmd_le_read_local_supported_features_return_t

#include <sdc_hci_cmd_le.h>

LE Read Local Supported Features return parameter(s).

Public Members

sdc_hci_le_le_features_t params

uint8_t raw[8]

struct sdc_hci_cmd_le_set_random_address_t: #include <sdc_hci_cmd_le.h>

LE Set Random Address command parameter(s).

struct sdc_hci_cmd_le_set_adv_params_t: #include <sdc_hci_cmd_le.h>

LE Set Advertising Parameters command parameter(s).

struct sdc_hci_cmd_le_read_adv_physical_channel_tx_power_return_t: #include <sdc_hci_cmd_le.h>

LE Read Advertising Physical Channel Tx Power return parameter(s).

struct sdc_hci_cmd_le_set_adv_data_t: #include <sdc_hci_cmd_le.h>

LE Set Advertising Data command parameter(s).

struct sdc_hci_cmd_le_set_scan_response_data_t: #include <sdc_hci_cmd_le.h>

LE Set Scan Response Data command parameter(s).

struct sdc_hci_cmd_le_set_adv_enable_t: #include <sdc_hci_cmd_le.h>

LE Set Advertising Enable command parameter(s).

struct sdc_hci_cmd_le_set_scan_params_t: #include <sdc_hci_cmd_le.h>

LE Set Scan Parameters command parameter(s).

struct sdc_hci_cmd_le_set_scan_enable_t: #include <sdc_hci_cmd_le.h>

LE Set Scan Enable command parameter(s).

struct sdc_hci_cmd_le_create_conn_t: #include <sdc_hci_cmd_le.h>

LE Create Connection command parameter(s).

struct sdc_hci_cmd_le_read_white_list_size_return_t: #include <sdc_hci_cmd_le.h>

LE Read White List Size return parameter(s).

struct sdc_hci_cmd_le_add_device_to_white_list_t: #include <sdc_hci_cmd_le.h>

LE Add Device To White List command parameter(s).

struct sdc_hci_cmd_le_remove_device_from_white_list_t: #include <sdc_hci_cmd_le.h>

LE Remove Device From White List command parameter(s).

struct sdc_hci_cmd_le_conn_update_t: #include <sdc_hci_cmd_le.h>

LE Connection Update command parameter(s).

struct sdc_hci_cmd_le_set_host_channel_classification_t: #include <sdc_hci_cmd_le.h>

LE Set Host Channel Classification command parameter(s).

struct sdc_hci_cmd_le_read_channel_map_t: #include <sdc_hci_cmd_le.h>

LE Read Channel Map command parameter(s).

struct sdc_hci_cmd_le_read_channel_map_return_t: #include <sdc_hci_cmd_le.h>

LE Read Channel Map return parameter(s).

struct sdc_hci_cmd_le_read_remote_features_t: #include <sdc_hci_cmd_le.h>

LE Read Remote Features command parameter(s).

struct sdc_hci_cmd_le_encrypt_t: #include <sdc_hci_cmd_le.h>

LE Encrypt command parameter(s).

struct sdc_hci_cmd_le_encrypt_return_t: #include <sdc_hci_cmd_le.h>

LE Encrypt return parameter(s).

struct sdc_hci_cmd_le_rand_return_t: #include <sdc_hci_cmd_le.h>

LE Rand return parameter(s).

struct sdc_hci_cmd_le_enable_encryption_t: #include <sdc_hci_cmd_le.h>

LE Enable Encryption command parameter(s).

struct sdc_hci_cmd_le_long_term_key_request_reply_t: #include <sdc_hci_cmd_le.h>

LE Long Term Key Request Reply command parameter(s).

struct sdc_hci_cmd_le_long_term_key_request_reply_return_t: #include <sdc_hci_cmd_le.h>

LE Long Term Key Request Reply return parameter(s).

struct sdc_hci_cmd_le_long_term_key_request_negative_reply_t: #include <sdc_hci_cmd_le.h>

LE Long Term Key Request Negative Reply command parameter(s).

struct sdc_hci_cmd_le_long_term_key_request_negative_reply_return_t: #include <sdc_hci_cmd_le.h>

LE Long Term Key Request Negative Reply return parameter(s).

struct sdc_hci_cmd_le_read_supported_states_return_t

#include <sdc_hci_cmd_le.h>

LE Read Supported States return parameter(s).

Public Members

uint8_t le_states[8]: See the table in Core_v5.2, Vol 4, Part E, Section 7.8.27.

struct sdc_hci_cmd_le_test_end_return_t: #include <sdc_hci_cmd_le.h>

LE Test End return parameter(s).

struct sdc_hci_cmd_le_set_data_length_t: #include <sdc_hci_cmd_le.h>

LE Set Data Length command parameter(s).

struct sdc_hci_cmd_le_set_data_length_return_t: #include <sdc_hci_cmd_le.h>

LE Set Data Length return parameter(s).

struct sdc_hci_cmd_le_read_suggested_default_data_length_return_t: #include <sdc_hci_cmd_le.h>

LE Read Suggested Default Data Length return parameter(s).

struct sdc_hci_cmd_le_write_suggested_default_data_length_t: #include <sdc_hci_cmd_le.h>

LE Write Suggested Default Data Length command parameter(s).

struct sdc_hci_cmd_le_add_device_to_resolving_list_t: #include <sdc_hci_cmd_le.h>

LE Add Device To Resolving List command parameter(s).

struct sdc_hci_cmd_le_remove_device_from_resolving_list_t: #include <sdc_hci_cmd_le.h>

LE Remove Device From Resolving List command parameter(s).

struct sdc_hci_cmd_le_read_resolving_list_size_return_t: #include <sdc_hci_cmd_le.h>

LE Read Resolving List Size return parameter(s).

struct sdc_hci_cmd_le_set_address_resolution_enable_t: #include <sdc_hci_cmd_le.h>

LE Set Address Resolution Enable command parameter(s).

struct sdc_hci_cmd_le_set_resolvable_private_address_timeout_t: #include <sdc_hci_cmd_le.h>

LE Set Resolvable Private Address Timeout command parameter(s).

struct sdc_hci_cmd_le_read_max_data_length_return_t: #include <sdc_hci_cmd_le.h>

LE Read Maximum Data Length return parameter(s).

struct sdc_hci_cmd_le_read_phy_t: #include <sdc_hci_cmd_le.h>

LE Read PHY command parameter(s).

struct sdc_hci_cmd_le_read_phy_return_t: #include <sdc_hci_cmd_le.h>

LE Read PHY return parameter(s).

struct sdc_hci_cmd_le_set_default_phy_t: #include <sdc_hci_cmd_le.h>

LE Set Default PHY command parameter(s).

struct sdc_hci_cmd_le_set_phy_t: #include <sdc_hci_cmd_le.h>

LE Set PHY command parameter(s).

struct sdc_hci_cmd_le_set_adv_set_random_address_t: #include <sdc_hci_cmd_le.h>

LE Set Advertising Set Random Address command parameter(s).

struct sdc_hci_cmd_le_set_ext_adv_params_t: #include <sdc_hci_cmd_le.h>

LE Set Extended Advertising Parameters command parameter(s).

struct sdc_hci_cmd_le_set_ext_adv_params_return_t: #include <sdc_hci_cmd_le.h>

LE Set Extended Advertising Parameters return parameter(s).

struct sdc_hci_cmd_le_set_ext_adv_data_t

#include <sdc_hci_cmd_le.h>

LE Set Extended Advertising Data command parameter(s).

Public Members

uint8_t adv_data[]: Size: adv_data_length.

struct sdc_hci_cmd_le_set_ext_scan_response_data_t

#include <sdc_hci_cmd_le.h>

LE Set Extended Scan Response Data command parameter(s).

Public Members

uint8_t scan_response_data[]: Size: scan_response_data_length.

struct sdc_hci_cmd_le_set_ext_adv_enable_t: #include <sdc_hci_cmd_le.h>

LE Set Extended Advertising Enable command parameter(s).

struct sdc_hci_cmd_le_read_max_adv_data_length_return_t: #include <sdc_hci_cmd_le.h>

LE Read Maximum Advertising Data Length return parameter(s).

struct sdc_hci_cmd_le_read_number_of_supported_adv_sets_return_t: #include <sdc_hci_cmd_le.h>

LE Read Number of Supported Advertising Sets return parameter(s).

struct sdc_hci_cmd_le_remove_adv_set_t: #include <sdc_hci_cmd_le.h>

LE Remove Advertising Set command parameter(s).

struct sdc_hci_cmd_le_set_periodic_adv_params_t: #include <sdc_hci_cmd_le.h>

LE Set Periodic Advertising Parameters command parameter(s).

struct sdc_hci_cmd_le_set_periodic_adv_data_t

#include <sdc_hci_cmd_le.h>

LE Set Periodic Advertising Data command parameter(s).

Public Members

uint8_t adv_data[]: Size: adv_data_length.

struct sdc_hci_cmd_le_set_periodic_adv_enable_t: #include <sdc_hci_cmd_le.h>

LE Set Periodic Advertising Enable command parameter(s).

struct sdc_hci_cmd_le_set_ext_scan_params_t: #include <sdc_hci_cmd_le.h>

LE Set Extended Scan Parameters command parameter(s).

struct sdc_hci_cmd_le_set_ext_scan_enable_t: #include <sdc_hci_cmd_le.h>

LE Set Extended Scan Enable command parameter(s).

struct sdc_hci_cmd_le_ext_create_conn_t: #include <sdc_hci_cmd_le.h>

LE Extended Create Connection command parameter(s).

struct sdc_hci_cmd_le_periodic_adv_create_sync_t: #include <sdc_hci_cmd_le.h>

LE Periodic Advertising Create Sync command parameter(s).

struct sdc_hci_cmd_le_periodic_adv_terminate_sync_t: #include <sdc_hci_cmd_le.h>

LE Periodic Advertising Terminate Sync command parameter(s).

struct sdc_hci_cmd_le_add_device_to_periodic_adv_list_t: #include <sdc_hci_cmd_le.h>

LE Add Device To Periodic Advertiser List command parameter(s).

struct sdc_hci_cmd_le_remove_device_from_periodic_adv_list_t: #include <sdc_hci_cmd_le.h>

LE Remove Device From Periodic Advertiser List command parameter(s).

struct sdc_hci_cmd_le_read_periodic_adv_list_size_return_t: #include <sdc_hci_cmd_le.h>

LE Read Periodic Advertiser List Size return parameter(s).

struct sdc_hci_cmd_le_read_transmit_power_return_t: #include <sdc_hci_cmd_le.h>

LE Read Transmit Power return parameter(s).

struct sdc_hci_cmd_le_set_privacy_mode_t: #include <sdc_hci_cmd_le.h>

LE Set Privacy Mode command parameter(s).

struct sdc_hci_cmd_le_set_periodic_adv_receive_enable_t: #include <sdc_hci_cmd_le.h>

LE Set Periodic Advertising Receive Enable command parameter(s).

struct sdc_hci_cmd_lc_disconnect_t: #include <sdc_hci_cmd_link_control.h>

Disconnect command parameter(s).

struct sdc_hci_cmd_lc_read_remote_version_information_t: #include <sdc_hci_cmd_link_control.h>

Read Remote Version Information command parameter(s).

struct sdc_hci_cmd_sp_read_rssi_t: #include <sdc_hci_cmd_status_params.h>

Read RSSI command parameter(s).

struct sdc_hci_cmd_sp_read_rssi_return_t: #include <sdc_hci_cmd_status_params.h>

Read RSSI return parameter(s).

struct sdc_hci_cmd_vs_zephyr_read_version_info_return_t

#include <sdc_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 sdc_hci_cmd_vs_zephyr_read_supported_commands_return_t

#include <sdc_hci_vs.h>

Zephyr Read Supported Commands return parameter(s).

Public Members

sdc_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 sdc_hci_cmd_vs_zephyr_write_bd_addr_t

#include <sdc_hci_vs.h>

Zephyr Write BD ADDR command parameter(s).

Public Members

uint8_t bd_addr[6]: BD_ADDR of the Device.

struct sdc_hci_cmd_vs_zephyr_read_static_addresses_return_t

#include <sdc_hci_vs.h>

Zephyr Read Static Addresses return parameter(s).

Public Members

uint8_t num_addresses: Number of static device addresses.

sdc_hci_vs_zephyr_static_address_t addresses[]: Zephyr Static Addresses. The number of addresses is specified in num_addresses.

struct sdc_hci_cmd_vs_zephyr_read_key_hierarchy_roots_return_t

#include <sdc_hci_vs.h>

Zephyr Read KEY Hierarchy Roots return parameter(s).

Public Members

uint8_t ir[16]: Zephyr Identity Root Key.

uint8_t er[16]: Zephyr Encryption Root Key.

struct sdc_hci_cmd_vs_zephyr_read_chip_temp_return_t

#include <sdc_hci_vs.h>

Zephyr Read Chip Temperature return parameter(s).

Public Members

int8_t temp: The measured temperature in degrees Celsius.

struct sdc_hci_cmd_vs_zephyr_write_tx_power_t

#include <sdc_hci_vs.h>

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

Public Members

uint8_t handle_type: Handle type. See sdc_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 sdc_hci_cmd_vs_zephyr_write_tx_power_return_t

#include <sdc_hci_vs.h>

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

Public Members

uint8_t handle_type: Handle type. See sdc_hci_vs_tx_power_handle_type.

uint16_t handle: See sdc_hci_cmd_vs_zephyr_write_tx_power_t.

int8_t selected_tx_power: The selected Tx Power in dBm.

struct sdc_hci_cmd_vs_zephyr_read_tx_power_t

#include <sdc_hci_vs.h>

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

Public Members

uint8_t handle_type: Handle type. See sdc_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.

struct sdc_hci_cmd_vs_zephyr_read_tx_power_return_t

#include <sdc_hci_vs.h>

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

Public Members

uint8_t handle_type: Handle type. See sdc_hci_vs_tx_power_handle_type.

uint16_t handle: See sdc_hci_cmd_vs_zephyr_read_tx_power_t.

int8_t selected_tx_power: The selected Tx Power in dBm.

union sdc_hci_cmd_vs_read_supported_vs_commands_return_t

#include <sdc_hci_vs.h>

Read Supported Vendor Specific Commands return parameter(s).

Public Members

sdc_hci_vs_supported_vs_commands_t params

uint8_t raw[64]

struct sdc_hci_cmd_vs_llpm_mode_set_t

#include <sdc_hci_vs.h>

Set Low Latency Packet Mode command parameter(s).

Public Members

uint8_t enable: Set to 1 to enable LLPM.

struct sdc_hci_cmd_vs_conn_update_t

#include <sdc_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 s.

struct sdc_hci_cmd_vs_conn_event_extend_t

#include <sdc_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 sdc_hci_cmd_vs_qos_conn_event_report_enable_t

#include <sdc_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 sdc_hci_cmd_vs_event_length_set_t

#include <sdc_hci_vs.h>

Set event length for connections command parameter(s).

Public Members

uint32_t event_length_us: Allocated event length in microseconds.

struct sdc_hci_cmd_vs_periodic_adv_event_length_set_t

#include <sdc_hci_vs.h>

Set event length for periodic advertisers command parameter(s).

Public Members

uint32_t event_length_us: Allocated periodic advertising event length in microseconds.

HCI VS API 

group HCI_VS_API

Functions

uint8_t sdc_hci_cmd_cb_set_event_mask(const sdc_hci_cmd_cb_set_event_mask_t *p_params)

Set Event Mask.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.1

The HCI_Set_Event_Mask command is used to control which events are generated by the HCI for the Host. If the bit in the Event_Mask is set to a one, then the event associated with that bit will be enabled. For an LE Controller, the “LE Meta event” bit in the event_Mask shall enable or disable all LE events in the LE Meta event (see Section 7.7.65). The event mask allows the Host to control how much it is interrupted.

The Controller shall ignore those bits which are reserved for future use or represent events which it does not support. If the Host sets any of these bits to 1, the Controller shall act as if they were set to 0.

Event(s) generated (unless masked away): When the HCI_Set_Event_Mask command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_cb_reset(void)

Reset.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.2

The HCI_Reset command will reset the Controller and the Link Manager on the BR/EDR Controller, the PAL on an AMP Controller, or the Link Layer on an LE Controller. If the Controller supports both BR/EDR and LE then the HCI_Reset command shall reset the Link Manager, Baseband and Link Layer. The HCI_Reset command shall not affect the used HCI transport layer since the HCI transport layers may have reset mechanisms of their own. After the reset is completed, the current operational state will be lost, the Controller will enter standby mode and the Controller will automatically revert to the default values for the parameters for which default values are defined in the specification. Note: The HCI_Reset command will not necessarily perform a hardware reset. This is implementation defined. On an AMP Controller, the HCI_Reset command shall reset the service provided at the logical HCI to its initial state, but beyond this the exact effect on the Controller device is implementation defined and should not interrupt the service provided to other protocol stacks. The Host shall not send additional HCI commands before the HCI_Command_Complete event related to the HCI_Reset command has been received.

Event(s) generated (unless masked away): When the reset has been performed, an HCI_Command_Complete event shall be generated.

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

uint8_t sdc_hci_cmd_cb_read_transmit_power_level(const sdc_hci_cmd_cb_read_transmit_power_level_t *p_params, sdc_hci_cmd_cb_read_transmit_power_level_return_t *p_return)

Read Transmit Power Level.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.35

This command reads the values for the TX_Power_Level parameter for the specified Connection_Handle. The Connection_Handle shall be a Connection_Handle for an ACL connection

Event(s) generated (unless masked away): When the HCI_Read_Transmit_Power_Level command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_cb_set_controller_to_host_flow_control(const sdc_hci_cmd_cb_set_controller_to_host_flow_control_t *p_params)

Set Controller To Host Flow Control.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.38

This command is used by the Host to turn flow control on or off for data and/or voice sent in the direction from the Controller to the Host. If flow control is turned off, the Host should not send the HCI_Host_Number_Of_Completed_Packets command. That command will be ignored by the Controller if it is sent by the Host and flow control is off. If flow control is turned on for HCI ACL Data packets and off for HCI Synchronous Data packets, HCI_Host_Number_Of_Completed_Packets commands sent by the Host should only contain Connection_Handles for ACL connections. If flow control is turned off for HCI ACL Data packets and on for HCI Synchronous Data packets, HCI_Host_Number_Of_Completed_Packets commands sent by the Host should only contain Connection_Handles for synchronous connections. If flow control is turned on for HCI ACL Data packets and HCI Synchronous Data packets, the Host will send HCI_Host_Number_Of_Completed_Packets commands both for ACL connections and synchronous connections.

The Flow_Control_Enable parameter shall only be changed if no connections exist.

Event(s) generated (unless masked away): When the HCI_Set_Controller_To_Host_Flow_Control command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_cb_host_buffer_size(const sdc_hci_cmd_cb_host_buffer_size_t *p_params)

Host Buffer Size.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.39

The HCI_Host_Buffer_Size command is used by the Host to notify the Controller about the maximum size of the data portion of HCI ACL and Synchronous Data packets sent from the Controller to the Host. The Controller shall segment the data to be transmitted from the Controller to the Host according to these sizes, so that the HCI Data packets will contain data with up to these sizes. The HCI_Host_Buffer_Size command also notifies the Controller about the total number of HCI ACL and Synchronous Data packets that can be stored in the data buffers of the Host. If flow control from the Controller to the Host is turned off, and the HCI_Host_Buffer_Size command has not been issued by the Host, this means that the Controller will send HCI Data packets to the Host with any lengths the Controller wants to use, and it is assumed that the data buffer sizes of the Host are unlimited. If flow control from the Controller to the Host is turned on, the HCI_Host_Buffer_Size command shall after a power-on or a reset always be sent by the Host before the first HCI_Host_Number_Of_Completed_Packets command is sent.

The Set Controller To Host Flow Control command is used to turn flow control on or off. The Host_ACL_Data_Packet_Length command parameter will be used to determine the size of the L2CAP segments contained in ACL Data packets, which are transferred from the Controller to the Host. The Host_Synchronous_Data_Packet_Length command parameter is used to determine the maximum size of HCI Synchronous Data packets. Both the Host and the Controller shall support command and event packets, where the data portion (excluding header) contained in the packets is 255 octets in size.

The Host_Total_Num_ACL_Data_Packets command parameter contains the total number of HCI ACL Data packets that can be stored in the data buffers of the Host. The Controller will determine how the buffers are to be divided between different Connection_Handles. The Host_Total_Num_Synchronous_ Data_Packets command parameter gives the same information for HCI Synchronous Data packets.

Note: The Host_ACL_Data_Packet_Length and Host_Synchronous_Data_ Packet_Length command parameters do not include the length of the HCI Data packet header.

Event(s) generated (unless masked away): When the HCI_Host_Buffer_Size command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_cb_host_number_of_completed_packets(const sdc_hci_cmd_cb_host_number_of_completed_packets_t *p_params)

Host Number Of Completed Packets.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.40

The HCI_Host_Number_Of_Completed_Packets command is used by the Host to indicate to the Controller the number of HCI Data packets that have been completed for each Connection_Handle since the previous HCI_Host_Number_Of_Completed_Packets command was sent to the Controller. This means that the corresponding buffer space has been freed in the Host. Based on this information, and the Host_Total_Num_ACL_Data_Packets and Host_Total_Num_Synchronous_Data_Packets command parameters of the HCI_Host_Buffer_Size command, the Controller can determine for which Connection_Handles the following HCI Data packets should be sent to the Host. The command should only be issued by the Host if flow control in the direction from the Controller to the Host is on and there is at least one connection, or if the Controller is in local loopback mode. Otherwise, the command will be ignored by the Controller. When the Host has completed one or more HCI Data packet(s) it shall send an HCI_Host_Number_Of_Completed_Packets command to the Controller, until it finally reports that all pending HCI Data packets have been completed. The frequency at which this command is sent is manufacturer specific.

The Set Controller To Host Flow Control command is used to turn flow control on or off. If flow control from the Controller to the Host is turned on, the HCI_Host_Buffer_Size command shall always be sent by the Host after a power- on or a reset before the first HCI_Host_Number_Of_Completed_Packets command is sent.

Note: The HCI_Host_Number_Of_Completed_Packets command is a special command in the sense that no event is normally generated after the command has completed. The command may be sent at any time by the Host when there is at least one connection, or if the Controller is in local loopback mode independent of other commands. The normal flow control for commands is not used for the HCI_Host_Number_Of_Completed_Packets command.

Event(s) generated (unless masked away): Normally, no event is generated after the HCI_Host_Number_Of_Completed_Packets command has completed. However, if the HCI_Host_Number_Of_Completed_Packets command contains one or more invalid parameters, the Controller shall return an HCI_Command_Complete event with a failure status indicating the Invalid HCI Command Parameters error code. The Host may send the HCI_Host_Number_Of_Completed_Packets command at any time when there is at least one connection, or if the Controller is in local loopback mode. The normal flow control for commands is not used for this command.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_cb_set_event_mask_page_2(const sdc_hci_cmd_cb_set_event_mask_page_2_t *p_params)

Set Event Mask Page 2.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.69

The HCI_Set_Event_Mask_Page_2 command is used to control which events are generated by the HCI for the Host. The Event_Mask_Page_2 is a logical extension to the Event_Mask parameter of the HCI_Set_Event_Mask command. If the bit in the Event_Mask_Page_2 is set to a one, then the event associated with that bit shall be enabled. The event mask allows the Host to control how much it is interrupted.

The Controller shall ignore those bits which are reserved for future use or represent events which it does not support. If the Host sets any of these bits to 1, the Controller shall act as if they were set to 0.

Event(s) generated (unless masked away): When the HCI_Set_Event_Mask_Page_2 command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_cb_read_authenticated_payload_timeout(const sdc_hci_cmd_cb_read_authenticated_payload_timeout_t *p_params, sdc_hci_cmd_cb_read_authenticated_payload_timeout_return_t *p_return)

Read Authenticated Payload Timeout.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.93

This command reads the Authenticated_Payload_Timeout (authenticatedPayloadTO, see [Vol 2] Part B, Appendix B for BR/EDR connections and [Vol 6] Part B, Section 5.4 for LE connections) parameter in the Primary Controller on the specified Connection_Handle.

When the Connection_Handle identifies a BR/EDR synchronous connection, the Controller shall return the error code Command Disallowed (0x0C).

Event(s) generated (unless masked away): When the HCI_Read_Authenticated_Payload_Timeout command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_cb_write_authenticated_payload_timeout(const sdc_hci_cmd_cb_write_authenticated_payload_timeout_t *p_params, sdc_hci_cmd_cb_write_authenticated_payload_timeout_return_t *p_return)

Write Authenticated Payload Timeout.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.3.94

This command writes the Authenticated_Payload_Timeout (authenticatedPayloadTO, see [Vol 2] Part B, Appendix B and [Vol 6] Part B, Section 5.4 for the LE connection) parameter in the Primary Controller for the specified Connection_Handle.

When the Connection_Handle identifies a BR/EDR ACL connection: • If the connection is in Sniff mode, the Authenticated_Payload_Timeout shall be equal to or greater than Tsniff. • If the connection is in Sniff Subrating mode, the Authenticated_Payload_Timeout shall be equal to or greater than (max subrate)xTsniff. • If the connection is in Hold mode, the Authenticated_Payload_Timeout shall be equal to or greater than the holdTO value.

When the Connection_Handle identifies a BR/EDR synchronous connection, this command shall be rejected with the error code Command Disallowed (0x0C).

When the Connection_Handle identifies an LE connection, the Authenticated_Payload_Timeout shall be equal to or greater than connInterval * (1 + connSlaveLatency).

When the Connection_Handle is associated with an ACL connection, the Link Manager will use this parameter to determine when to use the LMP ping sequence.

When the Connection_Handle is associated with an LE connection, the Link Layer will use this parameter to determine when to use the LE ping sequence.

Event(s) generated (unless masked away): When the HCI_Write_Authenticated_Payload_Timeout command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_ip_read_local_version_information(sdc_hci_cmd_ip_read_local_version_information_return_t *p_return)

Read Local Version Information.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.4.1

This command reads the values for the version information for the local Controller.

The HCI_Version information defines the version information of the HCI layer. The LMP_PAL_Version information defines the version of the LMP or PAL. The Manufacturer_Name information indicates the manufacturer of the local device.

The HCI_Revision and LMP_PAL_Subversion are implementation dependent.

Event(s) generated (unless masked away): When the HCI_Read_Local_Version_Information command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_ip_read_local_supported_commands(sdc_hci_cmd_ip_read_local_supported_commands_return_t *p_return)

Read Local Supported Commands.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.4.2

This command reads the list of HCI 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.

See Section 6.27 for more information.

Event(s) generated (unless masked away): When the HCI_Read_Local_Supported_Commands command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_ip_read_local_supported_features(sdc_hci_cmd_ip_read_local_supported_features_return_t *p_return)

Read Local Supported Features.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.4.3

This command requests a list of the supported features for the local BR/EDR Controller. This command will return a list of the LMP features. For details see [Vol 2] Part C, Link Manager Protocol Specification.

Event(s) generated (unless masked away): When the HCI_Read_Local_Supported_Features command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_ip_read_bd_addr(sdc_hci_cmd_ip_read_bd_addr_return_t *p_return)

Read BD_ADDR.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.4.6

On a BR/EDR Controller, this command reads the Bluetooth Controller address (BD_ADDR). (See [Vol 2] Part B, Section 1.2 and [Vol 3] Part C, Section 3.2.1).

On an LE Controller, this command shall read the Public Device Address as defined in [Vol 6] Part B, Section 1.3. If this Controller does not have a Public Device Address, the value 0x000000000000 shall be returned.

On a BR/EDR/LE Controller, the public address shall be the same as the BD_ADDR.

Event(s) generated (unless masked away): When the HCI_Read_BD_ADDR command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_event_mask(const sdc_hci_cmd_le_set_event_mask_t *p_params)

LE Set Event Mask.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.1

The HCI_LE_Set_Event_Mask command is used to control which LE events are generated by the HCI for the Host. If the bit in the LE_Event_Mask is set to a one, then the event associated with that bit will be enabled. The event mask allows the Host to control which events will interrupt it.

The Controller shall ignore those bits which are reserved for future use or represent events which it does not support. If the Host sets any of these bits to 1, the Controller shall act as if they were set to 0.

For LE events to be generated, the LE Meta event bit in the Event_Mask shall also be set. If that bit is not set, then LE events shall not be generated, regardless of how the LE_Event_Mask is set.

Event(s) generated (unless masked away): When the HCI_LE_Set_Event_Mask command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_buffer_size(sdc_hci_cmd_le_read_buffer_size_return_t *p_return)

LE Read Buffer Size [v1].

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.2

This command is used to read the maximum size of the data portion of ACL data packets and isochronous data packets sent from the Host to the Controller. The Host shall segment the data transmitted to the Controller according to these values so that the HCI Data packets and isochronous data packets will contain data up to this size. The HCI_LE_Read_Buffer_Size command also returns the total number of HCI LE ACL Data packets and isochronous data packets that can be stored in the data buffers of the Controller. The HCI_LE_Read_Buffer_Size command shall be issued by the Host before it sends any data to an LE Controller (see Section 4.1.1). If the Controller supports HCI ISO Data packets, it shall return non-zero values for the ISO_Data_Packet_Length and Total_Num_ISO_Data_Packets parameters.

If the Controller returns a length value of zero for ACL data packets, the Host shall use the HCI_Read_Buffer_Size command to determine the size of the data buffers (shared between BR/EDR and LE transports).

Note: Both the HCI_Read_Buffer_Size command and the HCI_LE_Read_Buffer_Size command may return buffer length and number of packets parameter values that are nonzero. This allows a Controller to offer different buffers and number of buffers for BR/EDR data packets and LE data packets.

The LE_ACL_Data_Packet_Length return parameter shall be used to determine the maximum size of the L2CAP PDU segments that are contained in ACL data packets, and which are transferred from the Host to the Controller to be broken up into packets by the Link Layer. The Total_Num_LE_ACL_Data_Packets return parameter contains the total number of HCI ACL Data packets that can be stored in the data buffers of the Controller. The Host determines how to divide the buffers between different connection handles.

The ISO_Data_Packet_Length return parameter shall be used to determine the maximum size of the SDU segments that are contained in isochronous data packets, and which are transferred from the Host to the Controller. The Total_Num_ISO_Data_Packets return parameter contains the total number of isochronous data packets that can be stored in the data buffers of the Controller. The Host determines how to divide the buffers between different connection handle(s).

Note: The LE_ACL_Data_Packet_Length and ISO_Data_Packet_Length return parameters do not include the length of the HCI Data packet header or the HCI ISO Data packet header respectively.

Event(s) generated (unless masked away): When the HCI_LE_Read_Buffer_Size command has completed, an HCI_Command_Complete event shall be generated

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_local_supported_features(sdc_hci_cmd_le_read_local_supported_features_return_t *p_return)

LE Read Local Supported Features.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.3

This command requests the list of the supported LE features for the Controller.

Event(s) generated (unless masked away): When the HCI_LE_Read_Local_Supported_Features command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_random_address(const sdc_hci_cmd_le_set_random_address_t *p_params)

LE Set Random Address.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.4

The HCI_LE_Set_Random_Address command is used by the Host to set the LE Random Device Address in the Controller (see [Vol 6] Part B, Section 1.3). If this command is used to change the address, the new random address shall take effect for advertising no later than the next successful HCI_LE_Set_Advertising_Enable command, for scanning no later than the next successful HCI_LE_Set_Scan_Enable command or HCI_LE_Set_Extended_Scan_Enable command, and for initiating no later than the next successful HCI_LE_Create_Connection command or HCI_LE_Extended_Create_Connection command. Note: If the extended advertising commands are in use, this command only affects the address used for scanning and initiating. The addresses used for advertising are set by the HCI_LE_Set_Advertising_Set_Random_Address command (see Section 7.8.52). If the Host issues this command when any of advertising (created using legacy advertising commands), scanning, or initiating are enabled, the Controller shall return the error code Command Disallowed (0x0C).

Event(s) generated (unless masked away): When the HCI_LE_Set_Random_Address command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_adv_params(const sdc_hci_cmd_le_set_adv_params_t *p_params)

LE Set Advertising Parameters.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.5

The HCI_LE_Set_Advertising_Parameters command is used by the Host to set the advertising parameters.

The Advertising_Interval_Min shall be less than or equal to the Advertising_Interval_Max. The Advertising_Interval_Min and Advertising_Interval_Max should not be the same value to enable the Controller to determine the best advertising interval given other activities.

For high duty cycle directed advertising, i.e. when Advertising_Type is 0x01 (ADV_DIRECT_IND, high duty cycle), the Advertising_Interval_Min and Advertising_Interval_Max parameters are not used and shall be ignored.

The Advertising_Type is used to determine the packet type that is used for advertising when advertising is enabled.

Own_Address_Type parameter indicates the type of address being used in the advertising packets.

If Own_Address_Type equals 0x02 or 0x03, the Peer_Address parameter contains the peer’s Identity Address and the Peer_Address_Type parameter contains the Peer’s Identity Type (i.e. 0x00 or 0x01). These parameters are used to locate the corresponding local IRK in the resolving list; this IRK is used to generate the own address used in the advertisement.

If directed advertising is performed, i.e. when Advertising_Type is set to 0x01 (ADV_DIRECT_IND, high duty cycle) or 0x04 (ADV_DIRECT_IND, low duty cycle mode), then the Peer_Address_Type and Peer_Address shall be valid.

If Own_Address_Type equals 0x02 or 0x03, the Controller generates the peer’s Resolvable Private Address using the peer’s IRK corresponding to the peer’s Identity Address contained in the Peer_Address parameter and peer’s Identity Address Type (i.e. 0x00 or 0x01) contained in the Peer_Address_Type parameter. The Advertising_Channel_Map is a bit field that indicates the advertising channel indices that shall be used when transmitting advertising packets. At least one channel bit shall be set in the Advertising_Channel_Map parameter.

The Advertising_Filter_Policy parameter shall be ignored when directed advertising is enabled.

The Host shall not issue this command when advertising is enabled in the Controller; if it is the Command Disallowed error code shall be used.

If the advertising interval range provided by the Host (Advertising_Interval_Min, Advertising_Interval_Max) is outside the advertising interval range supported by the Controller, then the Controller shall return the Unsupported Feature or Parameter Value (0x11) error code.

Event(s) generated (unless masked away): When the HCI_LE_Set_Advertising_Parameters command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_adv_physical_channel_tx_power(sdc_hci_cmd_le_read_adv_physical_channel_tx_power_return_t *p_return)

LE Read Advertising Physical Channel Tx Power.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.6

The HCI_LE_Read_Advertising_Physical_Channel_Tx_Power command is used by the Host to read the transmit power level used for LE advertising physical channel packets.

Event(s) generated (unless masked away): When the HCI_LE_Read_Advertising_Physical_Channel_Tx_Power command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_adv_data(const sdc_hci_cmd_le_set_adv_data_t *p_params)

LE Set Advertising Data.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.7

The HCI_LE_Set_Advertising_Data command is used to set the data used in advertising packets that have a data field. Only the significant part of the Advertising_Data should be transmitted in the advertising packets, as defined in [Vol 3] Part C, Section 11. If advertising is currently enabled, the Controller shall use the new data in subsequent advertising events. If an advertising event is in progress when this command is issued, the Controller may use the old or new data for that event. If advertising is currently disabled, the data shall be kept by the Controller and used once advertising is enabled.

Event(s) generated (unless masked away): When the HCI_LE_Set_Advertising_Data command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_scan_response_data(const sdc_hci_cmd_le_set_scan_response_data_t *p_params)

LE Set Scan Response Data.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.8

This command is used to provide data used in Scanning Packets that have a data field.

Only the significant part of the Scan_Response_Data should be transmitted in the Scanning Packets, as defined in [Vol 3] Part C, Section 11.

If advertising is currently enabled, the Controller shall use the new data in subsequent advertising events. If an advertising event is in progress when this command is issued, the Controller may use the old or new data for that event. If advertising is currently disabled, the data shall be kept by the Controller and used once advertising is enabled.

Event(s) generated (unless masked away): When the HCI_LE_Set_Scan_Response_Data command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_adv_enable(const sdc_hci_cmd_le_set_adv_enable_t *p_params)

LE Set Advertising Enable.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.9

The HCI_LE_Set_Advertising_Enable command is used to request the Controller to start or stop advertising. The Controller manages the timing of advertisements as per the advertising parameters given in the HCI_LE_Set_Advertising_Parameters command.

The Controller shall continue advertising until the Host issues an HCI_LE_Set_Advertising_Enable command with Advertising_Enable set to 0x00 (Advertising is disabled) or until a connection is created or until the Advertising is timed out due to high duty cycle Directed Advertising. In these cases, advertising is then disabled.

If Advertising_Enable is set to 0x01, the advertising parameters’ Own_Address_Type parameter is set to 0x01, and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If Advertising_Enable is set to 0x01, the advertising parameters’ Own_Address_Type parameter is set to 0x03, the controller’s resolving list did not contain a matching entry, and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

Enabling advertising when it is already enabled can cause the random address to change. Disabling advertising when it is already disabled has no effect.

Event(s) generated (unless masked away): When the HCI_LE_Set_Advertising_Enable command has completed, an HCI_Command_Complete event shall be generated.

If the Advertising_Type parameter is 0x01 (ADV_DIRECT_IND, high duty cycle) and the directed advertising fails to create a connection, an HCI_LE_Connection_Complete or HCI_LE_Enhanced_Connection_Complete event shall be generated with the Status code set to Advertising Timeout (0x3C).

If the Advertising_Type parameter is 0x00 (ADV_IND), 0x01 (ADV_DIRECT_IND, high duty cycle), or 0x04 (ADV_DIRECT_IND, low duty cycle) and a connection is created, an HCI_LE_Connection_Complete or HCI_LE_Enhanced_Connection_Complete event shall be generated.

Note: There is a possible race condition if the Advertising_Enable parameter is set to 0x00 (Disable) and the Advertising_Type parameter is 0x00, 0x01, or 0x04. The advertisements might not be stopped before a connection is created, and therefore both the HCI_Command_Complete event and either an HCI_LE_Connection_Complete event or an HCI_LE_Enhanced_Connection_Complete event could be generated. This can also occur when high duty cycle directed advertising is timed out and this command disables advertising.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_scan_params(const sdc_hci_cmd_le_set_scan_params_t *p_params)

LE Set Scan Parameters.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.10

The HCI_LE_Set_Scan_Parameters command is used to set the scan parameters.

The LE_Scan_Type parameter controls the type of scan to perform.

The LE_Scan_Interval and LE_Scan_Window parameters are recommendations from the Host on how long (LE_Scan_Window) and how frequently (LE_Scan_Interval) the Controller should scan (See [Vol 6] Part B, Section 4.4.3). The LE_Scan_Window parameter shall always be set to a value smaller or equal to the value set for the LE_Scan_Interval parameter. If they are set to the same value scanning should be run continuously.

Own_Address_Type parameter indicates the type of address being used in the scan request packets.

The Host shall not issue this command when scanning is enabled in the Controller; if it is the Command Disallowed error code shall be used.

Event(s) generated (unless masked away): When the HCI_LE_Set_Scan_Parameters command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_scan_enable(const sdc_hci_cmd_le_set_scan_enable_t *p_params)

LE Set Scan Enable.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.11

The HCI_LE_Set_Scan_Enable command is used to start and stop scanning. Scanning is used to discover advertising devices nearby.

The Filter_Duplicates parameter controls whether the Link Layer should filter out duplicate advertising reports (Filtering_Enabled) to the Host, or if the Link Layer should generate advertising reports for each packet received (Filtering_Disabled). See [Vol 6] Part B, Section 4.4.3.5. If LE_Scan_Enable is set to 0x00 then Filter_Duplicates shall be ignored.

If LE_Scan_Enable is set to 0x01, the scanning parameters’ Own_Address_Type parameter is set to 0x01 or 0x03, and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the LE_Scan_Enable parameter is set to 0x01 and scanning is already enabled, any change to the Filter_Duplicates setting shall take effect.

Disabling scanning when it is disabled has no effect.

Event(s) generated (unless masked away): When the HCI_LE_Set_Scan_Enable command has completed, an HCI_Command_Complete event shall be generated.

Zero or more LE Advertising Reports are generated by the Controller based on advertising packets received and the duplicate filtering. More than one advertising packet may be reported in each HCI_LE_Advertising_Report event.

When the Scanning_Filter_Policy is set to 0x02 or 0x03 (see Section 7.8.10) and a directed advertisement was received where the advertiser used a resolvable private address which the Controller is unable to resolve, an HCI_LE_Directed_Advertising_Report event shall be generated instead of an HCI_LE_Advertising_Report event.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_create_conn(const sdc_hci_cmd_le_create_conn_t *p_params)

LE Create Connection.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.12

The HCI_LE_Create_Connection command is used to create an ACL connection to a connectable advertiser. The LE_Scan_Interval and LE_Scan_Window parameters are recommendations from the Host on how long (LE_Scan_Window) and how frequently (LE_Scan_Interval) the Controller should scan. The LE_Scan_Window parameter shall be set to a value smaller or equal to the value set for the LE_Scan_Interval parameter. If both are set to the same value, scanning should run continuously. The Initiator_Filter_Policy is used to determine whether the White List is used. If the White List is not used, the Peer_Address_Type and the Peer_Address parameters specify the address type and address of the advertising device to connect to. Peer_Address_Type parameter indicates the type of address used in the connectable advertisement sent by the peer. The Host shall not set Peer_Address_Type to either 0x02 or 0x03 if both the Host and the Controller support the HCI_LE_Set_Privacy_Mode command. If a Controller that supports the HCI_LE_Set_Privacy_Mode command receives the HCI_LE_Create_Connection command with Peer_Address_Type set to either 0x02 or 0x03, it may use either device privacy mode or network privacy mode for that peer device. Peer_Address parameter indicates the Peer’s Public Device Address, Random (static) Device Address, Non-Resolvable Private Address or Resolvable Private Address depending on the Peer_Address_Type parameter. Own_Address_Type parameter indicates the type of address being used in the connection request packets. The Connection_Interval_Min and Connection_Interval_Max parameters define the minimum and maximum allowed connection interval. The Connection_Interval_Min parameter shall not be greater than the Connection_Interval_Max parameter. The Connection_Latency parameter defines the maximum allowed connection latency (see [Vol 6] Part B, Section 4.5.1). The Supervision_Timeout parameter defines the link supervision timeout for the connection. The Supervision_Timeout in milliseconds shall be larger than (1 + Connection_Latency) * Connection_Interval_Max * 2, where Connection_Interval_Max is given in milliseconds. (See [Vol 6] Part B, Section 4.5.2). The Min_CE_Length and Max_CE_Length parameters are informative parameters providing the Controller with the expected minimum and maximum length of the connection events. The Min_CE_Length parameter shall be less than or equal to the Max_CE_Length parameter. If the Host issues this command when another HCI_LE_Create_Connection command is pending in the Controller, the Controller shall return the error code Command Disallowed (0x0C). If the Own_Address_Type parameter is set to 0x01 and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the Own_Address_Type parameter is set to 0x03, the Initiator_Filter_Policy parameter is set to 0x00, the controller’s resolving list did not contain a matching entry, and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12). If the Own_Address_Type parameter is set to 0x03, the Initiator_Filter_Policy parameter is set to 0x01, and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

Event(s) generated (unless masked away): When the Controller receives the HCI_LE_Create_Connection command, the Controller sends the HCI_Command_Status event to the Host. An HCI_LE_Connection_Complete or HCI_LE_Enhanced_Connection_Complete event shall be generated when a connection is created or the connection creation procedure is cancelled. If a connection is created and the Controller supports the LE Channel Selection Algorithm #2 feature, this event shall be immediately followed by an HCI_LE_Channel_Selection_Algorithm event.

Note: No HCI_Command_Complete event is sent by the Controller to indicate that this command has been completed. Instead, the HCI_LE_Connection_Complete or HCI_LE_Enhanced_Connection_Complete event indicates that this command has been completed.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_create_conn_cancel(void)

LE Create Connection Cancel.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.13

The HCI_LE_Create_Connection_Cancel command is used to cancel the HCI_LE_Create_Connection or HCI_LE_Extended_Create_Connection commands. This command shall only be issued after the HCI_LE_Create_Connection or HCI_LE_Extended_Create_Connection commands have been issued, an HCI_Command_Status event has been received for the HCI_LE_Create_Connection or HCI_LE_Extended_Create_Connection commands, and before the HCI_LE_Connection_Complete or HCI_LE_Enhanced_Connection_Complete events.

Event(s) generated (unless masked away): When the HCI_LE_Create_Connection_Cancel command has completed, an HCI_Command_Complete event shall be generated.

If the HCI_LE_Create_Connection_Cancel command is sent to the Controller without a preceding LE_Create_Connection or HCI_LE_Extended_Create_Connection command, the Controller shall return an HCI_Command_Complete event with the error code Command Disallowed (0x0C).

If the cancellation was successful then, after the HCI_Command_Complete event for the HCI_LE_Create_Connection_Cancel command, either an LE Connection Complete or an HCI_LE_Enhanced_Connection_Complete event shall be generated. In either case, the event shall be sent with the error code Unknown Connection Identifier (0x02).

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

uint8_t sdc_hci_cmd_le_read_white_list_size(sdc_hci_cmd_le_read_white_list_size_return_t *p_return)

LE Read White List Size.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.14

The HCI_LE_Read_White_List_Size command is used to read the total number of White List entries that can be stored in the Controller.

Note: The number of entries that can be stored is not fixed and the Controller can change it at any time (e.g. because the memory used to store the White List can also be used for other purposes).

Event(s) generated (unless masked away): When the HCI_LE_Read_White_List_Size command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_clear_white_list(void)

LE Clear White List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.15

The HCI_LE_Clear_White_List command is used to clear the White List stored in the Controller.

This command shall not be used when: • any advertising filter policy uses the White List and advertising is enabled, • the scanning filter policy uses the White List and scanning is enabled, or • the initiator filter policy uses the White List and an HCI_LE_Create_Connection or HCI_LE_Extended_Create_Connection command is outstanding.

Event(s) generated (unless masked away): When the HCI_LE_Clear_White_List command has completed, an HCI_Command_Complete event shall be generated.

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

uint8_t sdc_hci_cmd_le_add_device_to_white_list(const sdc_hci_cmd_le_add_device_to_white_list_t *p_params)

LE Add Device To White List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.16

The HCI_LE_Add_Device_To_White_List command is used to add a single device to the White List stored in the Controller.

This command shall not be used when: • any advertising filter policy uses the White List and advertising is enabled, • the scanning filter policy uses the White List and scanning is enabled, or • the initiator filter policy uses the White List and an HCI_LE_Create_Connection or HCI_LE_Extended_Create_Connection command is outstanding.

When a Controller cannot add a device to the White List because there is no space available, it shall return the error code Memory Capacity Exceeded (0x07).

If the device is already in the White List, the Controller should not add the device to the White List again and should return success.

Address shall be ignored when Address_Type is set to 0xFF.

Event(s) generated (unless masked away): When the HCI_LE_Add_Device_To_White_List command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_remove_device_from_white_list(const sdc_hci_cmd_le_remove_device_from_white_list_t *p_params)

LE Remove Device From White List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.17

The HCI_LE_Remove_Device_From_White_List command is used to remove a single device from the White List stored in the Controller. This command shall not be used when: • any advertising filter policy uses the White List and advertising is enabled, • the scanning filter policy uses the White List and scanning is enabled, or • the initiator filter policy uses the White List and an HCI_LE_Create_Connection or HCI_LE_Extended_Create_Connection command is outstanding.

Address shall be ignored when Address_Type is set to 0xFF.

Event(s) generated (unless masked away): When the HCI_LE_Remove_Device_From_White_List command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_conn_update(const sdc_hci_cmd_le_conn_update_t *p_params)

LE Connection Update.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.18

The HCI_LE_Connection_Update command is used to change the ACL connection parameters. This command may be issued on both the master and slave.

The Connection_Interval_Min and Connection_Interval_Max parameters are used to define the minimum and maximum allowed connection interval. The Connection_Interval_Min parameter shall not be greater than the Connection_Interval_Max parameter.

The Connection_Latency parameter shall define the maximum allowed connection latency.

The Supervision_Timeout parameter shall define the link supervision timeout for the LE link. The Supervision_Timeout in milliseconds shall be larger than (1

Connection_Latency) * Connection_Interval_Max * 2, where Connection_Interval_Max is given in milliseconds.

The Min_CE_Length and Max_CE_Length are information parameters providing the Controller with a hint about the expected minimum and maximum length of the connection events. The Min_CE_Length shall be less than or equal to the Max_CE_Length.

The actual parameter values selected by the Link Layer may be different from the parameter values provided by the Host through this command.

Event(s) generated (unless masked away): When the Controller receives the HCI_LE_Connection_Update command, the Controller sends the HCI_Command_Status event to the Host. The HCI_LE_Connection_Update_Complete event shall be generated after the connection parameters have been applied by the Controller or if the command subsequently fails.

Note: An HCI_Command_Complete event is not sent by the Controller to indicate that this command has been completed. Instead, the HCI_LE_Connection_Update_Complete event indicates that this command has been completed.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_host_channel_classification(const sdc_hci_cmd_le_set_host_channel_classification_t *p_params)

LE Set Host Channel Classification.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.19

The HCI_LE_Set_Host_Channel_Classification command allows the Host to specify a channel classification for the data, secondary advertising, periodic, and isochronous physical channels based on its “local information”. This classification persists until overwritten with a subsequent HCI_LE_Set_Host_Channel_Classification command or until the Controller is reset using the HCI_Reset command (see [Vol 6] Part B, Section 4.5.8.1).

If this command is used, the Host should send it within 10 seconds of knowing that the channel classification has changed. The interval between two successive commands sent shall be at least one second.

This command shall only be used when the local device supports the Master role, supports extended advertising in the Advertising state, or supports the Isochronous Broadcaster role.

Event(s) generated (unless masked away): When the HCI_LE_Set_Host_Channel_Classification command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_channel_map(const sdc_hci_cmd_le_read_channel_map_t *p_params, sdc_hci_cmd_le_read_channel_map_return_t *p_return)

LE Read Channel Map.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.20

The HCI_LE_Read_Channel_Map command returns the current Channel_Map for the specified Connection_Handle. The returned value indicates the state of the Channel_Map specified by the last transmitted or received Channel_Map (in a CONNECT_IND or LL_CHANNEL_MAP_IND message) for the specified Connection_Handle, regardless of whether the Master has received an acknowledgment.

Event(s) generated (unless masked away): When the HCI_LE_Read_Channel_Map command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_remote_features(const sdc_hci_cmd_le_read_remote_features_t *p_params)

LE Read Remote Features.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.21

This command requests, from the remote device identified by the Connection_Handle, the features used on the connection and the features supported by the remote device. For details see [Vol 6] Part B, Section 4.6.

This command may be issued on both the master and slave.

Note: If a connection already exists between the two devices and the features have already been fetched on that connection, the Controller may use a cached copy of the features.

Event(s) generated (unless masked away): When the Controller receives the HCI_LE_Read_Remote_Features command, the Controller shall send the HCI_Command_Status event to the Host. When the Controller has completed the procedure to determine the remote features or has determined that it will be using a cached copy, the Controller shall send an HCI_LE_Read_Remote_Features_Complete event to the Host.

The HCI_LE_Read_Remote_Features_Complete event contains the status of this command and the parameter describing the features used on the connection and the features supported by the remote device.

Note: An HCI_Command_Complete event is not sent by the Controller to indicate that this command has been completed. Instead, the HCI_LE_Read_Remote_Features_Complete event indicates that this command has been completed.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_encrypt(const sdc_hci_cmd_le_encrypt_t *p_params, sdc_hci_cmd_le_encrypt_return_t *p_return)

LE Encrypt.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.22

The HCI_LE_Encrypt command is used to request the Controller to encrypt the Plaintext_Data in the command using the Key given in the command and returns the Encrypted_Data to the Host. The AES-128 bit block cypher is defined in NIST Publication FIPS-197 (https://csrc.nist.gov/publications/fips/ fips197/fips-197.pdf).

Event(s) generated (unless masked away): When the HCI_LE_Encrypt command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_rand(sdc_hci_cmd_le_rand_return_t *p_return)

LE Rand.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.23

The HCI_LE_Rand command is used to request the Controller to generate 8 octets of random data to be sent to the Host. The Random_Number shall be generated according to [Vol 2] Part H, Section 2 if the LE Feature (LE Encryption) is supported.

Event(s) generated (unless masked away): When the HCI_LE_Rand command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_enable_encryption(const sdc_hci_cmd_le_enable_encryption_t *p_params)

LE Enable Encryption.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.27.

The HCI_LE_Enable_Encryption command is used to authenticate the given encryption key associated with the remote device specified by the Connection_Handle, and once authenticated will encrypt the connection. The parameters are as defined in [Vol 3] Part H, Section 2.4.4.

If the connection is already encrypted then the Controller shall pause connection encryption before attempting to authenticate the given encryption key, and then re-encrypt the connection. While encryption is paused no user data shall be transmitted.

If the Connection_Handle parameter identifies an ACL with an associated CIS that has been created, the Controller shall return the error code Command Disallowed (0x0C).

On an authentication failure, the connection shall be automatically disconnected by the Link Layer. If this command succeeds, then the connection shall be encrypted.

This command shall only be used when the local device’s role is Master.

Event(s) generated (unless masked away): When the Controller receives the HCI_LE_Enable_Encryption command it shall send the HCI_Command_Status event to the Host. If the connection is not encrypted when this command is issued, an HCI_Encryption_Change event shall occur when encryption has been started for the connection. If the connection is encrypted when this command is issued, an HCI_Encryption_Key_Refresh_Complete event shall occur when encryption has been resumed.

Note: An HCI_Command_Complete event is not sent by the Controller to indicate that this command has been completed. Instead, the HCI_Encryption_Change or HCI_Encryption_Key_Refresh_Complete events indicate that this command has been completed.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_long_term_key_request_reply(const sdc_hci_cmd_le_long_term_key_request_reply_t *p_params, sdc_hci_cmd_le_long_term_key_request_reply_return_t *p_return)

LE Long Term Key Request Reply.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.25

The HCI_LE_Long_Term_Key_Request_Reply command is used to reply to an HCI_LE_Long_Term_Key_Request event from the Controller, and specifies the Long_Term_Key parameter that shall be used for this Connection_Handle. The Long_Term_Key is used as defined in [Vol 6] Part B, Section 5.1.3. This command shall only be used when the local device’s role is Slave.

Event(s) generated (unless masked away): When the HCI_LE_Long_Term_Key_Request_Reply command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_long_term_key_request_negative_reply(const sdc_hci_cmd_le_long_term_key_request_negative_reply_t *p_params, sdc_hci_cmd_le_long_term_key_request_negative_reply_return_t *p_return)

LE Long Term Key Request Negative Reply.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.26

The HCI_LE_Long_Term_Key_Request_Negative_Reply command is used to reply to an HCI_LE_Long_Term_Key_Request event from the Controller if the Host cannot provide a Long Term Key for this Connection_Handle.

This command shall only be used when the local device’s role is Slave.

Event(s) generated (unless masked away): When the HCI_LE_Long_Term_Key_Request_Negative_Reply command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_supported_states(sdc_hci_cmd_le_read_supported_states_return_t *p_return)

LE Read Supported States.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.27

The HCI_LE_Read_Supported_States command reads the states and state combinations that the Link Layer supports. See [Vol 6] Part B, Section 1.1.1.

LE_States is an 8-octet bit field. If a bit is set to 1 then this state or state combination is supported by the Controller. Multiple bits in LE_States may be set to 1 to indicate support for multiple state and state combinations.

Note: This command only provides information about the supported states that can be used with legacy advertising. It does not provide information about states, and combinations of states, that can only be used with the extended advertising commands (see Section 3.1.1).

Event(s) generated (unless masked away): When the HCI_LE_Read_Supported_States command has completed, an HCI_Command_Complete event will be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_test_end(sdc_hci_cmd_le_test_end_return_t *p_return)

LE Test End.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.30

This command is used to stop any test which is in progress. The Num_Packets for a transmitter test shall be reported as 0x0000. The Num_Packets is an unsigned number and contains the number of received packets.

Event(s) generated (unless masked away): When the HCI_LE_Test_End command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_data_length(const sdc_hci_cmd_le_set_data_length_t *p_params, sdc_hci_cmd_le_set_data_length_return_t *p_return)

LE Set Data Length.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.33

The HCI_LE_Set_Data_Length command allows the Host to suggest the maximum transmission payload size and maximum packet transmission time (connMaxTxOctets and connMaxTxTime - see [Vol 6] Part B, Section 4.5.10) to be used for LL Data PDUs on a given connection. The Controller may use smaller or larger values based on local information.

Event(s) generated (unless masked away): When the HCI_LE_Set_Data_Length command has completed, an HCI_Command_Complete event shall be generated.

If the command causes the maximum transmission packet size or maximum packet transmission time to change, an HCI_LE_Data_Length_Change event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_suggested_default_data_length(sdc_hci_cmd_le_read_suggested_default_data_length_return_t *p_return)

LE Read Suggested Default Data Length.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.34

The HCI_LE_Read_Suggested_Default_Data_Length command allows the Host to read the Host’s suggested values (Suggested_Max_TX_Octets and Suggested_Max_TX_Time) for the Controller’s maximum transmitted number of payload octets and maximum packet transmission time for packets containing LL Data PDUs to be used for new connections (see [Vol 6] Part B, Section 4.5.10).

Event(s) generated (unless masked away): When the HCI_LE_Read_Suggested_Default_Data_Length command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_write_suggested_default_data_length(const sdc_hci_cmd_le_write_suggested_default_data_length_t *p_params)

LE Write Suggested Default Data Length.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.35

The HCI_LE_Write_Suggested_Default_Data_Length command allows the Host to specify its suggested values for the Controller’s maximum transmission number of payload octets and maximum packet transmission time for packets containing LL Data PDUs to be used for new connections. The Controller may use smaller or larger values for connInitialMaxTxOctets and connInitialMaxTxTime based on local information. (See [Vol 6] Part B, Section 4.5.10).

Event(s) generated (unless masked away): When the HCI_LE_Write_Suggested_Default_Data_Length command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_add_device_to_resolving_list(const sdc_hci_cmd_le_add_device_to_resolving_list_t *p_params)

LE Add Device To Resolving List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.38

The HCI_LE_Add_Device_To_Resolving_List command is used to add one device to the resolving list used to generate and resolve Resolvable Private Addresses in the Controller.

This command shall not be used when address resolution is enabled in the Controller and: • Advertising (other than periodic advertising) is enabled, • Scanning is enabled, or • an HCI_LE_Create_Connection, HCI_LE_Extended_Create_Connection, or HCI_LE_Periodic_Advertising_Create_Sync command is outstanding.

This command may be used at any time when address resolution is disabled in the Controller.

The added device shall be set to Network Privacy mode.

When a Controller cannot add a device to the list because there is no space available, it shall return the error code Memory Capacity Exceeded (0x07).

Event(s) generated (unless masked away): When the HCI_LE_Add_Device_To_Resolving_List command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_remove_device_from_resolving_list(const sdc_hci_cmd_le_remove_device_from_resolving_list_t *p_params)

LE Remove Device From Resolving List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.39

The HCI_LE_Remove_Device_From_Resolving_List command is used to remove one device from the resolving list used to resolve Resolvable Private Addresses in the Controller.

This command shall not be used when address resolution is enabled in the Controller and: • Advertising (other than periodic advertising) is enabled, • Scanning is enabled, or • an HCI_LE_Create_Connection, HCI_LE_Extended_Create_Connection, or HCI_LE_Periodic_Advertising_Create_Sync command is outstanding.

This command may be used at any time when address resolution is disabled in the Controller.

When a Controller cannot remove a device from the resolving list because it is not found, it shall return the error code Unknown Connection Identifier (0x02).

Event(s) generated (unless masked away): When the HCI_LE_Remove_Device_From_Resolving_List command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_clear_resolving_list(void)

LE Clear Resolving List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.40

The HCI_LE_Clear_Resolving_List command is used to remove all devices from the resolving list used to resolve Resolvable Private Addresses in the Controller.

This command shall not be used when address resolution is enabled in the Controller and: • Advertising (other than periodic advertising) is enabled, • Scanning is enabled, or • an HCI_LE_Create_Connection, HCI_LE_Extended_Create_Connection, or HCI_LE_Periodic_Advertising_Create_Sync command is outstanding.

This command may be used at any time when address resolution is disabled in the Controller.

Event(s) generated (unless masked away): When the HCI_LE_Clear_Resolving_List command has completed, an HCI_Command_Complete event shall be generated.

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

uint8_t sdc_hci_cmd_le_read_resolving_list_size(sdc_hci_cmd_le_read_resolving_list_size_return_t *p_return)

LE Read Resolving List Size.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.41

The HCI_LE_Read_Resolving_List_Size command is used to read the total number of entries in the resolving list that can be stored in the Controller.

Note: The number of entries that can be stored is not fixed and the Controller can change it at any time (e.g. because the memory used to store the list can also be used for other purposes).

Event(s) generated (unless masked away): When the HCI_LE_Read_Resolving_List_Size command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_address_resolution_enable(const sdc_hci_cmd_le_set_address_resolution_enable_t *p_params)

LE Set Address Resolution Enable.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.44

The HCI_LE_Set_Address_Resolution_Enable command is used to enable resolution of Resolvable Private Addresses in the Controller. This causes the Controller to use the resolving list whenever the Controller receives a local or peer Resolvable Private Address.

This command shall not be used when: • Advertising (other than periodic advertising) is enabled, • Scanning is enabled, or • an HCI_LE_Create_Connection, HCI_LE_Extended_Create_Connection, or HCI_LE_Periodic_Advertising_Create_Sync command is outstanding.

Enabling address resolution when it is already enabled, or disabling it when it is already disabled, has no effect.

Note: This command does not affect the generation of Resolvable Private Addresses.

Event(s) generated (unless masked away): When the HCI_LE_Set_Address_Resolution_Enable command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_resolvable_private_address_timeout(const sdc_hci_cmd_le_set_resolvable_private_address_timeout_t *p_params)

LE Set Resolvable Private Address Timeout.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.45

The HCI_LE_Set_Resolvable_Private_Address_Timeout command set the length of time the Controller uses a Resolvable Private Address before a new resolvable private address is generated and starts being used.

This timeout applies to all resolvable private addresses generated by the Controller.

Event(s) generated (unless masked away): When the HCI_LE_Set_Resolvable_Private_Address_Timeout command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_max_data_length(sdc_hci_cmd_le_read_max_data_length_return_t *p_return)

LE Read Maximum Data Length.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.46

The HCI_LE_Read_Maximum_Data_Length command allows the Host to read the Controller’s maximum supported payload octets and packet duration times for transmission and reception (Supported_Max_TX_Octets and Supported_Max_TX_Time, Supported_Max_RX_Octets, and Supported_Max_RX_Time, see [Vol 6] Part B, Section 4.5.10).

Event(s) generated (unless masked away): When the HCI_LE_Read_Maximum_Data_Length command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_phy(const sdc_hci_cmd_le_read_phy_t *p_params, sdc_hci_cmd_le_read_phy_return_t *p_return)

LE Read PHY.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.47

The HCI_LE_Read_PHY command is used to read the current transmitter PHY and receiver PHY on the connection identified by the Connection_Handle.

Event(s) generated (unless masked away): When the HCI_LE_Read_PHY command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_default_phy(const sdc_hci_cmd_le_set_default_phy_t *p_params)

LE Set Default PHY.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.48

The HCI_LE_Set_Default_PHY command allows the Host to specify its preferred values for the transmitter PHY and receiver PHY to be used for all subsequent connections over the LE transport.

The All_PHYs parameter is a bit field that allows the Host to specify, for each direction, whether it has no preference among the PHYs that the Controller supports in a given direction or whether it has specified particular PHYs that it prefers in the TX_PHYs or RX_PHYs parameter.

The TX_PHYs parameter is a bit field that indicates the transmitter PHYs that the Host prefers the Controller to use. If the All_PHYs parameter specifies that the Host has no preference, the TX_PHYs parameter shall be ignored; otherwise at least one bit shall be set to 1.

The RX_PHYs parameter is a bit field that indicates the receiver PHYs that the Host prefers the Controller to use. If the All_PHYs parameter specifies that the Host has no preference, the RX_PHYs parameter shall be ignored; otherwise at least one bit shall be set to 1.

If the Host sets, in the TX_PHYs or RX_PHYs parameter, a bit for a PHY that the Controller does not support, including a bit that is reserved for future use, the Controller shall return the error code Unsupported Feature or Parameter Value (0x11).

If the Controller does not support asymmetric connections (see [Vol 6] Part B, Section 4.6.9.1) and the Host sets All_PHYs to 0x00 and TX_PHYs to a different value than RX_PHYs, the Controller shall return the error code Unsupported Feature or Parameter Value (0x11).

Event(s) generated (unless masked away): When the HCI_LE_Set_Default_PHY command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_phy(const sdc_hci_cmd_le_set_phy_t *p_params)

LE Set PHY.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.49

The HCI_LE_Set_PHY command is used to set the PHY preferences for the connection identified by the Connection_Handle. The Controller might not be able to make the change (e.g. because the peer does not support the requested PHY) or may decide that the current PHY is preferable (e.g., because it could not schedule other activities if the requested PHY was used or because it requires a PHY that supports Constant Tone Extensions).

The All_PHYs parameter is a bit field that allows the Host to specify, for each direction, whether it has no preference among the PHYs that the Controller supports in a given direction or whether it has specified particular PHYs that it prefers in the TX_PHYs or RX_PHYs parameter.

The TX_PHYs parameter is a bit field that indicates the transmitter PHYs that the Host prefers the Controller to use. If the All_PHYs parameter specifies that the Host has no preference, the TX_PHYs parameter shall be ignored; otherwise at least one bit shall be set to 1.

The RX_PHYs parameter is a bit field that indicates the receiver PHYs that the Host prefers the Controller to use. If the All_PHYs parameter specifies that the Host has no preference, the RX_PHYs parameter shall be ignored; otherwise at least one bit shall be set to 1.

If, for at least one direction, the Host has specified a preference and the current PHY is not one of those preferred, the Controller shall request a change. Otherwise the Controller may, but need not, request a change.

The PHY preferences provided by the HCI_LE_Set_PHY command override those provided via the HCI_LE_Set_Default_PHY command (Section 7.8.48) or any preferences previously set using the HCI_LE_Set_PHY command on the same connection.

The PHY_Options parameter is a bit field that allows the Host to specify options for PHYs. The default value for a new connection shall be all zero bits. The Controller may override any preferred coding for transmitting on the LE Coded PHY. The Host may specify a preferred coding even if it prefers not to use the LE Coded transmitter PHY since the Controller may override the PHY preference.

If the Host sets, in the TX_PHYs or RX_PHYs parameter, a bit for a PHY that the Controller does not support, including a bit that is reserved for future use, the Controller shall return the error code Unsupported Feature or Parameter Value (0x11).

If the Controller does not support asymmetric connections (see [Vol 6] Part B, Section 4.6.9.1) and the Host sets All_PHYs to 0x00 and TX_PHYs to a different value than RX_PHYs, the Controller shall return the error code Unsupported Feature or Parameter Value (0x11).

Event(s) generated (unless masked away): When the Controller receives the HCI_LE_Set_PHY command, the Controller shall send the HCI_Command_Status event to the Host. The HCI_LE_PHY_Update_Complete event shall be generated either when one or both PHY changes or when the Controller determines that neither PHY will change immediately.

Note: If the peer negotiation resulted in no change to either PHY, this is not an error and the HCI_LE_PHY_Update_Complete event will contain a status indicating success.

Note: An HCI_Command_Complete event is not sent by the Controller to indicate that this command has been completed. Instead, the HCI_LE_PHY_Update_Complete event indicates that this command has been completed. The HCI_LE_PHY_Update_Complete event may also be issued autonomously by the Link Layer.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_adv_set_random_address(const sdc_hci_cmd_le_set_adv_set_random_address_t *p_params)

LE Set Advertising Set Random Address.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.52

The HCI_LE_Set_Advertising_Set_Random_Address command is used by the Host to set the random device address specified by the Random_Address parameter. This address is used in the Controller (see [Vol 6] Part B, Section 1.3.2) for the advertiser’s address contained in the advertising PDUs for the advertising set specified by the Advertising_Handle parameter.

This command may be issued at any time after an advertising set identified by the Advertising_Handle parameter has been created using the HCI_LE_Set_Extended_Advertising_Parameters command (see Section 7.8.53). However, if the Host issues this command while the advertising set identified by the Advertising_Handle parameter is using connectable advertising and is enabled, the Controller shall return the error code Command Disallowed (0x0C).

If this command is used to change the address, the new random address shall take effect for advertising no later than the next successful HCI_LE_Extended_Set_Advertising_Enable command and for periodic advertising no later than the next successful HCI_LE_Periodic_Advertising_Enable command.

Event(s) generated (unless masked away): When the HCI_LE_Set_Advertising_Set_Random_Address command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_ext_adv_params(const sdc_hci_cmd_le_set_ext_adv_params_t *p_params, sdc_hci_cmd_le_set_ext_adv_params_return_t *p_return)

LE Set Extended Advertising Parameters.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.53

The HCI_LE_Set_Extended_Advertising_Parameters command is used by the Host to set the advertising parameters.

The Advertising_Handle parameter identifies the advertising set whose parameters are being configured.

The Advertising_Event_Properties parameter describes the type of advertising event that is being configured and its basic properties. The type shall be one supported by the Controller. In particular, the following restrictions apply to this parameter: • If legacy advertising PDU types are being used, then the parameter value shall be one of those specified in Table 7.2. If the advertising set already contains data, the type shall be one that supports advertising data and the amount of data shall not exceed 31 octets. Advertising Event Advertising Event Type PDU Type Properties Data

Connectable and scannable ADV_IND 0b00010011 Supported undirected

Connectable directed ADV_DIRECT_IND 0b00010101 Not allowed (low duty cycle)

Connectable directed ADV_DIRECT_IND 0b00011101 Not allowed (high duty cycle)

Scannable undirected ADV_SCAN_IND 0b00010010 Supported

Non-connectable and non- ADV_NONCONN_IND 0b00010000 Supported scannable undirected

Table 7.2: Advertising_Event_Properties values for legacy PDUs

• If extended advertising PDU types are being used (bit 4 = 0) then: The advertisement shall not be both connectable and scannable. High duty cycle directed connectable advertising (≤ 3.75 ms advertising interval) shall not be used (bit 3 = 0).

If the Advertising_Event_Properties parameter does not describe an event type supported by the Controller, contains an invalid bit combination, or specifies a type that does not support advertising data when the advertising set already contains some, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

The parameters beginning with “Secondary” are only valid when extended advertising PDU types are being used (bit 4 = 0).

The Own_Address_Type parameter shall be ignored for undirected anonymous advertising (bit 2 = 0 and bit 5 = 1).

If Directed advertising is selected, the Peer_Address_Type and Peer_Address shall be valid and the Advertising_Filter_Policy parameter shall be ignored.

The Primary_Advertising_Interval_Min parameter shall be less than or equal to the Primary_Advertising_Interval_Max parameter. The Primary_Advertising_Interval_Min and Primary_Advertising_Interval_Max parameters should not be the same value so that the Controller can choose the best advertising interval given other activities.

For high duty cycle connectable directed advertising event type (ADV_DIRECT_IND), the Primary_Advertising_Interval_Min and Primary_Advertising_Interval_Max parameters are not used and shall be ignored. If the primary advertising interval range provided by the Host (Primary_Advertising_Interval_Min, Primary_Advertising_Interval_Max) is outside the advertising interval range supported by the Controller, then the Controller shall return the error code Unsupported Feature or Parameter Value (0x11).

The Primary_Advertising_Channel_Map is a bit field that indicates the advertising channel indices that shall be used when transmitting advertising packets. At least one channel bit shall be set in the Primary_Advertising_Channel_Map parameter.

The Own_Address_Type parameter specifies the type of address being used in the advertising packets. For random addresses, the address is specified by the HCI_LE_Set_Advertising_Set_Random_Address command.

If Own_Address_Type equals 0x02 or 0x03, the Peer_Address parameter contains the peer’s Identity Address and the Peer_Address_Type parameter contains the peer’s Identity Type (i.e., 0x00 or 0x01). These parameters are used to locate the corresponding local IRK in the resolving list; this IRK is used to generate their own address used in the advertisement.

The Advertising_TX_Power parameter indicates the maximum power level at which the advertising packets are to be transmitted on the advertising physical channels. The Controller shall choose a power level lower than or equal to the one specified by the Host.

The Primary_Advertising_PHY parameter indicates the PHY on which the advertising packets are transmitted on the primary advertising physical channel. If legacy advertising PDUs are being used, the Primary_Advertising_PHY shall indicate the LE 1M PHY. The Secondary_Advertising_PHY parameter indicates the PHY on which the advertising packets are be transmitted on the secondary advertising physical channel. If the Host specifies a PHY that is not supported by the Controller, including a value that is reserved for future use, it should return the error code Unsupported Feature or Parameter Value (0x11). If Constant Tone Extensions are enabled for the advertising set and Secondary_Advertising_PHY specifies a PHY that does not allow Constant Tone Extensions, the Controller shall return the error code Command Disallowed (0x0C).

The Secondary_Advertising_Max_Skip parameter is the maximum number of advertising events that can be skipped before the AUX_ADV_IND can be sent.

The Advertising_SID parameter specifies the value to be transmitted in the Advertising SID subfield of the ADI field of the Extended Header of those advertising physical channel PDUs that have an ADI field. If the advertising set only uses PDUs that do not contain an ADI field, Advertising_SID shall be ignored.

The Scan_Request_Notification_Enable parameter indicates whether the Controller shall send notifications upon the receipt of a scan request PDU that is in response to an advertisement from the specified advertising set that contains its device address and is from a scanner that is allowed by the advertising filter policy.

If the Host issues this command when advertising is enabled for the specified advertising set, the Controller shall return the error code Command Disallowed (0x0C).

If the Host issues this command when periodic advertising is enabled for the specified advertising set and connectable, scannable, legacy, or anonymous advertising is specified, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If periodic advertising is enabled for the advertising set and the Secondary_Advertising_PHY parameter does not specify the PHY currently being used for the periodic advertising, the Controller shall return the error code Command Disallowed (0x0C).

If the Advertising_Handle does not identify an existing advertising set and the Controller is unable to support a new advertising set at present, the Controller shall return the error code Memory Capacity Exceeded (0x07).

If the advertising set already contains advertising data or scan response data, extended advertising is being used, and the length of the data is greater than the maximum that the Controller can transmit within the longest possible auxiliary advertising segment consistent with the parameters, the Controller shall return the error code Packet Too Long (0x45). If advertising on the LE Coded PHY, the S=8 coding shall be assumed.

Event(s) generated (unless masked away): When the HCI_LE_Set_Extended_Advertising_Parameters command has completed, an HCI_Command_Complete event shall be generated. The Selected_TX_Power return parameter indicates the transmit power selected by the Controller. The Controller shall not change the transmit power for this advertising set without being directed to by the Host.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_ext_adv_data(const sdc_hci_cmd_le_set_ext_adv_data_t *p_params)

LE Set Extended Advertising Data.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.54

The HCI_LE_Set_Extended_Advertising_Data command is used to set the data used in advertising PDUs that have a data field. This command may be issued at any time after an advertising set identified by the Advertising_Handle parameter has been created using the HCI_LE_Set_Extended_Advertising_Parameters command (see Section 7.8.53), regardless of whether advertising in that set is enabled or disabled.

If advertising is currently enabled for the specified advertising set, the Controller shall use the new data in subsequent extended advertising events for this advertising set. If an extended advertising event is in progress when this command is issued, the Controller may use the old or new data for that event.

If advertising is currently disabled for the specified advertising set, the data shall be kept by the Controller and used once advertising is enabled for that set. The data shall be discarded when the advertising set is removed.

Only the significant part of the advertising data should be transmitted in the advertising packets as defined in [Vol 3] Part C, Section 11.

The Host may set the advertising data in one or more operations using the Operation parameter in the command. If the combined length of the data exceeds the capacity of the advertising set identified by the Advertising_Handle parameter (see Section 7.8.57 LE Read Maximum Advertising Data Length command) or the amount of memory currently available, all the data shall be discarded and the Controller shall return the error code Memory Capacity Exceeded (0x07).

If the advertising set uses extended advertising and the combined length of the data is greater than the maximum that the Controller can transmit within the longest possible auxiliary advertising segment consistent with the current parameters of the advertising set (using the current advertising interval if advertising is enabled), all the data shall be discarded and the Controller shall return the error code Packet Too Long (0x45). If advertising on the LE Coded PHY, the S=8 coding shall be assumed. If Operation indicates the start of new data (values 0x01 or 0x03), then any existing partial or complete advertising data shall be discarded.

If the advertising data is discarded by the command or the combined length of the data after the command completes is zero, the advertising set will have no advertising data.

If Operation is 0x04, the behavior is the same as if the current advertising data had been sent again; this can be used to cause the Advertising DID value to be updated (see [Vol 6] Part B, Section 4.4.2.11).

The Fragment_Preference parameter provides a hint to the Controller as to whether advertising data should be fragmented.

If the advertising set specifies a type that does not support advertising data, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the advertising set uses legacy advertising PDUs that support advertising data and either Operation is not 0x03 or the Advertising_Data_Length parameter exceeds 31 octets, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If Operation is 0x04 and: • advertising is currently disabled for the advertising set; • the advertising set contains no data; • the advertising set uses legacy PDUs; or • Advertising_Data_Length is not zero;

then the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If Operation is not 0x03 or 0x04 and Advertising_Data_Length is zero, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If advertising is currently enabled for the specified advertising set and Operation does not have the value 0x03 or 0x04, the Controller shall return the error code Command Disallowed (0x0C).

If advertising is currently enabled for the specified advertising set, the advertising set uses extended advertising, and the length of the data is greater than the maximum that the Controller can transmit within the longest possible auxiliary advertising segment consistent with the current parameters of the advertising set, the Controller shall return the error code Packet Too Long (0x45). If advertising on the LE Coded PHY, the S=8 coding shall be assumed.

If the advertising set corresponding to the Advertising_Handle parameter does not exist, then the Controller shall return the error code Unknown Advertising Identifier (0x42).

Event(s) generated (unless masked away): When the HCI_LE_Set_Extended_Advertising_Data command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_ext_scan_response_data(const sdc_hci_cmd_le_set_ext_scan_response_data_t *p_params)

LE Set Extended Scan Response Data.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.55

The HCI_LE_Set_Extended_Scan_Response_Data command is used to provide scan response data used in scanning response PDUs. This command may be issued at any time after the advertising set identified by the Advertising_Handle parameter has been created using the HCI_LE_Set_Extended_Advertising_Parameters command (see Section 7.8.53) regardless of whether advertising in that set is enabled or disabled.

If advertising is currently enabled for the specified advertising set, the Controller shall use the new data in subsequent extended advertising events for this advertising set. If an extended advertising event is in progress when this command is issued, the Controller may use the old or new data for that event.

If advertising is currently disabled for the specified advertising set, the data shall be kept by the Controller and used once advertising is enabled for that set. The data shall be discarded when the advertising set is removed.

Only the significant part of the scan response data should be transmitted in the advertising packets as defined in [Vol 3] Part C, Section 11.

The Host may set the scan response data in one or more operations using the Operation parameter in the command. If the combined length of the data exceeds the capacity of the advertising set identified by the Advertising_Handle parameter (see Section 7.8.57 LE Read Maximum Advertising Data Length command) or the amount of memory currently available, all the data shall be discarded and the Controller shall return the error code Memory Capacity Exceeded (0x07).

If Operation indicates the start of new data (values 0x01 or 0x03), then any existing partial or complete scan response data shall be discarded.

If the scan response data is discarded by the command or the combined length of the data after the command completes is zero, the advertising set will have no scan response data. The Fragment_Preference parameter provides a hint to the Controller as to whether advertising data should be fragmented.

If the advertising set is non-scannable and the Host uses this command other than to discard existing data, the Controller shall return the error code Invalid HCI Command Parameters (0x12). If the advertising set uses scannable legacy advertising PDUs and either Operation is not 0x03 or the Scan_Response_Data_Length parameter exceeds 31 octets, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If Operation is not 0x03 and Scan_Response_Data_Length is zero, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If advertising is currently enabled for the specified advertising set and Operation does not have the value 0x03, the Controller shall return the error code Command Disallowed (0x0C).

If the advertising set uses extended advertising and the combined length of the data is greater than the maximum that the Controller can transmit within the longest possible auxiliary advertising segment consistent with the current parameters of the advertising set (using the current advertising interval if advertising is enabled), all the data shall be discarded and the Controller shall return the error code Packet Too Long (0x45). If advertising on the LE Coded PHY, the S=8 coding shall be assumed.

If the advertising set uses scannable extended advertising PDUs, advertising is currently enabled for the specified advertising set, and Scan_Response_Data_Length is zero, the Controller shall return the error code Command Disallowed (0x0C).

If the advertising set corresponding to the Advertising_Handle parameter does not exist, then the Controller shall return the error code Unknown Advertising Identifier (0x42).

Event(s) generated (unless masked away): When the HCI_LE_Set_Extended_Scan_Response_Data command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_ext_adv_enable(const sdc_hci_cmd_le_set_ext_adv_enable_t *p_params)

LE Set Extended Advertising Enable.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.56

The HCI_LE_Set_Extended_Advertising_Enable command is used to request the Controller to enable or disable one or more advertising sets using the advertising sets identified by the Advertising_Handle[i] parameter. The Controller manages the timing of advertisements in accordance with the advertising parameters given in the HCI_LE_Set_Extended_Advertising_Parameters command. The Num_Sets parameter is the number of advertising sets contained in the parameter arrays. If Enable and Num_Sets are both set to 0x00, then all advertising sets are disabled.

The Controller shall only start an advertising event when the corresponding advertising set is enabled. The Controller shall continue advertising until all advertising sets have been disabled. This can happen when the Host issues an HCI_LE_Set_Extended_Advertising_Enable command with the Enable parameter set to 0x00 (Advertising is disabled), a connection is created, the duration specified in the Duration[i] parameter expires, or the number of extended advertising events transmitted for the set exceeds the Max_Extended_Advertising_Events[i] parameter.

The Duration[i] parameter indicates the duration for which that advertising set is enabled. The duration begins at the start of the first advertising event of this advertising set. The Controller should not start an extended advertising event that it cannot complete within the duration.

If the advertising is high duty cycle connectable directed advertising, then Duration[i] shall be less than or equal to 1.28 seconds and shall not be equal to 0.

The Max_Extended_Advertising_Events[i] parameter, if non-zero, indicates the maximum number of extended advertising events that shall be sent prior to disabling the extended advertising set even if the Duration[i] parameter has not expired.

Duration[i] and Max_Extended_Advertising_Events[i] shall be ignored when Enable is set to 0x00. If the HCI_LE_Set_Extended_Advertising_Enable command is sent again for an advertising set while that set is enabled, the timer used for the duration and the number of events counter are reset and any change to the random address shall take effect.

Disabling the advertising set identified by the Advertising_Handle[i] parameter does not disable any periodic advertising associated with that set.

Disabling an advertising set that is already disabled has no effect.

If the same advertising set is identified by more than one entry in the Advertising_Handle[i] arrayed parameter, then the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the advertising set corresponding to the Advertising_Handle[i] parameter does not exist, then the Controller shall return the error code Unknown Advertising Identifier (0x42).

The remainder of this section only applies if Enable is set to 0x01.

If Num_Sets is set to 0x00, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the advertising data or scan response data in the advertising set is not complete, the Controller shall return the error code Command Disallowed (0x0C).

If the advertising set uses scannable extended advertising PDUs and no scan response data is currently provided, the Controller shall return the error code Command Disallowed (0x0C).

If the advertising set uses connectable extended advertising PDUs and the advertising data in the advertising set will not fit in the AUX_ADV_IND PDU, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

Note: The maximum amount of data that will fit in the PDU depends on which options are selected and on the maximum length of PDU that the Controller is able to transmit.

If extended advertising is being used and the length of any advertising data or of any scan response data is greater than the maximum that the Controller can transmit within the longest possible auxiliary advertising segment consistent with the chosen advertising interval, the Controller shall return the error code Packet Too Long (0x45). If advertising on the LE Coded PHY, the S=8 coding shall be assumed.

If the advertising set’s Own_Address_Type parameter is set to 0x01 and the random address for the advertising set has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12). If the advertising set’s Own_Address_Type parameter is set to 0x03, the controller’s resolving list did not contain a matching entry, and the random address for the advertising set has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

Event(s) generated (unless masked away): When the HCI_LE_Set_Extended_Advertising_Enable command has completed, an HCI_Command_Complete event shall be generated.

If the Duration[i] parameter is set to a value other than 0x0000, an HCI_LE_Advertising_Set_Terminated event shall be generated when the duration specified in the Duration[i] parameter expires.

If the Max_Extended_Advertising_Events[i] parameter is set to a value other than 0x00, an HCI_LE_Advertising_Set_Terminated event shall be generated when the maximum number of extended advertising events has been transmitted by the Controller.

If the advertising set is connectable and a connection gets created, an HCI_LE_Connection_Complete event shall be generated followed by an HCI_LE_Advertising_Set_Terminated event with the Status parameter set to 0x00.

If the advertising set is for high duty cycle connectable directed advertising that fails to create a connection before the duration expires, an HCI_LE_Connection_Complete event shall be generated with the Status parameter set to the error code Advertising Timeout (0x3C).

Note: If this command is used to disable advertising at about the same time that a connection is established or the advertising duration expires, there is a possible race condition in that it is possible to receive both an HCI_LE_Connection_Complete or HCI_LE_Advertising_Set_Terminated event and the HCI_Command_Complete event for this command.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_max_adv_data_length(sdc_hci_cmd_le_read_max_adv_data_length_return_t *p_return)

LE Read Maximum Advertising Data Length.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.57

The HCI_LE_Read_Maximum_Advertising_Data_Length command is used to read the maximum length of data supported by the Controller for use as advertisement data or scan response data in an advertising event or as periodic advertisement data.

Note: The maximum amount may be fragmented across multiple PDUs (see [Vol 6] Part B, Section 2.3.4.9).

Event(s) generated (unless masked away): When the HCI_LE_Read_Maximum_Advertising_Data_Length command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_number_of_supported_adv_sets(sdc_hci_cmd_le_read_number_of_supported_adv_sets_return_t *p_return)

LE Read Number of Supported Advertising Sets.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.58

The HCI_LE_Read_Number_of_Supported_Advertising_Sets command is used to read the maximum number of advertising sets supported by the advertising Controller at the same time.

Note: The number of advertising sets that can be supported is not fixed and the Controller can change it at any time because the memory used to store advertising sets can also be used for other purposes.

Event(s) generated (unless masked away): When the HCI_LE_Read_Number_of_Supported_Advertising_Sets command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_remove_adv_set(const sdc_hci_cmd_le_remove_adv_set_t *p_params)

LE Remove Advertising Set.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.59

The HCI_LE_Remove_Advertising_Set command is used to remove an advertising set from the Controller.

If the advertising set corresponding to the Advertising_Handle parameter does not exist, then the Controller shall return the error code Unknown Advertising Identifier (0x42). If advertising or periodic advertising on the advertising set is enabled, then the Controller shall return the error code Command Disallowed (0x0C).

Event(s) generated (unless masked away): When the HCI_LE_Remove_Advertising_Set command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_clear_adv_sets(void)

LE Clear Advertising Sets.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.60

The HCI_LE_Clear_Advertising_Sets command is used to remove all existing advertising sets from the Controller.

If advertising or periodic advertising is enabled on any advertising set, then the Controller shall return the error code Command Disallowed (0x0C).

Note: All advertising sets are cleared on HCI reset.

Event(s) generated (unless masked away): When the HCI_LE_Clear_Advertising_Sets command has completed, an HCI_Command_Complete event shall be generated.

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

uint8_t sdc_hci_cmd_le_set_periodic_adv_params(const sdc_hci_cmd_le_set_periodic_adv_params_t *p_params)

LE Set Periodic Advertising Parameters.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.61

The HCI_LE_Set_Periodic_Advertising_Parameters command is used by the Host to set the parameters for periodic advertising.

The Advertising_Handle parameter identifies the advertising set whose periodic advertising parameters are being configured. If the corresponding advertising set does not already exist, then the Controller shall return the error code Unknown Advertising Identifier (0x42).

The Periodic_Advertising_Interval_Min parameter shall be less than or equal to the Periodic_Advertising_Interval_Max parameter. The Periodic_Advertising_Interval_Min and Periodic_Advertising_Interval_Max parameters should not be the same value to enable the Controller to determine the best advertising interval given other activities.

The Periodic_Advertising_Properties parameter indicates which fields should be included in the advertising packet.

If the advertising set identified by the Advertising_Handle specified scannable, connectable, legacy, or anonymous advertising, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the Host issues this command when periodic advertising is enabled for the specified advertising set, the Controller shall return the error code Command Disallowed (0x0C).

If the Advertising_Handle does not identify an advertising set that is already configured for periodic advertising and the Controller is unable to support more periodic advertising at present, the Controller shall return the error code Memory Capacity Exceeded (0x07).

If the advertising set already contains periodic advertising data and the length of the data is greater than the maximum that the Controller can transmit within a periodic advertising interval of Periodic_Advertising_Interval_Max, the Controller shall return the error code Packet Too Long (0x45). If advertising on the LE Coded PHY, the S=8 coding shall be assumed.

Event(s) generated (unless masked away): When the HCI_LE_Set_Periodic_Advertising_Parameters command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_periodic_adv_data(const sdc_hci_cmd_le_set_periodic_adv_data_t *p_params)

LE Set Periodic Advertising Data.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.62

The HCI_LE_Set_Periodic_Advertising_Data command is used to set the data used in periodic advertising PDUs. This command may be issued at any time after the advertising set identified by the Advertising_Handle parameter has been configured for periodic advertising using the HCI_LE_Set_Periodic_Advertising_Parameters command (see Section 7.8.61), regardless of whether periodic advertising in that set is enabled or disabled. If the advertising set has not been configured for periodic advertising, then the Controller shall return the error code Command Disallowed (0x0C).

If periodic advertising is currently enabled for the specified advertising set, the Controller shall use the new data in subsequent periodic advertising events for this advertising set. If a periodic advertising event is in progress when this command is issued, the Controller may use the old or new data for that event.

If periodic advertising is currently disabled for the specified advertising set, the data shall be kept by the Controller and used once periodic advertising is enabled for that set. The data shall be discarded when the advertising set is removed.

Only the significant part of the periodic advertising data should be transmitted in the advertising packets as defined in [Vol 3] Part C, Section 11.

The Host may set the periodic advertising data in one or more operations using the Operation parameter in the command. If the combined length of the data exceeds the capacity of the advertising set identified by the Advertising_Handle parameter (see Section 7.8.57 LE Read Maximum Advertising Data Length command) or the amount of memory currently available, all the data shall be discarded and the Controller shall return the error code Memory Capacity Exceeded (0x07).

If the combined length of the data is greater than the maximum that the Controller can transmit within the current periodic advertising interval (if periodic advertising is currently enabled) or the Periodic_Advertising_Interval_Max for the advertising set (if currently disabled), all the data shall be discarded and the Controller shall return the error code Packet Too Long (0x45). If advertising on the LE Coded PHY, the S=8 coding shall be assumed. If Operation indicates the start of new data (values 0x01 or 0x03), then any existing partial or complete data shall be discarded.

If the periodic advertising data is discarded by the command or the combined length of the data after the command completes is zero, the advertising set will have no periodic advertising data.

If periodic advertising is currently enabled for the specified advertising set and Operation does not have the value 0x03, the Controller shall return the error code Command Disallowed (0x0C).

If the advertising set corresponding to the Advertising_Handle parameter does not exist, then the Controller shall return the error code Unknown Advertising Identifier (0x42).

Event(s) generated (unless masked away): When the HCI_LE_Set_Periodic_Advertising_Data command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_periodic_adv_enable(const sdc_hci_cmd_le_set_periodic_adv_enable_t *p_params)

LE Set Periodic Advertising Enable.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.63

The HCI_LE_Set_Periodic_Advertising_Enable command is used to request the Controller to enable or disable the periodic advertising for the advertising set specified by the Advertising_Handle parameter (ordinary advertising is not affected).

If the advertising set is not currently enabled (see the HCI_LE_Set_Extended_Advertising_Enable command), the periodic advertising is not started until the advertising set is enabled. Once the advertising set has been enabled, the Controller shall continue periodic advertising until the Host issues an HCI_LE_Set_Periodic_Advertising_Enable command with Enable set to 0x00 (periodic advertising is disabled). Disabling the advertising set has no effect on the periodic advertising once the advertising set has been enabled.

The Controller manages the timing of advertisements in accordance with the advertising parameters given in the HCI_LE_Set_Periodic_Advertising_Parameters command.

If the advertising set corresponding to the Advertising_Handle parameter does not exist, the Controller shall return the error code Unknown Advertising Identifier (0x42).

If Enable is set to 0x01 (periodic advertising is enabled) and the periodic advertising data in the advertising set is not complete, the Controller shall return the error code Command Disallowed (0x0C).

If Enable is set to 0x01 and the length of the periodic advertising data is greater than the maximum that the Controller can transmit within the chosen periodic advertising interval, the Controller shall return the error code Packet Too Long (0x45). If advertising on the LE Coded PHY, the S=8 coding shall be assumed.

If Enable is set to 0x01 and the advertising set identified by the Advertising_Handle specified scannable, connectable, legacy, or anonymous advertising, the Controller shall return the error code Command Disallowed (0x0C).

Enabling periodic advertising when it is already enabled can cause the random address to change. Disabling periodic advertising when it is already disabled has no effect.

Event(s) generated (unless masked away): When the HCI_LE_Set_Periodic_Advertising_Enable command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_ext_scan_params(const sdc_hci_cmd_le_set_ext_scan_params_t *p_params)

LE Set Extended Scan Parameters.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.64

The HCI_LE_Set_Extended_Scan_Parameters command is used to set the extended scan parameters to be used on the advertising physical channels.

The Scanning_PHYs parameter indicates the PHY(s) on which the advertising packets should be received on the primary advertising physical channel. The Host may enable one or more scanning PHYs. If the Host specifies a PHY that is not supported by the Controller, including a bit that is reserved for future use, it should return the error code Unsupported Feature or Parameter Value (0x11). The Scan_Type[i], Scan_Interval[i], and Scan_Window[i] parameters array elements are ordered in the same order as the set bits in the Scanning_PHY parameter, starting from bit 0. The number of array elements is determined by the number of bits set in the Scanning_PHY parameter.

The Scan_Type[i] parameter specifies the type of scan to perform.

The Scan_Interval[i] and Scan_Window[i] parameters are recommendations from the Host on how long (Scan_Window[i]) and how frequently (Scan_Interval[i]) the Controller should scan (see [Vol 6] Part B, Section 4.4.3); however the frequency and length of the scan is implementation specific. If the requested scan cannot be supported by the implementation, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

The Own_Address_Type parameter indicates the type of address being used in the scan request packets.

If the Host issues this command when scanning is enabled in the Controller, the Controller shall return the error code Command Disallowed (0x0C).

Event(s) generated (unless masked away): When the HCI_LE_Set_Extended_Scan_Parameters command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_ext_scan_enable(const sdc_hci_cmd_le_set_ext_scan_enable_t *p_params)

LE Set Extended Scan Enable.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.65

The HCI_LE_Set_Extended_Scan_Enable command is used to enable or disable scanning.

The Enable parameter determines whether scanning is enabled or disabled. If it is set to 0x00, the remaining parameters shall be ignored.

The Filter_Duplicates parameter controls whether the Link Layer should filter out duplicate advertising reports (filtering duplicates enabled) to the Host or if the Link Layer should generate advertising reports for each packet received (filtering duplicates disabled). See [Vol 6] Part B, Section 4.4.3.5.

If the Filter_Duplicates parameter is set to 0x00, all advertisements received from advertisers shall be sent to the Host in advertising report events.

If the Filter_Duplicates parameter is set to 0x01, duplicate advertisements should not be sent to the Host in advertising report events until scanning is disabled.

If the Filter_Duplicates parameter is set to 0x02, duplicate advertisements in a single scan period should not be sent to the Host in advertising report events; this setting shall only be used if both Period and Duration are non-zero. If Filter_Duplicates is set to 0x02 and either Period or Duration to zero, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the Duration parameter is zero or both the Duration parameter and Period parameter are non-zero, the Controller shall continue scanning until scanning is disabled by the Host issuing an HCI_LE_Set_Extended_Scan_Enable command with the Enable parameter set to 0x00 (Scanning is disabled). The Period parameter shall be ignored when the Duration parameter is zero.

If the Duration parameter is non-zero and the Period parameter is zero, the Controller shall continue scanning until the duration specified in the Duration parameter has expired.

If both the Duration and Period parameters are non-zero and the Duration is greater than or equal to the Period, the Controller shall return the error code Invalid HCI Command Parameters (0x12). When the Duration and Period parameters are non-zero, the Controller shall scan for the duration of the Duration parameter within a scan period specified by the Period parameter. After the scan period has expired, a new scan period shall begin and scanning shall begin again for the duration specified. The scan periods continue until the Host disables scanning.

If the HCI_LE_Set_Extended_Scan_Enable command with Enable set to 0x01 is sent while scanning is already enabled, the timers used for duration and period are reset to the new parameter values and a new scan period is started. Any change to the Filter_Duplicates setting or the random address shall take effect.

Disabling scanning when it is disabled has no effect.

Note: The duration of a scan period refers to the time spent scanning on both the primary and secondary advertising physical channels. However, expiry of the duration does not prevent the Link Layer from scanning for and receiving auxiliary packets of received advertisements.

If Enable is set to 0x01, the scanning parameters’ Own_Address_Type parameter is set to 0x01 or 0x03, and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

Event(s) generated (unless masked away): When the HCI_LE_Set_Extended_Scan_Enable command has completed, an HCI_Command_Complete event shall be generated.

Zero or more LE Extended Advertising Reports are generated by the Controller based on any advertising packets received and the duplicate filtering in effect. More than one advertising packet may be reported in each HCI_LE_Extended_Advertising_Report event.

At the end of a single scan (Duration non-zero but Period zero), an HCI_LE_Scan_Timeout event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_ext_create_conn(const sdc_hci_cmd_le_ext_create_conn_t *p_params)

LE Extended Create Connection.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.66

The HCI_LE_Extended_Create_Connection command is used to create an ACL connection to a connectable advertiser.

The Initiator_Filter_Policy parameter is used to determine whether the White List is used. If the White List is not used, the Peer_Address_Type and the Peer_Address parameters specify the address type and address of the advertising device to connect to.

The Own_Address_Type parameter indicates the type of address being used in the connection request packets.

The Peer_Address_Type parameter indicates the type of address used in the connectable advertisement sent by the peer.

The Peer_Address parameter indicates the Peer’s Public Device Address, Random (static) Device Address, Non-Resolvable Private Address, or Resolvable Private Address depending on the Peer_Address_Type parameter.

The Initiating_PHYs parameter indicates the PHY(s) on which the advertising packets should be received on the primary advertising physical channel and the PHYs for which connection parameters have been specified. The Host may enable one or more initiating PHYs. If the Host specifies a PHY that is not supported by the Controller, including a bit that is reserved for future use, the latter should return the error code Unsupported Feature or Parameter Value (0x11). The array elements of the arrayed parameters are ordered in the same order as the set bits in the Initiating_PHYs parameter, starting from bit 0. The number of array elements is determined by the number of bits set in the Initiating_PHYs parameter. When a connectable advertisement is received and a connection request is sent on one PHY, scanning on any other PHYs is terminated.

The Scan_Interval[i] and Scan_Window[i] parameters are recommendations from the Host on how long (Scan_Window[i]) and how frequently (Scan_Interval[i]) the Controller should scan (see [Vol 6] Part B, Section 4.5.3); however the frequency and length of the scan is implementation specific. If the requested scan cannot be supported by the implementation, the Controller shall return the error code Invalid HCI Command Parameters (0x12). If bit 1 is set in Initiating_PHYs, the values for the LE 2M PHY shall be ignored.

The Connection_Interval_Min[i] and Connection_Interval_Max[i] parameters define the minimum and maximum allowed connection interval. The Connection_Interval_Min[i] parameter shall not be greater than the Connection_Interval_Max[i] parameter.

The Connection_Latency[i] parameter defines the maximum allowed connection latency (see [Vol 6] Part B, Section 4.5.1).

The Supervision_Timeout[i] parameter defines the link supervision timeout for the connection. The Supervision_Timeout[i] in milliseconds shall be larger than (1 + Connection_Latency[i]) * Connection_Interval_Max[i] * 2, where Connection_Interval_Max[i] is given in milliseconds (see [Vol 6] Part B, Section 4.5.2).

The Min_CE_Length[i] and Max_CE_Length[i] parameters are informative parameters providing the Controller with the expected minimum and maximum length of the connection events. The Min_CE_Length[i] parameter shall be less than or equal to the Max_CE_Length[i] parameter.

Where the connection is made on a PHY whose bit is not set in the Initiating_PHYs parameter, the Controller shall use the Connection_Interval_Min[i], Connection_Interval_Max[i], Connection_Latency[i], Supervision_Timeout[i], Min_CE_Length[i], and Max_CE_Length[i] parameters for an implementation-chosen PHY whose bit is set in the Initiating_PHYs parameter.

If the Host issues this command when another HCI_LE_Extended_Create_Connection command is pending in the Controller, the Controller shall return the error code Command Disallowed (0x0C).

If the Own_Address_Type parameter is set to 0x01 and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the Own_Address_Type parameter is set to 0x03, the Initiator_Filter_Policy parameter is set to 0x00, the controller’s resolving list did not contain a matching entry, and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the Own_Address_Type parameter is set to 0x03, the Initiator_Filter_Policy parameter is set to 0x01, and the random address for the device has not been initialized, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the Initiating_PHYs parameter does not have at least one bit set for a PHY allowed for scanning on the primary advertising physical channel, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

Event(s) generated (unless masked away): When the Controller receives the HCI_LE_Extended_Create_Connection command, the Controller sends the HCI_Command_Status event to the Host. An HCI_LE_Enhanced_Connection_Complete event shall be generated when a connection is created or the connection creation procedure is cancelled. If a connection is created, this event shall be immediately followed by an HCI_LE_Channel_Selection_Algorithm event.

Note: No HCI_Command_Complete event is sent by the Controller to indicate that this command has been completed. Instead, the HCI_LE_Enhanced_Connection_Complete event indicates that this command has been completed.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_periodic_adv_create_sync(const sdc_hci_cmd_le_periodic_adv_create_sync_t *p_params)

LE Periodic Advertising Create Sync.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.67

The HCI_LE_Periodic_Advertising_Create_Sync command is used to synchronize with a periodic advertising train from an advertiser and begin receiving periodic advertising packets.

This command may be issued whether or not scanning is enabled and scanning may be enabled and disabled (see the LE Set Extended Scan Enable command) while this command is pending. However, synchronization can only occur when scanning is enabled. While scanning is disabled, no attempt to synchronize will take place.

The Options parameter is used to determine whether the Periodic Advertiser List is used and whether HCI_Periodic_Advertising_Report events for this periodic advertising train are initially enabled or disabled. If the Periodic Advertiser List is not used, the Advertising_SID, Advertiser Address_Type, and Advertiser Address parameters specify the periodic advertising device to listen to; otherwise they shall be ignored.

The Advertising_SID parameter, if used, specifies the value that must match the Advertising SID subfield in the ADI field of the received advertisement for it to be used to synchronize.

The Skip parameter specifies the maximum number of consecutive periodic advertising events that the receiver may skip after successfully receiving a periodic advertising packet.

The Sync_Timeout parameter specifies the maximum permitted time between successful receives. If this time is exceeded, synchronization is lost.

The Sync_CTE_Type parameter specifies whether to only synchronize to periodic advertising with certain types of Constant Tone Extension (a value of 0 indicates that the presence or absence of a Constant Tone Extension is irrelevant). If the periodic advertising has the wrong type of Constant Tone Extension then: • If bit 0 of Options is set, the Controller shall ignore this address and SID and continue to search for other periodic advertisements. • Otherwise, the Controller shall cancel the synchronization with the error code Unsupported Remote Feature/Unsupported LMP Feature (0x1A).

If the periodic advertiser changes the type of Constant Tone Extension after the scanner has synchronized with the periodic advertising, the scanner’s Link Layer shall remain synchronized.

If the Host sets all the non-reserved bits of the Sync_CTE_Type parameter to 1, the Controller shall return the error code Command Disallowed (0x0C).

Irrespective of the value of the Skip parameter, the Controller should stop skipping packets before the Sync_Timeout would be exceeded.

If the Host issues this command when another HCI_LE_Periodic_Advertising_Create_Sync command is pending (see page 2625), the Controller shall return the error code Command Disallowed (0x0C).

If the Host issues this command with bit 0 of Options not set and with Advertising_SID, Advertising_Address_Type, and Advertiser_Address the same as those of a periodic advertising train that the Controller is already synchronized to, the Controller shall return the error code Connection Already Exists (0x0B).

If the Host issues this command and the Controller has insufficient resources to handle any more periodic advertising trains, the Controller shall return the error code Memory Capacity Exceeded (0x07).

If bit 1 of the Options parameter is set to 1 and the Controller does not support the HCI_LE_Set_Periodic_Advertising_Receive_Enable command, the Controller shall return the error code Connection Failed to be Established / Synchronization Timeout (0x3E).

Event(s) generated (unless masked away): When the HCI_LE_Periodic_Advertising_Create_Sync command has been received, the Controller sends the HCI_Command_Status event to the Host. An HCI_LE_Periodic_Advertising_Sync_Established event shall be generated when the Controller starts receiving periodic advertising packets; until the event is generated, the command is considered to be pending.

When the Controller receives periodic advertising packets then, if reporting is enabled, it sends HCI_LE_Periodic_Advertising_Report events to the Host.

Note: No HCI_Command_Complete event is sent by the Controller to indicate that this command has been completed. Instead, the HCI_LE_Periodic_Advertising_Sync_Established event indicates that this command has been completed.

Note: The HCI_LE_Periodic_Advertising_Sync_Established event can be sent as a result of synchronization being canceled by an HCI_LE_Periodic_Advertising_Create_Sync_Cancel command.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_periodic_adv_create_sync_cancel(void)

LE Periodic Advertising Create Sync Cancel.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.68

The HCI_LE_Periodic_Advertising_Create_Sync_Cancel command is used to cancel the HCI_LE_Periodic_Advertising_Create_Sync command while it is pending.

If the Host issues this command while no HCI_LE_Periodic_Advertising_Create_Sync command is pending, the Controller shall return the error code Command Disallowed (0x0C).

Event(s) generated (unless masked away): When the HCI_LE_Periodic_Advertising_Create_Sync_Cancel command has completed, the Controller sends an HCI_Command_Complete event to the Host.

After the HCI_Command_Complete is sent and if the cancellation was successful, the Controller sends an HCI_LE_Periodic_Advertising_Sync_Established event to the Host with the error code Operation Cancelled by Host (0x44).

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

uint8_t sdc_hci_cmd_le_periodic_adv_terminate_sync(const sdc_hci_cmd_le_periodic_adv_terminate_sync_t *p_params)

LE Periodic Advertising Terminate Sync.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.69

The HCI_LE_Periodic_Advertising_Terminate_Sync command is used to stop reception of the periodic advertising train identified by the Sync_Handle parameter.

If the periodic advertising train corresponding to the Sync_Handle parameter does not exist, then the Controller shall return the error code Unknown Advertising Identifier (0x42).

Following successful completion of this command the Sync_Handle is destroyed.

Event(s) generated (unless masked away): When the HCI_LE_Periodic_Advertising_Terminate_Sync command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_add_device_to_periodic_adv_list(const sdc_hci_cmd_le_add_device_to_periodic_adv_list_t *p_params)

LE Add Device To Periodic Advertiser List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.70

The HCI_LE_Add_Device_To_Periodic_Advertiser_List command is used to add an entry, consisting of a single device address and SID, to the Periodic Advertiser list stored in the Controller. Any additions to the Periodic Advertiser list take effect immediately. If the entry is already on the list, the Controller shall return the error code Invalid HCI Command Parameters (0x12).

If the Host issues this command when an HCI_LE_Periodic_Advertising_Create_Sync command is pending, the Controller shall return the error code Command Disallowed (0x0C).

When a Controller cannot add an entry to the Periodic Advertiser list because the list is full, the Controller shall return the error code Memory Capacity Exceeded (0x07).

Event(s) generated (unless masked away): When the HCI_LE_Add_Device_To_Periodic_Advertiser_List command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_remove_device_from_periodic_adv_list(const sdc_hci_cmd_le_remove_device_from_periodic_adv_list_t *p_params)

LE Remove Device From Periodic Advertiser List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.71

The HCI_LE_Remove_Device_From_Periodic_Advertiser_List command is used to remove one entry from the list of Periodic Advertisers stored in the Controller. Removals from the Periodic Advertisers List take effect immediately.

If the Host issues this command when an HCI_LE_Periodic_Advertising_Create_Sync command is pending, the Controller shall return the error code Command Disallowed (0x0C).

When a Controller cannot remove an entry from the Periodic Advertiser list because it is not found, the Controller shall return the error code Unknown Advertising Identifier (0x42).

Event(s) generated (unless masked away): When the HCI_LE_Remove_Device_From_Periodic_Advertiser_List command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_clear_periodic_adv_list(void)

LE Clear Periodic Advertiser List.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.72

The HCI_LE_Clear_Periodic_Advertiser_List command is used to remove all entries from the list of Periodic Advertisers in the Controller.

If this command is used when an HCI_LE_Periodic_Advertising_Create_Sync command is pending, the Controller shall return the error code Command Disallowed (0x0C).

Event(s) generated (unless masked away): When the HCI_LE_Clear_Periodic_Advertiser_List command has completed, an HCI_Command_Complete event shall be generated.

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

uint8_t sdc_hci_cmd_le_read_periodic_adv_list_size(sdc_hci_cmd_le_read_periodic_adv_list_size_return_t *p_return)

LE Read Periodic Advertiser List Size.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.73

The HCI_LE_Read_Periodic_Advertiser_List_Size command is used to read the total number of Periodic Advertiser list entries that can be stored in the Controller.

Note: The number of entries that can be stored is not fixed and the Controller can change it at any time (e.g., because the memory used to store the list can also be used for other purposes).

Event(s) generated (unless masked away): When the HCI_LE_Read_Periodic_Advertiser_List_Size command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_read_transmit_power(sdc_hci_cmd_le_read_transmit_power_return_t *p_return)

LE Read Transmit Power.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.74

The HCI_LE_Read_Transmit_Power command is used to read the minimum and maximum transmit powers supported by the Controller across all supported PHYs.

Event(s) generated (unless masked away): When the HCI_LE_Read _Transmit_Power command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_privacy_mode(const sdc_hci_cmd_le_set_privacy_mode_t *p_params)

LE Set Privacy Mode.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.77

The HCI_LE_Set_Privacy_Mode command is used to allow the Host to specify the privacy mode to be used for a given entry on the resolving list. The effect of this setting is specified in [Vol 6] Part B, Section 4.7.

When an entry on the resolving list is removed, the mode associated with that entry shall also be removed.

This command shall not be used when address resolution is enabled in the Controller and: • Advertising (other than periodic advertising) is enabled, • Scanning is enabled, or • an HCI_LE_Create_Connection, HCI_LE_Extended_Create_Connection, or HCI_LE_Periodic_Advertising_Create_Sync command is outstanding.

This command may be used at any time when address resolution is disabled in the Controller.

If the device is not on the resolving list, the Controller shall return the error code Unknown Connection Identifier (0x02).

Event(s) generated (unless masked away): When the HCI_LE_Set_Privacy_Mode command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_le_set_periodic_adv_receive_enable(const sdc_hci_cmd_le_set_periodic_adv_receive_enable_t *p_params)

LE Set Periodic Advertising Receive Enable.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.8.88

The HCI_LE_Set_Periodic_Advertising_Receive_Enable command will enable or disable reports for the periodic advertising train identified by the Sync_Handle parameter.

The Enable parameter determines whether reporting is enabled or disabled. If the value is the same as the current state, the command has no effect.

If the periodic advertising train corresponding to the Sync_Handle parameter does not exist, the Controller shall return the error code Unknown Advertising Identifier (0x42).

Event(s) generated (unless masked away): When the HCI_LE_Set_Periodic_Advertising_Receive_Enable command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_lc_disconnect(const sdc_hci_cmd_lc_disconnect_t *p_params)

Disconnect.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.1.6

The HCI_Disconnect command is used to terminate an existing connection. The Connection_Handle command parameter indicates which connection is to be disconnected. The Reason command parameter indicates the reason for ending the connection and is copied into the error code field of the LMP_DETACH PDU on a BR/EDR connection or the error code field of the LL_TERMINATE_IND PDU, or the LL_CIS_TERMINATE_IND PDU on an LE connection. All SCO, eSCO, and CIS connections on a physical link should be disconnected before the ACL connection on the same physical connection is disconnected. If it does not, they will be implicitly disconnected as part of the ACL disconnection.

If this command is used to disconnect a CIS, the connection handle of the CIS and the associated data paths of the CIS shall remain valid.

If this command is issued for a CIS before the Controller has generated the HCI_CIS_Established event for that CIS, the Controller shall return the error code Command Disallowed (0x0C).

Note: The Host can recreate a disconnected CIS at a later point in time using the same connection handle.

Event(s) generated (unless masked away): When the Controller receives the HCI_Disconnect command, it shall send the HCI_Command_Status event to the Host. The HCI_Disconnection_Complete event will occur at each Host when the termination of the connection has completed, and on the local Host also indicates that this command has been completed. The Reason event parameter in the event on the local Host shall be set to the value Connection Terminated by Local Host (0x16), while that on the remote Host shall be set to the value of the Reason command parameter. However, if the termination procedure completes because a timer expires and, therefore, the local Controller cannot determine whether or not the Reason command parameter was received by the remote Controller, the Reason event parameter on the local Host should instead be set to the value LMP Response Timeout / LL Response Timeout (0x22).

Note: No HCI_Command_Complete event will be sent by the Controller to indicate that this command has been completed. Instead, the HCI_Disconnection_Complete event will indicate that this command has been completed.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_lc_read_remote_version_information(const sdc_hci_cmd_lc_read_remote_version_information_t *p_params)

Read Remote Version Information.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.1.23

This command will obtain the values for the version information for the remote device identified by the Connection_Handle parameter. The Connection_Handle shall be a Connection_Handle for an ACL-U or LE-U logical link.

Event(s) generated (unless masked away): When the Controller receives the HCI_Read_Remote_Version_Information command, the Controller shall send the HCI_Command_Status event to the Host. When the Link Manager or Link Layer has completed the sequence to determine the remote version information, the local Controller shall send an HCI_Read_Remote_Version_Information_Complete event to the Host. The HCI_Read_Remote_Version_Information_Complete event contains the status of this command, and parameters describing the version and subversion of the LMP or Link Layer used by the remote device.

Note: No HCI_Command_Complete event will be sent by the Controller to indicate that this command has been completed. Instead, the HCI_Read_Remote_Version_Information_Complete event will indicate that this command has been completed.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_sp_read_rssi(const sdc_hci_cmd_sp_read_rssi_t *p_params, sdc_hci_cmd_sp_read_rssi_return_t *p_return)

Read RSSI.

The description below is extracted from Core_v5.2, Vol 4, Part E, Section 7.5.4

This command reads the Received Signal Strength Indication (RSSI) value from a Controller.

For a BR/EDR Controller, a Connection_Handle is used as the Handle command parameter and return parameter. The RSSI parameter returns the difference between the measured Received Signal Strength Indication (RSSI) and the limits of the Golden Receive Power Range for a Connection_Handle to another BR/EDR Controller. The Connection_Handle shall be a Connection_Handle for an ACL connection. Any positive RSSI value returned by the Controller indicates how many dB the RSSI is above the upper limit, any negative value indicates how many dB the RSSI is below the lower limit. The value zero indicates that the RSSI is inside the Golden Receive Power Range.

Note: How accurate the dB values will be depends on the Bluetooth hardware. The only requirements for the hardware are that the BR/EDR Controller is able to tell whether the RSSI is inside, above or below the Golden Device Power Range.

The RSSI measurement compares the received signal power with two threshold levels, which define the Golden Receive Power Range. The lower threshold level corresponds to a received power between -56 dBm and 6 dB above the actual sensitivity of the receiver. The upper threshold level is 20 dB above the lower threshold level to an accuracy of ±6 dB.

For an AMP Controller, a Physical_Link_Handle is used for the Handle command parameter and return parameter. The meaning of the RSSI metric is AMP type specific and defined in the AMP PALs (see Volume 5).

For an LE transport, a Connection_Handle is used as the Handle command parameter and return parameter. The meaning of the RSSI metric is an absolute receiver signal strength value in dBm to ±6 dB accuracy. If the RSSI cannot be read, the RSSI metric shall be set to 127.

Event(s) generated (unless masked away): When the HCI_Read_RSSI command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_zephyr_read_version_info(sdc_hci_cmd_vs_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.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_zephyr_read_supported_commands(sdc_hci_cmd_vs_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.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_zephyr_write_bd_addr(const sdc_hci_cmd_vs_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.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_zephyr_read_static_addresses(sdc_hci_cmd_vs_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).

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_zephyr_read_key_hierarchy_roots(sdc_hci_cmd_vs_zephyr_read_key_hierarchy_roots_return_t *p_return)

Zephyr Read KEY Hierarchy Roots.

This commands reads the controller specific identify and encryption root keys.

This command shall return the identity root key and encryption root key programmed by the vendor at manufacturing time. If a key is set to all zeros, then the associated key is not available and it should not be used in the key hierarchy.

The identity root key and encryption root key may be used for the controllers public device address or a static random address generated by the host. It shall not be used for static addresses returned by Read_Static_Addresses command that have its dedicated identity root key assigned.

Note: For addresses returned by Read_Static_Addresses with an all zeros identity root key, the returned Identity_Root value may be used. It is however important that it only gets assigned to a single address (either public or static random).

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_zephyr_read_chip_temp(sdc_hci_cmd_vs_zephyr_read_chip_temp_return_t *p_return)

Zephyr Read Chip Temperature.

This commands reads the controller chip temperature.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_zephyr_write_tx_power(const sdc_hci_cmd_vs_zephyr_write_tx_power_t *p_params, sdc_hci_cmd_vs_zephyr_write_tx_power_return_t *p_return)

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

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

The Tx power of the Bluetooth LE radio interface is modified for any low-level link by the controller with a high degree of flexibility. The Bluetooth LE 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.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_zephyr_read_tx_power(const sdc_hci_cmd_vs_zephyr_read_tx_power_t *p_params, sdc_hci_cmd_vs_zephyr_read_tx_power_return_t *p_return)

Zephyr Read Tx Power Level (per Role/Connection) Command.

This command reads the BLE Tx power level.

In contrast to the standardized HCI command, i.e. Read_Transmit_Power_Level, which returns the transmitted power level only for a specified connection handle, this command operates for both connected and unconnected states. It gets the BLE Tx power level for any given handle type (advertiser, scanner, connection) and handle.

Parameters

p_params – [in] Input parameters.
p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_read_supported_vs_commands(sdc_hci_cmd_vs_read_supported_vs_commands_return_t *p_return)

Read Supported Vendor Specific Commands.

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

This command shall return a bitmap of the supported vendor specific commands.

Event(s) generated (unless masked away): When the HCI_Read_Supported_Vs_Commands command has completed, an HCI_Command_Complete event shall be generated.

Parameters

p_return – [out] Extra return parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_llpm_mode_set(const sdc_hci_cmd_vs_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 sdc_hci_cmd_vs_conn_update().

After HCI Reset, this feature is disabled.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_conn_update(const sdc_hci_cmd_vs_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.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_conn_event_extend(const sdc_hci_cmd_vs_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 sdc_hci_cmd_vs_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.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_qos_conn_event_report_enable(const sdc_hci_cmd_vs_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 sdc_hci_subevent_vs_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.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_event_length_set(const sdc_hci_cmd_vs_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 SoftDevice Controller will ensure that the anchor points of master link connections are spaced event_length_us apart.

The default event length is SDC_DEFAULT_EVENT_LENGTH_US.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

uint8_t sdc_hci_cmd_vs_periodic_adv_event_length_set(const sdc_hci_cmd_vs_periodic_adv_event_length_set_t *p_params)

Set event length for periodic advertisers.

Set the allocated event length for new periodic advertisers. The SoftDevice Controller will ensure that the anchor points of periodic advertising events are spaced event_length_us apart. If the advertiser requires less time to transmit all the data, the distance to the next scheduling activity will still be equal to the configured event length. If the advertiser requires more time to transmit all the data, scheduling conflicts may occur.

This API must be called before configuring a periodic advertiser for the event length to be applied.

The default event length is SDC_DEFAULT_EVENT_LENGTH_US.

Parameters

p_params – [in] Input parameters.

Return values

0 – if success.

Returns

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

SoftDevice Controller SoC 

group sdc_soc

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

Typedefs

typedef void (*sdc_soc_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.