Vendor-Specific HCI Commands and Events#

The Silicon Labs HCI and Controller support some vendor-specific commands and events as described in the following two sections. Additional vendor-specific commands can also be implemented, as described in Custom Commands.

Vendor-Specific HCI Commands#

The Silicon Labs HCI and Controller support the following vendor-specific HCI commands.

HCI VS_SiliconLabs_Forcefully_Kill_Connection – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Forcefully_Kill_Connection

0x3f/0x04

handle

status

HCI VS_SiliconLabs_Forcefully_Kill_Connection – Command Parameters#

ParameterSizeDescription

handle

2

Connection handle

status

1

Success (0x0),
Unknown Connection Identifier (0x02)

HCI_VS_SiliconLabs_Set_Connection_Config_Bits – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Set_Connection_Config_Bits

Configure various parameters of the Bluetooth connection.

0x3f/0x05

handleconfig_bits

status

HCI_VS_SiliconLabs_Set_Connection_Config_Bits – Command Parameters#

ParameterSizeDescription

handle

2

Connection handle

config_bits

4

Configure the connection. Supported values:
0x01 – Disable peripheral latency. Peripheral will ignore peripheral latency and treat it as being 0.
0x02 – Disable 1M PHY
0x04 – Disable 2M PHY
0x08 – Disable Coded PHY
These affect PHY-update procedure to allow selecting certain PHYs if remote end indicates support for multiple PHYs.

status

1

Success (0x0),
Unknown Connection Identifier (0x02)

HCI_VS_SiliconLabs_Clear_Connection_Config_Bits – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Clear_Connection_Config_Bits

0x3f/0x06

handle
config_bits

status

HCI_VS_SiliconLabs_Clear_Connection_Config_Bits – Command Parameters#

Parameter

Size

Description

handle

2

Connection handle

config_bits

4

Clears the connection configuration. The supported values are the same as the config_bits in HCI_VS_SiliconLabs_Set_Connection_Config_Bits command.

status

1

Success (0x00),
Unknown Connection Identifier (0x02)

HCI_VS_SiliconLabs_Configure – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Configure

Configure various aspects in Silicon Labs Bluetooth Controller.

0x3f/0x07

key,
length,
data

status

HCI_VS_SiliconLabs_Configure – Command Parameters#

Parameter

Size

Description

key

1

Configuration parameter key.

configuration data length

1

Length of the configuration data field.

data

0-255

Configuration data related to the configuration parameter (key).

status

1

Success (0x0),
Invalid HCI Command Parameters (0x12),
Unknown Advertising Identifier (0x42),
Invalid LL Parameters (0x1E),
Unsupported Feature or Parameter Value (0x11),
Unspecified Error (0x1F)

HCI_VS_SiliconLabs_Configure – Parameter Key#

Configuration parameter key [key value]

Parameters [size]

Description

CONFIG_KEY_HALT [1]

halt [1]

Halt (1) or resume (0) the radio

CONFIG_KEY_PRIORITY_RANGE [2]

rail_mapping_offset [2],
rail_mapping_range[2]

Sets the RAIL priority_mapping offset field of the link layer priority configuration structure to the first byte of the value field. Used with multiprotocol.
See Dynamic Multiprotocol User’s Guide

CONFIG_KEY_SCAN_CHANNELS [3]

channel_map [1]

Set primary channels to be scanned. Only the three least significant bits are meaningful. 0x1 = Channel 37, 0x2 = Channel 38, 0x4 = Channel 39

CONFIG_KEY_SET_FLAGS [4]

flags [4]

Sets the link layer configuration flags. The value is a little endian 32-bit integer. Currently supported flag values:
0x00000001 – Disable Automatic Feature Exchange when peripheral,
0x00000002 – Disable Automatic Feature Exchange when central,
0x00000004 – Enable Completed Packets Event,
0x00000008 – Enable Advertisement Channel Info,
0x00000040 – Enable Raw IQ Sampling mode,
0x00000400 – Enable Host Session Key Generation,

0x00008000 – Disable Auto Data Length Update,
0x00020000 – Enable connection event extension in multitask situations to improve connection throughput,
0x00040000 – Enable the scanner to abort the reception of a packet if it will conflict with another scheduled higher priority task,
0x00080000 – Enable inaccurate sleep clock

CONFIG_KEY_CLR_FLAGS [5]

flags [4]

Clear the link layer configuration flags. The supported values are the same as with CONFIG_KEY_SET_FLAGS.

CONFIG_KEY_SET_AFH_INTERVAL [7]

scanning_interval [1]

Set the AFH scanning interval. The unit is 0.1 secs.

CONFIG_KEY_PERIODIC_ADV_STATUS_EVENT [8]

handle [1],
enable [1]

handle: Advertising handle
enable: Enable (1) or disable (0) status event on the sync advertiser

CONFIG_KEY_SET_PRIORITY_TABLE [9]

scan_min [1],
scan_max [1],
adv_min [1],
adv_max [1],
conn_min [1],
conn_max [1],
init_min [1],
init_max [1],
rail_mapping_offset [1],
rail_mapping_range [1],
reserved [1],
adv_step [1],
scan_step [1],
pawr_tx_min [1],
pawr_tx_max [1],
pawr_rx_min [1],
pawr_rx_max [1]

Configure link layer task priorities.

(1) CONFIG_KEY_SET_RX_PACKET_FILTERING [10]

