Move docs in-source (#1357)

docs/source/docs/hardware/customhardware.rst

@@ -0,0 +1,112 @@
+Deploying on Custom Hardware
+============================
+
+Configuration
+-------------
+
+By default, PhotonVision attempts to make minimal assumptions of the hardware it runs on. However, it may be configured to enable custom LED control, branding, and other functionality.
+
+``hardwareConfig.json`` is the location for this configuration. It is included when settings are exported, and can be uploaded as part of a .zip, or on its own.
+
+LED Support
+-----------
+
+For Raspberry-Pi based hardware, PhotonVision can use `PiGPIO <https://abyz.me.uk/rpi/pigpio/>`_ to control IO pins. The mapping of which pins control which LED's is part of the hardware config. The pins are active-high: set high when LED's are commanded on, and set low when commanded off.
+
+.. tab-set-code::
+   .. code-block:: json
+
+      {
+        "ledPins" : [ 13 ],
+        "ledSetCommand" : "",
+        "ledsCanDim" : true,
+        "ledPWMRange" : [ 0, 100 ],
+        "ledPWMSetRange" : "",
+        "ledPWMFrequency" : 0,
+        "ledDimCommand" : "",
+        "ledBlinkCommand" : "",
+        "statusRGBPins" : [ ],
+      }
+
+.. note:: No hardware boards with status RGB LED pins or non-dimming LED's have been tested yet. Please reach out to the development team if these features are desired, they can assist with configuration and testing.
+
+Hardware Interaction Commands
+-----------------------------
+
+For Non-Raspberry-Pi hardware, users must provide valid hardware-specific commands for some parts of the UI interaction (including performance metrics, and executing system restarts).
+
+Leaving a command blank will disable the associated functionality.
+
+.. tab-set-code::
+   .. code-block::  json
+
+      {
+        "cpuTempCommand" : "",
+        "cpuMemoryCommand" : "",
+        "cpuUtilCommand" : "",
+        "gpuMemoryCommand" : "",
+        "gpuTempCommand" : "",
+        "ramUtilCommand" : "",
+        "restartHardwareCommand" : "",
+      }
+
+.. note:: These settings have no effect if PhotonVision detects it is running on a Raspberry Pi. See `the MetricsBase class <https://github.com/PhotonVision/photonvision/blob/dbd631da61b7c86b70fa6574c2565ad57d80a91a/photon-core/src/main/java/org/photonvision/common/hardware/metrics/MetricsBase.java>`_ for the commands utilized.
+
+Known Camera FOV
+----------------
+
+If your hardware contains a camera with a known field of vision, it can be entered into the hardware configuration. This will prevent users from editing it in the GUI.
+
+.. tab-set-code::
+   .. code-block:: json
+
+      {
+        "vendorFOV" : 98.9
+      }
+
+Cosmetic & Branding
+-------------------
+
+To help differentiate your hardware from other solutions, some customization is allowed.
+
+.. tab-set-code::
+   .. code-block:: json
+
+      {
+        "deviceName" : "Super Cool Custom Hardware",
+        "deviceLogoPath" : "",
+        "supportURL" : "https://cat-bounce.com/",
+      }
+
+.. note:: Not all configuration is currently presented in the User Interface. Additional file uploads may be needed to support custom images.
+
+Example
+-------
+
+Here is a complete example ``hardwareConfig.json``:
+
+.. tab-set-code::
+   .. code-block:: json
+
+      {
+        "deviceName" : "Blinky McBlinkface",
+        "deviceLogoPath" : "",
+        "supportURL" : "https://www.youtube.com/watch?v=b-CvLWbfZhU",
+        "ledPins" : [2, 13],
+        "ledSetCommand" : "",
+        "ledsCanDim" : true,
+        "ledPWMRange" : [ 0, 100 ],
+        "ledPWMSetRange" : "",
+        "ledPWMFrequency" : 0,
+        "ledDimCommand" : "",
+        "ledBlinkCommand" : "",
+        "statusRGBPins" : [ ],
+        "cpuTempCommand" : "",
+        "cpuMemoryCommand" : "",
+        "cpuUtilCommand" : "",
+        "gpuMemoryCommand" : "",
+        "gpuTempCommand" : "",
+        "ramUtilCommand" : "",
+        "restartHardwareCommand" : "",
+        "vendorFOV" : 72.5
+      }

docs/source/docs/hardware/index.rst

@@ -0,0 +1,9 @@
+Hardware Selection
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   selecting-hardware
+   picamconfig
+   customhardware

docs/source/docs/hardware/picamconfig.rst

@@ -0,0 +1,55 @@
+Pi Camera Configuration
+=======================
+
+Background
+----------
+
+The Raspberry Pi CSI Camera port is routed through and processed by the GPU. Since the GPU boots before the CPU, it must be configured properly for the attached camera. Additionally, this configuration cannot be changed without rebooting.
+
+The GPU is not always capable of detecting other cameras automatically. The file ``/boot/config.txt`` is parsed by the GPU at boot time to determine what camera, if any, is expected to be attached. This file must be updated for some cameras.
+
+.. warning:: Incorrect camera configuration will cause the camera to not be detected. It looks exactly the same as if the camera was unplugged.
+
+Updating ``config.txt``
+-----------------------
+
+After flashing the pi image onto an SD card, open the ``boot`` segment in a file browser.
+
+.. note:: 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:
+
+.. code-block::
+
+  ##############################################################
+  ### PHOTONVISION CAM CONFIG
+  ### Comment/Uncomment to change which camera is supported
+  ### Picam V1, V2 or HQ: uncomment (remove leading # ) from camera_auto_detect=1,
+  ### and comment out all following lines
+  ### IMX290/327/OV9281/Any other cameras that require additional overlays:
+  ### Comment out (add a # ) to camera_auto_detect=1, and uncomment the line for
+  ### the sensor you're trying to user
+
+  cameraAutoDetect=1
+
+  # dtoverlay=imx290,clock-frequency=74250000
+  # dtoverlay=imx290,clock-frequency=37125000
+  # dtoverlay=imx378
+  # dtoverlay=ov9281
+
+  ##############################################################
+
+Remove the leading ``#`` character to uncomment the line associated with your camera. Add a ``#`` in front of other cameras.
+
+.. warning:: Leave lines outside the PhotonVision Camera Config block untouched. They are necessary for proper raspberry pi functionality.
+
+Save the file, close the editor, and eject the drive. The boot configuration should now be ready for your selected camera.
+
+Additional Information
+----------------------
+
+See `the libcamera documentation <https://github.com/raspberrypi/documentation/blob/679fab721855a3e8f17aa51819e5c2a7c447e98d/documentation/asciidoc/computers/camera/rpicam_configuration.adoc>`_ for more details on configuring cameras.

docs/source/docs/hardware/selecting-hardware.rst

@@ -0,0 +1,101 @@
+Selecting Hardware
+==================
+
+In order to use PhotonVision, you need a coprocessor and a camera. This page will help you select the right hardware for your team depending on your budget, needs, and experience.
+
+Choosing a Coprocessor
+----------------------
+
+Minimum System Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Ubuntu 22.04 LTS or Windows 10/11
+    * We don't recommend using Windows for anything except testing out the system on a local machine.
+* CPU: ARM Cortex-A53 (the CPU on Raspberry Pi 3) or better
+* At least 8GB of storage
+* 2GB of RAM
+    * PhotonVision isn't very RAM intensive, but you'll need at least 2GB to run the OS and PhotonVision.
+* The following IO:
+    * At least 1 USB or MIPI-CSI port for the camera
+        * Note that we only support using the Raspberry Pi's MIPI-CSI port, other MIPI-CSI ports from other coprocessors may not work.
+    * Ethernet port for networking
+
+Coprocessor Recommendations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When selecting a coprocessor, it is important to consider various factors, particularly when it comes to AprilTag detection. Opting for a coprocessor with a more powerful CPU can generally result in higher FPS AprilTag detection, leading to more accurate pose estimation. However, it is important to note that there is a point of diminishing returns, where the benefits of a more powerful CPU may not outweigh the additional cost. Below is a list of supported hardware, along with some notes on each.
+
+* Orange Pi 5 ($99)
+    * This is the recommended coprocessor for most teams. It has a powerful CPU that can handle AprilTag detection at high FPS, and is relatively cheap compared to processors of a similar power.
+* Raspberry Pi 4/5 ($55-$80)
+    * This is the recommended coprocessor for teams on a budget. It has a less powerful CPU than the Orange Pi 5, but is still capable of running PhotonVision at a reasonable FPS.
+* Mini PCs (such as Beelink N5095)
+    * This coprocessor will likely have similar performance to the Orange Pi 5 but has a higher performance ceiling (when using more powerful CPUs). Do note that this would require extra effort to wire to the robot / get set up. More information can be found in the set up guide `here. <https://docs.google.com/document/d/1lOSzG8iNE43cK-PgJDDzbwtf6ASyf4vbW8lQuFswxzw/edit?usp=drivesdk>`_
+* Other coprocessors can be used but may require some extra work / command line usage in order to get it working properly.
+
+Choosing a Camera
+-----------------
+
+PhotonVision works with Pi Cameras and most USB Cameras, the recommendations below are known to be working and have been tested. Other cameras such as webcams, virtual cameras, etc. are not officially supported and may not work. It is important to note that fisheye cameras should only be used as a driver camera and not for detecting targets.
+
+PhotonVision relies on `CSCore <https://github.com/wpilibsuite/allwpilib/tree/main/cscore>`_ to detect and process cameras, so camera support is determined based off compatibility with CScore along with native support for the camera within your OS (ex. `V4L compatibility <https://en.wikipedia.org/wiki/Video4Linux>`_ if using a Linux machine like a Raspberry Pi).
+
+.. note::
+    Logitech Cameras and integrated laptop cameras will not work with PhotonVision due to oddities with their drivers. We recommend using a different camera.
+
+.. note::
+    We do not currently support the usage of two of the same camera on the same coprocessor. You can only use two or more cameras if they are of different models or they are from Arducam, which has a `tool that allows for cameras to be renamed <https://docs.arducam.com/UVC-Camera/Serial-Number-Tool-Guide/>`_.
+
+Recommended Cameras
+^^^^^^^^^^^^^^^^^^^
+For colored shape detection, any non-fisheye camera supported by PhotonVision will work. We recommend the Pi Camera V1 or a high fps USB camera.
+
+For driver camera, we recommend a USB camera with a fisheye lens, so your driver can see more of the field.
+
+For AprilTag detection, we recommend you use a global shutter camera that has ~100 degree diagonal FOV. This will allow you to see more AprilTags in frame, and will allow for more accurate pose estimation. You also want a camera that supports high FPS, as this will allow you to update your pose estimator at a higher frequency.
+
+* Recommendations For AprilTag Detection
+    * Arducam USB OV9281
+        * This is the recommended camera for AprilTag detection as it is a high FPS, global shutter camera USB camera that has a ~70 degree FOV.
+    * Innomaker OV9281
+    * Spinel AR0144
+    * Pi Camera Module V1
+        * The V1 is strongly preferred over the V2 due to the V2 having undesirable FOV choices
+
+AprilTags and Motion Blur
+^^^^^^^^^^^^^^^^^^^^^^^^^
+When detecting AprilTags, you want to reduce the "motion blur" as much as possible. Motion blur is the visual streaking/smearing on the camera stream as a result of movement of the camera or object of focus. You want to mitigate this as much as possible because your robot is constantly moving and you want to be able to read as many tags as you possibly can. The possible solutions to this include:
+
+1. Cranking your exposure as low as it goes and increasing your gain/brightness. This will decrease the effects of motion blur and increase FPS.
+2. Using a global shutter (as opposed to rolling shutter) camera. This should eliminate most, if not all motion blur.
+3. Only rely on tags when not moving.
+
+.. image:: images/motionblur.gif
+    :align: center
+
+Using Multiple Cameras
+^^^^^^^^^^^^^^^^^^^^^^
+
+Using multiple cameras on your robot will help you detect more AprilTags at once and improve your pose estimation as a result. In order to use multiple cameras, you will need to create multiple PhotonPoseEstimators and add all of their measurements to a single drivetrain pose estimator. Please note that the accuracy of your robot to camera transform is especially important when using multiple cameras as any error in the transform will cause your pose estimations to "fight" each other. For more information, see :ref:`the programming reference. <docs/programming/index:programming reference>`.
+
+
+Performance Matrix
+------------------
+
+.. raw:: html
+
+    <embed>
+
+        <iframe src="https://docs.google.com/spreadsheets/d/e/2PACX-1vTojOew2d2NQY4PRA98vjkS1ECZ2YNvods-aOdk2x-Q4aF_7r4mcwlyTe8GjUKmUxEiVgGNnJNhEdyd/pubhtml?gid=1779881081&amp;single=true&amp;widget=true&amp;headers=false" width="760" height="500" frameborder="0" marginheight="0" marginwidth="0">Loading…</iframe>
+
+    </embed>
+
+Please submit performance data to be added to the matrix here:
+
+.. raw:: html
+
+    <embed>
+
+        <iframe src="https://docs.google.com/forms/d/e/1FAIpQLSf5iK3pX0Tn8bxpRYgcTAy4scUu14rUvJqkTyfzoKc-GiV7Vg/viewform?embedded=true" width="760" height="500" frameborder="0" marginheight="0" marginwidth="0">Loading…</iframe>
+
+    </embed>