-
Notifications
You must be signed in to change notification settings - Fork 1.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
FAQ updates/rewrite #4593
FAQ updates/rewrite #4593
Conversation
WalkthroughThis pull request focuses on enhancing the ESPHome documentation, specifically in the FAQ and getting started guides. Key changes include the addition of a new section on selecting ESP microcontrollers, a restructuring of troubleshooting instructions, and improvements in document clarity. Additionally, a reference label was introduced in the getting started guide to facilitate better navigation and cross-referencing. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 1
🧹 Nitpick comments (3)
guides/faq.rst (3)
8-87
: Add a reference label for the ESP selection guide section.Consider adding a reference label to make this section linkable from other parts of the documentation, as it's a frequently referenced topic.
+.. _which-esp-to-use: + Which ESP should I use for my project? --------------------------------------
Line range hint
200-233
: Enhance YAML example readability with comments.The YAML examples would benefit from inline comments explaining the purpose of each section, especially for the variables substitution feature.
binary_sensor: - platform: gpio id: button1 pin: GPIOXX - on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax + on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # Inline syntax with variable substitution - platform: gpio id: button2 pin: GPIOXX on_multi_click: !include - # multi-line syntax + # Multi-line syntax with variable substitution file: on-multi-click.yaml vars: id: 2
288-290
: Make logging level guidance more prominent.Consider making the logging level guidance more prominent by using a note directive, as it's crucial for troubleshooting.
-3. If it's a hardware communication issue (such as with an I²C or SPI device), try setting the - :ref:`log level <logger-log_levels>` to ``VERY_VERBOSE`` as it may provide better insight into what is going on. -4. Please describe what troubleshooting steps you've already tried as that may also help us track down the issue. +3. .. note:: + + If it's a hardware communication issue (such as with an I²C or SPI device), try setting the + :ref:`log level <logger-log_levels>` to ``VERY_VERBOSE`` as it may provide better insight into what is going on. + +4. Please describe what troubleshooting steps you've already tried as that may also help us track down the issue.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
guides/faq.rst
(7 hunks)guides/getting_started_hassio.rst
(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- guides/getting_started_hassio.rst
🧰 Additional context used
📓 Path-based instructions (1)
guides/faq.rst (1)
Pattern **
: - Do not generate or add any sequence diagrams
🪛 GitHub Check: build
guides/faq.rst
[failure] 342-342:
Directive 'code-block' is not followed by an empty line. Please insert an empty line after guides/faq.rst:342
🔇 Additional comments (2)
guides/faq.rst (2)
293-353
: LGTM! Clear and comprehensive update instructions.The update instructions are well-organized and cover all installation methods clearly.
🧰 Tools
🪛 GitHub Check: build
[failure] 342-342:
Directive 'code-block' is not followed by an empty line. Please insert an empty line after guides/faq.rst:342
Line range hint
354-644
: LGTM! Well-structured FAQ sections with clear explanations.The remaining FAQ sections are comprehensive and well-formatted, providing clear guidance on various topics.
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 1
🧹 Nitpick comments (4)
guides/faq.rst (4)
8-87
: Excellent addition of ESP device recommendations!The new section provides comprehensive guidance on ESP device selection with clear categorization and well-reasoned explanations. The recommendations are current and align with best practices.
396-430
: Comprehensive Wi-Fi troubleshooting guide.The section provides detailed explanations of common Wi-Fi issues and their potential solutions, including power save modes, hardware considerations, and connection management.
Line range hint
489-532
: Well-documented Docker setup with network considerations.The Docker Compose example and networking explanations are clear and include important considerations for different environments.
586-608
: Comprehensive explanation of strapping pins.The section effectively explains the implications of using strapping pins and provides clear guidance on when and how to use them safely.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
guides/faq.rst
(7 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
guides/faq.rst (1)
Pattern **
: - Do not generate or add any sequence diagrams
🔇 Additional comments (8)
guides/faq.rst (8)
91-190
: Well-structured USB installation troubleshooting guide.The reorganized section improves clarity by:
- Separating common issues into clear bullet points
- Providing detailed steps for manual installation
- Including comprehensive troubleshooting steps
259-268
: Clear and concise troubleshooting steps.The section effectively directs users to relevant resources and documentation.
272-292
: Enhanced issue reporting guidelines.The section now better emphasizes the importance of providing detailed information and following best practices when reporting issues.
355-365
: Clear explanation of Home Assistant secrets integration.The section effectively explains how to integrate Home Assistant's secrets.yaml with ESPHome configurations.
435-447
: Clear instructions for NVS partition issues.The section effectively explains how to handle NVS partition issues affecting state restoration.
569-575
: Important naming convention guidance.The section clearly explains why underscores should be avoided in device names and provides the recommended alternative.
613-631
: Clear instructions for testing pull requests.The section provides a practical approach to testing pull requests using external components.
633-638
: Clear explanation of deep sleep entity behavior.The section effectively explains why entities might appear as "unavailable" during deep sleep and provides a solution.
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (5)
guides/faq.rst (5)
8-87
: Excellent section with room for technical enhancements.The new section provides clear guidance on ESP selection. Consider enhancing it with:
- Specific technical capabilities of ESP32-C3 (e.g., single-core frequency, RAM size)
- Exact RAM/flash specifications for recommended ESP32 variants for easier comparison
166-167
: Consider adding USB-C specific guidance.The USB cable section could benefit from mentioning common issues with USB-C cables, particularly:
- USB-C to USB-C cables that may be power-only
- USB-C cables that don't properly negotiate data connections
211-238
: Enhance YAML examples with explanatory comments.The multi-click example would be clearer with inline comments explaining:
- The purpose of the
${id}
substitution- The relationship between the included files
433-436
: Clarify DTIM impact statement.The explanation of DTIM's impact on power usage could be clearer. Consider specifying:
- Which devices are affected by increased power usage
- Whether this applies to both battery and mains-powered devices
Line range hint
469-494
: Add Docker volume permissions guidance.Consider adding a note about:
- Required permissions for the config directory
- How to handle permission issues in different operating systems
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
guides/faq.rst
(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
guides/faq.rst (1)
Pattern **
: - Do not generate or add any sequence diagrams
🔇 Additional comments (1)
guides/faq.rst (1)
281-353
: Well-structured issue reporting guidelines.The section provides clear, actionable guidance for users to report issues effectively.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (7)
guides/faq.rst (7)
31-31
: Enhance link text for better accessibility.The link text "per Espressif" could be more descriptive for better accessibility and context.
- - Generally intended (`per Espressif <https://www.espressif.com/news/ESP32_C3>`__) to replace the well-known ESP8266. + - Generally intended (`according to Espressif's announcement <https://www.espressif.com/news/ESP32_C3>`__) to replace the well-known ESP8266.
66-69
: Add cross-reference links to technical terms.Consider adding cross-reference links to technical terms like "displays" and "vendor-provided libraries" to help users find related documentation.
- - Some components require more RAM than is available on the ESP8266 -- (large) displays and - :doc:`some sensors</components/sensor/bme68x_bsec2>` are known to regularly provoke issues/crashes on ESP8266s. + - Some components require more RAM than is available on the ESP8266 -- :doc:`large displays</components/display/index>` and + :doc:`some sensors</components/sensor/bme68x_bsec2>` are known to regularly provoke issues/crashes on ESP8266s.
193-195
: Add empty line after code-block directive.For consistency with RST formatting standards, add an empty line after the code-block directive.
.. code-block:: bash + esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash 0x0 your_node_firmware.bin
212-225
: Add comments explaining the variables in the YAML example.Consider adding comments to explain the purpose of variables and the structure of the configuration.
binary_sensor: - platform: gpio id: button1 pin: GPIOXX + # Example of inline variable substitution on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax - platform: gpio id: button2 pin: GPIOXX + # Example of multi-line variable substitution on_multi_click: !include # multi-line syntax file: on-multi-click.yaml vars: id: 2
319-334
: Improve version-specific instructions formatting.Consider using a definition list or table to clearly separate instructions for different installation methods.
-ESPHome has a beta release cycle so that new releases can easily be tested before the changes are deployed to the -stable channel. You can help test ESPHome (and use new features) by installing the beta: +ESPHome has a beta release cycle so that new releases can easily be tested before the changes are deployed to the +stable channel. You can help test ESPHome (and use new features) by installing the beta using one of these methods: -- For Home Assistant supervised installs, search for "ESPHome" in the Add-on Store. Note that the add-ons are named - accordingly; for the beta version, you'll want "ESPHome Device Builder (beta)". -- If you're running the container in Docker independently of Home Assistant: +Home Assistant supervised installs + Search for "ESPHome" in the Add-on Store. Note that the add-ons are named accordingly; for the beta version, + you'll want "ESPHome Device Builder (beta)". +Docker container (independent of Home Assistant) .. code-block:: bash # For pip-based installs
408-437
: Organize Wi-Fi troubleshooting steps by category.Consider grouping the troubleshooting steps into categories (e.g., Configuration, Hardware, Network) for better readability.
Here are some steps that may help mitigate the issue: +Configuration-related: - If you're using a hidden Wi-Fi network, make sure to enable ``fast_connect`` mode in your device's Wi-Fi configuration. Note that this may help with non-hidden networks, as well. - Give your ESPHome device a :ref:`static IP <wifi-manual_ip>`. - Set the ``power_save_mode`` to ``light`` in your ``wifi:`` configuration. + +Hardware-related: - The issue seems to happen with "cheap" boards more frequently -- especially the "cheap" NodeMCU boards from eBay which sometimes have bad antennas. + +Connection-related: - ESPHome intentionally reboots after a configured duration in specific situations, such as when the
Line range hint
470-496
: Group Docker commands by functionality.Consider organizing the Docker commands into logical groups (e.g., Basic Usage, Advanced Usage, Configuration) for better readability.
-ESPHome Command Reference: +ESPHome Docker Command Reference: + +Basic Usage: # Start a new file wizard for file livingroom.yaml docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml # Compile and upload livingroom.yaml docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome run livingroom.yaml # View logs docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome logs livingroom.yaml +Advanced Usage: # Map /dev/ttyUSB0 into container docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome ... +Dashboard Configuration: # Start dashboard on port 6052 (general command)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
guides/faq.rst
(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
guides/faq.rst (1)
Pattern **
: - Do not generate or add any sequence diagrams
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (4)
guides/faq.rst (4)
125-197
: Consider adding a note about Linux permissions.The esptool section is well-documented, but it would be helpful to add a note about requiring appropriate permissions (e.g., being in the
dialout
group) to access serial ports on Linux systems.
213-240
: Fix YAML example consistency.The YAML example uses
GPIOXX
as a placeholder pin number, which might be confusing. Consider using a realistic GPIO number (e.g.,GPIO5
) for better clarity.
405-438
: Consider adding antenna placement guidance.While the Wi-Fi troubleshooting section is comprehensive, it would be helpful to add a note about antenna orientation and placement affecting signal strength (e.g., keeping the antenna vertical and away from metal objects).
Line range hint
471-497
: Consider adding SELinux guidance.For Linux users, it would be helpful to add a note about potential SELinux-related issues when accessing USB devices and how to resolve them (e.g., using
semanage
to allow container access to USB devices).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
guides/faq.rst
(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
guides/faq.rst (1)
Pattern **
: - Do not generate or add any sequence diagrams
🔇 Additional comments (4)
guides/faq.rst (4)
8-89
: Excellent section on ESP selection guidance!The section provides clear, well-reasoned recommendations with detailed explanations of the pros and cons of each microcontroller option. The additional considerations about RAM, flash memory, and future-proofing are particularly valuable.
93-119
: Well-structured installation instructions!The section provides clear, step-by-step instructions for both automated and manual installation methods, with proper cross-references to related sections.
160-198
: Comprehensive USB troubleshooting guide!The section effectively covers common issues and provides clear, actionable solutions.
267-300
: Excellent guidance on issue reporting!The sections effectively guide users on how to report issues and what information to include, which will help maintainers provide better support.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 1
🧹 Nitpick comments (5)
guides/faq.rst (5)
8-88
: Enhance microcontroller selection guidance with specific requirements.The section provides excellent recommendations, but could be even more helpful by:
- Including minimum RAM/flash requirements for running ESPHome.
- Adding a comparison table of key specifications (RAM, flash, GPIO count, etc.) for quick reference.
279-299
: Consider adding an issue template example.The issue reporting guidelines are excellent. Consider adding a minimal issue template to demonstrate the expected format and required information.
434-437
: Consider explaining DTIM in more detail.While the DTIM interval recommendation is valuable, consider adding a brief explanation of what DTIM is and how it affects Wi-Fi devices, to help users make informed decisions about adjusting this setting.
Line range hint
496-539
: Consider adding security best practices for Docker deployment.The Docker configuration examples are clear, but consider adding security best practices such as:
- Using non-root user inside the container
- Setting resource limits
- Using read-only mounts where possible
593-615
: Consider adding specific pin numbers for common boards.The strapping pins explanation is excellent. Consider adding a table listing the specific strapping pin numbers for commonly used boards (ESP8266, ESP32, ESP32-S3, etc.) to make the guidance more actionable.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
guides/faq.rst
(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
guides/faq.rst (1)
Pattern **
: - Do not generate or add any sequence diagrams
🔇 Additional comments (2)
guides/faq.rst (2)
92-118
: LGTM! Clear and comprehensive installation instructions.The installation instructions are well-structured and provide both automated and manual approaches.
266-275
: LGTM! Clear troubleshooting guidance.The section effectively guides users through common troubleshooting steps and provides appropriate resources.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
🧹 Nitpick comments (1)
guides/faq.rst (1)
34-35
: Clarify power usage description.Based on past review comments, consider clarifying that this refers to electrical power usage.
- - You need a lower-power device than the ESP32(-Sx) family offers. + - You need a device with lower (electricity) power usage than the ESP32(-Sx) family offers.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
guides/faq.rst
(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
guides/faq.rst (1)
Pattern **
: - Do not generate or add any sequence diagrams
🔇 Additional comments (5)
guides/faq.rst (5)
Line range hint
8-637
: Well-structured and comprehensive documentation update!The documentation provides clear guidance on ESP selection, troubleshooting, and best practices. The new sections, particularly the ESP selection guide, will be very helpful for users.
342-342
:⚠️ Potential issueFix RST formatting: Add empty line after code-block directive.
Add an empty line after the code-block directive to comply with RST formatting standards.
.. code-block:: bash + pip3 install https://github.com/esphome/esphome/archive/dev.zip
Likely invalid or redundant comment.
194-194
:⚠️ Potential issueFix circular reference in troubleshooting section.
The line creates a circular reference by pointing back to the same section. Consider removing this line or providing alternative next steps.
-If you *still* can't get it to work, you might want to revisit :ref:`faq-usb_troubleshooting` above.
Likely invalid or redundant comment.
27-27
:⚠️ Potential issueFix incorrect component reference.
The line references
micro_wake_word
component, but based on past review comments, this should bevoice_assistant
.- learning (:doc:`/components/micro_wake_word`, for example). + learning (:doc:`/components/voice_assistant`, for example).Likely invalid or redundant comment.
346-348
:⚠️ Potential issueFix RST formatting: Remove extra backtick.
There's an extra backtick at the end of the command.
- pip3 install https://github.com/esphome/esphome/archive/dev.zip`` + pip3 install https://github.com/esphome/esphome/archive/dev.zipLikely invalid or redundant comment.
Description:
SSIA
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable): esphome/esphome#
Checklist:
I am merging into
next
because this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
current
because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/index.rst
when creating new documents for new components or cookbook.