Merge branch 'master' into RPI-Update-7-4-24

.github/workflows/build.yml

@@ -416,15 +416,27 @@ jobs:
           - os: ubuntu-latest
             artifact-name: LinuxArm64
             image_suffix: orangepi5
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2024.0.10/photonvision_opi5.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-3/photonvision_opi5.img.xz
             cpu: cortex-a8
-            image_additional_mb: 4096
+            image_additional_mb: 1024
+          - os: ubuntu-latest
+            artifact-name: LinuxArm64
+            image_suffix: orangepi5b
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-3/photonvision_opi5b.img.xz
+            cpu: cortex-a8
+            image_additional_mb: 1024
           - os: ubuntu-latest
             artifact-name: LinuxArm64
             image_suffix: orangepi5plus
-            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2024.0.10/photonvision_opi5plus.img.xz
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-3/photonvision_opi5plus.img.xz
             cpu: cortex-a8
-            image_additional_mb: 4096
+            image_additional_mb: 1024
+          - os: ubuntu-latest
+            artifact-name: LinuxArm64
+            image_suffix: orangepi5pro
+            image_url: https://github.com/PhotonVision/photon-image-modifier/releases/download/v2025.0.0-beta-3/photonvision_opi5pro.img.xz
+            cpu: cortex-a8
+            image_additional_mb: 1024
 
     runs-on: ${{ matrix.os }}
     name: "Build image - ${{ matrix.image_url }}"
@@ -437,7 +449,7 @@ jobs:
       - uses: actions/download-artifact@v4
         with:
           name: jar-${{ matrix.artifact-name }}
-      - uses: pguyot/arm-runner-action@v2
+      - uses: pguyot/arm-runner-action@HEAD
         name: Generate image
         id: generate_image
         with:
@@ -462,7 +474,7 @@ jobs:
           name: image-${{ matrix.image_suffix }}
           path: photonvision*.xz
   release:
-    needs: [build-package, build-image]
+    needs: [build-package, build-image, combine]
     runs-on: ubuntu-22.04
     steps:
       # Download all fat JARs

docs/.gitignore

