From f256fda25ee1a405fdfbaba5f81b86f61422b5f4 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Thu, 26 Oct 2023 17:29:59 -0500 Subject: [PATCH] Add resource warnings to BLE, voice and audio component docs (#3298) --- components/binary_sensor/ble_presence.rst | 11 +++++-- components/ble_client.rst | 38 +++++++++++------------ components/esp32_ble.rst | 8 +++++ components/esp32_ble_beacon.rst | 7 +++++ components/esp32_ble_server.rst | 8 +++++ components/esp32_ble_tracker.rst | 16 +++++++--- components/esp32_improv.rst | 9 +++++- components/microphone/i2s_audio.rst | 13 ++++++-- components/output/ble_client.rst | 15 ++++++--- components/sensor/ble_client.rst | 15 ++++++--- components/sensor/ble_rssi.rst | 8 +++++ components/speaker/i2s_audio.rst | 13 ++++++-- components/switch/ble_client.rst | 17 ++++++---- components/text_sensor/ble_scanner.rst | 19 +++++++++--- components/voice_assistant.rst | 8 +++++ 15 files changed, 155 insertions(+), 50 deletions(-) diff --git a/components/binary_sensor/ble_presence.rst b/components/binary_sensor/ble_presence.rst index 9d75e472a..8f744dbb5 100644 --- a/components/binary_sensor/ble_presence.rst +++ b/components/binary_sensor/ble_presence.rst @@ -5,8 +5,15 @@ ESP32 Bluetooth Low Energy Device :description: Instructions for setting up BLE binary sensors for the ESP32. :image: bluetooth.svg -The ``ble_presence`` binary sensor platform lets you track the presence of a -Bluetooth Low Energy device. +The ``ble_presence`` binary sensor platform lets you track the presence of a Bluetooth Low Energy device. + +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. figure:: images/esp32_ble-ui.png :align: center diff --git a/components/ble_client.rst b/components/ble_client.rst index 7424ecf70..a14cdf5a8 100644 --- a/components/ble_client.rst +++ b/components/ble_client.rst @@ -5,33 +5,31 @@ BLE Client :description: Configuration of the BLE client on ESP32. :image: bluetooth.svg -The ``ble_client`` component enables connections to Bluetooth -Low Energy devices in order to query and control them. This -component does not expose any sensors or output components itself, -but merely manages connections to them for use by other components. +The ``ble_client`` component enables connections to Bluetooth Low Energy devices in order to query and +control them. This component does not expose any sensors or output components itself, but merely manages +connections to them for use by other components. + +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. note:: - The BLE software stack on the ESP32 consumes a significant - amount of RAM on the device. As such, you may experience - frequent crashes due to out-of-memory if you enable many - other components. + A maximum of three devices is supported due to limitations in the ESP32 BLE stack. If you wish to + connect more devices, use additional ESP32 boards. - A maximum of three devices is supported due to limitations in the - ESP32 BLE stack. If you wish to connect more devices, use additional - ESP32 boards. + This component supports devices that require a 6 digit PIN code for authentication. - This component supports devices that require a 6 digit PIN code - for authentication. - - Currently, devices connected with the client cannot be - supported by other components based on :doc:`/components/esp32_ble_tracker` - as they listen to advertisements which are only sent by devices + Currently, devices connected with the client cannot be supported by other components based on + :doc:`/components/esp32_ble_tracker` as they listen to advertisements which are only sent by devices without an active connection. -Despite the last point above, the ``ble_client`` component requires -the ``esp32_ble_tracker`` component in order to discover available -client devices. +Despite the last point above, the ``ble_client`` component requires the ``esp32_ble_tracker`` component in order +to discover available client devices. .. code-block:: yaml diff --git a/components/esp32_ble.rst b/components/esp32_ble.rst index 325ce59f0..146d7e868 100644 --- a/components/esp32_ble.rst +++ b/components/esp32_ble.rst @@ -8,6 +8,14 @@ BLE Component The ``esp32_ble`` component in ESPHome sets up the Bluetooth LE stack on the device so that a :doc:`esp32_ble_server` can run. +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. + .. code-block:: yaml # Example configuration diff --git a/components/esp32_ble_beacon.rst b/components/esp32_ble_beacon.rst index 79e350c7a..cd312cf88 100644 --- a/components/esp32_ble_beacon.rst +++ b/components/esp32_ble_beacon.rst @@ -9,6 +9,13 @@ The ``esp32_ble_beacon`` component creates a Bluetooth Low Energy Beacon with yo Beacons are BLE devices that repeatedly just send out a pre-defined packet of data. This packet can then be received by devices like smartphones and can then be used to track a phone's location. +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. code-block:: yaml diff --git a/components/esp32_ble_server.rst b/components/esp32_ble_server.rst index 357b43aef..c4f1ca609 100644 --- a/components/esp32_ble_server.rst +++ b/components/esp32_ble_server.rst @@ -9,6 +9,14 @@ The ``esp32_ble_server`` component in ESPHome sets up a simple BLE GATT server t manufacturer and board. This component allows other components to create their own services 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. + .. code-block:: yaml # Example configuration diff --git a/components/esp32_ble_tracker.rst b/components/esp32_ble_tracker.rst index f1b59149d..fa32e37bd 100644 --- a/components/esp32_ble_tracker.rst +++ b/components/esp32_ble_tracker.rst @@ -5,11 +5,19 @@ ESP32 Bluetooth Low Energy Tracker Hub :description: Instructions for setting up ESP32 bluetooth low energy device trackers using ESPHome. :image: bluetooth.svg -The ``esp32_ble_tracker`` component creates a global hub so that you can track bluetooth low -energy devices using your ESP32 node. +The ``esp32_ble_tracker`` component creates a global hub so that you can track bluetooth low energy devices +using your ESP32 node. -See :ref:`Setting up devices ` -for information on how you can find out the MAC address of a device and track it using ESPHome. +See :ref:`Setting up devices ` for information on how you can determine +the MAC address of a device and track it using ESPHome. + +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. code-block:: yaml diff --git a/components/esp32_improv.rst b/components/esp32_improv.rst index ed53f0959..f12aa3d55 100644 --- a/components/esp32_improv.rst +++ b/components/esp32_improv.rst @@ -6,10 +6,17 @@ Improv via BLE :image: improv-social.png The ``esp32_improv`` component in ESPHome implements the open `Improv standard `__ -for configuring Wi-Fi on an ESP32 device by using Bluetooth Low Energy to receive the credentials. +for configuring Wi-Fi on an ESP32 device by using Bluetooth Low Energy (BLE) to receive the credentials. The ``esp32_improv`` component will automatically set up the :doc:`BLE Server `. +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. code-block:: yaml diff --git a/components/microphone/i2s_audio.rst b/components/microphone/i2s_audio.rst index 2afb3f9c0..d7dc646ad 100644 --- a/components/microphone/i2s_audio.rst +++ b/components/microphone/i2s_audio.rst @@ -5,8 +5,17 @@ I²S Audio Microphone :description: Instructions for setting up I²S based microphones in ESPHome. :image: i2s_audio.svg -The ``i2s_audio`` microphone platform allows you to receive audio via the the -:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips. +The ``i2s_audio`` microphone platform allows you to receive audio via the the :doc:`/components/i2s_audio`. + +This platform only works on ESP32 based chips. + +.. warning:: + + Audio and voice components consume a significant amount of resources (RAM, CPU) on the device. + + **Crashes are likely to occur** if you include too many additional components in your device's + configuration. In particular, Bluetooth/BLE components are known to cause issues when used in + combination with Voice Assistant and/or other audio components. .. code-block:: yaml diff --git a/components/output/ble_client.rst b/components/output/ble_client.rst index bda99d4e9..3aed40ed7 100644 --- a/components/output/ble_client.rst +++ b/components/output/ble_client.rst @@ -5,12 +5,17 @@ BLE Client Binary Output :description: Writes a binary value to a BLE device. :image: bluetooth.svg -The ``ble_client`` component is a output that can -write a binary value to service characteristics of -BLE devices. +The ``ble_client`` component is a output that can write a binary value to service characteristics of BLE devices. -For more information on BLE services and characteristics, see -:doc:`/components/ble_client`. +For more information on BLE services and characteristics, see :doc:`/components/ble_client`. + +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. code-block:: yaml diff --git a/components/sensor/ble_client.rst b/components/sensor/ble_client.rst index b579e305e..469c81099 100644 --- a/components/sensor/ble_client.rst +++ b/components/sensor/ble_client.rst @@ -5,11 +5,18 @@ BLE Client Sensor :description: Fetch numeric values from BLE devices. :image: bluetooth.svg -The ``ble_client`` component is a sensor platform that can -query BLE devices for RSSI or specific values of service characteristics. +The ``ble_client`` component is a sensor platform that can query BLE devices for RSSI or specific +values of service characteristics. -For more information on BLE services and characteristics, see -:doc:`/components/ble_client`. +For more information on BLE services and characteristics, see :doc:`/components/ble_client`. + +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. code-block:: yaml diff --git a/components/sensor/ble_rssi.rst b/components/sensor/ble_rssi.rst index 6fcee5840..724f96d61 100644 --- a/components/sensor/ble_rssi.rst +++ b/components/sensor/ble_rssi.rst @@ -10,6 +10,14 @@ The ``ble_rssi`` sensor platform lets you track the RSSI value or signal strengt BLE device. See :ref:`the binary sensor setup ` for instructions for setting up this platform. +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. + .. code-block:: yaml # Example configuration entry diff --git a/components/speaker/i2s_audio.rst b/components/speaker/i2s_audio.rst index 3ece5e99a..c322f179b 100644 --- a/components/speaker/i2s_audio.rst +++ b/components/speaker/i2s_audio.rst @@ -5,8 +5,17 @@ I²S Audio Speaker :description: Instructions for setting up I²S based speakers in ESPHome. :image: i2s_audio.svg -The ``i2s_audio`` speaker platform allows you to receive audio via the the -:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips. +The ``i2s_audio`` speaker platform allows you to receive audio via the the :doc:`/components/i2s_audio`. + +This platform only works on ESP32 based chips. + +.. warning:: + + Audio and voice components consume a significant amount of resources (RAM, CPU) on the device. + + **Crashes are likely to occur** if you include too many additional components in your device's + configuration. In particular, Bluetooth/BLE components are known to cause issues when used in + combination with Voice Assistant and/or other audio components. .. code-block:: yaml diff --git a/components/switch/ble_client.rst b/components/switch/ble_client.rst index cf3fd13d4..96b3599b9 100644 --- a/components/switch/ble_client.rst +++ b/components/switch/ble_client.rst @@ -5,13 +5,18 @@ BLE Client Switch :description: Control the state of BLE clients. :image: bluetooth.svg -The ``ble_client`` component is a switch platform that is used to enable -and disable a ``ble_client``. This has several uses, such as minimizing -battery usage or for allowing other clients (Eg phone apps) to connect to -the device. +The ``ble_client`` component is a switch platform that is used to enable and disable a ``ble_client``. This has +several uses, such as minimizing battery usage or for allowing other clients (Eg phone apps) to connect to the device. -For more information on BLE services and characteristics, see -:doc:`/components/ble_client`. +For more information on BLE services and characteristics, see :doc:`/components/ble_client`. + +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. code-block:: yaml diff --git a/components/text_sensor/ble_scanner.rst b/components/text_sensor/ble_scanner.rst index 3d21c3df1..6b4c0873e 100644 --- a/components/text_sensor/ble_scanner.rst +++ b/components/text_sensor/ble_scanner.rst @@ -7,11 +7,22 @@ ESP32 Bluetooth Low Energy Scanner :keywords: ESP32 The ``ble_scanner`` text sensor platform lets you track reachable BLE devices. -See the :ref:`BLE Tracker Configuration variables ` for -instructions for setting up scan parameters. -The sensor platform is similar to :doc:`/components/sensor/ble_rssi` but in contrast to that platform, this text sensor sends out all raw BLE scan information and does not filter devices. -The data this sensor publishes is intended to be processed by the remote (for example an MQTT client) and sends the data in JSON format. +See the :ref:`BLE Tracker Configuration variables ` for instructions for setting up scan parameters. + +The sensor platform is similar to :doc:`/components/sensor/ble_rssi` but in contrast to that platform, this text +sensor sends out all raw BLE scan information and does not filter devices. + +The data this sensor publishes is intended to be processed by the remote (for example an MQTT client) and sends +the data in JSON format. + +.. 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 :doc:`/components/voice_assistant` and other + audio components are most likely to cause issues. .. code-block:: yaml diff --git a/components/voice_assistant.rst b/components/voice_assistant.rst index 0eaffdf52..0a5fa2f54 100644 --- a/components/voice_assistant.rst +++ b/components/voice_assistant.rst @@ -11,6 +11,14 @@ ESPHome devices with a microphone are able to stream the audio to Home Assistant Voice Assistant requires Home Assistant 2023.5 or later. +.. warning:: + + Audio and voice components consume a significant amount of resources (RAM, CPU) on the device. + + **Crashes are likely to occur** if you include too many additional components in your device's + configuration. In particular, Bluetooth/BLE components are known to cause issues when used in + combination with Voice Assistant and/or other audio components. + Configuration: --------------