common: consolidate firmware loading onto a single page - #8002
Conversation
|
It probably makes sense to have a single page but it becomes a big page so I wonder if we should have an index at the top to allow users to more quickly jump to the section they need. |
|
It does....that's the content directive...got to build it to see |
|
Is the intent for this to cover all firmware loading? If so, it seems to be missing any reference to Linux boards, which generally handle things differently (at least as I understand it, though admittedly I only have experience using Linux boards with BlueOS). Not sure if there are other board types that similarly don't follow the described process here 🤷♂️ |
no Chibios only...historically Linux boards assume a developer level knowledge and other than listing some Linux boardds, we dont ahve much in the wiki....contributions would be welcome, of course.... |
peterbarker
left a comment
peterbarker
left a comment
There was a problem hiding this comment.
The other numbers are still made up, but this one is correct
5f01240 to
7b8b0e2
Compare
|
Thanks for this. I'm sorry but I'm not a big fan of this change because it moves the most common path that users will be on (e.g. loading ArduPilot onto a board that already has an AP bootloader on it) down at least one level (maybe two levels). Previously users would most likely be greeted with this view which immediately shows them they first need to plug in a USB cable With this change their instead presented with a complex looking list of links and many lines of text before an image is visible. If they just scroll down they're most likely misled into thinking they need to manually download a firmware from firmware.ardupilot.org. |
The setup sidebar carried two separate "Loading Firmware" entries, one for boards that already have an ArduPilot compatible bootloader and one for boards that do not, forcing the reader to decide which page applied before either page explained how to tell. Both pages also carried their own copies of the firmware download instructions and the beta/developer version descriptions. Add a single "Loading Firmware" page as the sidebar entry, ordered as the reader actually proceeds rather than as a table of contents: 1. Connect the Autopilot to the Computer - plug in over USB, without holding DFU/BOOT, so that the board comes up as it normally would. 2. Check What is Already on the Autopilot - the board's provenance, then how to read the USB device name on Windows, Linux and macOS, and what each result means. 3. Load the Firmware - branch to the ground station page or to the DFU page. 4. Test that it Worked. Reference material that interrupted that flow - firmware server navigation, the Stable, Beta, Latest Developer and Custom Builds descriptions, Parameter Conversion, Loading Firmware via SD Card, and Firmware Feature Limitations - moves to an Additional Information section below it, and the local contents block is dropped. A ground station downloads Stable firmware by itself, so only the DFU path and the non-Stable builds need the download instructions at all. The per-OS detection instructions identify the board by its own USB product string rather than by the manufacturer, since 53 of the 464 hwdefs set their own USB_STRING_MANUFACTURER, and note that the bootloader appends -BL or -Secure-BL-v10 to that name, though not every board changes it. The Parameter Conversion section takes the "Parameter Migration" text and its version migration table from ArduPilot#7981, as suggested by rmackay9 there; the wording and the table are peterbarker's. Retitle the two loading pages to say which case they cover, and reduce them to just the loading procedure, with the download, beta/developer, SD card, feature limitation and testing content now on the parent page. Both keep their existing anchors so the many board pages that link straight to them are unaffected. The ground station page also drops its own "Connect autopilot to computer" section, which is now step 1 of the parent page. Drop the Zadig and Betaflight Configurator alternate DFU method, leaving STM32CubeProgrammer as the single documented path, and remove the two images it used. The external flash/SSBL section stays, as those boards cannot be loaded with STM32CubeProgrammer at all. Point the cross-references that previously offered the reader a choice between the two pages at the new page instead. Co-authored-by: Peter Barker <pb-gh@barker.dropbear.id.au> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
7b8b0e2 to
e63ed89
Compare
4 participants
The setup sidebar carried two separate "Loading Firmware" entries — one for boards that already have an ArduPilot compatible bootloader, one for boards that do not — which asked the reader to decide which page applied before either page explained how to tell. Both pages also carried their own copies of the firmware download instructions and the beta/developer version descriptions.
New page
Adds a single Loading Firmware page (
common-loading-firmware.rst) as the sidebar entry, with a local.. contents::jump table and four sections:.apj/_with_bl.hex/.abin/.bin), then Stable, Beta, Latest Developer Version and Custom Builds.Existing pages
Both loading pages are retitled to say which case they cover, and reduced to just the loading procedure — the download, beta/developer, SD card, feature limitation and testing content now lives once on the parent page:
common-loading-firmware-onto-pixhawk→ "Loading Firmware to Boards with an ArduPilot Compatible Bootloader"common-loading-firmware-onto-chibios-only-boards→ "Loading Firmware to Boards without an ArduPilot Compatible Bootloader"Both keep their existing anchors, so the many board pages that link straight to them are unaffected.
The Zadig / Betaflight Configurator alternate DFU method is dropped, leaving STM32CubeProgrammer as the single documented path, and the two images it used are removed. The external flash / SSBL section stays, since those boards cannot be loaded with STM32CubeProgrammer at all.
The sidebar entries collapse to one in all seven menus (copter, copter tradheli, plane, rover, sub, blimp, planner), and the cross-references that previously offered the reader a choice between the two pages now point at the new page.
Parameter Conversion
The Parameter Conversion section takes the "Parameter Migration" text and its version migration table from #7981, as @rmackay9 suggested there. The wording and table are @peterbarker's.
This overlaps #7981:
common-firmware-update.rstthere still holds the same section, and would need trimming (or reducing to just its "Flying Stable ArduPilot Point Releases" section) so the text does not live in two places. No files are touched in common with #7981, so the two do not conflict in git.Testing
update.py --fastbuilds clean on copter, plane, rover and sub; no new Sphinx warnings.🤖 Generated with Claude Code