diff --git a/src/content/docs/components/index.mdx b/src/content/docs/components/index.mdx index 24a83901e5..deb5442657 100644 --- a/src/content/docs/components/index.mdx +++ b/src/content/docs/components/index.mdx @@ -124,6 +124,7 @@ ESPHome-specific components or components supporting ESPHome device provisioning ["Improv via BLE", "/components/esp32_improv/", "improv.svg", "dark-invert"], ["Nordic UART Service (NUS)", "/components/ble_nus/", "bluetooth.svg", "dark-invert"], ["RP2040 BLE", "/components/rp2040_ble/", "bluetooth.svg", "dark-invert"], + ["Zephyr BLE Server", "/components/zephyr_ble_server/", "bluetooth.svg", "dark-invert"], ]} /> ## Management and Monitoring diff --git a/src/content/docs/components/zephyr_ble_server.mdx b/src/content/docs/components/zephyr_ble_server.mdx new file mode 100644 index 0000000000..e8751c74a1 --- /dev/null +++ b/src/content/docs/components/zephyr_ble_server.mdx @@ -0,0 +1,93 @@ +--- +description: "Zephyr BLE Server" +title: "Zephyr BLE Server" +--- + +The `zephyr_ble_server` component enables a Bluetooth Low Energy GATT server on devices running the +Zephyr RTOS. It supports secure pairing flows, including the **Numeric Comparison** passkey +confirmation model defined in the Bluetooth specification. + +```yaml +# Example configuration entry +zephyr_ble_server: + on_numeric_comparison_request: + then: + - logger.log: + format: "Compare this passkey with the one on your BLE device: %06d" + args: [passkey] + - ble_server.numeric_comparison_reply: + accept: true +``` + +## Configuration variables + +- **on_numeric_comparison_request** (*Optional*, [Automation](/automations)): An automation to + compare the passkeys shown on the two BLE devices. See [`on_numeric_comparison_request`](#on_numeric_comparison_request). + +## BLE Server Automation + +### `on_numeric_comparison_request` + +This automation is triggered when a numeric comparison is requested by the BLE device. + +```yaml +zephyr_ble_server: + on_numeric_comparison_request: + then: + - logger.log: + format: "Compare this passkey with the one on your BLE device: %06d" + args: [passkey] + - ble_server.numeric_comparison_reply: + accept: true +``` + +## `ble_server.numeric_comparison_reply` Action + +This action triggers an authentication attempt after a numeric comparison. + +Example usage: + +```yaml +on_...: + then: + - ble_server.numeric_comparison_reply: + accept: true +``` + +### Configuration variables + +- **accept** (**Required**, boolean, [templatable](/automations/templates)): Should be `true` if the + passkeys displayed on both BLE devices are matching. + +## Passkey examples + +Secure connection with numeric comparison accepted automatically: + +```yaml +zephyr_ble_server: + on_numeric_comparison_request: + then: + - logger.log: + format: "Compare this passkey with the one on your BLE device: %06d" + args: [passkey] + - ble_server.numeric_comparison_reply: + accept: true +``` + +Secure connection with numeric comparison accepted via a lambda: + +```yaml +zephyr_ble_server: + on_numeric_comparison_request: + then: + - logger.log: + format: "Compare this passkey with the one on your BLE device: %06d" + args: [passkey] + - ble_server.numeric_comparison_reply: + accept: !lambda "return true;" +``` + +## See Also + +- [BLE Client](/components/ble_client) +- [Automations](/automations)