filter_count [1],
filter_offset [1],
filter_length [1],
filter_bitmask [1],
filter_list [variable]

Enable and configure, or disable, RX packet filtering.
Filter_count: number of template filters in the list. At most four filters can be configured. Setting the value 0 disables the feature, and all other parameters are ignored.
Filter_offset: offset of the field in the received link layer packet where the filters and bitmask are applied. The offset 0 is the first octet after the access address field.
filterLength: The length of the filters and bitmask in octets. All filters and bitmask must be equal in length.
Filter_bitmask: Bitmask of Filter_length octets used for filtering. The LSB must be the first byte. The bitmask must be given in the following format as a byte string: xx:xx:xx:xx:xx:xx
^- LSB MSB -^
The same bitmask is applied to all filter templates.
Filter_list: Up to four filters, Filter_length octets each, used for filtering. The filters must be given the LSB first order. The filtering list must be given in the following format as a byte string: xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx …
^- LSB MSB -^ ^- LSB MSB -^ ^- field1 -^ ^- field2 -^ …

(1) CONFIG_KEY_SET_SIMULTANEOUS_SCANNING [11]

enable [1]

Enable (1) or disable (0) simultaneous 1M and Coded PHY scanning feature.

CONFIG_KEY_SET_CHANNELMAP_FLAGS [12]

flags [4]

Configure channel map flags. Supported flag values:
0x01 – Enable active adaptivity,
0x02 – Enable passive adaptivity
Note: AFH must be enabled to enable adaptivity.

CONFIG_KEY_POWER_CONTROL_GOLDEN_RANGE [16]

golden_rssi_min_1m [1],
golden_rssi_max_1m [1],
golden_rssi_min_2m [1],
golden_rssi_max_2m [1],
golden_rssi_min_coded_s8 [1],
golden_rssi_max_coded_s8 [1],
golden_rssi_min_coded_s2 [1],
golden_rssi_max_coded_s2 [1]

Configure the golden range values of the power control feature

CONFIG_KEY_ACTIVE_SCANNER_BACKOFF_UPPER_LIMIT [17]

backoff_upper_limit [2]

Sets a new maximum for the scanner backoff upper limit. This value is used to mitigate collisions between different scanners in a busy environment. Lower value implies a more aggressive scanner.
Set to 0 for default value (256).
Minimum value: 16
Maximum value: 256

CONFIG_KEY_AFH_RSSI_THRESHOLD [18]

threshold [1]

Configure the cutoff RSSI used to block channels.
Default is -70 dBm.

CONFIG_KEY_AFH_CHANNEL_COOLDOWN [19]

cooldown [2]

Configure the cooldown value when a channel is blocked.
Default is 8 seconds.

CONFIG_KEY_SET_REPORT_ALL_SCAN_RSPS [20]

enable [1]

Enable (1) or disable (0) all received SCAN_RSP reporting

(1) Supported only by EFR32XG22/24 devices.

HCI_VS_SiliconLabs_Get_Timing – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Get_Timing

0x3f/0x08

timers
clear_timers

status

HCI_VS_SiliconLabs_Get_Timing – Command Parameters#

Parameter

Size

Description

timers

1

Select timer.
0 – Start timestamp
1 – Maximum timer value
2 – Number of measurements performed
3 – Total accumulated time

clear_timers

1

0 – Do not clear timers
1 – Clear timers

status

1

Success (0x0)
Unsupported Feature or Parameter Value (0x11)

HCI_VS_SiliconLabs_Change_Periodic_Advertising_Parameters – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Change_Periodic_Advertising_Parameters

0x3f/0x09

advertising_handle
interval_min
interval_max
periodic_advertising_properties
num_subevents
subevent_interval
response_slot_delay
response_slot_spacing
num_response_slots
new_phy
repeat_count

advertising_handle

HCI_VS_SiliconLabs_Change_Periodic_Advertising_Parameters – Command Parameters#

Parameter

Size

Description

advertising_handle

1

Advertising handle

interval_min

2

Minimum periodic advertising interval

Interval_max

2

Maximum periodic advertising interval

periodic_advertising_properties

2

Bitmap describing properties.
- Bit 6: include TX power to advertising PDUs.
- All other bits reserved for future use.

num_subevents

1

Number of subevents in one event

subevent_interval

1

Interval between subevents.

response_slot_delay

1

Delay to the first response slot.

response_slot_spacing

1

Duration of response slot to update

num_response_slots

1

Response slots used.

new_phy

1

New PHY for the PAwR train

repeat_count

1

Number of times the new train parameters is sent on subevents before new set is taken into use

HCI_VS_Siliconlabs_Periodic_Advertising_Set_Info_Transfer – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_Siliconlabs_Periodic_Advertising_Set_Info_Transfer

0x3f/0x0a

source_advertising_handle
service_data
target_advertising_handle
repeat_count
subevents_length
subevents[0]

status

HCI_VS_Siliconlabs_Periodic_Advertising_Set_Info_Transfer – Command Parameters#

Parameter

Size

Description

Source_advertising_handle

1

Advertising handle of the source train

Service_data

2

A value provided by the application for use by the peer device

Target_advertising_handle

1

Advertising handle of the target train

Repeat_count

1

Number of times the new train parameters are sent to synchroniser the new set is taken into use.

Subevents_length

1

Number of subevents in one event to send new train info

subevents

1

Subevents list to send new train info

status

1

