Skip to content

Update docs for max_connections move to esp32_ble component #5445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 6, 2025
Merged

Update docs for max_connections move to esp32_ble component #5445

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
176f3c1
Update docs for max_connections move to esp32_ble component
bdraco Oct 3, 2025
2c79e19
Update content/components/esp32_ble_tracker.md
jesserockz Oct 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/components/bluetooth_proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ bluetooth_proxy:
Each configured slot consumes ~1KB of RAM, with a maximum of `9`. It is recommended not to exceed `5`
connection slots to avoid memory issues. Defaults to `3`.
The value must not exceed the total configured `max_connections`
for {{< docref "esp32_ble_tracker/" >}}.
for {{< docref "esp32_ble/" >}}.

The Bluetooth proxy depends on {{< docref "esp32_ble_tracker/" >}} so make sure to add that to your configuration.

Expand Down
13 changes: 13 additions & 0 deletions content/components/esp32_ble.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ esp32_ble:
io_capability: keyboard_only
disable_bt_logs: true # Default, saves flash
connection_timeout: 20s # Default, matches client timeout
max_connections: 3 # Default, total BLE connections
# advertising: true # Only needed for advanced use cases
max_notifications: 12 # Default, increase if needed
```
Expand Down Expand Up @@ -64,6 +65,18 @@ esp32_ble:
> The `advertising` option is an advanced feature that manually enables BLE advertising compilation. In most cases, you don't need to set this as advertising is automatically enabled when using components that require it (like `esp32_ble_server` or `esp32_ble_beacon` ). This option is primarily useful for custom components or special use cases where you need advertising functionality without the standard server or beacon components.

- **advertising_cycle_time** (*Optional*, [Time](#config-time)): The time interval for cycling through multiple advertisements. Only applicable when advertising is enabled. Defaults to `10s`.

- **max_connections** (*Optional*, integer): The maximum number of simultaneous BLE connections (client + server combined). Defaults to `3`.

- Range: 1 to 9
- Each connection slot consumes approximately 1KB of RAM
- This limit is shared between {{< docref "esp32_ble_tracker/" >}} (BLE client), {{< docref "bluetooth_proxy/" >}}, and {{< docref "esp32_ble_server/" >}} (BLE server)
- Total BLE instances (ADV/SCAN + connections) is limited to 10 on ESP32-C3/S3
- It is recommended not to exceed `5` connection slots to avoid memory issues

> [!NOTE]
> The `max_connections` option sets both `CONFIG_BT_ACL_CONNECTIONS` (total instances including ADV/SCAN) and `CONFIG_BTDM_CTRL_BLE_MAX_CONN` (connection slots only) in ESP-IDF. This configuration was previously located in `esp32_ble_tracker` but has been moved here as it applies to all BLE functionality (client and server). For backward compatibility, setting it in `esp32_ble_tracker` will still work but will show a deprecation warning.

- **max_notifications** (*Optional*, integer): The maximum number of BLE characteristics that can have notifications enabled across all connections. Defaults to `12`.

- Range: 1 to 64
Expand Down
9 changes: 2 additions & 7 deletions content/components/esp32_ble_tracker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ the MAC address of a device and track it using ESPHome.
```yaml
# Example configuration entry
esp32_ble_tracker:
max_connections: 3

binary_sensor:
- platform: ble_presence
Expand Down Expand Up @@ -94,12 +93,8 @@ sensor:
Defaults to `true`.

- **id** (*Optional*, [ID](#config-id)): Manually specify the ID for this ESP32 BLE Hub.
- **max_connections** (*Optional*, int): The maximum number of BLE connection slots to use.
Each configured slot consumes ~1KB of RAM. It is recommended not to exceed `5`
connection slots to avoid memory issues. Defaults to `3`, with a maximum of `9`.
This value cannot exceed the total number of `connection_slots` for the
{{< docref "bluetooth_proxy/" >}} component combined with the total
configured {{< docref "ble_client/" >}} instances.
- **max_connections** (*Optional*, int): **DEPRECATED** - This option has been moved to the {{< docref "esp32_ble/" >}} component.
Please configure `max_connections` there instead. This option is kept for backward compatibility only. This option will be removed in ESPHome 2026.10.0.

Automations:

Expand Down