Skip to content
Get started

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 ]
  • 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 board chosen 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_connections value configured in the ESP32 BLE component. Defaults to 1. 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_only or display_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_pairing and ble_server.disable_pairing actions to change it later. Defaults to true. 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 id variable which contains the ID of the client that connected. See on_connect.
  • on_disconnect (Optional, Automation): An action to be performed when a client disconnects from the BLE server. It provides the id variable which contains the ID of the client that disconnected. See on_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.

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);

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);

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: 123456

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"]

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: true

Accepting 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.

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!"
  • 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.

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!"
  • 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 CUD descriptor (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, notify or indicate. Defaults to false. 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 to false. 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 write or write_no_response. Defaults to false. 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 to false. See Security.
  • broadcast (Optional, boolean): If the characteristic should be broadcast. Defaults to false.
  • notify (Optional, boolean): If the characteristic supports notifications. If true, a CCCD descriptor will be automatically added to the characteristic. Defaults to false.
  • indicate (Optional, boolean): If the characteristic supports indications. If true, a CCCD descriptor will be automatically added to the characteristic. Defaults to false.
  • 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 write property. See on_write Trigger.

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!"
  • 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_value Action action.

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();'
  • 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 the bytebuffer::ByteBuffer helper 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, double and string. It must be defined if the value is not templatable.
  • endianness (Optional, string): The endianness of the value. Can be BIG or LITTLE. Defaults to LITTLE.
  • 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 to utf-8.

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]
  • id (Required, string): The ID of the characteristic to set the value of.
  • value (Required, Value Configuration): The new value of the characteristic.

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_characteristic
  • id (Required, string): The ID of the characteristic to notify the client about (must have the notify property).

This action sets the value of a descriptor.

on_...:
then:
- ble_server.descriptor.set_value:
id: test_write_descriptor
value: [0, 1, 2]
  • id (Required, string): The ID of the descriptor to set the value of.
  • value (Required, Value Configuration): The new value of the descriptor.

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.

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_window

WARNING

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.

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;.

This action answers an on_passkey_request with the passkey.

on_passkey_request:
then:
- ble_server.passkey_reply:
address: !lambda return address;
passkey: 123456
  • 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: true
  • id (Optional, ID): The ID of the BLE server.
  • address (Required, MAC address, templatable): The address of the client.
  • accept (Required, boolean, templatable): true if the numbers shown on both devices match, false to reject the pairing.

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:56
  • id (Optional, ID): The ID of the BLE server.
  • address (Required, MAC address, templatable): The address of the bonded device.

This action makes the server accept pairing requests. See also the pairing_enabled option.

on_...:
then:
- ble_server.enable_pairing:
  • id (Optional, ID): The ID of the BLE server.

This action makes the server reject pairing requests from clients.

on_...:
then:
- ble_server.disable_pairing:
  • id (Optional, ID): The ID of the BLE server.