@@ -3,8 +3,6 @@ build/*
 .vscode/*
 .idea/*
 source/_build
-source/_build
-photon-docs/build
 source/docs/_build
 
 venv/*

docs/requirements.txt

@@ -40,3 +40,5 @@ sphinxext-remoteliteralinclude==0.4.0
 stevedore==5.1.0
 urllib3==2.1.0
 yarg==0.1.9
+sphinx-autobuild==2024.4.16
+myst_parser==3.0.1

docs/source/404.md

@@ -0,0 +1,7 @@
+---
+orphan: true
+---
+
+# Requested Page Not Found
+
+This page you were looking for was not found. If you think this is a mistake, [file an issue on our GitHub.](https://github.com/PhotonVision/photonvision-docs/issues)

docs/source/conf.py

@@ -35,6 +35,7 @@
     "sphinxext.opengraph",
     "sphinxcontrib.ghcontributors",
     "sphinx_design",
+    "myst_parser",
 ]
 
 # Configure OpenGraph support
@@ -71,6 +72,8 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+source_suffix = [".rst", ".md"]
+
 
 def setup(app):
     app.add_css_file("css/pv-icons.css")
@@ -124,3 +127,6 @@ def setup(app):
 # Excluded links for linkcheck
 # These should be periodically checked by hand to ensure that they are still functional
 linkcheck_ignore = ["https://www.raspberrypi.com/software/"]
+
+# MyST configuration (https://myst-parser.readthedocs.io/en/latest/configuration.html)
+myst_enable_extensions = ["colon_fence"]

docs/source/docs/additional-resources/best-practices.md

@@ -0,0 +1,29 @@
+# Best Practices For Competition
+
+## Before Competition
+
+- Ensure you have spares of the relevant electronics if you can afford it (switch, coprocessor, cameras, etc.).
+- Download the latest release .jar onto your computer and update your Pi if necessary (only update if the release is labeled "critical" or similar, we do not recommend updating right before an event in case there are unforeseen bugs).
+- Test out PhotonVision at your home setup.
+- Ensure that you have set up SmartDashboard / Shuffleboard to view your camera streams during matches.
+- Follow all the recommendations under the Networking section in installation (network switch and static IP).
+- Use high quality ethernet cables that have been rigorously tested.
+- Set up port forwarding using the guide in the Networking section in installation.
+
+## During the Competition
+
+- Make sure you take advantage of the field calibration time given at the start of the event:
+    - Bring your robot to the field at the allotted time.
+    - Turn on your robot and pull up the dashboard on your driver station.
+    - Point your robot at the target(s) and ensure you get a consistent tracking (you hold one target consistently, the ceiling lights aren't detected, etc.).
+    - If you have problems with your pipeline, go to the pipeline tuning section and retune the pipeline using the guide there. You want to make your exposure as low as possible with a tight hue value to ensure no extra targets are detected.
+    - Move the robot close, far, angled, and around the field to ensure no extra targets are found anywhere when looking for a target.
+    - Go to a practice match to ensure everything is working correctly.
+- After field calibration, use the "Export Settings" button in the "Settings" page to create a backup.
+    - Do this for each coprocessor on your robot that runs PhotonVision, and name your exports with meaningful names.
+    - This will contain camera information/calibration, pipeline information, network settings, etc.
+    - In the event of software/hardware failures (IE lost SD Card, broken device), you can then use the "Import Settings" button and select "All Settings" to restore your settings.
+    - This effectively works as a snapshot of your PhotonVision data that can be restored at any point.
+- Before every match, check the ethernet connection going into your coprocessor and that it is seated fully.
+- Ensure that exposure is as low as possible and that you don't have the dashboard up when you don't need it to reduce bandwidth.
+- Stream at as low of a resolution as possible while still detecting targets to stay within bandwidth limits.

docs/source/docs/additional-resources/config.md

@@ -0,0 +1,50 @@
+# Filesystem Directory
+
+PhotonVision stores and loads settings in the {code}`photonvision_config` directory, in the same folder as the PhotonVision JAR is stored. On the Pi image as well as the Gloworm, this is in the {code}`/opt/photonvision` directory. The contents of this directory can be exported as a zip archive from the settings page of the interface, under "export settings". This export will contain everything detailed below. These settings can later be uploaded using "import settings", to restore configurations from previous backups.
+
+## Directory Structure
+
+The directory structure is outlined below.
+
+```{image} images/configDir.png
+:alt: Config directory structure
+:width: 600
+```
+
+- calibImgs
+    - Images saved from the last run of the calibration routine
+- cameras
+    - Contains a subfolder for each camera. This folder contains the following files:
+        - pipelines folder, which contains a {code}`json` file for each user-created pipeline.
+        - config.json, which contains all camera-specific configuration. This includes FOV, pitch, current pipeline index, and calibration data
+        - drivermode.json, which contains settings for the driver mode pipeline
+- imgSaves
+    - Contains images saved with the input/output save commands.
+- logs
+    - Contains timestamped logs in the format {code}`photonvision-YYYY-MM-D_HH-MM-SS.log`. Note that on Pi or Gloworm these timestamps will likely be significantly behind the real time.
+- hardwareSettings.json
+    - Contains hardware settings. Currently this includes only the LED brightness.
+- networkSettings.json
+    - Contains network settings, including team number (or remote network tables address), static/dynamic settings, and hostname.
+
+## Importing and Exporting Settings
+
+The entire settings directory can be exported as a ZIP archive from the settings page.
+
+```{raw} html
+<video width="85%" controls>
+    <source src="../../_static/assets/import-export-settings.mp4" type="video/mp4">
+    Your browser does not support the video tag.
+</video>
+```
+
+A variety of files can be imported back into PhotonVision:
+
+- ZIP Archive ({code}`.zip`)
+    - Useful for restoring a full configuration from a different PhotonVision instance.
+- Single Config File
+    - Currently-supported Files
+        - {code}`hardwareConfig.json`
+        - {code}`hardwareSettings.json`
+        - {code}`networkSettings.json`
+    - Useful for simple hardware or network configuration tasks without overwriting all settings.

docs/source/docs/additional-resources/nt-api.md

@@ -0,0 +1,70 @@
+# NetworkTables API
+
+## About
+
+:::{warning}
+PhotonVision interfaces with PhotonLib, our vendor dependency, using NetworkTables. If you are running PhotonVision on a robot (ie. with a RoboRIO), you should **turn the NetworkTables server switch (in the settings tab) off** in order to get PhotonLib to work. Also ensure that you set your team number. The NetworkTables server should only be enabled if you know what you're doing!
+:::
+
+## API
+
+:::{warning}
+NetworkTables is not a supported setup/viable option when using PhotonVision as we only send one target at a time (this is problematic when using AprilTags, which will return data from multiple tags at once). We recommend using PhotonLib.
+:::
+
+The tables below contain the the name of the key for each entry that PhotonVision sends over the network and a short description of the key. The entries should be extracted from a subtable with your camera's nickname (visible in the PhotonVision UI) under the main `photonvision` table.
+
+### Getting Target Information
+
+| Key             | Type       | Description                                                              |
+| --------------- | ---------- | ------------------------------------------------------------------------ |
+| `rawBytes`      | `byte[]`   | A byte-packed string that contains target info from the same timestamp.  |
+| `latencyMillis` | `double`   | The latency of the pipeline in milliseconds.                             |
+| `hasTarget`     | `boolean`  | Whether the pipeline is detecting targets or not.                        |
+| `targetPitch`   | `double`   | The pitch of the target in degrees (positive up).                        |
+| `targetYaw`     | `double`   | The yaw of the target in degrees (positive right).                       |
+| `targetArea`    | `double`   | The area (percent of bounding box in screen) as a percent (0-100).       |
+| `targetSkew`    | `double`   | The skew of the target in degrees (counter-clockwise positive).          |
+| `targetPose`    | `double[]` | The pose of the target relative to the robot (x, y, z, qw, qx, qy, qz)   |
+| `targetPixelsX` | `double`   | The target crosshair location horizontally, in pixels (origin top-right) |
+| `targetPixelsY` | `double`   | The target crosshair location vertically, in pixels (origin top-right)   |
+
+### Changing Settings
+
+| Key             | Type      | Description                 |
+| --------------- | --------- | --------------------------- |
+| `pipelineIndex` | `int`     | Changes the pipeline index. |
+| `driverMode`    | `boolean` | Toggles driver mode.        |
+
+### Saving Images
+
+PhotonVision can save images to file on command. The image is saved when PhotonVision detects the command went from `false` to `true`.
+
+PhotonVision will automatically set these back to `false` after 500ms.
+
+Be careful saving images rapidly - it will slow vision processing performance and take up disk space very quickly.
+
+Images are returned as part of the .zip package from the "Export" operation in the Settings tab.
+
+| Key                | Type      | Description                                       |
+| ------------------ | --------- | ------------------------------------------------- |
+| `inputSaveImgCmd`  | `boolean` | Triggers saving the current input image to file.  |
+| `outputSaveImgCmd` | `boolean` | Triggers saving the current output image to file. |
+
+:::{warning}
+If you manage to make calls to these commands faster than 500ms (between calls), additional photos will not be captured.
+:::
+
+### Global Entries
+
+These entries are global, meaning that they should be called on the main `photonvision` table.
+
+| Key       | Type  | Description                                              |
+| --------- | ----- | -------------------------------------------------------- |
+| `ledMode` | `int` | Sets the LED Mode (-1: default, 0: off, 1: on, 2: blink) |
+
+:::{warning}
+Setting the LED mode to -1 (default) when `multiple` cameras are connected may result in unexpected behavior. {ref}`This is a known limitation of PhotonVision. <docs/troubleshooting/common-errors:LED Control>`
+
+Single camera operation should work without issue.
+:::