BLE Server
The esp32_ble_server component in ESPHome sets up a BLE GATT server that exposes the device name,
manufacturer and board. BLE GATT services and characteristics can be added to the server to expose data and control.
WARNING
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
Crashes are likely to occur if you include too many additional components in your device’s configuration. Memory-intensive components such as Voice Assistant and other audio components are most likely to cause issues.
# Example configuration
esp32_ble_server: manufacturer: "Orange" manufacturer_data: [0x4C, 0, 0x23, 77, 0xF0 ]Configuration variables
Section titled “Configuration variables”- manufacturer (Optional, Value Configuration): The name of the manufacturer/firmware creator. Defaults to
ESPHome. - model (Optional, Value Configuration): The model name of the device. Defaults to the project’s name defined in the core configuration if present, otherwise to the friendly name of the
boardchosen in the core configuration. - appearance (Optional, int): Sets the appearance of the device (included in advertising data.) Defaults to
0. - firmware_version (Optional, Value Configuration): The firmware version of the device. Defaults to the project’s version defined in the core configuration if present, otherwise to the ESPHome version.
- manufacturer_data (Optional, list of bytes): The manufacturer-specific data to include in the advertising packet. Should be a list of bytes, where the first two are the little-endian representation of the 16-bit manufacturer ID as assigned by the Bluetooth SIG.
- max_clients (Optional, int): The maximum number of simultaneous BLE client connections the server will
accept. When set to a value greater than 1, the server resumes advertising after a client connects so that
additional clients can discover and connect, up to this limit. Must not exceed the
max_connectionsvalue configured in the ESP32 BLE component. Defaults to1. Range: 1 to 9. - passkey (Optional, int): A fixed passkey that this device uses for Passkey Entry when it displays the
passkey (
io_capability: display_onlyordisplay_yes_no). It does not set the number shown for numeric comparison. Range: 000000 to 999999. Omit to generate a random passkey. - pairing_enabled (Optional, boolean): Whether the server accepts pairing requests after boot. Use the
ble_server.enable_pairingandble_server.disable_pairingactions to change it later. Defaults totrue. See Security. - services (Optional, list of Service Configuration): A list of services to expose on the BLE GATT server.
- on_connect (Optional, Automation): An action to be performed when a client connects to
the BLE server. It provides the
idvariable which contains the ID of the client that connected. Seeon_connect. - on_disconnect (Optional, Automation): An action to be performed when a client disconnects
from the BLE server. It provides the
idvariable which contains the ID of the client that disconnected. Seeon_disconnect. - on_passkey_request (Optional, Automation): An automation to enter
the passkey required by the other BLE device. See
on_passkey_request. - on_passkey_notification (Optional, Automation): An automation to
display the passkey to the user. See
on_passkey_notification. - on_numeric_comparison_request (Optional, Automation): An automation to
compare the passkeys shown on the two BLE devices. See
on_numeric_comparison_request.
Automations
Section titled “Automations”on_connect
Section titled “on_connect”This automation is triggered when a client connects to the BLE server.
esp32_ble_server: id: my_ble_server on_connect: then: - lambda: |- ESP_LOGD("BLE", "Connection from %d", id);on_disconnect
Section titled “on_disconnect”This automation is triggered when a client disconnects from the BLE server.
esp32_ble_server: id: my_ble_server on_disconnect: then: - lambda: |- ESP_LOGD("BLE", "Disconnection from %d", id);on_passkey_request
Section titled “on_passkey_request”This automation is triggered when the client asks for a passkey, which must be entered on this device. Answer it
with the ble_server.passkey_reply action. The address variable (uint64_t)
holds the address of the client.
esp32_ble_server: id: my_ble_server on_passkey_request: then: - ble_server.passkey_reply: address: !lambda return address; passkey: 123456on_passkey_notification
Section titled “on_passkey_notification”This automation is triggered when a passkey must be entered on the client. Show the passkey to the user. The
address variable (uint64_t) holds the address of the client, and passkey (uint32_t) holds the passkey.
esp32_ble_server: id: my_ble_server on_passkey_notification: then: - logger.log: format: "Enter this passkey on your BLE device: %06u" args: ["(unsigned) passkey"]on_numeric_comparison_request
Section titled “on_numeric_comparison_request”This automation is triggered when the client and this device must both show a number for the user to compare.
Answer it with the ble_server.numeric_comparison_reply action. The
address variable (uint64_t) holds the address of the client, and passkey (uint32_t) holds the number.
esp32_ble_server: id: my_ble_server on_numeric_comparison_request: then: - logger.log: format: "Compare this passkey with the one on your BLE device: %06u" args: ["(unsigned) passkey"] - ble_server.numeric_comparison_reply: address: !lambda return address; accept: trueAccepting without asking the user, as above, skips the check that numeric comparison exists for, so it gives no
more protection against a man in the middle than Just Works, even with read_encrypt_mitm or write_encrypt_mitm.
To have the user confirm the number, see the button example in Security.
Service Configuration
Section titled “Service Configuration”Services are the main way to expose data and control over BLE. Services communicate with the client through characteristics. Each service can have multiple characteristics.
esp32_ble_server: services: - uuid: 2a24b789-7aab-4535-af3e-ee76a35cc42d advertise: false characteristics: - uuid: cad48e28-7fbe-41cf-bae9-d77a6c233423 read: true value: value: "Hello, World!"Configuration variables
Section titled “Configuration variables”- uuid (Required, string, int): The UUID of the service.
- advertise (Optional, boolean): If the service should be advertised. Defaults to
false. - characteristics (Optional, list of Characteristic Configuration): A list of characteristics to expose in this service.
Characteristic Configuration
Section titled “Characteristic Configuration”Characteristics expose data and control for a BLE service. Each characteristic has a value that may be readable and or writable, and may permit a client to subscribe to notifications. Characteristics can also have multiple descriptors to provide additional information about the characteristic.
esp32_ble_server: services: # ... advertise: true characteristics: - id: test_characteristic uuid: cad48e28-7fbe-41cf-bae9-d77a6c233423 description: "Sample description" read: true value: data: "123.1" type: float endianness: BIG descriptors: - uuid: cad48e28-7fbe-41cf-bae9-d77a6c211423 value: "Hello, World Descriptor!"Configuration variables
Section titled “Configuration variables”- id (Optional, string): An ID to refer to this characteristic in automations.
- uuid (Required, string, int): The UUID of the characteristic.
- description (Optional, Value Configuration): The description of the characteristic - not templatable. It will add a
CUDdescriptor (0x2901) to the characteristic with the value of the description. - read (Optional, boolean): If the characteristic should be readable. Defaults to
false. - read_encrypt (Optional, boolean): If the characteristic should be readable only through a secure
connection. It does not make the characteristic readable, so it needs
read,notifyorindicate. Defaults tofalse. See Security. - read_encrypt_mitm (Optional, boolean): Like
read_encrypt, but the client must also have paired with a passkey or numeric comparison, not Just Works. Defaults tofalse. See Security. - write (Optional, boolean): If the characteristic should be writable. Defaults to
false. - write_encrypt (Optional, boolean): If the characteristic should be writable only through a secure
connection. It does not make the characteristic writable, so it needs
writeorwrite_no_response. Defaults tofalse. See Security. - write_encrypt_mitm (Optional, boolean): Like
write_encrypt, but the client must also have paired with a passkey or numeric comparison, not Just Works. Defaults tofalse. See Security. - broadcast (Optional, boolean): If the characteristic should be broadcast. Defaults to
false. - notify (Optional, boolean): If the characteristic supports notifications. If
true, aCCCDdescriptor will be automatically added to the characteristic. Defaults tofalse. - indicate (Optional, boolean): If the characteristic supports indications. If
true, aCCCDdescriptor will be automatically added to the characteristic. Defaults tofalse. - write_no_response (Optional, boolean): If the characteristic should be writable without a response. Defaults to
false. - value (Optional, Value Configuration): The value of the characteristic.
- descriptors (Optional, list of Descriptor Configuration): A list of descriptors to expose in this characteristic.
- on_write (Optional, Automation): An action to be performed when the characteristic is written to. The characteristic must have the
writeproperty. Seeon_writeTrigger.
Descriptor Configuration
Section titled “Descriptor Configuration”Descriptors are optional and are used to provide additional information (metadata) about a characteristic.
esp32_ble_server: services: - uuid: # ... characteristics: - uuid: # ... descriptors: - uuid: 2901 value: value: "Hello, World Descriptor!"Configuration variables
Section titled “Configuration variables”- id (Optional, string): An ID to refer to this descriptor in automations.
- uuid (Required, string, int): The UUID of the descriptor.
- value (Required, Value Configuration): The value of the descriptor. templatable values are not allowed. In order to set the value of a descriptor dynamically, use the
ble_server.descriptor.set_valueAction action.
Value Configuration
Section titled “Value Configuration”Values can be of different types and are used to define the value of a characteristic or descriptor. The value of a characteristic is templatable. If the value is templated, the template will be evaluated each time the characteristic is read, or a notification is triggered. The value of a descriptor is not templatable as it is expected to be static.
esp32_ble_server: services: - uuid: # ... characteristics: - uuid: # ... # Simple value (auto-detect type) value: "Hello, World!" - uuid: # ... # String value value: data: "Hello, World!" type: string string_encoding: utf-8 - uuid: # ... # Integer value value: data: "123" type: uint16_t endianness: LITTLE - uuid: # ... # Array of bytes value value: data: [9, 9, 9] - uuid: # ... # Lambda value value: data: !lambda 'return std::vector<uint8_t>({9, 9, 9});' - uuid: # ... # Lambda value using ByteBuffer value: data: !lambda 'return bytebuffer::ByteBuffer::wrap(0.182).get_data();'Configuration variables
Section titled “Configuration variables”- data (Required, string, int, float, boolean, list of bytes, templatable): The value of the characteristic or descriptor. For templatable values, the lambda function must return a
std::vector<uint8_t>(you may use thebytebuffer::ByteBufferhelper class to transform different data types into a byte array). The value is computed each time the characteristic is read. - type (Optional, string): The C++ type of the value. The available values are
uint8_t,uint16_t,uint32_t,uint64_t,int8_t,int16_t,int32_t,int64_t,float,doubleandstring. It must be defined if the value is not templatable. - endianness (Optional, string): The endianness of the value. Can be
BIGorLITTLE. Defaults toLITTLE. - string_encoding (Optional, string): The encoding of the string. Only applicable if the type is
string. The conversion is done in Python before compilation, so the encoding must be a valid Python encoding. Defaults toutf-8.
on_write Trigger
Section titled “on_write Trigger”With this configuration option you can write complex automations that are triggered when a characteristic is written to. It provides the x variable which contains the new value of the characteristic as a std::vector<uint8_t> and the id variable which contains the ID of the client that wrote to the characteristic.
esp32_ble_server: services: - uuid: # ... characteristics: # ... write: true on_write: then: - lambda: |- ESP_LOGD("BLE", "Descriptor received: %s from %d", std::string(x.begin(), x.end()).c_str(), id);ble_server.characteristic.set_value Action
Section titled “ble_server.characteristic.set_value Action”This action sets the value of a characteristic. A characteristic may not have a set_value action if it also has a templated value in its configuration.
on_...: then: - ble_server.characteristic.set_value: id: test_write_characteristic value: [0, 1, 2]Configuration variables
Section titled “Configuration variables”- id (Required, string): The ID of the characteristic to set the value of.
- value (Required, Value Configuration): The new value of the characteristic.
ble_server.characteristic.notify Action
Section titled “ble_server.characteristic.notify Action”This action triggers a notification to the client. The value sent will be the current value of the characteristic, or the value from evaluation of the template, if present.
on_...: then: - ble_server.characteristic.notify: id: test_notify_characteristicConfiguration variables
Section titled “Configuration variables”- id (Required, string): The ID of the characteristic to notify the client about (must have the
notifyproperty).
ble_server.descriptor.set_value Action
Section titled “ble_server.descriptor.set_value Action”This action sets the value of a descriptor.
on_...: then: - ble_server.descriptor.set_value: id: test_write_descriptor value: [0, 1, 2]Configuration variables
Section titled “Configuration variables”- id (Required, string): The ID of the descriptor to set the value of.
- value (Required, Value Configuration): The new value of the descriptor.
BLE Security
Section titled “BLE Security”By default, connections to your BLE server are not encrypted and any device in range can connect. Security requires pairing: the two BLE devices check each other and exchange keys so the connection can be encrypted. After pairing, the devices can store these keys and use them for later connections without pairing again. This is called bonding.
The available pairing methods depend on what input and output your device has:
- Just Works: The devices exchange keys without any check by the user. It needs no display or input, but does not protect against an attacker who sits between the two devices (a “man in the middle” attack).
- Passkey Entry: One device shows a 6-digit passkey and the user enters it on the other device.
- Numeric Comparison: Both devices show a 6-digit number. The user checks that the numbers match and confirms on each device.
The input and output of your device (io_capability) and the pairing mode (auth_req_mode) are set in the
esp32_ble component.
NOTE
The server requests pairing when a client reads or writes a characteristic that needs encryption. Clients can also start pairing themselves, which the server accepts while pairing is enabled.
The descriptors of a characteristic that needs encryption need the same encryption, except its description,
which clients read while browsing. Reading a descriptor needs the characteristic’s read encryption and writing it
needs the characteristic’s write encryption. Subscribing to notifications or indications follows read_encrypt and
read_encrypt_mitm, since a subscription delivers the value. On a characteristic with notify or indicate but
no read, these options protect only the subscription.
WARNING
read_encrypt and write_encrypt only require an encrypted connection, and a Just Works pairing gives one. A
client that reports no display or input can still pair with Just Works and read or write these characteristics,
even when this device uses a passkey or numeric comparison. Use read_encrypt_mitm and write_encrypt_mitm to
require a passkey or numeric comparison pairing; the device then needs an io_capability that can show or enter a
passkey.
Examples
Section titled “Examples”A device that uses “Just Works” pairing, without a check by the user:
esp32_ble: io_capability: none # Just Works pairing auth_req_mode: sc_bond # store the keys
esp32_ble_server: id: my_ble_server services: ...A device with a screen that shows the passkey. The user enters it on the client.
esp32_ble: io_capability: display_only auth_req_mode: sc_mitm_bond
esp32_ble_server: id: my_ble_server on_passkey_notification: - logger.log: format: "Passkey: %06u" args: ["(unsigned) passkey"] # Show the passkey on the display here services: ...The same, but with a fixed passkey. This is useful when the device has no display: the passkey can be printed on a label or in the manual.
esp32_ble: io_capability: display_only auth_req_mode: sc_mitm_bond
esp32_ble_server: id: my_ble_server passkey: 123456 services: ...A device that uses numeric comparison. The user must confirm the number on both devices. On the ESP32 this is done
with the ble_server.numeric_comparison_reply action, here from two buttons that accept or reject the pairing. The
address of the client is kept in a global variable until a button is pressed, so this example handles one pending
pairing at a time: a new request rejects the one still waiting, which would otherwise time out without an answer.
esp32_ble: io_capability: display_yes_no auth_req_mode: sc_mitm_bond
globals: - id: pairing_address type: uint64_t initial_value: "0"
esp32_ble_server: id: my_ble_server on_numeric_comparison_request: then: - if: condition: lambda: return id(pairing_address) != 0; then: - ble_server.numeric_comparison_reply: address: !lambda return id(pairing_address); accept: false - logger.log: format: "Press the button if your BLE device shows %06u" args: ["(unsigned) passkey"] - globals.set: id: pairing_address value: !lambda return address; services: ...
button: - platform: template name: Confirm pairing on_press: - if: condition: lambda: return id(pairing_address) != 0; then: - ble_server.numeric_comparison_reply: address: !lambda return id(pairing_address); accept: true - globals.set: id: pairing_address value: "0" - platform: template name: Reject pairing on_press: - if: condition: lambda: return id(pairing_address) != 0; then: - ble_server.numeric_comparison_reply: address: !lambda return id(pairing_address); accept: false - globals.set: id: pairing_address value: "0"A device that only accepts new pairings for two minutes after a button press. Devices that are already bonded can still connect. The script restarts on each press, so every press gives a full two minutes.
esp32_ble_server: id: my_ble_server pairing_enabled: false services: ...
script: - id: pairing_window mode: restart then: - ble_server.enable_pairing: - delay: 120s - ble_server.disable_pairing:
button: - platform: template name: Allow pairing on_press: - script.execute: pairing_windowWARNING
On ESP-IDF 5.5.6, the current default, a bond only survives the first reconnect after each boot
(espressif/esp-idf#19286). From the next reconnect on, the
client has to pair again until the ESP32 reboots, and with pairing_enabled: false it cannot, so it loses access
to encrypted characteristics. Open the pairing window again, or reboot the ESP32, to let it back in.
Security Actions
Section titled “Security Actions”Several clients can pair at the same time, so the reply actions take the address of the client they answer.
Inside the triggers above, pass it on with address: !lambda return address;.
ble_server.passkey_reply Action
Section titled “ble_server.passkey_reply Action”This action answers an on_passkey_request with the passkey.
on_passkey_request: then: - ble_server.passkey_reply: address: !lambda return address; passkey: 123456Configuration variables
Section titled “Configuration variables”- id (Optional, ID): The ID of the BLE server.
- address (Required, MAC address, templatable): The address of the client.
- passkey (Required, int, templatable): The 6-digit passkey. Range: 000000 to 999999.
ble_server.numeric_comparison_reply Action
Section titled “ble_server.numeric_comparison_reply Action”This action answers an on_numeric_comparison_request.
on_numeric_comparison_request: then: - ble_server.numeric_comparison_reply: address: !lambda return address; accept: trueConfiguration variables
Section titled “Configuration variables”- id (Optional, ID): The ID of the BLE server.
- address (Required, MAC address, templatable): The address of the client.
- accept (Required, boolean, templatable):
trueif the numbers shown on both devices match,falseto reject the pairing.
ble_server.remove_bond Action
Section titled “ble_server.remove_bond Action”This action removes a bonded device and its stored keys. The device must pair again the next time it connects.
button: - platform: template name: Forget phone on_press: - ble_server.remove_bond: address: 04:00:6E:12:34:56Configuration variables
Section titled “Configuration variables”- id (Optional, ID): The ID of the BLE server.
- address (Required, MAC address, templatable): The address of the bonded device.
ble_server.enable_pairing Action
Section titled “ble_server.enable_pairing Action”This action makes the server accept pairing requests. See also the pairing_enabled option.
on_...: then: - ble_server.enable_pairing:Configuration variables
Section titled “Configuration variables”- id (Optional, ID): The ID of the BLE server.
ble_server.disable_pairing Action
Section titled “ble_server.disable_pairing Action”This action makes the server reject pairing requests from clients.
on_...: then: - ble_server.disable_pairing:Configuration variables
Section titled “Configuration variables”- id (Optional, ID): The ID of the BLE server.