[nRF52] Put the most common case first (Adafruit bootloader) #5549
Conversation
lboue
changed the title
There was a problem hiding this comment.
Pull Request Overview
This PR reorganizes the flashing instructions for nRF52 boards by reordering sections and improving documentation clarity.
- Moved Adafruit nRF52 Bootloader section before MCUboot section
- Enhanced board compatibility information for Adafruit bootloader method
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughReorders and updates the nRF52 documentation: reintroduces MCUboot SWD flashing steps with example device config, moves that section after the Adafruit bootloader content, and expands the Adafruit bootloader flashing steps to cover additional boards, UF2 copy instructions, and USB CDC update notes. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsGit: Failed to clone repository. Please run the 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. Comment |
![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 (2)
content/components/nrf52.md (2)
34-34: Inconsistent list formatting in board specification.Line 34 mixes board names with inconsistent structure: "Adafruit, Promicro nRF52840, Seeed Studio XIAO BLE" creates ambiguity about which items are brands vs. model numbers.
-For Adafruit, Promicro nRF52840, Seeed Studio XIAO BLE boards via a flash drive. +For Adafruit, Promicro nRF52840, and Seeed Studio XIAO BLE boards, flashing is done via a USB flash drive:This addition clarifies that all three boards use the USB flash drive method and improves readability.
32-50: Add clarity to distinguish initial flashing from update procedures.The section combines two distinct operational phases (initial flashing via USB drive; subsequent updates via USB CDC) in a way that could confuse readers about their relationship and usage flow.
Consider adding subheadings or clearer introductory text to separate these methods:
-This bootloader supports updates over USB CDC. - -1. Connect the board to the PC via USB. -1. Quickly short the reset pin to ground twice. -1. Run `esphome upload yourfile.yaml`. +### Updating Firmware (After Initial Flash) + +This bootloader supports updates over USB CDC without needing the flash drive: + +1. Connect the board to the PC via USB. +1. Quickly short the reset pin to ground twice. +1. Run `esphome upload yourfile.yaml`.This helps readers understand that the USB CDC method applies to subsequent updates, not the initial flash.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/components/nrf52.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
content/components/nrf52.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Learnt from: CR
Repo: esphome/esphome-docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-24T00:13:13.459Z
Learning: Open pull requests against the correct base branch: use `current` for documentation-only revisions and `next` for changes tied to new features in esphome/esphome
🔇 Additional comments (1)
content/components/nrf52.md (1)
52-63: MCUboot section is well-structured and complete.The reintroduced MCUboot section clearly explains the SWD flashing requirement, provides practical guidance (ST-Link V2 reference), and includes appropriate example configuration. The placement after Adafruit bootloader successfully prioritizes the more common case, aligning with the PR objective.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
content/components/nrf52.md (2)
34-34: Clarify board enumeration in the introductory line.Line 34 could be misleading: "Adafruit" without qualification is vague—it should reference specific board variants from the configuration variables (line 23:
adafruit_feather_nrf52840,adafruit_itsybitsy_nrf52840). Consider rephrasing to explicitly name the boards or reference the configuration section.Current phrasing:
For Adafruit, ProMicro nRF52840, Seeed Studio XIAO BLE boards via a flash drive.Suggested revision:
For Adafruit Feather, Adafruit ItsyBitsy, ProMicro nRF52840, and Seeed Studio XIAO BLE boards (flashing via USB mass storage).
36-44: Clarify the two-step Adafruit flashing workflow.The instructions present two separate procedures (lines 36–38 for initial flashing, lines 42–44 for USB CDC updates), but the distinction between them is not explicit. This can confuse users about whether both steps are needed for the first flash.
Consider restructuring as:
### Initial Flashing 1. Connect the board to the PC via USB. 1. Quickly short the reset pin to ground twice. 1. Copy the UF2 package to the flash drive. ### Updating via USB CDC This bootloader supports updates over USB CDC for subsequent firmware updates. 1. Connect the board to the PC via USB. 1. Quickly short the reset pin to ground twice. 1. Run `esphome upload yourfile.yaml`.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/components/nrf52.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
content/components/nrf52.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Learnt from: CR
Repo: esphome/esphome-docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-24T00:13:13.459Z
Learning: Open pull requests against the correct base branch: use `current` for documentation-only revisions and `next` for changes tied to new features in esphome/esphome
🔇 Additional comments (1)
content/components/nrf52.md (1)
52-63: LGTM!The MCUboot section is properly structured with clear instructions for SWD-based flashing, hardware requirements (ST-Link V2 reference), and a complementary example configuration. Placement after the Adafruit bootloader section aligns with the PR objective to put the most common case first.
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
1 participant
Description:
This PR reorganizes the flashing instructions for nRF52 boards by reordering sections and improving documentation clarity.
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.New Component Images
If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.
To generate a component image:
Comment on this pull request with the following command, replacing
COMPONENT_NAMEwith your component name in UPPER_CASE format with underscores (e.g.,BME280,SHT3X,DALLAS_TEMP):The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.
Extract the SVG file and place it in the
images/folder of this repository.Use the image in your component's index table entry in
/components/index.rst.Example: For a component called "DHT22 Temperature Sensor", use: