Max 31 bytes
1s – 11.5 hours
Conn Complete
Global + Per-Link
Sections 9.2.6 to 9.2.11 — The Operational Commands
The previous files covered command groups that initialise and configure the controller at startup (Device Setup, Controller Flow Control, Host Flow Control, White List, Resolving List, Controller Information, Remote Information). This file covers the groups that drive actual BLE operation: setting up advertising, running a scan, making connections, updating them mid-flight, and reading link-quality information.
These are the commands your application code calls every time it does anything on a BLE link.
9.2.6 — Controller Configuration
Controller configuration commands are how the host tells the controller everything it needs to know before advertising can start. There is a specific order these must be called in — advertising parameters and data must be set before advertising is enabled. Calling enable first without setting parameters first will use default values, which may not match what the application needs.
HCI_LE_Set_Advertising_Parameters
Sets everything about how advertising will work. The controller will use these values for every advertising event until this command is called again. Key parameters include:
HCI_LE_Set_Advertising_Data
Loads the payload that goes inside every ADV_IND, ADV_NONCONN_IND, or ADV_SCAN_IND packet the controller broadcasts. The host provides up to 31 bytes of advertising data in the standard AD Structure format (each structure has a length byte, a type byte, and the data). Typical content includes the device name, service UUIDs, TX power level, and manufacturer-specific data. This data stays in the controller’s memory until overwritten.
HCI_LE_Set_Scan_Response_Data
Similar to advertising data, but this payload is sent inside SCAN_RSP packets — the responses to active scan requests. Also up to 31 bytes. The split between advertising data and scan response data lets the device advertise a compact summary (ADV_IND payload) and provide extra detail only when a scanner actively asks for it (SCAN_RSP payload). A common pattern: put the service UUID in the ADV_IND data and put the full device name in the SCAN_RSP data.
HCI_LE_Set_Advertise_Enable
The on/off switch. One byte parameter: 0x01 starts advertising, 0x00 stops it. The controller keeps all parameters and data from the previous commands — they do not need to be re-sent if you just want to temporarily stop and restart advertising with the same settings. Advertising must be stopped before changing parameters or data.
HCI_LE_Set_Random_Address
Sets the 6-byte random address the controller should use when own_bdaddr_type in the advertising parameters is set to random (0x01). This is how static random addresses and non-resolvable private addresses are loaded. For resolvable private addresses the controller generates them automatically using the IRK — this command is only needed for manually assigned random addresses.
HCI_Read_LE_Host_Support / HCI_Write_LE_Host_Support
These two commands read and write two specific flag bits that the controller stores in its page 1 LMP feature bits. These flags are visible to remote devices during LMP feature exchange and tell them about this device’s capabilities:
HCI_LE_Set_Resolvable_Private_Address_Timeout BLE 4.2Controls how long the controller uses one Resolvable Private Address before generating a new one. The default is 15 minutes (900 seconds). The valid range is 1 second at the shortest (maximum privacy, highest power) up to 11.5 hours (65535 seconds) at the longest (lowest overhead, weakest privacy). Choose based on the application’s privacy requirements — a medical device needs shorter intervals, a device in a controlled environment can use longer ones.
/* Full advertising setup sequence using BlueZ HCI */
#include <bluetooth/hci.h>
#include <bluetooth/hci_lib.h>
int start_le_advertising(int sock)
{
/* Step 1: Set parameters */
le_set_advertising_parameters_cp adv_params;
memset(&adv_params, 0, sizeof(adv_params));
adv_params.min_interval = htobs(0x0800); /* 1280 ms */
adv_params.max_interval = htobs(0x0800);
adv_params.advtype = 0x00; /* ADV_IND */
adv_params.own_bdaddr_type = 0x00; /* public address */
adv_params.chan_map = 0x07; /* channels 37,38,39 */
adv_params.filter_policy = 0x00; /* accept all */
hci_send_cmd(sock, OGF_LE_CTL,
OCF_LE_SET_ADVERTISING_PARAMETERS,
LE_SET_ADVERTISING_PARAMETERS_CP_SIZE,
&adv_params);
/* Step 2: Set advertising data */
le_set_advertising_data_cp adv_data;
memset(&adv_data, 0, sizeof(adv_data));
/* AD structure: Flags (type 0x01), General Discoverable */
adv_data.data[0] = 0x02; /* length */
adv_data.data[1] = 0x01; /* type: Flags */
adv_data.data[2] = 0x06; /* LE General Discoverable */
/* AD structure: Shortened name (type 0x08) */
adv_data.data[3] = 0x05; /* length */
adv_data.data[4] = 0x08; /* type: Shortened Name */
memcpy(&adv_data.data[5], "MySen", 5);
adv_data.length = 10;
hci_send_cmd(sock, OGF_LE_CTL,
OCF_LE_SET_ADVERTISING_DATA,
LE_SET_ADVERTISING_DATA_CP_SIZE,
&adv_data);
/* Step 3: Enable advertising */
le_set_advertise_enable_cp enable;
enable.enable = 0x01;
return hci_send_cmd(sock, OGF_LE_CTL,
OCF_LE_SET_ADVERTISE_ENABLE,
LE_SET_ADVERTISE_ENABLE_CP_SIZE,
&enable);
}
/* Or use the command line: */
/* sudo hciconfig hci0 leadv */9.2.7 — Device Discovery
Device Discovery is how the host puts the link layer into Scanning state and receives information about nearby devices. Like advertising, scanning has a separate parameter-set-then-enable flow.
HCI_LE_Set_Scan_Parameters
Configures the scanner before it is enabled. Key parameters:
HCI_LE_Set_Scan_Enable
Two-byte command: first byte is enable/disable (0x01/0x00), second byte is the duplicate filter (0x01 = filter out duplicate addresses so the same device is only reported once, 0x00 = report every individual packet). The duplicate filter is useful in a crowded environment where you want one notification per device, not hundreds.
HCI_LE_Advertising_Report_Event
This event is the controller telling the host “I just received one or more advertising packets.” One single event can contain multiple reports bundled together — the host reads a count at the start and then iterates through each report. Each individual report contains: the event type (ADV_IND, SCAN_RSP, etc.), the address type and address of the Advertiser, the payload data bytes, and an RSSI reading for that packet. RSSI tells the host how strong the signal was — useful for proximity estimation.
HCI_LE_Direct_Advertising_Report_Event BLE 4.2A new event type added specifically for privacy support. This event fires when the scanner receives a connectable directed advertising packet (ADV_DIRECT_IND) where the InitA field contains a resolvable private address that the controller successfully resolved to a known local identity. Without this event, these packets would be silently dropped in BLE 4.0 since the address in InitA would not match the scanner’s current public address. BLE 4.2 correctly identifies them and delivers this specialised event so the host knows a known bonded device is trying to reach it via directed advertising.
• num_reports = 3 (3 devices seen)
• [0]: ADV_IND, addr=AA:BB:CC:11:22:33, RSSI=-67dBm
• [1]: SCAN_RSP, addr=AA:BB:CC:11:22:33, data=”MySensor”
• [2]: ADV_IND, addr=DD:EE:FF:44:55:66, RSSI=-82dBm
/* Scanning for LE devices using BlueZ */
/* Command line (simplest): */
/* sudo hcitool lescan */
/* sudo hcitool lescan --passive (passive, no SCAN_REQ) */
/* sudo hcitool lescan --duplicates (show every packet) */
/* Programmatic scanning with raw HCI: */
int start_le_scan(int sock, int active)
{
le_set_scan_parameters_cp params;
memset(¶ms, 0, sizeof(params));
params.type = active ? 0x01 : 0x00; /* active or passive */
params.interval = htobs(0x0010); /* 10ms scan interval */
params.window = htobs(0x0010); /* 10ms scan window */
params.own_bdaddr_type = 0x00; /* public address */
params.filter = 0x00; /* accept all */
hci_send_cmd(sock, OGF_LE_CTL,
OCF_LE_SET_SCAN_PARAMETERS,
LE_SET_SCAN_PARAMETERS_CP_SIZE, ¶ms);
le_set_scan_enable_cp en;
en.enable = 0x01; /* start scanning */
en.filter_dup = 0x01; /* filter duplicates */
return hci_send_cmd(sock, OGF_LE_CTL,
OCF_LE_SET_SCAN_ENABLE,
LE_SET_SCAN_ENABLE_CP_SIZE, &en);
}
/* Parsing the advertising report event: */
/* Event code: HCI_LE_META_EVENT (0x3E) */
/* Subevent: EVT_LE_ADVERTISING_REPORT (0x02) */
/* Payload: num_reports + [event_type, addr_type, addr, */
/* data_length, data[], rssi] repeated N times */9.2.8 — Connection Setup
Connection Setup commands manage the full lifecycle of a connection from creation to teardown. There is one command to initiate a connection and one to close it, each with a matching completion event.
HCI_LE_Create_Connection
Tells the controller to enter the Initiating state and connect to a specific connectable Advertiser. The host provides the target device’s address, the scan interval and window to use while searching for it, the initiator filter policy (specific device or white list), and the desired connection parameters (interval, latency, supervision timeout). The controller keeps scanning until it finds a matching ADV_IND, sends the CONNECT_REQ, and reports back via LE_Connection_Complete_Event.
LE_Connection_Complete_Event
Received on both the connecting device (Master) and the accepting device (Slave) once the connection has been created. Contains: status, connection handle, role (Master/Slave), peer address type and address, negotiated connection interval, slave latency, supervision timeout, and the master clock accuracy. Both sides receive this simultaneously — the connection handle is the local reference used in all subsequent commands on this link.
HCI_Disconnect
Terminates an existing connection. Parameters: connection handle, and an error code indicating why the link is being closed (e.g. 0x13 = “remote user terminated connection”). The controller sends LL_TERMINATE_IND to the peer and reports the result back to the host via Disconnection_Complete_Event.
Disconnection_Complete_Event
Sent by the controller to the host when a connection has been closed — whether the local side initiated it or the remote side did. Contains the connection handle, status, and the disconnect reason code. After this event the connection handle is no longer valid and must not be used in further HCI commands.
HCI_LE_Enhanced_Connection_Complete_Event BLE 4.2A replacement for the standard LE_Connection_Complete_Event, introduced in BLE 4.2 specifically to support Link Layer Privacy. It contains all the same fields as the original event, plus two additional address fields:
If neither device used an RPA, these two extra fields are filled with zeros. The controller generates this event instead of the original one whenever it supports BLE 4.2.
/* Creating a BLE connection with BlueZ */
/* Command line: */
/* bluetoothctl */
/* [bluetooth]# connect AA:BB:CC:DD:EE:FF */
/* Programmatic (using hci_lib): */
int conn_handle;
bdaddr_t target;
str2ba("AA:BB:CC:DD:EE:FF", &target);
/* Parameters: interval range, latency, supervision timeout */
conn_handle = hci_le_create_conn(
sock,
htobs(0x0004), /* scan_interval: 2.5ms */
htobs(0x0004), /* scan_window: 2.5ms */
0x00, /* initiator_filter: use specific address */
LE_PUBLIC_ADDRESS, &target,
LE_PUBLIC_ADDRESS,
htobs(0x0028), /* conn_interval_min: 50ms */
htobs(0x0028), /* conn_interval_max: 50ms */
htobs(0x0000), /* conn_latency: 0 (slave must respond) */
htobs(0x002A), /* supervision_timeout: 420 × 10ms = 4.2s*/
htobs(0x0000), /* min_ce_length */
htobs(0x0000), /* max_ce_length */
25000); /* timeout: 25 seconds to connect */
/* hci_le_create_conn blocks until Connected or timeout */
/* Returns the connection handle on success, -1 on error */
/* Disconnecting: */
hci_disconnect(sock, conn_handle, HCI_OE_USER_ENDED_CONNECTION, 10000);9.2.9 — Connection State
Connection State commands modify the behaviour of a connection that is already established. These are the HCI-layer equivalents of the LLCP procedures we studied in Chapter 8.
HCI_LE_Connection_Update
The host (Master side) uses this to change the connection interval, slave latency, or supervision timeout of an active connection. When the host calls this, the controller triggers the LL_CONNECTION_UPDATE_REQ LLCP procedure with the Slave. Once the new parameters take effect, the controller fires LE_Connection_Update_Complete_Event back to the host. The Slave is not consulted — it simply applies whatever the Master sends.
LE_Connection_Update_Complete_Event
Confirms that the connection parameters have been successfully changed. Contains the connection handle and the new values for interval, latency, and timeout. Both Master and Slave receive this event on their respective hosts.
BLE 4.1 additions — Slave can now request changes:
HCI_LE_Remote_Connection_Parameter_Request_Event 4.1Fired by the controller when the remote Slave has used the BLE 4.1 LL_CONNECTION_PARAM_REQ procedure to ask for different parameters. The host now has a choice: it can accept or reject the request. This event delivers the proposed values so the host can make an informed decision.
HCI_LE_Remote_Connection_Parameter_Request_Reply 4.1The host’s acceptance response. Called after receiving the Request_Event above. Carries the accepted parameter values — which may differ from what the Slave proposed (the Master can propose alternative values, not just accept or reject blindly). The controller then applies them.
HCI_LE_Remote_Connection_Parameter_Request_Negative_Reply 4.1The host’s rejection response. Used when the Master cannot or will not accommodate the Slave’s proposed parameters. Includes an error code explaining the rejection reason. The controller passes this rejection back to the Slave via LL_REJECT_IND_EXT.
BLE 4.2 additions — Data length negotiation per connection:
HCI_LE_Write_Suggested_Default_Data_Length_Command 4.2Sets the host’s global default preferred PDU size for all future connections. Two values: preferred max TX octets (27–251) and preferred max TX time (328–2120 µs). When a new connection is established, the controller uses these values as the starting point for Data Length Update negotiation, rather than the minimum defaults from BLE 4.0.
HCI_LE_Read_Suggested_Default_Data_Length_Command 4.2Reads back the values currently set by the Write command above. Useful for confirming what defaults are active before starting new connections.
HCI_LE_Set_Data_Length 4.2Unlike the Write_Suggested_Default command which affects all future connections, this command targets one specific active connection identified by its handle. It suggests new TX octets and TX time values for that particular connection. The controller then initiates the Data Length Update LLCP procedure with the peer. Note: the controller may use different values than suggested if hardware constraints require it.
HCI_LE_Data_Length_Change_Event 4.2Fired by the controller when the data length parameters for a connection actually change — whether triggered by the local host or by the peer initiating the Data Length Update procedure first. Contains the connection handle and all four updated values: max RX octets, max RX time, max TX octets, max TX time. The host reads these to know the current PDU size limits in use.
/* Updating connection parameters and data length via BlueZ */
/* Update connection parameters (Central / Master side): */
/* hcitool lecup --handle 0x0040 */
/* --min 0x0050 --max 0x0050 */
/* --latency 0 --timeout 0x00C8 */
/* 0x0050 = 80 × 1.25ms = 100ms interval */
/* Set data length for a specific connection (BLE 4.2): */
/* OGF=0x08, OCF=0x0022 = LE Set Data Length */
le_set_data_len_cp dl;
dl.handle = htobs(conn_handle);
dl.tx_octets = htobs(200); /* request 200-byte PDUs */
dl.tx_time = htobs(1712); /* max TX time for 200 bytes */
hci_send_cmd(sock, OGF_LE_CTL, OCF_LE_SET_DATA_LEN,
sizeof(dl), &dl);
/* Wait for HCI_LE_Data_Length_Change_Event (subevent 0x07) */
/* Set global default data length for all new connections: */
/* OGF=0x08, OCF=0x0024 = LE Write Suggested Default DL */
/* Parameters: suggested_max_tx_octets + suggested_max_tx_time */9.2.10 — Physical Links
There is exactly one LE command in the Physical Links group. Its purpose is to give the host a way to feed channel quality information to the controller so that the controller can keep its adaptive frequency hopping channel map up to date.
HCI_LE_Set_Host_Channel_Classification
The host passes a 37-bit channel map to the controller. Each bit represents one of the 37 data channels. Bit = 1 means the host believes that channel is good. Bit = 0 means the host has detected interference or poor conditions on that channel and recommends the controller avoid it.
Where does the host get this interference information? The host may have access to Wi-Fi scan data, co-existence signals from a Wi-Fi chip on the same board, or application-level metrics (e.g. high retransmission counts on certain channels). The controller on its own knows about Bluetooth-level packet losses, but the host may have a wider view of the RF environment.
The controller is not obligated to follow this map exactly — it uses the host input as a hint combined with its own measurements. The controller must always keep at least 2 channels enabled, even if the host tries to disable more than 35.
/* Setting channel classification via BlueZ HCI */
/* OGF=0x08, OCF=0x0013 = LE Set Host Channel Classification */
/* Parameters: 37-bit channel map (5 bytes, LE byte order) */
/* Bit 0 = channel 0, Bit 36 = channel 36 */
/* All 37 channels enabled (all good): */
uint8_t all_good[5] = { 0xFF, 0xFF, 0xFF, 0xFF, 0x1F };
hcitool cmd 0x08 0x0013 FF FF FF FF 1F
/* Disable channels 0-5 (e.g. Wi-Fi on 2.4 GHz ch 1 present): */
/* Channel 0 is 2402 MHz, channels 0-4 overlap Wi-Fi ch 1 */
uint8_t no_wifi1[5] = { 0xE0, 0xFF, 0xFF, 0xFF, 0x1F };
/* bit 0-4 = 0 (avoid), bit 5+ = 1 (good) */
hcitool cmd 0x08 0x0013 E0 FF FF FF 1F9.2.11 — Link Information
Link Information commands are all read-only queries that the host can send at any time during an active connection to get diagnostic information about the current state of the radio link.
HCI_Read_Transmit_Power_Level
Returns the current TX power level being used for a specific connection handle. The controller can dynamically adjust transmit power based on link conditions (lower power if the remote device is close, higher if it is far away). This command lets the host see what power level is currently active. The value is in dBm. Two variants are available: current level and maximum level.
HCI_Read_RSSI
Returns the RSSI (Received Signal Strength Indicator) for a connection. RSSI measures how strong the incoming radio signal is at the receiver, in dBm. It is not a direct measure of distance, but it is a useful proxy — typically a stronger signal means a closer device, though walls, interference, and body orientation all affect it. Applications use RSSI for proximity detection, connection quality monitoring, and deciding whether to initiate a connection parameter update.
HCI_LE_Read_Advertising_Channel_Tx_Power
Returns the TX power level the controller uses when sending advertising packets. Unlike the connection TX power (which varies per connection and can be dynamically adjusted), this is the fixed power level used during advertising events. The value is useful for including in the advertising data payload — the “TX Power Level” AD type lets scanners use this value to estimate distance to the Advertiser.
HCI_LE_Read_Channel_Map
Returns the current 37-bit channel map being used for a specific connection. Shows which data channels are currently considered good (bit=1) and which are being avoided (bit=0) by the adaptive frequency hopping algorithm. The Master and Slave must have the same channel map — this command confirms what is actually in use. Useful for debugging connectivity problems where interference may be limiting the available channels.
/* Reading link quality information with BlueZ */
/* Read RSSI for connection handle 0x0040: */
/* hcitool rssi AA:BB:CC:DD:EE:FF */
/* Returns RSSI in dBm (negative value, e.g. -65 dBm) */
/* Read advertising TX power: */
/* OGF=0x08, OCF=0x0007 = LE Read Advertising Channel TX Power */
hcitool cmd 0x08 0x0007
/* Returns: 1 byte signed TX power in dBm (e.g. 0x04 = +4 dBm) */
/* Read channel map for a connection: */
/* OGF=0x08, OCF=0x0015 = LE Read Channel Map */
/* Parameter: connection handle (2 bytes) */
uint8_t handle_bytes[2] = { 0x40, 0x00 }; /* handle 0x0040 */
hcitool cmd 0x08 0x0015 40 00
/* Returns: handle (2 bytes) + channel_map (5 bytes) */
/* e.g. FF FF FF FF 1F = all 37 channels in use */
/* Programmatic RSSI reading: */
int8_t rssi;
hci_read_rssi(sock, htobs(conn_handle), &rssi, 1000);
printf("RSSI: %d dBm\n", rssi);- Set_Advertising_Parameters
- Set_Advertising_Data (31 bytes)
- Set_Scan_Response_Data (31 bytes)
- Set_Advertise_Enable (on/off)
- Write_LE_Host_Support (flags)
- Set_RPA_Timeout (1s–11.5h)
- Set_Scan_Parameters (type, interval)
- Set_Scan_Enable (on, dup filter)
- Advertising_Report_Event (multi)
- Direct_Advertising_Report (4.2)
- LE_Create_Connection
- LE_Connection_Complete_Event
- Disconnect + Complete_Event
- Enhanced_Connection_Complete (4.2)
+ local/peer RPA fields
- LE_Connection_Update (Master)
- Remote_Param_Request_* (4.1)
- Write/Read_Suggested_Default_DL (4.2)
- LE_Set_Data_Length (per-link, 4.2)
- Data_Length_Change_Event (4.2)
- Set_Host_Channel_Classification (AFH)
- Read_Transmit_Power_Level
- Read_RSSI
- LE_Read_Advertising_Channel_Tx_Power
- LE_Read_Channel_Map
Chapter 9 HCI — Complete!
All HCI command groups are now covered end to end. You have a full reference for every LE HCI command, what it does, when to call it, and how to call it from BlueZ.
← PDF 13: Table 9.1 & Flow Control ← PDF 46: White List & Controller Info