Add troubleshooting guide #4995
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
""" WalkthroughA new troubleshooting guide was added, focusing on diagnosing device crashes and obtaining decoded backtraces. Multiple documentation files were updated to reference this guide in their "See Also" or warning sections, and the FAQ was updated to suggest the guide as a troubleshooting step for crashes. No code or API changes were made. Changes
Sequence Diagram(s)sequenceDiagram
User->>Documentation: Encounters device crash
Documentation->>guides/troubleshooting.rst: Directs user to troubleshooting guide
User->>guides/troubleshooting.rst: Follows step-by-step instructions
guides/troubleshooting.rst->>User: Provides procedures for obtaining and decoding backtraces
User->>Support/Issue Tracker: Submits decoded backtrace if further help is needed
Suggested reviewers
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. 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 (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
guides/troubleshooting.rst (4)
4-7: Validate SEO metadata and image reference
The:description:and:image:entries look correct, but double-check thatbug-report.svgis available in the static assets and that the description captures key search terms (e.g., “backtrace”, “crash debugging”).
8-11: Intro needs a stronger hook
Consider adding a brief sentence linking here from the main index or noting prerequisites (e.g., YAML version) to orient the reader.
49-64: Collapse excessive blank lines in backtrace example
Lines 60–63 are blank within thecode-block:: text; consider removing or reducing them to improve readability.
89-95: Consider adding Safe Mode to See Also
To mirror the cross-references you've added elsewhere, you may want to include the Safe Mode guide here:- :doc:`/components/safe_mode` - Safe Mode recovery guidecomponents/logger.rst (1)
326-326: Unify link text across components
Phrasing (“including how to get backtraces”) differs slightly from other components. Consider standardizing to “Troubleshooting guide for obtaining decoded backtraces”.components/debug.rst (1)
101-101: Standardize cross-ref phrasing
Link text (“including how to get backtraces from crashes”) differs from logger/safe_mode. Consider aligning wording for consistency.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
components/debug.rst(1 hunks)components/logger.rst(1 hunks)components/safe_mode.rst(1 hunks)components/voice_assistant.rst(1 hunks)guides/faq.rst(1 hunks)guides/troubleshooting.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
components/safe_mode.rstcomponents/logger.rstcomponents/debug.rstcomponents/voice_assistant.rstguides/faq.rstguides/troubleshooting.rst
🔇 Additional comments (14)
guides/troubleshooting.rst (11)
1-2: Title formatting is correct
The underline matches the title length and uses the proper level for a top-level heading.
13-18: Checklist formatting is consistent
Numbered list clearly outlines prerequisites. No changes needed.
19-21: Section heading style is correct
The underline length and character (~) are appropriate for a second-level section.
22-31: Step 1 link verification
The reference to the CLI guide uses an absolute path (:doc:/guides/cli``). Please verify this resolves correctly in the built documentation.
32-36: Code block indentation is valid
The block directive and its content are indented properly; no adjustments required.
37-40: Note admonition is clear
The rationale for preferring USB upload is concise and well-placed.
41-48: Steps 2 and 3 are self-explanatory
Instructions for connecting via USB and monitoring logs are clear.
45-48: Logs code block indentation
Matches the earlier block. Consistency confirmed.
73-78: Decoded backtrace explanation is clear
The bullet list succinctly summarizes what the user gains from the decoded output.
79-82: “Important” note formatting is correct
The admonition emphasizes the need for matching debug symbols.
83-88: Common issues section is well-structured
Both troubleshooting tips address the most likely user mistakes.components/safe_mode.rst (1)
53-53: New See Also entry looks good
The link text accurately reflects the guide’s purpose.guides/faq.rst (1)
270-270: FAQ entry is consistent
Bullet and bold formatting matches the existing style and clearly points to the troubleshooting guide.components/voice_assistant.rst (1)
21-22: Add troubleshooting guide reference for crashesNicely directs users experiencing crashes to the new troubleshooting guide. Links and formatting match existing documentation patterns.
There was a problem hiding this comment.
We also have https://esphome.github.io/esp-stacktrace-decoder/ to allow users to "upload" (nothing leaves the browser) the encoded stack trace along with the .elf file (available to download from the dashboard in the menu on the card [only works if you have not recompiled since last flashing the device])
|
Didn't know about that. I'll incorporate it in as its not mentioned anywhere in the docs currently AFAICT |
|
Yeah its relatively new to ESPHome, I forked it as someone wanted to fix some bugs then the author reached out recently and we transferred into the org for better visibility |
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
components/debug.rst(1 hunks)components/logger.rst(1 hunks)guides/troubleshooting.rst(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- components/debug.rst
- components/logger.rst
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
guides/troubleshooting.rst
🪛 GitHub Check: build
guides/troubleshooting.rst
[failure] 97-97:
Directive 'note' is not followed by an empty line. Please insert an empty line after guides/troubleshooting.rst:97
🪛 GitHub Actions: Lint
guides/troubleshooting.rst
[error] 97-97: lint: Directive 'note' is not followed by an empty line. Please insert an empty line after line 97.
🔇 Additional comments (1)
guides/troubleshooting.rst (1)
1-122: Comprehensive and well-structured guideThe new troubleshooting document is thorough, clear, and logically organized—covering compilation, USB connection, log monitoring, decoding (both CLI and web-based), and common pitfalls. It integrates examples and “See Also” links effectively.
|
Thanks 🙏 |
Description:
This PR adds comprehensive documentation on how to obtain stack traces from ESPHome device crashes. The new troubleshooting guide provides step-by-step instructions for debugging crashes, including:
esphome logsto capture and automatically decode stack tracesThe guide has been linked from relevant documentation pages including the logger component, debug component, safe mode component, FAQ, and voice assistant warnings.
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.