Success (0x0)
Memory Capacity Exceeded (0x7)
Unknown Advertising Identifier (0x42)
Invalid HCI Command Parameters (0x12)
Command Disallowed (0xC)

HCI_VS_SiliconLabs_Config_Flags – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Config_Flags

Configure the link layer configuration flags.

0x3f/0x11

set
clr
read

flags
status

HCI_VS_SiliconLabs_Config_Flags – Command Parameters#

Parameter

Size

Description

set

4

Enable the link layer flags. Supported values are listed in Table 4.9, CONFIG_KEY_SET_FLAGS.

clr

4

Clear the link layer flags.

read

4

Return link layer configuration flags with bitmask applied as determined by this field.

flags

4

Return the flags.

status

1

Success (0x0)
Unsupported Feature or Parameter Value (0x11)

HCI_VS_SiliconLabs_Get_Counters – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Get_Counters

Read radio counters.

0x3f/0x12

reset

status

HCI_VS_SiliconLabs_Get_Counters – Command Parameters#

Parameter

Size

Description

reset

1

Reset counters after reading them
1 – yes, 0 – no.

status

1

Success (0x0)

tx_packets

2

Number of transmitted radio packets.

Rx_packets

2

Number of received radio packets.

Crc_errors

2

Number of received packets detected with a CRC error.

Failures

2

Number of radio failures, indicating errors in radio resource scheduling.

HCI_VS_Silabs_Sleep – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_Silabs_Sleep
Enter EM2 sleep mode

0x3f/0x13

sleep

status
sleep

HCI_VS_Silabs_Sleep – Command Parameters#

Parameter

Size

Description

sleep

1

Set to 1 to enter sleep mode. Returns 0 if sleep request unsuccessful.

Status

1

Success (0x0)
Unsupported Feature or Parameter Value (0x11)

HCI_VS_Silabs_Set_Min_Max_TX_Power – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_Silabs_Set_Min_Max_Tx_Power

Set minimum and maximum TX power levels.

0x3f/0x14

min_tx_power
max_tx_power

status

HCI_VS_Silabs_Set_Min_Max_TX_Power – Command Parameters#

Parameter

Size

Description

min_tx_power

2

Minimum TX power to be used. The unit is in deci-dBm and the value must be within the range min_supported_tx_power—max_supported_tx_power. See HCI_VS_SiliconLabs_Read_Current_TX_Power_Configuration

max_tx_power

2

Maximum TX power to be used. The unit is in deci-dBm and the value must be within the range min_supported_tx_power—max_supported_tx_power. See HCI_VS_SiliconLabs_Read_Current_TX_Power_Configuration

status

1

Success (0x0)
Unspecified Error (0x1F)

HCI_VS_Silabs_Set_Cte_Transmit_Enable – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_Silabs_Set_Cte_Transmit_Enable
Enable CTE transmission.

0x3f/0x15

advertising_handle
cte_enable
cte_length
cte_type
cte_count
switching_pattern_len
antenna_ids

status

HCI_VS_Silabs_Set_Cte_Transmit_Enable – Command Parameters#

Parameter

Size

Description

advertising_handle

1

Handle of the advertiser used for CTE transmission.

Cte_enable

1

Enable (1) or disable (0) CTE transmission. If transmission is disabled, the remaining parameters can be omitted.

Cte_length

1

Length of the CTE. Valid range 0x2 – 0x14.

Cte_type

1

Type of the CTE (0x0 or 0x1).

Cte_count

1

CTE count. Valid range 0x1 – 0x10.

Switching_pattern_length

1

Length of the switching pattern.

Antenna_ids

variable

Antenna identifiers for CTE transmission (number of IDs must equal switching_pattern_length).

Status

1

Success (0x0)
Memory Capacity Exceeded (0x7)
Unknown Advertising Identifier (0x42)
Invalid HCI Command Parameters (0x12)
Unsupported Feature or Parameter Value (0x11)

HCI_VS_Silabs_Set_Iq_Sampling_Enable – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_Silabs_Set_Iq_Sampling_Enable
Enable SiliconLabs proprietary IQ sampling.
For further information, refer to the following documents:
For further information, refer to the following documents:
Bluetooth® Direction Finding Fundamentals
Silicon Labs Direction-Finding Solution Quick-Start Guide
Application Development with Silicon Labs’ RTL Library

0x3f/0x16

sampling_enable
slot_durations
max_sampled_ctes
switching_pattern_len
antenna_ids

status

HCI_VS_Silabs_Set_Iq_Sampling_Enable – Command Parameters#

Parameter

Size

Description

sampling_enable

1

Enable (1) or disable (0) IQ sampling. If sampling is disabled, the remaining parameters can be omitted.

Slot_durations

1

CTE slot durations.

Max_sampled_ctes

1

Currently always 0.

Switching_pattern_length

1

Length of the switching pattern.

Antenna_ids

variable

Antenna identifiers for IQ sampling (number of IDs must equal switching_pattern_length).

Status

1

Success (0x0)
Memory Capacity Exceeded (0x7)
Invalid HCI Command Parameters (0x12)
Unsupported Feature or Parameter Value (0x11)

HCI_VS_Silabs_Read_Current_TX_Power_Configuration – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_Silabs_Read_Current_TX_Power_Configuration
Read the TX power range supported by the radio, and the current TX power configuration.

0x3f/0x17

-

Status
min_supported_tx_power
max_supported_tx_power
min_configured_tx_power
max_configured_tx_power
tx_rf_path_compensation

