PhotonVision/docs/source/docs/contributing/building-photon.md

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 2026+. Windows Users must use the JDK that ships with WPILib. For other platforms, 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 22 or later is required. To install Node JS, follow the instructions for your platform on the official Node JS website.

pnpm:

pnpm is the package manager used to download dependencies for the UI. To install pnpm, follow the instructions on the official pnpm website.

Cross-Compilation Toolchains (Optional):

If you plan to deploy PhotonVision to a coprocessor like a Raspberry Pi, you will need to install the appropriate cross-compilation toolchain for your platform. For linuxarm64 devices, this can be accomplished by running ./gradlew installArm64Toolchain in the root folder of the project.

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:

:alt: Download source code from git
:width: 600

Install Necessary Node JS Dependencies

In the photon-client directory:

pnpm install

Using hot reload on the UI

In the photon-client directory:

pnpm run dev

This allows you to make UI changes quickly without having to spend time rebuilding the jar. Hot reload is enabled, so changes that you make and save are reflected in the UI immediately. Running this command will give you the URL for accessing the UI, which is on a different port than normal. You must use the printed URL to use hot reload.

Build and Run PhotonVision

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

.. tab-set::

   .. tab-item:: Linux
      :sync: linux

      ``./gradlew run``

   .. tab-item:: macOS
      :sync: macos

      ``./gradlew run``

   .. tab-item:: Windows (cmd)
      :sync: windows

      ``gradlew run``

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

.. tab-set::

   .. tab-item:: Linux
      :sync: linux

      ``./gradlew shadowJar``

   .. tab-item:: macOS
      :sync: macos

      ``./gradlew shadowJar``

   .. tab-item:: Windows (cmd)
      :sync: windows

      ``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. It uses deploy-utils, so it works very similarly to deploys on robot projects.

An architecture override is required to specify the deploy target's architecture.

.. tab-set::

   .. tab-item:: Linux
      :sync: linux

      ``./gradlew clean``

      ``./gradlew deploy -PArchOverride=linuxarm64``

   .. tab-item:: macOS
      :sync: macos

      ``./gradlew clean``

      ``./gradlew deploy -PArchOverride=linuxarm64``

   .. tab-item:: Windows (cmd)
      :sync: windows

      ``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 automatically 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:

.. tab-set::

   .. tab-item:: Linux
      :sync: linux

      ``./gradlew publishToMavenLocal``

   .. tab-item:: macOS
      :sync: macos

      ``./gradlew publishToMavenLocal``

   .. tab-item:: Windows (cmd)
      :sync: windows

      ``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()
}

VSCode Test Runner Extension

With the VSCode Extension Pack for Java, you can get the Test Runner for Java and Gradle for Java extensions. This lets you easily run specific tests through the IDE:

:alt: An image showing how unit tests can be ran in VSCode through the Test Runner for Java extension.

To correctly run PhotonVision tests this way, you must delegate the tests to Gradle. Debugging tests like this will not currently collect outputs.

Running Tests With UI

By default, tests are run with UI disabled so they are not obtrusive during a build. All tests should be useful when the UI is disabled. However, if a particular test would benefit from having UI access (i.e. for debugging info), the UI can be enabled by passing the enableTestUi project property to Gradle. This will run all tests by default, but the Gradle --tests option can be used to filter for specific tests.

.. tab-set::

   .. tab-item:: Linux
      :sync: linux

      ``./gradlew test -PenableTestUi``

   .. tab-item:: macOS
      :sync: macos

      ``./gradlew test -PenableTestUi``

   .. tab-item:: Windows (cmd)
      :sync: windows

      ``gradlew test -PenableTestUi``

Debugging PhotonVision Running Locally

Unit tests can instead be debugged through the test Gradle task for a specific subproject in VSCode, found in the Gradle tab:

:alt: An image showing how unit tests can be debugged in VSCode through the Gradle for Java extension.

However, this will run all tests in a subproject.

Similarly, a local instance of PhotonVision can be debugged in the same way using the Gradle run task. In both cases, additional arguments can be specified:

:alt: An image showing how VSCode gradle tasks can specify additional arguments.

Debugging PhotonVision Running on a CoProcessor

Set up a VSCode configuration in {code}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: {code}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. This will also 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 <example-name>:simulateJava

~/photonvision$ cd photonlib-cpp-examples
~/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>

Downloading Pipeline Artifacts

Using the GitHub CLI, we can download artifacts from pipelines by run ID and name:

~/photonvision$ gh run download 11759699679 -n jar-Linux

MacOS Builds

MacOS builds are not published to releases as MacOS is not an officially supported platform. However, MacOS builds are still available from the MacOS build action, which can be found here.

Forcing Object Detection in the UI

In order to force the Object Detection interface to be visible, it's necessary to hardcode the platform that Platform.java returns. This can be done by changing the function that detects the RK3588S/QCS6490 platform to always return true, and changing the getCurrentPlatform() function to always return the RK3588S/QCS6490 architecture. Alternatively, it's possible to modify the frontend code by changing all instances of useSettingsStore().general.supportedBackends.length > 0 to true, which will force the card to render. Make sure to revert these changes before submitting a Pull Request.