Add more networking troubleshooting (#259)

* Banner, sidebar, networking

* lint

* Add troubleshooting checklist

* Add static admonition

* Update common-errors.rst

* Update calibImgs.png

* Move checklist to networking troubleshooting

* Address review comments

* Update calibration.rst

Co-authored-by: mdurrani808 <[email protected]>

Author: mcm001

source/docs/getting-started/installation/networking.rst

@@ -15,7 +15,7 @@ Digital Networking
 ------------------
 PhotonVision *STRONGLY* recommends the usage of Static IPs as it increases reliability on the field and when using PhotonVision in general. To properly set up your static IP, follow the steps below:
 
-.. warning:: Only use a static IP when connected to the robot radio, unless you are well versed in networking or have the relevant "know how".
+.. warning:: Only use a static IP when connected to the **robot radio**, and never when testing at home, unless you are well versed in networking or have the relevant "know how".
 
 1. Ensure your robot is on and you are connected to the robot network.
 2. Navigate to ``photonvision.local:5800`` (this may be different if you are using a Gloworm / Limelight) in your browser.

source/docs/getting-started/pipeline-tuning/calibration.rst

@@ -9,6 +9,30 @@ To calibrate a camera, images of a chessboard (or grid of dots) are taken. by co
 
 .. note::The calibration data collected during calibration is specific to each physical camera, as well as each individual resolution.
 
+Calibration Tips
+----------------
+Accurate camera calibration is required in order to get accurate pose measurements when using AprilTags and 3D mode. The tips below should help ensure success:
+
+1. Practice calibration using your laptop webcam and https://www.calibdb.net/. The target can be found on the website and should be printed out if possible. Once you print it out, try to line up your target with the overlay on the screen as best as possible. The point of this practice is to notice how you are prompted to place targets in certain positions on the screen that make sure you account for all regions of the sensor. The chessboard should (in general) not be facing parallel to the camera (straight on), nor should it be aligned with any of the camera axes (ie, rotated only about an axis going left/right, up/down, or out-of-the-camera).
+
+2. Ensure your the images you take have the target in different positions and angles, with as big of a difference between angles as possible. It is important to make sure the target overlay still lines up with the board while doing this. Tilt no more than 45 degrees.
+
+3. Use as big of a calibration target as your printer can print.
+
+4. Ensure that your printed pattern has enough white border around it.
+
+5. Ensure your camera stays in one position during the duration of the calibration.
+
+6. Make sure you get all 12 images from varying distances and angles.
+
+7. Take at least one image that covers the total image area, and generally ensure that you get even coverage of the lens with your image set.
+
+8. Have good lighting, having a diffusely lit target would be best (light specifically shining on the target without shadows).
+
+9. Ensure the calibration target is completely flat and does not bend or fold in any way. It should be mounted/taped down to something flat and then used for calibration, do not just hold it up.
+
+Following the ideas above should help in getting an accurate calibration.
+
 Calibration Steps
 -----------------
 
@@ -40,34 +64,10 @@ Now, we'll capture images of our chessboard from various angles. The most import
             Your browser does not support the video tag.
         </video>
 
-Calibration Tips
-----------------
-Accurate camera calibration is required in order to get accurate pose measurements when using AprilTags and 3D mode. The tips below should help ensure success:
-
-1. Practice calibration using your laptop webcam and https://www.calibdb.net/. The target can be found on the website and should be printed out if possible. Once you print it out, try to line up your target with the overlay on the screen as best as possible. The point of this practice is to notice how you are prompted to place targets in certain positions on the screen that make sure you account for all regions of the sensor. Also notice how the target is tilted when taking calibration pictures. When taking calibration pictures for PhotonVision, keep those same principles in mind.
-
-2. Ensure your the images you take have the target in different positions and angles, with as big of a difference between angles as possible. It is important to make sure the target overlay still lines up with the board while doing this. Tilt no more than 45 degrees.
-
-3. Use as big of a calibration target as your printer can print.
-
-4. Ensure that your printed pattern has enough white border around it.
-
-5. Ensure your camera stays in one position during the duration of the calibration.
-
-6. Make sure you get all 12 images from varying distances and angles.
-
-7. Take at least one image that covers the total image area, and generally ensure that you get even coverage of the lens with your image set.
-
-8. Have good lighting, having a diffusely lit target would be best (light specifically shining on the target without shadows).
-
-9. Ensure the calibration target is completely flat and does not bend or fold in any way. It should be mounted/taped down to something flat and then used for calibration, do not just hold it up.
-
-Following the ideas above should help in getting an accurate calibration.
-
-
 Accessing Calibration Images
 ----------------------------
-For advanced users, these calibrations can be later accessed by :ref:`exporting your config directory <docs/hardware/config:Directory Structure>` and viewing the camera's config.json file. Furthermore, the most recent snapshots will be saved to the calibImgs directory.
+
+For advanced users, these calibrations can be later accessed by :ref:`exporting your config directory <docs/hardware/config:Directory Structure>` and viewing the camera's config.json file. Furthermore, the most recent snapshots will be saved to the calibImgs directory. The example images below are from `the calibdb website <https://calibdb.net>` -- focus on how the target is oriented, as the same general tips for positioning apply for chessboard targets as for ChArUco.
 
 .. image:: images/calibImgs.png
    :width: 600

source/docs/getting-started/pipeline-tuning/images/calibImgs.png

@@ -21,9 +21,11 @@ For now, if you are using multiple cameras, it is recommended that teams set the
 Commonly Seen Issues
 --------------------
 
+
 Networking Issues
 ^^^^^^^^^^^^^^^^^
-Ensure that you have followed :ref:`all the recommendations in the networking section <docs/getting-started/installation/networking:Physical Networking>`.
+
+Please refer to our comprehensive :ref:`networking troubleshooting tips <docs/troubleshooting/networking-troubleshooting:Networking Troubleshooting>` for debugging suggestions and possible causes.
 
 Camera won't show up
 ^^^^^^^^^^^^^^^^^^^^
@@ -42,6 +44,18 @@ Not getting data from PhotonLib
 
 2. Ensure that you have your team number set properly.
 
+3. Use Glass to verify that PhotonVision has connected to the NetworkTables server served by your robot. With Glass connected in client mode to your RoboRIO, we expect to see "photonvision" listed under the Clients tab of the NetworkTables Info pane.
+
+.. image:: images/glass-connections.png
+   :width: 600
+   :alt: Using Glass to check NT connections
+
+4. When creating a `PhotonCamera` in code, does the `cameraName` provided match the name in the upper-right card of the web interface? Glass can be used to verify the RoboRIO is receiving NetworkTables data by inspecting the `photonvision` subtable for your camera nickname.
+
+.. image:: images/camera-subtable.png
+   :width: 600
+   :alt: Using Glass to check camera publishing
+
 Unable to download PhotonLib
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Ensure all of your network firewalls are disabled and you aren't on a school-network.

source/docs/troubleshooting/common-errors.rst

@@ -1,7 +1,27 @@
 Networking Troubleshooting
 ==========================
 
-Before reading further, ensure that you follow all the reccomendations in our networking section. You must be following these guidelines in order for PhotonVision to work properly, other networking setups are not officially supported.
+Before reading further, ensure that you follow all the recommendations :ref:`in our networking section <docs/getting-started/installation/networking:Physical Networking>`. You should follow these guidelines in order for PhotonVision to work properly; other networking setups are not officially supported.
+
+
+Checklist
+^^^^^^^^^
+
+A few issues make up the majority of support requests. Run through this checklist quickly to catch some common mistakes.
+
+- Is your camera connected to the robot's radio through a :ref:`network switch <docs/getting-started/installation/networking:Physical Networking>`?
+   - Ethernet straight from a laptop to a coprocessor will not work (most likely), due to the unreliability of link-local connections.
+   - Even if there's a switch between your laptop and coprocessor, you'll still want a radio or router in the loop somehow.
+   - The FRC radio is the *only* router we will officially support due to the innumerable variations between routers.
+- (Raspberry Pi & Limelight only) have you flashed the correct image, and is it up to date?
+   - Limelights and Gloworms should be flashed using the Limelight image (eg, `photonvision-v2023.1.2-linuxarm64-image_limelight.xz`).
+   - Raspberry Pi devices (including Pi 3, Pi 4, CM3 and CM4) should be flashed using the Limelight image (eg, `photonvision-v2023.1.2-linuxarm64-image_RaspberryPi.xz`).
+   - This is due to Limelight-specific hardware configuration that makes the image incompatible with stock Raspberry Pi devices.
+- Is your robot code using a **2023** version of WPILib, and is your coprocessor using the most up to date **2023** release?
+   - 2022 and 2023 versions of either cannot be mix-and-matched!
+   - Your PhotonVision version can be checked on the :ref:`settings tab<docs/hardware/Settings:settings>`.
+- Is your team number correctly set on the :ref:`settings tab<docs/hardware/Settings:settings>`?
+
 
 photonvision.local Not Found
 ----------------------------
@@ -10,7 +30,7 @@ Use `Angry IP Scanner <https://angryip.org/>`_ and look for an IP that has port
 
 Alternatively, you can plug your coprocessor into a display, plug in a keyboard, and run ``hostname -I`` in the terminal. This should give you the IP Address of your coprocessor, then go to your web browser and do <IP ADDRESS>:5800.
 
-If nothing shows up, ensure your coprocessor has power, and you are following all of our networking reccomendations, feel free to :ref:`contact us <index:contact us>` and we will help you.
+If nothing shows up, ensure your coprocessor has power, and you are following all of our networking recommendations, feel free to :ref:`contact us <index:contact us>` and we will help you.
 
 Can't Connect To Robot
 ----------------------
@@ -22,4 +42,10 @@ Please check that:
 4. You are using the 2023 version of WPILib and RoboRIO image.
 5. Your robot is on.
 
-If all of the above are met and you still have issues, feel free to :ref:`contact us <index:contact us>` and we will help you.
+If all of the above are met and you still have issues, feel free to :ref:`contact us <index:contact us>` and provide the following information:
+
+- The WPILib version used by your robot code
+- PhotonLib vendor dependency version
+- PhotonVision version (from the UI)
+- Your settings exported from your coprocessor (if you're able to access it)
+- How your RoboRIO/coprocessor are networked together