HCI_VS_Silabs_Read_Current_TX_Power_Configuration – Command Parameters#

Parameter

Size

Description

status

1

Success (0x0)

min_supported_tx_power

2

Minimum TX power supported by the radio. The unit is deci-dBm.

Max_support_tx_power

2

Maximum TX power supported by the radio. The unit is deci-dBm

min_configured_tx_power

2

Minimum TX power configured to be used. The unit is in deci-dBm and value must be within the range min_supported_tx_power—max_supported_tx_power.

Max_configured_tx_power

2

Maximum TX power configured to be used. The unit is in deci-dBm and value must be within the range min_supported_tx_power—max_supported_tx_power.

Tx_rf_path_compensation

2

Currently configured TX RF path compensation in deci-dBms.

HCI_VS_Silabs_Enter_Bootloader_Mode – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_Silabs_Enter_Bootloader_Mode
Set Controller to bootloader mode and reset it, for example for firmware update purposes.

0x3f/0x18

-

-

Note: the controller does not reply with a Command Complete event.

HCI_VS_SiliconLabs_Set_Advertising_Config_Bits – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Set_Advertising_Config_Bits

0x3f/0x19

advertising_handle
config_bits

status

HCI_VS_SiliconLabs_Set_Advertising_Config_Bits – Command Parameters#

Parameter

Size

Description

advertising_handle

1

Advertising handle

config_bits

4

0x00000001 – Force public address usage in advertising packets.
0x00000002 – Include advertising address in advertising packets.
0x00000004 – Include advertising TX power in advertising packets.

Status

1

Success (0x0)
Unknown Advertising Identifier (0x42)

HCI_VS_SiliconLabs_Clear_Advertising_Config_Bits – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Clear_Advertising_Config_Bits

0x3f/0x1a

advertising_handle
config_bits

-

HCI_VS_SiliconLabs_Clear_Advertising_Config_Bits – Command Parameters#

Parameter

Size

Description

advertising_handle

1

Advertising handle

config_bits

4

0x00000001 – Remove requirement of public address usage in advertising packets.
0x00000002 – Remove advertising address from advertising packets.
0x00000004 – Remove advertising TX power from advertising packets.

Status

1

Success (0x0)
Unknown Advertising Identifier (0x42)

HCI_VS_SiliconLabs_Set_Max_Low_Tx_Power – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Set_Max_Low_Tx_Power
Set the maximum power in low-power mode for each PHY.

0x3f/0x1b

max_1m_low_power
max_2m_low_power
max_125k_low_power
max_500k_low_power

-

HCI_VS_SiliconLabs_Set_Max_Low_Tx_Power – Command Parameters#

Parameter

Size

Description

max_1m_low_power

2

The maximum power in low-power mode (DTS mode) for 1M PHY set to a level allowed by the region.

max_2m_low_power

2

The maximum power in low-power mode (DTS mode) for 2M PHY set to a level allowed by the region.

max_125k_low_power

2

The maximum power in low-power mode (DTS mode) for 125k PHY set to a level allowed by the region.

max_500k_low_power

2

The maximum power in low-power mode (DTS mode) for 500k PHY set to a level allowed by the region.

HCI_VS_SiliconLabs_Allocate_Connections – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Allocate_Connections
Allocates memory for connection descriptors.

0x3f/0x20

num_connections

-

HCI_VS_SiliconLabs_Allocate_Connections – Command Parameter#

Parameter

Size

Description

num_connections

1

The number of connections for which memory will be allocated.

HCI_VS_SiliconLabs_Allocate_Advertisers – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Allocate_Advertisers
Allocates memory for advertiser descriptors.

0x3f/0x21

num_advertisers

-

HCI_VS_SiliconLabs_Allocate_Advertisers – Command Parameter#

Parameter

Size

Description

num_advertisers

1

The number of advertisers for which memory will be allocated.

HCI_VS_SiliconLabs_Allocate_Addresses – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Allocate_Addresses
Allocates memory for stored addresses.

0x3f/0x22

num_addresses

-

HCI_VS_SiliconLabs_Allocate_Addresses – Command Parameter#

Parameter

Size

Description

num_addresses

1

The number of addresses for which memory will be allocated.

HCI_VS_SiliconLabs_Allocate_PeriodicAdv – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Allocate_PeriodicAdv

Allocates memory for periodic advertiser descriptors.

0x3f/0x23

num_periodicadv

-

HCI_VS_SiliconLabs_Allocate_PeriodicAdv – Command Parameter#

ParameterSizeDescription
num_periodicadv1The number of periodic advertisers for which memory will be allocated.

HCI_VS_SiliconLabs_Allocate_PeriodicScan – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Allocate_PeriodicScan

Allocates memory for periodic advertisement synchronization descriptors.

0x3f/0x24

num_periodicscan

-

HCI_VS_SiliconLabs_Allocate_PeriodicScan – Command Parameter#

ParameterSizeDescription
num_periodicscan1The number of periodic advertisement synchronizations for which memory will be allocated.

HCI_VS_SiliconLabs_Deinit – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Deinit

De-initializes the Bluetooth Controller and frees up allocated memory.

0x3f/0x25

-

-

HCI_VS_SiliconLabs_MemBufResize – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_MemBufResize

Allocates memory for periodic advertisement synchronization descriptors.

0x3f/0x26

buffer_memory

