Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-01-25 22:11:29 +01:00
Code Issues Projects Releases Wiki Activity

Add resource warnings to BLE, voice and audio component docs (#3298)

Browse Source
This commit is contained in:
Keith Burzinski 2023-10-26 17:29:59 -05:00 committed by GitHub
parent 255018db43
commit f256fda25e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 155 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
components/binary_sensor/ble_presence.rst
View File

@ -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

38
components/ble_client.rst
View File

@ -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

8
components/esp32_ble.rst
View File

@ -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

7
components/esp32_ble_beacon.rst
View File

@ -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

8
components/esp32_ble_server.rst
View File

@ -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

16
components/esp32_ble_tracker.rst
View File

@ -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 <esp32_ble_tracker-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 <esp32_ble_tracker-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

9
components/esp32_improv.rst
View File

@ -6,10 +6,17 @@ Improv via BLE
:image: improv-social.png
The ``esp32_improv`` component in ESPHome implements the open `Improv standard <https://www.improv-wifi.com/>`__
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 <esp32_ble>`.
.. 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

13
components/microphone/i2s_audio.rst
View File

@ -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

15
components/output/ble_client.rst
View File

@ -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

15
components/sensor/ble_client.rst
View File

@ -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

8
components/sensor/ble_rssi.rst
View File

@ -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 <esp32_ble_tracker-setting_up_devices>` 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

13
components/speaker/i2s_audio.rst
View File

@ -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

17
components/switch/ble_client.rst
View File

@ -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

19
components/text_sensor/ble_scanner.rst
View File

@ -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 <config-esp32_ble_tracker>` 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 <config-esp32_ble_tracker>` 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

8
components/voice_assistant.rst
View File

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