Build Instructions
This section contains the build instructions from the source code available at our GitHub page.
Development Setup
Prerequisites
Java Development Kit:
This project requires Java Development Kit (JDK) 17 to be compiled. This is the same Java version that comes with WPILib for 2025+. If you don’t have this JDK with WPILib, you can follow the instructions to install JDK 17 for your platform here.
Node JS:
The UI is written in Node JS. To compile the UI, Node 18.20.4 to Node 20.0.0 is required. To install Node JS follow the instructions for your platform on the official Node JS website. However, modify this line
nvm install 20
so that it instead reads
nvm install 18.20.4
Compiling Instructions
Getting the Source Code
Get the source code from git:
git clone https://github.com/PhotonVision/photonvision
or alternatively download the source code from GitHub and extract the zip:
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 PhotonVision
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
Build and Run PhotonVision on a Raspberry Pi Coprocessor
As a convenience, the build has a built-in deploy
command which builds, deploys, and starts the current source code on a coprocessor.
An architecture override is required to specify the deploy target’s architecture.
./gradlew clean
./gradlew deploy -PArchOverride=linuxarm64
./gradlew clean
./gradlew deploy -PArchOverride=linuxarm64
gradlew clean
gradlew deploy -PArchOverride=linuxarm64
The deploy
command is tested against Raspberry Pi coprocessors. Other similar coprocessors may work too.
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 {
mavenLocal()
}
Debugging PhotonVision Running Locally
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: https://go.microsoft.com/fwlink/?linkid=830387
"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.
Debugging PhotonVision Running on a CoProcessor
Set up a VSCode configuration in launch.json
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"type": "java",
"name": "Attach to CoProcessor",
"request": "attach",
"hostName": "photonvision.local",
"port": "5801",
"projectName": "photon-core"
},
]
}
Stop any existing instance of PhotonVision.
Launch the program with the following additional argument to the JVM: java -jar -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5801 photonvision.jar
Once the program says it is listening on port 5801, launch the debug configuration in VSCode.
The program will wait for the VSCode debugger to attach before proceeding.
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-*-examples subdirectories for each language.
Running C++/Java
PhotonLib must first be published to your local maven repository, then the copy PhotonLib 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 not yet supported.
~/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
Running Python
PhotonLibPy must first be built into a wheel.
> cd photon-lib/py
> buildAndTest.bat
Then, you must enable using the development wheels. robotpy will use pip behind the scenes, and this bat file tells pip about your development artifacts.
Note: This is best done in a virtual environment.
> enableUsingDevBuilds.bat
Then, run the examples:
> cd photonlib-python-examples
> run.bat <example name>