status
buffers_allocated

HCI_VS_SiliconLabs_MemBufResize – Command Parameters#

Parameter

Size

Description

buffer_memory

4

Size of memory to allocate

status

1

Success (0x0),
Unspecified Error (0x1F)

buffers_allocated

4

Number of memory buffers allocated

HCI_VS_SiliconLabs_ExtScanPHYsAllowed – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_ExtScanPHYsAllowed

Sets the used PHYs used for scanning for external advertisements, Aux Pointer will not be followed unless it has one of the allowed PHYs.
If a given PHY is not supported by the device, bt_err_invalid_command_parameters will be returned

0x3f/0x27

phys

status

HCI_VS_SiliconLabs_ExtScanPHYsAllowed – Command Parameters#

Parameter

Size

Description

phys

1

Bitfield:
ll_phy_1M = 1
ll_phy_2M = 2,
ll_phy_Coded = 4

status

1

Success (0x0),
Invalid HCI Command Parameters (0x12)

HCI_VS_SiliconLabs_Set_Public_Address – Command#

CommandCommand Value (OGF/OCF)Command ParametersReturn Parameters
HCI_VS_SiliconLabs_Set_Public_Address0x3f/0x28bdaddr[6]status

HCI_VS_SiliconLabs_Set_Public_Address – Command Parameters#

ParameterSizeDescription
bdaddr[6]1Address to set the public address.
If NULL, device unique address is used.
status1Success (0x0)

HCI_VS_SiliconLabs_Periodic_Advertising_Update_Sync_Parameters – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Periodic_Advertising_Update_Sync_Parameters

0x3f/0x29

sync_handle
skip
sync_timeout

status

HCI_VS_SiliconLabs_Periodic_Advertising_Update_Sync_Parameters – Command Parameters#

Parameter

Size

Description

sync_handle

2

Periodic advertising sync handle

skip

2

New value for the skip parameter

sync_timeout

2

New timeout value

status

1

Success (0x0),
Invalid HCI Command Parameters (0x12),
Command Disallowed (0xC),
Unknown Advertising Identifier (0x42)

HCI_VS_SiliconLabs_Get_Conn_Params – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Get_Conn_Params

Get the Bluetooth connection parameters.

0x3f/0x2a

handle

status
interval
access_address,
crc_init.
start_time,
event_counter,
channel,
flags,
hop,
central_phy,
peripheral_phy,
channel_map[5],
central_sca
supervision_timeout

HCI_VS_SiliconLabs_Get_Conn_Params – Command Parameters#

Parameter

Size

Description

handle

2

Connection handle

status

1

Success (0x0),
Command Disallowed (0xC)

interval

2

Connection interval

access_address

4

Access Address Field of packet

crc_init

4

Value used to initialize the CRC algorithm

start_time

4

Start time of the connection task

event_counter

2

Number of connection events

channel

1

Channel on which next event will occur

flags

1

Bit 1 set if Channel Selection Algorithm #2 in use

hop

1

Channel hop value

central_phy

1

PHY in use on Central device

peripheral_phy

1

PHY in use on Peripheral device

channel_map[5]

1

Bitmap of valid channels

Central_sca

1

Sleep clock accuracy

Supervision_timeout

2

Connection supervision timeout configured for the connection

HCI_VS_SiliconLabs_Allocate_ResolvingList – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Allocate_ResolvingList

Allocates memory for the resolving list.

0x3f/0x2c

entries

-

HCI_VS_SiliconLabs_Set_CS_Antenna_Config – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Set_CS_Antenna_Config

Set the distance offset of antenna(s) for channel sounding.

0x3f/0x2d

num_antenna_elements
antenna_element_offset[]

status

HCI_VS_SiliconLabs_Set_CS_Antenna_Config – Command Parameters#

Parameter

Size

Description

num_antenna_elements

1

Number of antennas

antenna_element_offset[]

2

Antenna offset in cm. Array size is length of antenna elements.

status

1

Success (0x0),
Unspecified Error (0x1F)

HCI_VS_SiliconLabs_Allocate_PawrAdv – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Allocate_PawrAdv

Allocates memory for PAwR advertisers.

0x3f/0x2e

num_pawradv

status

HCI_VS_SiliconLabs_Allocate_PawrAdv – Command Parameter#

Parameter

Size

Description

num_pawradv

1

Allocate memory to the specified number of PAwR advertisers

status

1

Success (0x0),
No More Resource (0x1A)

HCI_VS_SiliconLabs_Allocate_PawrSync – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Allocate_PawrSync
Allocates memory for PAwR synchronizers.

0x3f/0x2f

num_pawrsync

status

HCI_VS_SiliconLabs_Allocate_PawrSync – Command Parameter#

Parameter

Size

Description

num_pawrsync

1

Allocate memory to the specified number of PAwR synchronizers.

Status

1

Success (0x0),
Memory Capacity Exceeded (0x7)

HCI_VS_Siliconlabs_Set_Connection_Tx_Power – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_Siliconlabs_Set_Connection_Tx_Power

0x3f/0x30

handle
tx_power

tx_power

HCI_VS_Siliconlabs_Set_Connection_Tx_Power – Command Parameters#

Parameter

Size

Description

handle

2

Connection handle

Tx_power

2

TX power in deci-dBm

status

1

Success (0x0),
Unknown Connection Identifier (0x02)

HCI_VS_SiliconLabs_Read_Connection_Statistics – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Read_Connection_Statistics

