[docs] Reorganize camera configuration pages and add camera matching documentation (#1917)

docs/source/docs/camera-specific-configuration/index.md

@@ -0,0 +1,8 @@
+# Camera-Specifc Configuration
+
+```{toctree}
+:maxdepth: 2
+
+arducam-cameras
+picamconfig
+```

docs/source/docs/camera-specific-configuration/picamconfig.md

@@ -23,6 +23,7 @@ Windows may report "There is a problem with this drive". This should be ignored.
 Locate `config.txt` in the folder, and open it with your favorite text editor.
 
 ```{image} images/bootConfigTxt.png
+
 ```
 
 Within the file, find this block of text:

docs/source/docs/hardware/index.md

@@ -4,6 +4,5 @@
 :maxdepth: 2
 
 selecting-hardware
-picamconfig
 customhardware
 ```

docs/source/docs/quick-start/camera-matching.md

@@ -0,0 +1,41 @@
+# Camera Matching
+
+## Activating and Deactivating Cameras
+
+When you first plug in a camera, it will be detected and added to the list of cameras with the "Unassigned" status, as shown below. You can press the "Activate" button to enable PhotonVision to use the camera.
+
+```{image} images/camera-matching/unassigned-camera.png
+:scale: 50%
+```
+
+If a camera has been activated in the past, it will be listed as "Deactivated" in the camera list. You can press the "Activate" button to enable PhotonVision to use the camera.
+
+```{image} images/camera-matching/deactivated-camera.png
+:scale: 50%
+```
+
+Once a camera is activated, it will be listed as "Active" in the camera list. You can press the "Deactivate" button to stop PhotonVision from using the camera.
+
+```{image} images/camera-matching/activated-camera.png
+:scale: 50%
+```
+
+## Deleting Cameras
+
+If you want to remove a camera from the list, you can press the delete button. This will clear all settings for that particular camera, including the calibration data and any other settings you have configured. It is recommended to make a backup of the camera's settings before deleting it, as this action cannot be undone.
+
+## Matching Cameras
+
+When you plug in a camera, PhotonVision will attempt to match it to a previously configured camera based on the physical USB port it is connected to. If you plug another camera into that port, the cameras will have a "Camera Mismatch" status, indicating that the camera is not recognized as the one that was previously configured.
+
+Additionally, pressing on the Details button will show you the details of the camera mismatch, allowing you to compare the current camera with the previously configured camera.
+
+```{image} images/camera-matching/camera-mismatch-details.png
+:scale: 50%
+```
+
+```{note}
+Camera matching is based on the USB ports on the device. If you unplug a camera and plug it into a different port, PhotonVision will attempt to use settings from the camera that was previously configured in that port, causing unexpected behavior.
+```
+
+To resolve the camera mismatch, you should ensure each camera is plugged into the same port that you configured it in.

docs/source/docs/quick-start/common-setups.md

@@ -34,7 +34,7 @@ Innomaker and Arducam are common manufacturers of hardware designed specifically
 - Driver Camera
   - OV9281
   - OV9782
-  - Pi Camera Module V1 {ref}`(More setup info)<docs/hardware/picamconfig:Pi Camera Configuration>`
+  - Pi Camera Module V1 {ref}`(More setup info)<docs/camera-specific-configuration/picamconfig:Pi Camera Configuration>`
 
 Feel free to get started with any color webcam you have sitting around.
 

docs/source/docs/quick-start/index.md

@@ -7,7 +7,7 @@ common-setups
 quick-install
 wiring
 networking
-arducam-cameras
+camera-matching
 camera-calibration
 quick-configure
 ```

docs/source/docs/troubleshooting/camera-troubleshooting.md

@@ -2,7 +2,7 @@
 
 ## Pi Cameras
 
-If you haven't yet, please refer to {ref}`the Pi CSI Camera Configuration page <docs/hardware/picamconfig:Pi Camera Configuration>` for information on updating {code}`config.txt` for your use case. If you've tried that, and things still aren't working, restart PhotonVision using the restart button in the settings tab, and press tilde (\`) in the web UI once connection is restored. This should show the most recent boot log.
+If you haven't yet, please refer to {ref}`the Pi CSI Camera Configuration page <docs/camera-specific-configuration/picamconfig:Pi Camera Configuration>` for information on updating {code}`config.txt` for your use case. If you've tried that, and things still aren't working, restart PhotonVision using the restart button in the settings tab, and press tilde (\`) in the web UI once connection is restored. This should show the most recent boot log.
 
 |                                 | Expected output                                       | Bad                                |
 | ------------------------------- | ----------------------------------------------------- | ---------------------------------- |
@@ -12,7 +12,7 @@ If you haven't yet, please refer to {ref}`the Pi CSI Camera Configuration page <
 
 If the driver isn't loaded, you may be using a non-official Pi image, or an image not new enough. Try updating to the most recent image available (one released for 2023) -- if that doesn't resolve the problem, {ref}`contact us<index:Contact Us>` with your settings ZIP file and Pi version/camera version/config.txt file used.
 
-If the camera is not detected, the most likely cause is either a config.txt file incorrectly set-up, or a ribbon cable attached backwards. Review the {ref}`picam configuration page <docs/hardware/picamconfig:pi camera configuration>`, and verify the ribbon cable is properly oriented at both ends, and that it is _fully_ inserted into the FFC connector. Then, {ref}`contact us<index:Contact Us>` with your settings ZIP file and Pi version/camera version/config.txt file used.
+If the camera is not detected, the most likely cause is either a config.txt file incorrectly set-up, or a ribbon cable attached backwards. Review the {ref}`picam configuration page <docs/camera-specific-configuration/picamconfig:pi camera configuration>`, and verify the ribbon cable is properly oriented at both ends, and that it is _fully_ inserted into the FFC connector. Then, {ref}`contact us<index:Contact Us>` with your settings ZIP file and Pi version/camera version/config.txt file used.
 
 ## USB cameras
 
@@ -27,7 +27,7 @@ USB cameras supported by CSCore require no libcamera driver initialization to wo
 
 On Linux devices (including Raspberry Pi), PhotonVision uses WPILib's CSCore to interact with video devices, which internally uses Video4Linux (v4l2). CSCore, and therefore Photon, requires that cameras attached have good v4l drivers for proper functionality. These should be built into the Linux kernel, and do not need to be installed manually. Valid picamera setup (from /boot/config.txt) can also be determined using these steps. The list-devices command will show all valid video devices detected, and list-formats the list of "video modes" each camera can be in.
 
-- For picams: edit the config.txt file as described in the {ref}`picam configuration page <docs/hardware/picamconfig:pi camera configuration>`
+- For picams: edit the config.txt file as described in the {ref}`picam configuration page <docs/camera-specific-configuration/picamconfig:pi camera configuration>`
 - SSH into your Pi: {code}`ssh pi@photonvision.local` and enter the username "pi" & password "raspberry"
 - run {code}`v4l2-ctl --list-devices` and {code}`v4l2-ctl --list-formats`