Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/inspector.json
Original file line number Diff line number Diff line change
Expand Up @@ -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/",
Expand Down
4 changes: 2 additions & 2 deletions source/docs/romi-robot/programming-romi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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-<number>`` 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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
4 changes: 2 additions & 2 deletions source/docs/software/basic-programming/deploy-directory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 </docs/software/pathplanning/choreo/index>` and [PathPlanner](https://pathplanner.dev) from getting confused by files that were deleted locally but still exist on the SystemCore.
Expand Down
28 changes: 14 additions & 14 deletions source/docs/software/basic-programming/java-gc.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 <docs/software/advanced-gradlerio/profiling-with-visualvm:Analyzing a Heap Dump>`.
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 <docs/software/advanced-gradlerio/profiling-with-visualvm:Analyzing a Heap Dump>`.

.. 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 </docs/software/systemcore-info/roborio-ftp>` 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.

Expand All @@ -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 </docs/software/advanced-gradlerio/profiling-with-visualvm>` first.

Expand All @@ -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 </docs/software/systemcore-info/roborio-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 </docs/software/systemcore-info/roborio-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

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 </docs/software/vscode-overview/wpilib-commands-vscode>` for more information about the command `WPILib: Hardware Sim Robot Code`.

Expand Down Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions source/docs/xrp-robot/programming-xrp.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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-<IDENT>`` 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

Expand Down
Loading