0x3f/0x31

handle
reset

-

HCI_VS_SiliconLabs_Read_Connection_Statistics – Commands Parameters#

ParameterSizeDescription
handle2Connection handle
reset1Reset the connection parameters

HCI_VS_SiliconLabs_Sniff_Connection_Packets – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Sniff_Connection_Packets

Sniff Bluetooth LE connection packets based on the provided connection settings.

0x3f/0x32

interval
access_address
crc_init
start_time
event_counter
channel
options
hop
central_phy
peripheral_phy
channel_map[5]
central_sca
supervision_timeout

sniffer_handle

HCI_VS_SiliconLabs_Sniff_Connection_Packets – Command Parameters#

Parameter

Size

Description

interval

2

Connection interval

access_address

4

Access Address Field of packet

crc_init

4

Value used to initialize the CRC algorithm

start_time

4

Start time of the connection task

event_counter

2

Number of connection events

channel

1

Channel on which next event will occur

options

1

Bit 1 – Channel Selection Algorithm #2 in use
Bit 2 – Ignore start_time parameter

hop

1

Channel hop value

central_phy

1

PHY in use on Central device

peripheral_phy

1

PHY in use on Peripheral device

channel_map[5]

1

Bitmap of valid channels

central_sca

1

Sleep clock accuracy

supervision_timeout

2

Connection supervision timeout

sniffer_handle

1

Index of sniffer

HCI_VS_SiliconLabs_Get_Stack_Space – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Get_Stack_Space

0x3f/0x33

-

transport_thr_stack_space
linklayer_thr_stack_space
status

HCI_VS_SiliconLabs_Get_Stack_Space – Command Parameters#

Parameter

Size

Description

transport_thr_stack_space

4

Stack space of transport thread in a RTOS

linklayer_thr_stack_space

4

Stack space of link layer thread in a RTOS

status

1

Success (0x0)
Command Disallowed (0xC)

HCI_VS_SiliconLabs_Stop_Sniff_Connection_Packets – Command#

CommandCommand Value (OGF/OCF)Command ParametersReturn Parameters
HCI_VS_SiliconLabs_Stop_Sniff_Connection_Packets0x3f/0x34sniffer_handlestatus

HCI_VS_SiliconLabs_Stop_Sniff_Connection_Packets – Command Parameters#

Parameter

Size

Description

sniffer_handle

1

Index of sniffer to stop

status

1

Success (0x0)
Invalid HCI Command Parameters (0x12)

HCI_VS_SiliconLabs_Read_AFH_Channel_Map_Quality – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Read_AFH_Channel_Map_Quality

Read the channel map quality when AFH is enabled and the passive adaptivity channel map flag is enabled

0x3f/0x35

operation_mode

status
quality_map

HCI_VS_SiliconLabs_Read_AFH_Channel_Map_Quality – Command Parameters#

Parameter

Size

Description

mode

1

Operation mode to select what the output will contain
0x00 – Get channel quality map; error otherwise

status

1

Success (0x0)
Invalid HCI Command Parameters (0x12)
Command Disallowed (0xC)

quality_map

40

Channel map quality score for each data channel (first 37 bytes) and the 3 advertisement channels (last 3 bytes)
Active channel quality range: [-112,80]
Blocked channel quality: -127

HCI_VS_SiliconLabs_Event_Info_Reporting_Enable – Command#

Command

Command Value (OGF/OCF)

Command Parameters

Return Parameters

HCI_VS_SiliconLabs_Event_Info_Reporting_Enable

Enable event info reporting

0x3f/0x36

enable
configuration
procedure_type
procedure_identifier_length
procedure_identifier[]

status
procedure_type
procedure_identifier_length
procedure_identifier[]

HCI_VS_SiliconLabs_Event_Info_Reporting_Enable – Command Parameters#

Parameter

Size

Description

enable

1

Enable (1) or disable (0) event info reporting

configuration

4

Bitfield for configuration options
0x000001 - PAwR event counter

procedure_type

1

Type of procedure for reporting
0 - PAwR ADV

procedure_identifier_length

1

Length of procedure identifier data array for the procedure type
0x02 - PAwR ADV

procedure_identifier[]

1

Procedure identifier data
PAwR ADV:
Byte 1 - Advertising handle
Byte 2 - Subevent

status

1

Success (0x0)
Invalid HCI Command Parameters (0x12)
Memory Capacity Exceeded (0x7)

response: procedure_type

1

Type of procedure

response: procedure_identifier_length

1

Length of procedure identifier array

response: procedure_identifier[]

variable

Procedure identifier data

Vendor-Specific HCI Events#

The Silicon Labs HCI and Controller support the following vendor-specific HCI events.

Note: The vendor-specific events use the Vendor-Specific HCI Event code (0xFF). The first event parameter, subevent_code, contains the vendor-specific subevent identifier (subcode) that selects the concrete event. Legacy behaviour of using 0x3F as vendor specific event code can be configure by SL_BT_CONTROLLER_USE_LEGACY_VENDOR_SPECIFIC_EVENT_CODE option in HCI controller configuration.

HCI_Event_Le_Silabs_IQ_Report – Event#

Event

Event Value

Event Parameters

HCI_Event_Le_Silabs_IQ_Report
Receive SiliconLabs proprietary IQ sampling reports.
For further information, refer to the following documents:
Bluetooth® Direction Finding Fundamentals
Silicon Labs Direction-Finding Solution Quick-Start Guide
Application Development with Silicon Labs’ RTL Library

