Build Instructions

This section contains the build instructions from the source code available at our GitHub page.

Development Setup


Java Development Kit: This project requires Java Development Kit (JDK) 11 to be compiled. This is the same Java version that comes with WPILib. If you don’t have this JDK with WPILib, you can follow the instructions to install JDK 11 for your platform here.
Node JS: The UI is written in Node JS. To compile the UI, Node 10 or newer is required. To install Node JS follow the instructions for your platform on the official Node JS website.

Compiling Instructions

Getting the Source Code

Get the source code from git:

git clone

or alternatively download to source code from github and extract the zip:

Download source code from git

Install Necessary Node JS Dependencies

In the photon-client directory:

npm install

Build and Copy UI to Java Source

In the root directory:

./gradlew buildAndCopyUI

./gradlew buildAndCopyUI

gradlew buildAndCopyUI

Build and Run the Source

To compile and run the project, issue the following command in the root directory:

./gradlew run

./gradlew run

gradlew run

Running the following command under the root directory will build the jar under photon-server/build/libs:

./gradlew shadowJar

./gradlew shadowJar

gradlew shadowJar

Using PhotonLib Builds

The build process includes the following task:

./gradlew generateVendorJson

./gradlew generateVendorJson

gradlew generateVendorJson

This generates a vendordep JSON of your local build at photon-lib/build/generated/vendordeps/photonlib.json.

The photonlib source can be published to your local maven repository after building:

./gradlew publishToMavenLocal

./gradlew publishToMavenLocal

gradlew publishToMavenLocal

After adding the generated vendordep to your project, add the following to your project’s build.gradle under the plugins {} block.

repositories {

Debugging a local PhotonVision build

One way is by running the program using gradle with the --debug-jvm flag. Run the program with ./gradlew run --debug-jvm, and attach to it with VSCode by adding the following to launch.json. Note args can be passed with --args="foobar".

   // Use IntelliSense to learn about possible attributes.
   // Hover to view descriptions of existing attributes.
   // For more information, visit:
   "version": "0.2.0",
   "configurations": [
            "type": "java",
            "name": "Attach to Remote Program",
            "request": "attach",
            "hostName": "localhost",
            "port": "5005",
            "projectName": "photon-core",

PhotonVision can also be run using the gradle tasks plugin with "args": "--debug-jvm" added to launch.json.

Running examples

You can run one of the many built in examples straight from the command line, too! They contain a fully featured robot project, and some include simulation support. The projects can be found inside the photonlib-java-examples and photonlib-cpp-examples subdirectories, respectively. The projects currently available include:

  • photonlib-java-examples:
    • aimandrange:simulateJava

    • aimattarget:simulateJava

    • getinrange:simulateJava

    • simaimandrange:simulateJava

    • simposeest:simulateJava

  • photonlib-cpp-examples:
    • aimandrange:simulateNative

    • getinrange:simulateNative

To run them, use the commands listed below. Photonlib must first be published to your local maven repository, then the copyPhotonlib task will copy the generated vendordep json file into each example. After that, the simulateJava/simulateNative task can be used like a normal robot project. Robot simulation with attached debugger is technically possible by using simulateExternalJava and modifying the launch script it exports, though unsupported.

~/photonvision$ ./gradlew publishToMavenLocal

~/photonvision$ cd photonlib-java-examples
~/photonvision/photonlib-java-examples$ ./gradlew copyPhotonlib
~/photonvision/photonlib-java-examples$ ./gradlew <example-name>:simulateJava

~/photonvision$ cd photonlib-cpp-examples
~/photonvision/photonlib-cpp-examples$ ./gradlew copyPhotonlib
~/photonvision/photonlib-cpp-examples$ ./gradlew <example-name>:simulateNative