da88867c60
## 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
7.0 KiB
Quick Installation Guide
- For the following supported coprocessors
- {ref}
Raspberry Pi 3,4,5 <docs/quick-start/quick-install:Raspberry Pi and Orange Pi Installation> - {ref}
Orange Pi 5, 5B, 5 Pro <docs/quick-start/quick-install:Raspberry Pi and Orange Pi Installation> - {ref}
Limelight 2, 2+, 3, 3G, 4 <docs/quick-start/quick-install:LimeLight Installation> - {ref}
Rubik Pi 3 <docs/quick-start/quick-install:Rubik Pi 3 Installation>
- {ref}
For installing on non-supported devices {ref}see here. <docs/advanced-installation/sw_install/index:Software Installation>
Download the latest preconfigured image of photonvision for your coprocessor
| Coprocessor | Image filename | Jar |
|---|---|---|
| Raspberry Pi 3, 4, 5 | photonvision-{version}-linuxarm64_RaspberryPi.img.xz | photonvision-{version}-linuxarm64.jar |
| OrangePi 5 | photonvision-{version}-linuxarm64_orangepi5.img.xz | photonvision-{version}-linuxarm64.jar |
| OrangePi 5B | photonvision-{version}-linuxarm64_orangepi5b.img.xz | photonvision-{version}-linuxarm64.jar |
| OrangePi 5 Pro | photonvision-{version}-linuxarm64_orangepi5pro.img.xz | photonvision-{version}-linuxarm64.jar |
| Limelight 2 | photonvision-{version}-linuxarm64_limelight2.img.xz | photonvision-{version}-linuxarm64.jar |
| Limelight 3 | photonvision-{version}-linuxarm64_limelight3.img.xz | photonvision-{version}-linuxarm64.jar |
| Limelight 3G | photonvision-{version}-linuxarm64_limelight3G.img.xz | photonvision-{version}-linuxarm64.jar |
| Limelight 4 | photonvision-{version}-linuxarm64_limelight4.img.xz | photonvision-{version}-linuxarm64.jar |
| Rubik Pi 3 | photonvision-{version}-linuxarm64_rubikpi3.tar.xz | photonvision-{version}-linuxarm64.jar |
Unless otherwise noted in release notes or if updating from the prior years version, to update PhotonVision after the initial installation, use the offline update option in the settings page with the downloaded jar file from the latest release.
Raspberry Pi and Orange Pi Installation
Use the Raspberry Pi Imager 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 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. :::
Limelight Installation
In order to flash your Limelight you should follow the instructions on the Limelight documentation for the relevant version. Make sure to replace the Limelight OS image with the relevant PhotonVision image.
| Limelight Version | Limelight Documentation | PhotonVision Image | |
|---|---|---|---|
| 2 | Updating Limelight 2 OS | photonvision-{version}-linuxarm64_limelight2.img.xz | |
| 3 | Updating Limelight 3 OS | photonvision-{version}-linuxarm64_limelight3.img.xz | |
| 3G | Updating Limelight 3G OS | photonvision-{version}-linuxarm64_limelight3g.img.xz | |
| 4 | Updating Limelight 4 OS | photonvision-{version}-linuxarm64_limelight4.img.xz |
:::{note} Limelight models will need a custom hardware config file for LEDs or other hardware features to work. :::
Rubik Pi 3 Installation
:::{warning}
The Qualcomm Launcher caches files. If you flash multiple times, you may need to clear the cache by navigating to your temp directory, and deleting the qualcomm-launcher folder.
:::
To flash the Rubik Pi 3 coprocessor, it's necessary to use the Qualcomm Launcher. Upload a custom image by selecting the Custom option in the launcher. Choose the downloaded PhotonVision .tar.xz file and follow the prompts to complete the installation. It is recommended to skip the Configure Login process, as PhotonVision will handle the necessary settings.
Alternative Flashing Method (advanced users only)
Follow the specific steps listed below from the Rubik Pi 3 Docs.
Step 1 should be completed once per computer. Step 2 and Step 3 should be completed once per Rubik Pi 3.
After completing these steps, unzip your downloaded PhotonVision image to a folder. Navigate to that folder in your terminal or command prompt. After putting your Rubik Pi 3 into EDL mode, run the command below to flash PhotonVision. There is no need to complete any further steps from the Rubik Pi 3 documentation after running this command.
::::{tab-set} :::{tab-item} Ubuntu host
qdl --storage ufs prog_firehose_ddr.elf rawprogram*.xml patch*.xml
:::
:::{tab-item} Windows host
QDL.exe prog_firehose_ddr.elf rawprogram0.xml rawprogram1.xml rawprogram2.xml rawprogram3.xml rawprogram4.xml rawprogram5.xml rawprogram6.xml patch1.xml patch2.xml patch3.xml patch4.xml patch5.xml patch6.xml
:::
:::{tab-item} macOS host
qdl prog_firehose_ddr.elf rawprogram*.xml patch*.xml
::: ::::