Merge branch 'current' into addressable_light_digital_display

Author: daweizhangau

components/api.rst

@@ -31,6 +31,16 @@ A Python library that implements this protocol is `aioesphomeapi <https://github
     # Example configuration entry
     api:
 
+.. code-block:: yaml
+
+    # Example with more options
+    api:
+      port: 6053
+      batch_delay: 50ms  # Reduce latency for real-time applications
+      encryption:
+        key: "YOUR_ENCRYPTION_KEY_HERE"
+      reboot_timeout: 30min
+
 Configuration variables:
 ------------------------
 
@@ -75,6 +85,9 @@ Configuration variables:
         Support for configuring the encryption key on-the-fly will be implemented in a future release of Home Assistant.
 
 - **actions** (*Optional*, list): A list of user-defined actions. See :ref:`api-device-actions`.
+- **batch_delay** (*Optional*, :ref:`config-time`): The delay time for batching multiple state update messages
+  together to reduce network overhead. Lower values send updates sooner but use more network packets,
+  while higher values batch more efficiently but add latency. Defaults to ``100ms``.
 - **reboot_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before rebooting when no
   client connects to the API. This is needed because sometimes the low level ESP functions report that
   the ESP is connected to the network, when in fact it is not - only a full reboot fixes it.

components/debug.rst

@@ -98,5 +98,6 @@ See Also
 
 - :ref:`sensor-filters`
 - :doc:`logger`
+- :doc:`/guides/troubleshooting` - Troubleshooting guide for debugging crashes and boot failures
 - :apiref:`debug/debug_component.h`
 - :ghedit:`Edit`

components/logger.rst

@@ -343,5 +343,6 @@ See Also
 
 - :doc:`/components/uart`
 - :doc:`/components/select/logger`
+- :doc:`/guides/troubleshooting` - Troubleshooting guide for debugging crashes and boot failures
 - :apiref:`logger/logger.h`
 - :ghedit:`Edit`

components/safe_mode.rst

@@ -50,4 +50,5 @@ See Also
 - :apiref:`safe_mode/safe_mode.h`
 - :doc:`/components/button/safe_mode`
 - :doc:`/components/switch/safe_mode`
+- :doc:`/guides/troubleshooting` - Troubleshooting guide for debugging crashes and boot failures
 - :ghedit:`Edit`

components/voice_assistant.rst

@@ -18,6 +18,8 @@ ESPHome devices with a microphone are able to stream the audio to Home Assistant
     **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.
+    
+    If you experience crashes, see the :doc:`/guides/troubleshooting` guide for how to get a backtrace.
 
 Configuration variables:
 ------------------------

guides/cli.rst

@@ -285,3 +285,53 @@ You can register ESPHome for auto-completion by adding the following to your ~/.
     eval "$(register-python-argcomplete esphome)"
 
 For more information, see `argcomplete <https://kislyuk.github.io/argcomplete/>`__ documentation.
+
+Using logging tools supplied with ESPHome
+-----------------------------------------
+There are two types of logging interfaces supplied with ESPHome: API and Serial (UART) logging.
+For serial logging, there are many options including `ESPHome Web <https://web.esphome.io>`__ and
+the ESPHome CLI's ``run`` command.
+
+For basic API based logging uses, one can use the ``aioesphomeapi-logs`` command bundled with ESPHome,
+Which is especially useful for ESP devices in a remote/inaccessible location.
+
+The syntax is as follows:
+
+.. code-block:: console
+
+    aioesphomeapi-logs <IPv4 pr IPv6 address>
+
+Some working examples include:
+
+.. code-block:: console
+
+    aioesphomeapi-logs 192.168.x.y
+    aioesphomeapi-logs fe80::cdef:0123:4567:89ab
+    aioesphomeapi-logs 2001:0db8:3333:4444:5555:6666:7777:8888
+
+Press ``CTRL+C`` to exit the logging view.
+
+If you have configured encryption for API, provide the key from the yaml as follows:
+
+.. code-block:: console
+
+    aioesphomeapi-logs 192.168.x.y --noise-psk <your-api-key-from-yaml>
+
+If you do not know/wish to know the IP address of an ESPHome device,
+one can also use ``aioesphomeapi-discover`` to discover online ESPHome devices on the local network.
+
+The syntax is as follows:
+
+.. code-block:: console
+
+    aioesphomeapi-discover
+
+The response lists info about currently available ESPHome devices:
+
+``Status |Name |Address |MAC |Version |Platform |Board``
+
+See Also
+--------
+
+- :doc:`Guides </guides/index>`
+- :ghedit:`Edit`

guides/faq.rst

@@ -267,6 +267,7 @@ That's no good. Here are some steps that resolve some problems:
 
 - **If you're having Wi-Fi problems**: See :ref:`wifi-problems`.
 - :ref:`Enable verbose logs<logger-log_levels>` in your ESPHome device's ``logger:`` section.
+- **If your device is crashing**: See the :doc:`/guides/troubleshooting` guide for how to get a backtrace.
 - **Still seeing an error?** Check if there is a known issue in the
   `ESPHome issue tracker <https://github.com/esphome/issues/issues>`__. If not, you can create a new issue to describe your
   problem there. We will take a look at it as soon as we can. Thanks!

guides/troubleshooting.rst

