[docs] Create quick-start guide (#1528)

Add a quick-start guide to help answer more questions with fewer words.
---------

Co-authored-by: Matt M <matthew.morley.ca@gmail.com>

docs/source/docs/advanced-installation/index.md

@@ -0,0 +1,18 @@
+# Advanced Installation
+
+This page will help you install PhotonVision on non-supported coprocessor.
+
+## Step 1: Software Install
+
+This section will walk you through how to install PhotonVision on your coprocessor. Your coprocessor is the device that has the camera and you are using to detect targets (ex. if you are using a Limelight / Raspberry Pi, that is your coprocessor and you should follow those instructions).
+
+:::{warning}
+You only need to install PhotonVision on the coprocessor/device that is being used to detect targets, you do NOT need to install it on the device you use to view the webdashboard. All you need to view the webdashboard is for a device to be on the same network as your vision coprocessor and an internet browser.
+:::
+
+```{toctree}
+:maxdepth: 3
+
+sw_install/index
+prerelease-software
+```

docs/source/docs/advanced-installation/prerelease-software.md

@@ -0,0 +1,23 @@
+# Installing Pre-Release Versions
+
+Pre-release/development version of PhotonVision can be tested by installing/downloading artifacts from Github Actions (see below), which are built automatically on commits to open pull requests and to PhotonVision's `master` branch, or by {ref}`compiling PhotonVision locally <docs/contributing/building-photon:Build Instructions>`.
+
+:::{warning}
+If testing a pre-release version of PhotonVision with a robot, PhotonLib must be updated to match the version downloaded! If not, packet schema definitions may not match and unexpected things will occur. To update PhotonLib, refer to {ref}`installing specific version of PhotonLib<docs/programming/photonlib/adding-vendordep:Install Specific Version - Java/C++>`.
+:::
+
+GitHub Actions builds pre-release version of PhotonVision automatically on PRs and on each commit merged to master. To test a particular commit to master, navigate to the [PhotonVision commit list](https://github.com/PhotonVision/photonvision/commits/master/) and click on the check mark (below). Scroll to "Build / Build fat JAR - PLATFORM", click details, and then summary. From here, JAR and image files can be downloaded to be flashed or uploaded using "Offline Update".
+
+```{image} images/gh_actions_1.png
+:alt: Github Actions Badge
+```
+
+```{image} images/gh_actions_2.png
+:alt: Github Actions artifact list
+```
+
+Built JAR files (but not image files) can also be downloaded from PRs before they are merged. Navigate to the PR in GitHub, and select Checks at the top. Click on "Build" to display the same artifact list as above.
+
+```{image} images/gh_actions_3.png
+:alt: Github Actions artifacts from PR
+```

docs/source/docs/advanced-installation/sw_install/advanced-cmd.md

@@ -0,0 +1,56 @@
+# Advanced Command Line Usage
+
+PhotonVision exposes some command line options which may be useful for customizing execution on Debian-based installations.
+
+## Running a JAR File
+
+Assuming `java` has been installed, and the appropriate environment variables have been set upon installation (a package manager like `apt` should automatically set these), you can use `java -jar` to run a JAR file. If you downloaded the latest stable JAR of PhotonVision from the [GitHub releases page](https://github.com/PhotonVision/photonvision/releases), you can run the following to start the program:
+
+```bash
+java -jar /path/to/photonvision/photonvision.jar
+```
+
+## Updating a JAR File
+
+When you need to update your JAR file, run the following:
+
+```bash
+wget https://git.io/JqkQ9 -O update.sh
+sudo chmod +x update.sh
+sudo ./update.sh
+sudo reboot now
+```
+
+## Creating a `systemd` Service
+
+You can also create a systemd service that will automatically run on startup. To do so, first navigate to `/lib/systemd/system`. Create a file called `photonvision.service` (or name it whatever you want) using `touch photonvision.service`. Then open this file in the editor of your choice and paste the following text:
+
+```
+[Unit]
+Description=Service that runs PhotonVision
+
+[Service]
+WorkingDirectory=/path/to/photonvision
+# Optional: run photonvision at "nice" -10, which is higher priority than standard
+# Nice=-10
+ExecStart=/usr/bin/java -jar /path/to/photonvision/photonvision.jar
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then copy the `.service` file to `/etc/systemd/system/` using `cp photonvision.service /etc/systemd/system/photonvision.service`. Then modify the file to have `644` permissions using `chmod 644 /etc/systemd/system/photonvision.service`.
+
+:::{note}
+Many ARM processors have a big.LITTLE architecture where some of the CPU cores are more powerful than others. On this type of architecture, you may get more consistent performance by limiting which cores PhotonVision can use. To do this, add the parameter `AllowedCPUs` to the systemd service file in the `[Service]` section.
+
+For instance, for an Orange Pi 5, cores 4 through 7 are the fast ones, and you can target those cores with the line `AllowedCPUs=4-7`.
+:::
+
+## Installing the `systemd` Service
+
+To install the service, simply run `systemctl enable photonvision.service`.
+
+:::{note}
+It is recommended to reload configurations by running `systemctl daemon-reload`.
+:::

docs/source/docs/advanced-installation/sw_install/files/Limelight2+/hardwareConfig.json

@@ -0,0 +1,9 @@
+{
+  "deviceName" : "Limelight 2+",
+  "supportURL" : "https://limelightvision.io",
+  "ledPins" : [ 13, 18 ],
+  "ledsCanDim" : true,
+  "ledPWMRange" : [ 0, 100 ],
+  "ledPWMFrequency" : 30000,
+  "vendorFOV" : 75.76079874010732
+}

docs/source/docs/advanced-installation/sw_install/files/Limelight2/hardwareConfig.json

@@ -0,0 +1,7 @@
+{
+  "deviceName" : "Limelight 2",
+  "supportURL" : "https://limelightvision.io",
+  "ledPins" : [ 17, 18 ],
+  "ledsCanDim" : false,
+  "vendorFOV" : 75.76079874010732
+}

docs/source/docs/advanced-installation/sw_install/index.md

@@ -0,0 +1,21 @@
+# Software Installation
+
+## Desktop Environments
+
+```{toctree}
+:maxdepth: 1
+
+windows-pc
+linux-pc
+mac-os
+```
+
+## Other
+
+```{toctree}
+:maxdepth: 1
+
+other-coprocessors
+advanced-cmd
+romi
+```

docs/source/docs/advanced-installation/sw_install/linux-pc.md

@@ -0,0 +1,47 @@
+# Linux PC Installation
+
+PhotonVision may be run on a Debian-based Linux Desktop PC for basic testing and evaluation.
+
+:::{note}
+You do not need to install PhotonVision on a Windows PC in order to access the webdashboard (assuming you are using an external coprocessor like a Raspberry Pi).
+:::
+
+## Installing Java
+
+PhotonVision requires a JDK installed and on the system path. JDK 11 is needed (different versions will not work). If you don't have JDK 11 already, run the following to install it:
+
+```
+$ sudo apt-get install openjdk-11-jdk
+```
+
+:::{warning}
+Using a JDK other than JDK11 will cause issues when running PhotonVision and is not supported.
+:::
+
+## Downloading the Latest Stable Release of PhotonVision
+
+Go to the [GitHub releases page](https://github.com/PhotonVision/photonvision/releases) and download the relevant .jar file for your coprocessor.
+
+:::{note}
+If your coprocessor has a 64 bit ARM based CPU architecture (OrangePi, Raspberry Pi, etc.), download the LinuxArm64.jar file.
+
+If your coprocessor has an 64 bit x86 based CPU architecture (Mini PC, laptop, etc.), download the Linuxx64.jar file.
+:::
+
+:::{warning}
+Be careful to pick the latest stable release. "Draft" or "Pre-Release" versions are not stable and often have bugs.
+:::
+
+## Running PhotonVision
+
+To run PhotonVision, open a terminal window of your choice and run the following command:
+
+```
+$ java -jar /path/to/photonvision/photonvision-xxx.jar
+```
+
+If your computer has a compatible webcam connected, PhotonVision should startup without any error messages. If there are error messages, your webcam isn't supported or another issue has occurred. If it is the latter, please open an issue on the [PhotonVision issues page](https://github.com/PhotonVision/photonvision/issues).
+
+## Accessing the PhotonVision Interface
+
+Once the Java backend is up and running, you can access the main vision interface by navigating to `localhost:5800` inside your browser.

docs/source/docs/advanced-installation/sw_install/mac-os.md

@@ -0,0 +1,53 @@
+# Mac OS Installation
+
+:::{warning}
+Due to current [cscore](https://github.com/wpilibsuite/allwpilib/tree/main/cscore) restrictions, the PhotonVision server backend may have issues running macOS.
+:::
+
+:::{note}
+You do not need to install PhotonVision on a Windows PC in order to access the webdashboard (assuming you are using an external coprocessor like a Raspberry Pi).
+:::
+
+VERY Limited macOS support is available.
+
+## Installing Java
+
+PhotonVision requires a JDK installed and on the system path. JDK 11 is needed (different versions will not work). You may already have this if you have installed WPILib. If not, [download and install it from here](https://adoptium.net/temurin/releases?version=11).
+
+:::{warning}
+Using a JDK other than JDK11 will cause issues when running PhotonVision and is not supported.
+:::
+
+## Downloading the Latest Stable Release of PhotonVision
+
+Go to the [GitHub releases page](https://github.com/PhotonVision/photonvision/releases) and download the relevant .jar file for your coprocessor.
+
+:::{note}
+If you have an M1/M2 Mac, download the macarm64.jar file.
+
+If you have an Intel based Mac, download the macx64.jar file.
+:::
+
+:::{warning}
+Be careful to pick the latest stable release. "Draft" or "Pre-Release" versions are not stable and often have bugs.
+:::
+
+## Running PhotonVision
+
+To run PhotonVision, open a terminal window of your choice and run the following command:
+
+```
+$ java -jar /path/to/photonvision/photonvision-xxx.jar
+```
+
+:::{warning}
+Due to current [cscore](https://github.com/wpilibsuite/allwpilib/tree/main/cscore) restrictions, the PhotonVision using test mode is all that is known to work currently.
+:::
+
+## Accessing the PhotonVision Interface
+
+Once the Java backend is up and running, you can access the main vision interface by navigating to `localhost:5800` inside your browser.
+
+:::{warning}
+Due to current [cscore](https://github.com/wpilibsuite/allwpilib/tree/main/cscore) restrictions, it is unlikely any streams will open from real webcams.
+:::

docs/source/docs/advanced-installation/sw_install/other-coprocessors.md

@@ -0,0 +1,39 @@
+# Other Debian-Based Co-Processor Installation
+
+:::{warning}
+Working with unsupported coprocessors requires some level of "know how" of your system. The install script has only been tested on Debian/Raspberry Pi OS Buster and Ubuntu Bionic. If any issues arise with your specific OS, please open an issue on our [issues page](https://github.com/PhotonVision/photonvision/issues).
+:::
+
+:::{note}
+We'd love to have your input! If you get PhotonVision working on another coprocessor, consider documenting your steps and submitting a [docs issue](https://github.com/PhotonVision/photonvision-docs/issues)., [pull request](https://github.com/PhotonVision/photonvision-docs/pulls) , or [ping us on Discord](https://discord.com/invite/wYxTwym). For example, Limelight and Romi install instructions came about because someone spent the time to figure it out, and did a writeup.
+:::
+
+## Installing PhotonVision
+
+We provide an [install script](https://git.io/JJrEP) for other Debian-based systems (with `apt`) that will automatically install PhotonVision and make sure that it runs on startup.
+
+```bash
+$ wget https://git.io/JJrEP -O install.sh
+$ sudo chmod +x install.sh
+$ sudo ./install.sh
+$ sudo reboot now
+```
+
+:::{note}
+Your co-processor will require an Internet connection for this process to work correctly.
+:::
+
+For installation on any other co-processors, we recommend reading the {ref}`advanced command line documentation <docs/advanced-installation/sw_install/advanced-cmd:Advanced Command Line Usage>`.
+
+## Updating PhotonVision
+
+PhotonVision can be updated by downloading the latest jar file, copying it onto the processor, and restarting the service.
+
+For example, from another computer, run the following commands. Substitute the correct username for "\[user\]" ( Provided images use username "pi")
+
+```bash
+$ scp [jar name].jar [user]@photonvision.local:~/
+$ ssh [user]@photonvision.local
+$ sudo mv [jar name].jar /opt/photonvision/photonvision.jar
+$ sudo systemctl restart photonvision.service
+```

docs/source/docs/advanced-installation/sw_install/romi.md

@@ -0,0 +1,23 @@
+# Romi Installation
+
+The [Romi](https://docs.wpilib.org/en/latest/docs/romi-robot/index.html) is a small robot that can be controlled with the WPILib software. The main controller is a Raspberry Pi that must be imaged with [WPILibPi](https://docs.wpilib.org/en/latest/docs/romi-robot/imaging-romi.html) .
+
+## Installation
+
+The WPILibPi image includes FRCVision, which reserves USB cameras; to use PhotonVision, we need to edit the `/home/pi/runCamera` script to disable it. First we will need to make the file system writeable; the easiest way to do this is to go to `10.0.0.2` and choose "Writable" at the top.
+
+SSH into the Raspberry Pi (using Windows command line, or a tool like [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/) ) at the Romi's default address `10.0.0.2`. The default user is `pi`, and the password is `raspberry`.
+
+Follow the process for installing PhotonVision on {ref}`"Other Debian-Based Co-Processor Installation" <docs/advanced-installation/sw_install/other-coprocessors:Other Debian-Based Co-Processor Installation>`. As it mentions this will require an internet connection so plugging into the ethernet jack on the Raspberry Pi will be the easiest solution. The pi must remain writable!
+
+Next, from the SSH terminal, run `sudo nano /home/pi/runCamera` then arrow down to the start of the exec line and press "Enter" to add a new line. Then add `#` before the exec command to comment it out. Then, arrow up to the new line and type `sleep 10000`. Hit "Ctrl + O" and then "Enter" to save the file. Finally press "Ctrl + X" to exit nano. Now, reboot the Romi by typing `sudo reboot`.
+
+```{image} images/nano.png
+
+```
+
+After it reboots, you should be able to [locate the PhotonVision UI](https://photonvision.github.io/gloworm-docs/docs/quickstart/#finding-gloworm) at: `http://10.0.0.2:5800/`.
+
+:::{warning}
+In order for settings, logs, etc. to be saved / take effect, ensure that PhotonVision is in writable mode.
+:::

docs/source/docs/advanced-installation/sw_install/windows-pc.md

@@ -0,0 +1,41 @@
+# Windows PC Installation
+
+PhotonVision may be run on a Windows Desktop PC for basic testing and evaluation.
+
+:::{note}
+You do not need to install PhotonVision on a Windows PC in order to access the webdashboard (assuming you are using an external coprocessor like a Raspberry Pi).
+:::
+
+## Install Bonjour
+
+Bonjour provides more stable networking when using Windows PCs. Install [Bonjour here](https://support.apple.com/downloads/DL999/en_US/BonjourPSSetup.exe) before continuing to ensure a stable experience while using PhotonVision.
+
+## Installing Java
+
+PhotonVision requires a JDK installed and on the system path. **JDK 11 is needed** (different versions will not work). You may already have this if you have installed WPILib, but ensure that running `java -version` shows JDK 11. If not, [download and install it from here](https://adoptium.net/temurin/releases?version=11) and ensure that the new JDK is being used.
+
+:::{warning}
+Using a JDK other than JDK11 will cause issues when running PhotonVision and is not supported.
+:::
+
+## Downloading the Latest Stable Release of PhotonVision
+
+Go to the [GitHub releases page](https://github.com/PhotonVision/photonvision/releases) and download the winx64.jar file.
+
+## Running PhotonVision
+
+To run PhotonVision, open a terminal window of your choice and run the following command:
+
+```
+> java -jar C:\path\to\photonvision\NAME OF JAR FILE GOES HERE.jar
+```
+
+If your computer has a compatible webcam connected, PhotonVision should startup without any error messages. If there are error messages, your webcam isn't supported or another issue has occurred. If it is the latter, please open an issue on the [PhotonVision issues page](https://github.com/PhotonVision/photonvision/issues).
+
+:::{warning}
+Using an integrated laptop camera may cause issues when trying to run PhotonVision. If you are unable to run PhotonVision on a laptop with an integrated camera, try disabling the camera's driver in Windows Device Manager.
+:::
+
+## Accessing the PhotonVision Interface
+
+Once the Java backend is up and running, you can access the main vision interface by navigating to `localhost:5800` inside your browser.