Doc: Add a warning about versions 2.0.2 and later of the Raspberry Pi Imager not working properly (#2340)

## Description

FRC Team 6413 ran into problems trying to write the 2026.1.1 image using
the Raspberry Pi Imager tool. After some investigation we discovered a
bug was introduced in v2.0.2 of the imager tool which prevents it from
writing the PhotonVision images to any SD card on any Windows 10 or
Windows 11 computer.

Attempting to write a custom image (.img and .img.xz) results in the
following error dialog appearing as soon as the write action is
confirmed:

<img width="684" height="483" alt="photonvisionBurnFailure202"
src="https://github.com/user-attachments/assets/5c802ef0-75f9-4056-ac1f-760dcd3605bf"
/>

Versions 2.0.0 and earlier will successfully write the image files to
the selected SD card.

## Meta

Merge checklist:
- [X] Pull Request title is [short, imperative
summary](https://cbea.ms/git-commit/) of proposed changes
- [X] The description documents the _what_ and _why_, including events
that led to this PR
- [ ] If this PR changes behavior or adds a feature, user documentation
is updated
- [ ] If this PR touches photon-serde, all messages have been
regenerated and hashes have not changed unexpectedly
- [ ] If this PR touches configuration, this is backwards compatible
with all settings going back to the previous seasons's last release
(seasons end after champs ends)
- [ ] If this PR touches pipeline settings or anything related to data
exchange, the frontend typing is updated
- [ ] If this PR addresses a bug, a regression test for it is added
This commit is contained in:
Bruce Kahn
2026-01-28 17:45:30 -07:00
committed by GitHub
parent a39844328d
commit da88867c60

View File

@@ -28,6 +28,10 @@ Unless otherwise noted in release notes or if updating from the prior years vers
Use the [Raspberry Pi Imager](https://www.raspberrypi.com/software/) to flash the image onto the coprocessors microSD card. Select the downloaded `.img.xz` file, select your microSD card, and flash.
:::{warning}
Avoid using Raspberry Pi Imager version 2.0.2 or later. Those versions fail to write the image to an SD card. Versions 2.0.0 and earlier write images successfully. [GitHub issue 1489](https://github.com/raspberrypi/rpi-imager/issues/1489) was created for this problem.
:::
:::{warning}
Balena Etcher has been recommended in the past, but should no longer be used due to instability and lack of ongoing support from developers.
:::