0xff

subevent_code
address_type
address
rx_phy
channel_index
rssi
rssi_antenna_id
cte_type
slot_durations
packet_status
packet_counter
sample_count
sample

HCI_Event_Le_Silabs_IQ_Report – Event Parameters#

ParameterSizeDescription
subevent_code1Vendor-specific subevent identifier (subcode) for this event. Value: 0xEE.
address_type1Bluetooth address type
address6Bluetooth address
rx_phy1Used PHY
channel_index1Channel index for the report.
rssi1RSSI
rssi_antenna_id1ID of the antenna where the samples are collected.
cte_type1CTE type
slot_durations1Slot duration
packet_status1Status of received packets
packet_counter2Number of received packets
sample_count1Number of samples
samplevariableIQ samples

HCI_Event_Le_Silabs_Sk_Request – Event#

Event

Event Value

Event Parameters

HCI_Event_Le_Silabs_Sk_Request

Request for host to generate session key.

0xff

subevent_code
Handle
RandomDiversifier
SKD

HCI_Event_Le_Silabs_Sk_Request – Event Parameters#

ParameterSizeDescription
subevent_code1Vendor-specific subevent identifier (subcode) for this event. Value: 0xED.
Handle2Connection handle
Random1Random data
Diversifier2Encryption diversifier
SKD1Session key diversifier

HCI_Event_VS_SiliconLabs_Connection_Statistics Event#

Event

Event Value

Event Parameters

HCI_Event_VS_SiliconLabs_Connection_Statistics

Statistics report of a connection.

0xff

subevent_code
handle
rssi_min
rssi_max
events_total
events_success
events_missed
crc_errors

HCI_Event_VS_SiliconLabs_Connection_Statistics Event Parameters#

Parameter

Size

Description

subevent_code

1

Vendor-specific subevent identifier (subcode) for this event. Value: 0xEF.

handle

2

Connection handle

rssi_min

1

Minimum RSSI received in connection packets.
0x7f if RSSI is unknown.

rssi_max

1

Maximum RSSI receiver in connection packets.
-0x7f if RSSI is unknown.

events_total

4

Total number of connection events

events_success

4

Number of successful connection events

events_missed

4

Number of missed connection events

crc_errors

4

Increased when packet with bad crc is received

HCI_Event_Le_Silabs_Sniff_Connection – Event#

Event

Event Value

Event Parameters

HCI_Event_Le_Silabs_Sniff_Connection

Report of the sniffed connection.

0xff

subevent_code
central_rssi
peripheral_rssi
flags
sniffer_handle

HCI_Event_Le_Silabs_Sniff_Connection – Event Parameters#

ParameterSizeDescription
subevent_code1Vendor-specific subevent identifier (subcode) for this event. Value: 0xF0.
central_rssi1Central packet RSSI
peripheral_rssi1Peripheral packet RSSI
flags1Sniffer flags
sniffer_handle1Sniffer instance handle

HCI_Event_Le_Silabs_Sniff_Complete – Event#

Event

Event Value

Event Parameters

HCI_Event_Le_Silabs_Sniff_Complete

Received when connection sniffing is complete.

0xff

subevent_code
sniffer_handle
reason

HCI_Event_Le_Silabs_Sniff_Complete – Event Parameters#

ParameterSizeDescription
subevent_code1Vendor-specific subevent identifier (subcode) for this event. Value: 0xF1.
sniffer_handle1Index of sniffer
reason1Reason to stop

HCI_Event_ VS_Siliconlabs_Periodic_Advertising_Sync_Transfer_Received – Event#

Event

Event Value

Event Parameters

HCI_Event_
VS_Siliconlabs_Periodic_Advertising_Sync_Transfer_Received

Received when the periodic advertising sync parameters are changed or the receiver drops the current synchronizer and establishes a new one

0xff

subevent_code
status
receiving_sync_handle
service_data
sync_handle
advertising_sid
advertiser_address_type
advertiser_address
advertiser_phy
periodic_advertising_interval
advertiser_clock_accuracy
num_subevents
subevent_interval
response_slot_delay
response_slot_spacing

HCI_Event_ VS_Siliconlabs_Periodic_Advertising_Sync_Transfer_Received – Event Parameters#

ParameterSizeDescription
subevent_code1Vendor-specific subevent identifier (subcode) for this event. Value: 0xEC.
status1Status when device tried to synchronize
receiving_sync_handle2The sync handle after synchronization established
service_data2Identification of PAwR train
sync_handle2Sync handle for the sync
avertising_sid1Advertising SID
advertiser_address_type1Type of advertiser
advertiser_address1Advertiser’s address
advertiser_phy1Advertiser’s PHY
periodic_advertising_interval2Periodic advertising interval
advertiser_clock_accuracy1Advertiser’s sleep clock accuracy
num_subevents1Number of subevents in PAwR train
subevent_interval1Subevent interval
response_slot_delay1Response slot delay
response_slot_spacing1Response slot spacing

HCI_VS_SiliconLabs_Event_Info_Report - Event#

Event

Event Value

Event Parameters

HCI_VS_SiliconLabs_Event_Info_Report


Report of the event information

0xff

subevent_code
configuration
procedure_type
procedure_identifier_length
procedure_identifier
event_info_length
event_info

HCI_VS_SiliconLabs_Event_Info_Report - Event Parameters#