@@ -0,0 +1,121 @@
+Troubleshooting
+===============
+
+.. seo::
+    :description: Guide for troubleshooting ESPHome issues, debugging crashes, and obtaining decoded stack traces from device failures.
+    :image: bug-report.svg
+
+This guide helps you diagnose and debug ESPHome device issues, particularly crashes and boot failures. Whether you're experiencing random resets, watchdog timeouts, or need to analyze stack traces, this guide provides step-by-step instructions for capturing and understanding crash data.
+
+.. note::
+
+    This guide assumes you have ESPHome installed and basic familiarity with the command line. For installation instructions, see :doc:`/guides/installing_esphome`.
+
+Getting a Stack Trace from Crashes
+-----------------------------------
+
+When your ESPHome device crashes, you can obtain a decoded stack trace to help identify the cause. This requires:
+
+1. Compiling the firmware locally (to have matching debug symbols)
+2. Connecting the device via USB cable for serial console access
+3. Running the logs command to capture and decode the crash
+
+Steps to Get a Stack Trace
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Compile locally**: Build your configuration on your local machine to ensure you have matching debug symbols.
+
+   If you're using the ESPHome Device Builder web interface:
+   
+   - Click the overflow menu (three dots) next to your device
+   - Select "Download YAML" to get your configuration file
+   - Save it to a local directory
+   
+   Then use the command line interface (see the :doc:`/guides/cli` guide for full details):
+
+   .. code-block:: bash
+
+       esphome compile your-device.yaml
+       esphome upload your-device.yaml
+
+   .. note::
+
+       While you can use OTA for the upload, you'll need a USB connection anyway to capture the crash output in the next steps, so uploading via USB is usually more convenient.
+
+2. **Connect via USB**: Connect your device to your computer using a USB cable. The device must be connected via serial console (not over WiFi/OTA) to capture the crash output.
+
+3. **Monitor logs**: Run the logs command to monitor the device output:
+
+   .. code-block:: bash
+
+       esphome logs your-device.yaml
+
+4. **Wait for crash**: When the device crashes, ESPHome will automatically detect and decode the stack trace. You'll see output similar to this:
+
+   .. code-block:: text
+
+       [08:17:06]E (5906) task_wdt: Task watchdog got triggered. The following tasks/users did not reset the watchdog in time:
+       [08:17:06]E (5906) task_wdt:  - loopTask (CPU 0)
+       [08:17:06]E (5906) task_wdt: Tasks currently running:
+       [08:17:06]E (5906) task_wdt: CPU 0: esp_timer
+       [08:17:06]E (5906) task_wdt: CPU 1: IDLE1
+       [08:17:06]E (5906) task_wdt: Aborting.
+       [08:17:06]E (5906) task_wdt: Print CPU 0 (current core) backtrace
+       
+       [08:17:06]Backtrace: 0x4013d30e:0x3ffbac20 0x4013d383:0x3ffbac40 0x4014b23e:0x3ffbac70
+       WARNING Found stack trace! Trying to decode it
+       WARNING Decoded 0x4013d30e: touch_ll_is_measure_done at /Users/bdraco/.platformio/packages/framework-espidf/components/hal/esp32/include/hal/touch_sensor_ll.h:505
+        (inlined by) _touch_pad_read at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:365
+       WARNING Decoded 0x4013d383: touch_pad_filter_cb at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:108
+        (inlined by) touch_pad_filter_cb at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:98
+       WARNING Decoded 0x4014b23e: timer_process_alarm at /Users/bdraco/.platformio/packages/framework-espidf/components/esp_timer/src/esp_timer.c:456
+        (inlined by) timer_task at /Users/bdraco/.platformio/packages/framework-espidf/components/esp_timer/src/esp_timer.c:482
+
+The decoded stack trace shows:
+
+- The exact function names and source files where the crash occurred
+- Line numbers in the source code
+- The call stack leading to the crash
+
+.. note::
+
+    **Important**: You must compile locally and upload the firmware before capturing the crash. The debug symbols must match the running firmware for the stack trace to be decoded correctly.
+
+Common Issues
+~~~~~~~~~~~~~
+
+- **No decoded output**: Ensure you compiled and uploaded the firmware locally before capturing the crash
+- **Cannot connect**: Make sure you're using a USB data cable (not just a charging cable) and the correct serial port
+
+Alternative: Web-Based Stack Trace Decoder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you already have a stack trace but need to decode it, you can use the `ESP Stack Trace Decoder <https://esphome.github.io/esp-stacktrace-decoder/>`__ web tool:
+
+1. **Download the .elf file**: From the ESPHome dashboard, click the overflow menu (three dots) on your device card and select "Download .elf file"
+   
+   .. note::
+
+       The .elf file must be from the same compilation that produced the firmware currently running on your device. If you've recompiled since flashing, the debug symbols won't match.
+
+2. **Open the decoder**: Navigate to https://esphome.github.io/esp-stacktrace-decoder/
+
+3. **Upload files**: 
+   
+   - Click "Choose File" under "ELF File" and select your downloaded .elf file
+   - Paste your stack trace into the text area
+   - Click "Decode Stack Trace"
+
+4. **View results**: The tool will decode the addresses and show you the function names, file paths, and line numbers
+
+.. note::
+
+    This tool runs entirely in your browser - no data is sent to any server, ensuring your firmware and debug information remain private.
+
+See Also
+--------
+
+- :doc:`/components/logger` - Configure logging levels and outputs
+- :doc:`/components/debug` - Debug component for additional diagnostics
+- :doc:`/components/safe_mode` - Safe Mode recovery guide
+- :doc:`/guides/faq` - Frequently asked questions