Update docs for max_connections move to esp32_ble component

[bdraco]

Description:

This PR updates the documentation to reflect the breaking change in esphome/esphome#11006, which moves max_connections from esp32_ble_tracker to esp32_ble.

Why this breaking change was necessary:

1. max_connections is a shared limit: The ESP-IDF CONFIG_BT_ACL_CONNECTIONS setting controls the total number of BLE connections across both client and server, not just the tracker/client side
2. Correct location is esp32_ble: The base component that both client (esp32_ble_tracker) and server (esp32_ble_server) depend on
3. Architectural correctness: The shared limit should be configured in the base component, not in a client-specific component

⚠️ Migration required by 2026.10.0: Users with max_connections in esp32_ble_tracker must move it to esp32_ble before ESPHome 2026.10.0, or their configurations will fail. Temporary backward compatibility is provided with a deprecation warning until that release.

Changes Made

content/components/esp32_ble.md

• Added comprehensive max_connections documentation with:
  • Full parameter description and default value
  • Explanation of the range (1-9) and memory implications (~1KB per slot)
  • Clarification that it's shared between client and server components
  • Technical details about ESP-IDF config settings (CONFIG_BT_ACL_CONNECTIONS, CONFIG_BTDM_CTRL_BLE_MAX_CONN)
  • Note about the 10-instance total limit on ESP32-C3/S3
  • Recommendation not to exceed 5 slots to avoid memory issues
• Added example configuration showing max_connections: 3

content/components/esp32_ble_tracker.md

• Marked max_connections as DEPRECATED with clear migration instruction
• Added deadline: Will be removed in ESPHome 2026.10.0
• Updated description to indicate it has been moved to the esp32_ble component
• Retained the parameter for backward compatibility documentation

content/components/bluetooth_proxy.md

• Updated reference from esp32_ble_tracker to esp32_ble for the connection limit
• Changed line 57 to reference the correct component for max_connections validation
• Updated example configuration comment to reflect the new location

Example Configuration

New (correct) location shown in updated docs:

esp32_ble:
  max_connections: 5  # Total connections for client + server combined

esp32_ble_tracker:
  # max_connections: 5  # DEPRECATED - Will be removed in 2026.10.0, move to esp32_ble
  scan_parameters:
    interval: 1100ms
    window: 1100ms

bluetooth_proxy:
  active: true
  connection_slots: 3  # Must be <= max_connections in esp32_ble

Related issue (if applicable): Documents the architectural change from esphome/esphome#11006

Pull request in esphome with YAML changes (if applicable):

• [esp32_ble] Fix max_connections architecture (shared client+server limit) esphome#11006

Checklist:

• I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
  or

• I am merging into current because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.

• Link added in /components/index.rst when creating new documents for new components or cookbook.

[netlify]

✅ Deploy Preview for esphome ready!

Name	Link
🔨 Latest commit	2c79e19
🔍 Latest deploy log	https://app.netlify.com/projects/esphome/deploys/68e2ded00762670008ce452e
😎 Deploy Preview	https://deploy-preview-5445--esphome.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull Request Overview

This PR updates the documentation to reflect a breaking change that moves the max_connections parameter from esp32_ble_tracker to esp32_ble. The change is necessary because the connection limit is shared between both BLE client and server components, making the base esp32_ble component the correct location for this configuration.

• Documents the new location of max_connections in the esp32_ble component with comprehensive details
• Marks the parameter as deprecated in esp32_ble_tracker with migration instructions
• Updates references in bluetooth_proxy to point to the correct component

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
content/components/esp32_ble.md	Adds comprehensive documentation for max_connections parameter with technical details and usage guidelines
content/components/esp32_ble_tracker.md	Marks max_connections as deprecated and provides migration instructions
content/components/bluetooth_proxy.md	Updates component reference from esp32_ble_tracker to esp32_ble for connection validation