Parameter Size Description
subevent_code 1 Vendor-specific subevent identifier (subcode) for this event. Value: 0xF2.
configuration 4 Configuration value
procedure_type 1 Type of procedure
procedure_identifier_length 1 Length (in bytes) of procedure_identifier.
procedure_identifier Variable Procedure identifier. Length is procedure_identifier_length bytes.
event_info_length 1 Length (in bytes) of event_info.
event_info Variable Event information. Length is event_info_length bytes.

Custom Commands#

On RCP builds it is possible to hook custom message handlers to the message processing. The Application needs to allocate the sl_btctrl_command_handler_t structure in the heap and implement a callback function. The stack adds this to the list of message handlers, and calls it during message processing. When the handler receives a message, if it does not handle it must return false. If the message is processed, the handler must return true. If no handler handles the HCI command, then a Command Complete event with 0x01 (Unknown HCI Command) is returned to the host.

Silicon Labs uses opcodes starting from 0xfc00 forward. To prevent collisions with these opcodes, use opcodes starting from 0xff00 in your applications.

Example#

This example implements a simple vendor-specific HCI command with opcode 0xff00 that receives a 32-bit number, then returns the same number increased by one.

  1. Include this header in the application file:

    #include "sl_btctrl_hci_handler.h"
  2. Allocate the structure in heap:

    struct sl_btctrl_command_handler custom_handler;
  3. Implement the callback function:

    bool custom_message_handler(struct sl_btctrl_hci_message * msg)
    {
        uint16_t opcode;
        if(sl_btctrl_hci_message_get_opcode(msg, &opcode) != SL_STATUS_OK){
            return false;
        }
        size_t length;
        if(sl_btctrl_hci_message_get_length(msg, &length) != SL_STATUS_OK){
            return false;
        }
    
        switch(opcode)
        {
            case 0xff00:{
                uint32_t params;
                    if(sl_btctrl_hci_message_get_parameters(msg, (uint8_t*)&params, sizeof(params)) != SL_STATUS_OK){
                        sl_btctrl_hci_message_set_response(msg, 0x12, NULL, 0);
                        // 0x12 is "Invalid HCI Command Parameters"-error.
                        // Set response only fails if NULL pointers or too long data is passed
                    }else{
                        params++;//Increase
                        sl_btctrl_hci_message_set_response(msg, 0x0, (uint8_t*)&params, sizeof(params));
                    }
            }
            return true;//Command is handled
            }
        return false;
        ```
    
  4. Register handler in startup code:

sl_btctrl_hci_register_handler(&custom_handler, &custom_message_handler);

Custom Commands Provided as Software Components#

Some Silicon Labs specific features are provided as software components. They implement custom command handling for different functionalities.

HCI Get Version#

Add the software component HCI Get Version Vendor Specific Command to the project. The Opcode for this vendor specific command can be defined in the component. By default, it is 0xFF10.

Return parameters:

ParameterSizeDescription
major2The major version number
minor2The minor version number
patch2The patch version number
build2The build number of the version

The return parameter structure is defined in the file sl_bt_hci_version_config.h.

HCI Coex#

Add the component HCI Coex Vendor Specific Commands to the project. The Opcodes for this vendor specific command can be defined in the component.

The provided commands have the same inputs and return parameters as the Coex commands defined in SoC projects: https://docs.silabs.com/bluetooth/latest/bluetooth-stack-api/sl-bt-coex

HCI Extended Advertisement Filtering#

Add the software components HCI Event(s) Filtering and HCI Extended Advertisement Filtering in the project to enable filtering of advertisements using RSSI and/or UUID (16-bit and 32-bit).

HCI Extended Advertisment Filtering 1HCI Extended Advertisment Filtering 1

The default filter configuration can be set in the HCI Extended Advertisement Filtering component configuration, if needed.

Note: The number of UUIDs to be included in the advertisement report must be configured in the component in order to allocate the memory for the maximum UUID array size.

HCI Extended Advertisement Filtering 2HCI Extended Advertisement Filtering 2

The Opcode for this vendor specific command can be defined in the component. By default, it is 0xFF11.

Command parameters:

Parameter

Size

Description

filter_config

4

Bitmap that holds configuration of the filter
0x00000001 – Enable RSSI filtering
0x00000002 – Enable filtering of 16-bit Service Data UUIDs
0x00000004 – Enable filtering of Incomplete Lists of 16-bit Service Class UUIDs
0x00000008 - Enable filtering of Complete Lists of 16-bit Service Class UUIDs
0x00000010 - Enable 32-bit Service Data UUID filtering
0x00000020 – Enable filtering of Incomplete Lists of 32-bit Service Class UUIDs
0x00000040 - Enable filtering of Complete Lists of 32-bit Service Class UUIDs

rssi_threshold

1

Threshold value in dBm for RSSI when event filtering by RSSI is enabled

uuid_array_length

1

Array length of 16-bit UUID array. Must be less than or equal to SL_BT_HCI_FILTER_16BIT_UUID_ARRAY_LEN

uuid_array [ ]

variable

16-bit UUID array. Array size is the length set for 16-bit UUID array

uuid_array_length

1

Array length of 32-bit UUID array. Must be less than or equal to SL_BT_HCI_FILTER_32BIT_UUID_ARRAY_LEN

uuid_array [ ]

variable

32-bit UUID array. Array size is the length set for 32-bit UUID array