You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/components/bluetooth_proxy.md
+29-11Lines changed: 29 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,8 @@ and Home Assistant.
16
16
Note that while this component is named `bluetooth_proxy`, only BLE devices (and their Home Assistant integrations)
17
17
are supported.
18
18
19
-
If you'd like to buy a ready-made Bluetooth proxy or flash your own device, see [ESPHome projects with Bluetooth proxy support](/projects/?type=bluetooth).
19
+
If you'd like to buy a ready-made Bluetooth proxy or flash your own device, see
20
+
[ESPHome projects with Bluetooth proxy support](/projects/?type=bluetooth).
20
21
21
22
## Configuration
22
23
@@ -30,23 +31,31 @@ bluetooth_proxy:
30
31
-**active** (*Optional*, boolean): Enables proxying active GATT connections to BLE devices.
31
32
This is separate from active *scanning* (configured in [ESP32 BLE Tracker](/components/esp32_ble_tracker)).
32
33
Defaults to `true`.
33
-
-**cache_services** (*Optional*, boolean): Enables caching GATT services in NVS flash storage which significantly speeds up active connections. Defaults to `true`.
34
+
-**cache_services** (*Optional*, boolean): Enables caching GATT services in NVS flash storage which
35
+
significantly speeds up active connections. Defaults to `true`.
34
36
-**connection_slots** (*Optional*, int): The maximum number of BLE connection slots to use.
35
37
Each configured slot consumes ~1KB of RAM, with a maximum of `9`. It is recommended not to exceed `5`
36
38
connection slots to avoid stability and memory issues. Defaults to `3`.
37
39
Ethernet-based proxies can generally handle `4` connection slots reliably.
38
40
The value must not exceed the total configured `max_connections`
39
41
for [ESP32 BLE](/components/esp32_ble).
40
42
41
-
The Bluetooth proxy depends on [ESP32 BLE Tracker](/components/esp32_ble_tracker) so make sure to add that to your configuration.
43
+
The Bluetooth proxy depends on [ESP32 BLE Tracker](/components/esp32_ble_tracker) so make sure to add that
44
+
to your configuration.
42
45
43
46
### How Active Connections Work
44
47
45
-
The Bluetooth proxy provides Home Assistant with a limited number of simultaneous active GATT connections (configured via `connection_slots`). The default is 3 slots. Ethernet-based proxies can generally handle 4 slots reliably since they don't share the radio with WiFi traffic. Set `connection_slots: 4` if you need more connections (each slot uses additional RAM).
48
+
The Bluetooth proxy provides Home Assistant with a limited number of simultaneous active GATT connections
49
+
(configured via `connection_slots`). The default is 3 slots. Ethernet-based proxies can generally handle
50
+
4 slots reliably since they don't share the radio with WiFi traffic. Set `connection_slots: 4` if you need
51
+
more connections (each slot uses additional RAM).
46
52
47
-
Devices that stay connected continuously (like some locks or thermostats) use one slot the entire time. Devices that connect briefly to exchange data and then disconnect (like many sensors) free up the slot for other devices, so you can use more devices than you have slots.
53
+
Devices that stay connected continuously (like some locks or thermostats) use one slot the entire time.
54
+
Devices that connect briefly to exchange data and then disconnect (like many sensors) free up the slot
55
+
for other devices, so you can use more devices than you have slots.
48
56
49
-
Passively broadcasted sensor data (advertised by devices without requiring active connections, such as many BTHome sensors) is received separately and is not limited by the number of connection slots.
57
+
Passively broadcasted sensor data (advertised by devices without requiring active connections, such as
58
+
many BTHome sensors) is received separately and is not limited by the number of connection slots.
50
59
51
60
## Improving reception performance
52
61
@@ -77,11 +86,15 @@ esp32_ble_tracker:
77
86
active: false
78
87
```
79
88
80
-
Avoid placing the ESP node in racks, close to routers/switches or other network equipment as EMI interference will degrade Bluetooth signal reception. For best results put as far away as possible, at least 3 meters distance from any other such equipment. Place your ESPHome devices close to the Bluetooth devices that you want to interact with for the best experience.
89
+
Avoid placing the ESP node in racks, close to routers/switches or other network equipment as EMI
90
+
interference will degrade Bluetooth signal reception. For best results put as far away as possible,
91
+
at least 3 meters distance from any other such equipment. Place your ESPHome devices close to the
92
+
Bluetooth devices that you want to interact with for the best experience.
81
93
82
94
## Complete sample recommended configuration for a WiFi-connected Bluetooth proxy
83
95
84
-
Below is a complete sample recommended configuration for a WiFi-connected Bluetooth proxy. If you experience issues with your proxy, try reducing your configuration to be as similar to this as possible.
96
+
Below is a complete sample recommended configuration for a WiFi-connected Bluetooth proxy. If you
97
+
experience issues with your proxy, try reducing your configuration to be as similar to this as possible.
85
98
86
99
```yaml
87
100
substitutions:
@@ -117,9 +130,12 @@ bluetooth_proxy:
117
130
118
131
## Complete sample recommended configuration for an ethernet-connected Bluetooth proxy
119
132
120
-
Below is a complete sample recommended configuration for an ethernet-connected Bluetooth proxy. This configuration is not for a Wi-Fi based proxy. If you experience issues with your proxy, try reducing your configuration to be as similar to this as possible.
133
+
Below is a complete sample recommended configuration for an ethernet-connected Bluetooth proxy. This
134
+
configuration is not for a Wi-Fi based proxy. If you experience issues with your proxy, try reducing
135
+
your configuration to be as similar to this as possible.
121
136
122
-
This configuration is for an Olimex ESP32-PoE-ISO board with an Ethernet connection to the network. If you use a different board, you must change the `board` substitution to match your board.
137
+
This configuration is for an Olimex ESP32-PoE-ISO board with an Ethernet connection to the network.
138
+
If you use a different board, you must change the `board` substitution to match your board.
123
139
124
140
```yaml
125
141
substitutions:
@@ -180,7 +196,9 @@ If you experience memory issues, consider the following:
180
196
181
197
### Device Compatibility
182
198
183
-
Not all BLE devices are supported and ESPHome does not decode or keep a list. To find out if your device is supported, please search for it in the [Home Assistant Integrations](https://www.home-assistant.io/integrations/) list.
199
+
Not all BLE devices are supported and ESPHome does not decode or keep a list. To find out if your device
0 commit comments