From e1752d6cde5f273ba18be5cc9cd60d67a8af3a0c Mon Sep 17 00:00:00 2001 From: sciencewhiz Date: Thu, 3 Sep 2026 19:54:32 -0700 Subject: [PATCH 1/3] Update VS Code RLIs to 2027 Alpha 7 --- .github/workflows/inspector.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/inspector.json b/.github/workflows/inspector.json index e932319b06..5803c2e43f 100644 --- a/.github/workflows/inspector.json +++ b/.github/workflows/inspector.json @@ -18,7 +18,7 @@ { "baseUrl": "https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/", "versionScheme": "v\\d{4}\\.\\d\\.\\d(?:-(?:alpha|beta)-\\d)?|[0-9a-f]{40}", - "latestVersion": "v2027.0.0-alpha-6" + "latestVersion": "v2027.0.0-alpha-7" }, { "baseUrl": "https://raw.githubusercontent.com/wpilibsuite/StandaloneAppSamples/", From d3e09ed8fa6b0c4bf62866c8fb44abb81568d425 Mon Sep 17 00:00:00 2001 From: sciencewhiz Date: Thu, 3 Sep 2026 20:17:37 -0700 Subject: [PATCH 2/3] Manually update RLIs and java-gc article for Systemcore --- source/docs/romi-robot/programming-romi.rst | 4 +-- .../profiling-with-visualvm.rst | 9 ++++-- .../basic-programming/deploy-directory.rst | 4 +-- .../software/basic-programming/java-gc.rst | 28 +++++++++---------- source/docs/xrp-robot/programming-xrp.rst | 4 +-- 5 files changed, 26 insertions(+), 23 deletions(-) diff --git a/source/docs/romi-robot/programming-romi.rst b/source/docs/romi-robot/programming-romi.rst index 9a401e88a3..0d57482d1c 100644 --- a/source/docs/romi-robot/programming-romi.rst +++ b/source/docs/romi-robot/programming-romi.rst @@ -40,9 +40,9 @@ One aspect where a Romi project differs from a regular FRC or FTC robot project To run a Romi program, first, ensure that your Romi is powered on. Next, connect to the ``WPILibPi-`` WiFi network broadcast by the Romi. If you changed the Romi network settings (for example, to connect it to your own WiFi network) you may change the IP address that your program uses to connect to the Romi. To do this, open the ``build.gradle`` file and update the ``wpi.sim.envVar`` line to the appropriate IP address. -.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-6/vscode-wpilib/resources/gradle/javaromi/build.gradle +.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-7/vscode-wpilib/resources/gradle/javaromi/build.gradle :language: groovy - :lines: 44-47 + :lines: 45-48 :lineno-match: :emphasize-lines: 2 diff --git a/source/docs/software/advanced-gradlerio/profiling-with-visualvm.rst b/source/docs/software/advanced-gradlerio/profiling-with-visualvm.rst index 18cf673b22..85558b2977 100644 --- a/source/docs/software/advanced-gradlerio/profiling-with-visualvm.rst +++ b/source/docs/software/advanced-gradlerio/profiling-with-visualvm.rst @@ -10,17 +10,20 @@ To begin, [download VisualVM](https://visualvm.github.io/download.html) and unpa GradleRIO supports passing JVM launch arguments, and this is what is necessary to enable remote debugging. Remote debugging is a feature that allows a local machine (such as the user's desktop) to view important information about a remote target (in our case, a SystemCore). To begin, locate the ``wpilibJava`` code block located in the projects ``build.gradle``. Below is what is looks like. -.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-6/vscode-wpilib/resources/gradle/java/build.gradle +.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-7/vscode-wpilib/resources/gradle/java/build.gradle :language: groovy - :lines: 16-46 + :lines: 16-48 :lineno-match: - :emphasize-lines: 18-19 + :emphasize-lines: 18-21 We will be replacing the highlighted lines with: ```groovy wpilibJava(getArtifactTypeClass('WPILibJavaArtifact')) { + // Set to true to use debug including JNI, which will drastically impact performance. + debugJni = false + // Enable VisualVM connection jvmArgs.add("-Dcom.sun.management.jmxremote=true") jvmArgs.add("-Dcom.sun.management.jmxremote.port=1198") diff --git a/source/docs/software/basic-programming/deploy-directory.rst b/source/docs/software/basic-programming/deploy-directory.rst index bb75446ab6..bf81967dfa 100644 --- a/source/docs/software/basic-programming/deploy-directory.rst +++ b/source/docs/software/basic-programming/deploy-directory.rst @@ -28,9 +28,9 @@ To access files from the deploy directory in your robot code, use the ``Filesyst By default the deploy directory in your project is transferred to the SystemCore when code is deployed. It is initiated by this section of the ``build.gradle`` file. -.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-6/vscode-wpilib/resources/gradle/java/build.gradle +.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-7/vscode-wpilib/resources/gradle/java/build.gradle :language: groovy - :lines: 36-42 + :lines: 38-44 :lineno-match: This will overwrite any duplicate files found in the ``/home/systemcore/deploy`` directory on the RIO and copy over any additional not present there. If ``deleteOldFiles`` is false it will not remove any files no longer present in the project deploy directory. Changing it to `true` helps prevent programs like :doc:`Choreo ` and [PathPlanner](https://pathplanner.dev) from getting confused by files that were deleted locally but still exist on the SystemCore. diff --git a/source/docs/software/basic-programming/java-gc.rst b/source/docs/software/basic-programming/java-gc.rst index da2f649427..6178a63830 100644 --- a/source/docs/software/basic-programming/java-gc.rst +++ b/source/docs/software/basic-programming/java-gc.rst @@ -33,16 +33,18 @@ All objects in Java are retained in a section of memory called the *heap*. As ob Since ``OutOfMemoryError``\ s both crash the program and are a common reason to want a heap dump, the JVM can be configured to automatically take a heap dump the moment an ``OutOfMemoryError`` is caught by the JVM. To configure these options, locate the ``wpilibJava`` code block in your project's ``build.gradle``: -.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-6/vscode-wpilib/resources/gradle/java/build.gradle +.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-7/vscode-wpilib/resources/gradle/java/build.gradle :language: groovy - :lines: 16-46 + :lines: 16-48 :lineno-match: - :emphasize-lines: 18-19 + :emphasize-lines: 18-21 Add to the code block so that it contains two ``jvmArgs`` commands, as shown below: ```groovy wpilibJava(getArtifactTypeClass('WPILibJavaArtifact')) { + // Set to true to use debug including JNI, which will drastically impact performance. + debugJni = false // If you have other configuration here, you do not need to remove it. // Enable automatic heap dumps on OutOfMemoryError // Note: the heap dump path here is a path on a USB flash drive, see below @@ -51,11 +53,9 @@ wpilibJava(getArtifactTypeClass('WPILibJavaArtifact')) { } ``` -This will cause the JVM to write heap dumps to a file named ``wpilib-usercode.hprof`` at the root of a USB flash drive attached to the roboRIO when the code runs out of memory. It is recommended to save these heap dumps to a USB flash drive because heap dumps intrinsically consume the same amount of space on disk as the program heap did in memory when the program crashed, and are likely to be larger than the roboRIO's internal storage has capacity for. Once you have reproduced the ``OutOfMemoryError``, redeploy your code without these options enabled, and use the USB flash drive to transfer the heap dump to a computer for analysis in a memory profiler such as :ref:`VisualVM `. +This will cause the JVM to write heap dumps to a file named ``wpilib-usercode.hprof`` at the root of a USB flash drive attached to the Systemcore when the code runs out of memory. It is recommended to save these heap dumps to a USB flash drive because heap dumps intrinsically consume the same amount of space on disk as the program heap did in memory when the program crashed, and are likely to be larger than the Systemcore's internal storage has capacity for. Once you have reproduced the ``OutOfMemoryError``, redeploy your code without these options enabled, and use the USB flash drive to transfer the heap dump to a computer for analysis in a memory profiler such as :ref:`VisualVM `. -.. warning:: Configuring the JVM this way requires that the flash drive remain connected to the roboRIO while your code is running. - -Larger SD cards may provide enough onboard storage to allow the use of these options on the roboRIO 2 without a USB flash drive. To do this, set the ``-XX:HeapDumpPath`` option to reference a path on the SD card, and use :doc:`FTP/SFTP to transfer the heap dump to a computer ` before deleting it from the SD card. +.. warning:: Configuring the JVM this way requires that the flash drive remain connected to the Systemcore while your code is running. Note that the JVM will **not** overwrite heap dumps with the exact path and filename specified by ``-XX:HeapDumpPath`` if they already exist, nor will it dump the process heap to a file with a different name. If a path to a directory is supplied instead of a path to a file, the JVM will instead write out heap dumps with unique filenames within the specified directory, with the name ``java_pidNNNN.hprof``, where ``NNNN`` is the process ID of the JVM that ran out of memory. Note that this can cause large files to build up on disk if they are not cleaned out, so if you configure the JVM this way, be sure to frequently copy heap dumps to a computer and delete them from the flash drive/SD card afterward. @@ -65,9 +65,9 @@ Note that the JVM will **not** overwrite heap dumps with the exact path and file ## System Memory Tuning -If the JVM cannot allocate memory, the program will be terminated. As an embedded system with only a small amount of memory available (256 MB on the roboRIO 1, 512 MB on the roboRIO 2), the roboRIO is particularly susceptible to running out of memory. +If the JVM cannot allocate memory, the program will be terminated. As an embedded system with only a small amount of memory available (256 MB on the roboRIO 1, 512 MB on the roboRIO 2), the roboRIO was particularly susceptible to running out of memory. -.. admonition :: No amount of system tuning can fix out of memory errors caused by out-of-control allocations. +.. warning:: The Systemcore has significantly more memory available (4GB) than the roboRIO, so it is unlikely that you will run out of memory when running your robot code. If you are running out of memory, always investigate allocations with heap dumps and/or :doc:`VisualVM ` first. @@ -77,7 +77,7 @@ If you continue to run out of memory even after investigating with VisualVM and - Periodically calling the garbage collector - Setting up swap on a USB flash drive -Implementing most of these options require :doc:`connecting with SSH ` to the roboRIO and running commands. If run incorrectly, it may require a reimage to recover, so be careful when following the instructions. +Implementing most of these options require :doc:`connecting with SSH ` to the Systemcore and running commands. If run incorrectly, it may require a reimage to recover, so be careful when following the instructions. ### Setting sysctls @@ -87,7 +87,7 @@ Several Linux kernel options (called sysctls) can be set to tweak how the kernel - Setting ``vm.vfs_cache_pressure`` to 1000 (the default value is 100). Increasing this causes the kernel to much more aggressively reclaim file system object caches; it may slightly degrade performance. - Setting ``vm.swappiness`` to 100 (the default value is 60). This causes the kernel to more aggressively swap process memory to the swap file. Changing this option has no effect unless you add a swap file. -You can set some or all of these options; the most important one is ``vm.overcommit_memory``. Setting these options requires connecting to the roboRIO with SSH and logging in as the ``admin`` user, then running the following commands: +You can set some or all of these options; the most important one is ``vm.overcommit_memory``. Setting these options requires connecting to the Systemcore with SSH and logging in as the ``admin`` user, then running the following commands: ```text echo "vm.overcommit_memory=1" >> /etc/sysctl.conf @@ -125,13 +125,13 @@ public void periodic() { ### Setting Up Swap on a USB Flash Drive -A swap file on a Linux system provides disk-backed space that can be used by the system as additional virtual memory to put infrequently used data and programs when they aren't being used, freeing up physical RAM for active use such as the robot program. It is strongly recommended to not use the built-in non-replaceable flash storage on the roboRIO 1 for a swap file, as it has very limited write cycles and may wear out quickly. Instead, however, a FAT32-formatted USB flash drive may be used for this purpose. This does require the USB flash drive to always be plugged into the roboRIO before boot. +A swap file on a Linux system provides disk-backed space that can be used by the system as additional virtual memory to put infrequently used data and programs when they aren't being used, freeing up physical RAM for active use such as the robot program. It is strongly recommended to not use the built-in non-replaceable flash storage on the Systemcore for a swap file, as it has very limited write cycles and may wear out quickly. Instead, however, a FAT32-formatted USB flash drive may be used for this purpose. This does require the USB flash drive to always be plugged into the Systemcore before boot. -.. caution:: Having a swap file on a USB stick means it's critical the USB stick stay connected to the roboRIO at all times it is powered. +.. caution:: Having a swap file on a USB stick means it's critical the USB stick stay connected to the Systemcore at all times it is powered. This should be used as a last resort if none of the other steps above help. Generally needing swap is indicative of some other allocation issue, so use VisualVM first to optimize allocations. -A swap file can be set up by plugging the USB flash drive into the roboRIO USB port, connecting to the roboRIO with SSH and logging in as the ``admin`` user, and running the following commands. Note the vi step requires knowledge of how to edit and save a file in vi. +A swap file can be set up by plugging the USB flash drive into the Systemcore USB port, connecting to the Systemcore with SSH and logging in as the ``admin`` user, and running the following commands. Note the vi step requires knowledge of how to edit and save a file in vi. ```text fallocate -l 100M /u/swapfile diff --git a/source/docs/xrp-robot/programming-xrp.rst b/source/docs/xrp-robot/programming-xrp.rst index d609d10457..59583ca268 100644 --- a/source/docs/xrp-robot/programming-xrp.rst +++ b/source/docs/xrp-robot/programming-xrp.rst @@ -40,9 +40,9 @@ One aspect where an XRP project differs from a regular FRC or FTC robot project To run an XRP program, first, ensure that your XRP is powered on. Next, connect to ``XRP-`` WiFi network broadcast by the XRP. If you changed the XRP network settings (for example, to connect it to your own network), you may change the IP address that your program uses to connect to the XRP. To do this, open the ``build.gradle`` file and update the ``wpi.sim.envVar`` line to the appropriate IP address. -.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-6/vscode-wpilib/resources/gradle/javaxrp/build.gradle +.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-7/vscode-wpilib/resources/gradle/javaxrp/build.gradle :language: groovy - :lines: 44-47 + :lines: 45-48 :lineno-match: :emphasize-lines: 2 From e7256dd4d2570082c05e93e7d0cb1e98a62aa7dc Mon Sep 17 00:00:00 2001 From: sciencewhiz Date: Thu, 3 Sep 2026 20:25:30 -0700 Subject: [PATCH 3/3] Update unit simulation --- .../software/wpilib-tools/robot-simulation/introduction.rst | 4 ++-- .../software/wpilib-tools/robot-simulation/unit-testing.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/docs/software/wpilib-tools/robot-simulation/introduction.rst b/source/docs/software/wpilib-tools/robot-simulation/introduction.rst index b8c8f46206..7be25e37e0 100644 --- a/source/docs/software/wpilib-tools/robot-simulation/introduction.rst +++ b/source/docs/software/wpilib-tools/robot-simulation/introduction.rst @@ -61,7 +61,7 @@ Often a team may want to test their code without having an actual robot availabl .. image:: images/vscode-run-bad.png :alt: Run button to the left of the WPIlib Button - .. note:: Simulation can also be run outside of VS Code using ``./gradlew simulateJava`` for Java or ``./gradlew simulateNative`` for C++. + .. note:: Simulation can also be run outside of VS Code using ``./gradlew runa`` for Java or ``./gradlew simulateNative`` for C++. .. note:: Some vendors support attaching hardware to your PC and using the hardware in desktop simulation (e.g. CANivore). See :doc:`vendor documentation ` for more information about the command `WPILib: Hardware Sim Robot Code`. @@ -100,7 +100,7 @@ Glass, Elastic, and AdvantageScope can be used with WPILib simulation when they ### Glass -Glass is automatically configured to look for a NetworkTables instance from the roboRIO, but **not from other sources**. To connect to a simulation, open :guilabel:`NetworkTables Settings` under the :guilabel:`NetworkTables` menu and in the :guilabel:`Team/IP` field, enter the IP address or hostname of the NetworkTables host. For a standard simulation configuration, use ``localhost``. +Glass is automatically configured to look for a NetworkTables instance from the Systemcore, but **not from other sources**. To connect to a simulation, open :guilabel:`NetworkTables Settings` under the :guilabel:`NetworkTables` menu and in the :guilabel:`Team/IP` field, enter the IP address or hostname of the NetworkTables host. For a standard simulation configuration, use ``localhost``. .. image:: images/glass-networktables.png :alt: Glass NetworkTables Preferences showing Team/IP set to localhost. diff --git a/source/docs/software/wpilib-tools/robot-simulation/unit-testing.rst b/source/docs/software/wpilib-tools/robot-simulation/unit-testing.rst index 03f0bcdc8d..05524a685a 100644 --- a/source/docs/software/wpilib-tools/robot-simulation/unit-testing.rst +++ b/source/docs/software/wpilib-tools/robot-simulation/unit-testing.rst @@ -70,9 +70,9 @@ For more advanced usage of JUnit and Google Test, see the framework docs. For Java tests to run, make sure that your ``build.gradle`` file contains the following block: -.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-6/vscode-wpilib/resources/gradle/java/build.gradle +.. rli:: https://raw.githubusercontent.com/wpilibsuite/vscode-wpilib/v2027.0.0-alpha-7/vscode-wpilib/resources/gradle/java/build.gradle :language: groovy - :lines: 82-85 + :lines: 83-86 :lineno-match: Use :guilabel:`Test Robot Code` from the Command Palette to run the tests. Results will be reported in the terminal output, each test will have a ``FAILED`` or ``PASSED``/``OK`` label next to the test name in the output. JUnit (Java only) will generate a HTML document in ``build/reports/tests/test/index.html`` with a more detailed overview of the results; if there are any failed tests a link to render the document in your browser will be printed in the terminal output.