BertLib

BertLib is BERT's reusable Java library for FIRST Robotics Competition (FRC) robot projects.

Status: this repository contains reusable menu, circuit-breaker, sticky-diagnostic, rumble, speed-limit, and logging utilities derived from BERT's Yoshi robot. Circuit breakers and sticky asserts distinguish best-effort command control from telemetry-only pit diagnostics. See consumer integration for RobotContainer / Constants setup and extraction notes for provenance and boundaries. Version 2026.0.0 is the initial local development version, not an announcement of an available hosted release. The online installation instructions below work only once the matching Maven artifacts and vendordep JSON have been published. Use local installation until then.

• Source: https://forge.bert133.dev/bert/bertlib
• Git origin: https://forge.bert133.dev/bert/bertlib.git
• Maven coordinates: dev.bert133:bertlib-java:2026.0.0
• Intended Maven registry: https://forge.bert133.dev/api/packages/bert/maven
• Season: 2026; Java 17; built and tested with WPILib/GradleRIO 2026.2.1
• Separate 2027 preview compatibility work targets commands v3

Dependency and compatibility policy

BertLib uses the normal FRC model: the robot project supplies WPILib through its own GradleRIO configuration. BertLib's JAR does not bundle WPILib, and its published POM and Gradle module metadata do not pull WPILib in transitively. The vendordep pins the BertLib version, not a WPILib patch version.

Your robot project must already be a working Java command-based WPILib project for the 2026 season, including WPILibNewCommands.json and implementation wpi.java.vendor.java(). Keep its normal WPILib Java, roboRIO JNI, and desktop simulation configuration. Installing BertLib does not install the WPILib toolchain or configure a standalone Java application to run robot simulation.

There is no exact WPILib-version restriction in BertLib's dependency metadata. That is not a guarantee of compatibility with every release: only 2026.2.1 has been exercised by these utilities. Future releases must document and test their supported WPILib versions. Do not assume a 2026 release supports the next season without validation.

Install a hosted release in a robot project

These instructions apply after a maintainer publishes a release. Both the JSON URL and the referenced artifacts must be anonymously readable; teams should not need Forgejo accounts or tokens to install BertLib.

Option 1: WPILib VS Code dependency manager

1. Open your existing 2026 Java robot project in WPILib VS Code.

2. Open the WPILib Vendor Dependencies view. Alternatively, open the command palette and choose WPILib: Manage Vendor Libraries, then Install new libraries (online).

3. Supply this vendordep URL:

   https://forge.bert133.dev/bert/bertlib/raw/branch/main/vendordeps/BertLib.json
   

4. Confirm that vendordeps/BertLib.json appears in your robot project.

5. Build the robot project. The first build needs internet access to download BertLib and any other dependencies not already cached.

6. Commit vendordeps/BertLib.json to your team's Git repository so everyone uses the same BertLib version.

The URL follows the descriptor on main. The copied JSON pins an artifact version; it does not update automatically on every build.

Option 2: command line

From the robot project's root, not the BertLib source checkout:

./gradlew vendordep --url=https://forge.bert133.dev/bert/bertlib/raw/branch/main/vendordeps/BertLib.json
./gradlew build

On Windows PowerShell:

.\gradlew.bat vendordep --url=https://forge.bert133.dev/bert/bertlib/raw/branch/main/vendordeps/BertLib.json
.\gradlew.bat build

Option 3: copy the JSON manually

Download the release descriptor and save it as vendordeps/BertLib.json in your robot project. If the directory does not exist, create it. Do not place the JSON in src/main/java, and do not copy the BertLib source checkout's build configuration over your robot project's configuration.

A standard Java robot project already has this line:

dependencies {
    implementation wpi.java.vendor.java()
}

It allows GradleRIO to use the Java dependencies listed in the vendordep. If you intentionally use a nonstandard build, ensure that this line and your normal WPILib dependencies are present. BertLib has no native artifacts of its own, so its jniDependencies and cppDependencies arrays are empty.

Verify installation

In the robot project, run:

./gradlew dependencyInsight --dependency bertlib-java --configuration compileClasspath
./gradlew build

The dependency report should contain dev.bert133:bertlib-java:2026.0.0 (or the release version you installed). You can resolve the marker class with:

import dev.bert133.bertlib.BertLib;

There is nothing to instantiate or call yet. The import demonstrates the package name; it does not add any robot behavior.

Updates, removal, and offline use

• Update: use the dependency manager's online update check, or rerun the vendordep --url=... command. Review and commit the changed JSON, then build and test your robot code before deploying.
• Remove: remove BertLib through the dependency manager, or delete vendordeps/BertLib.json and any BertLib imports. Rebuild afterward.
• Offline: build successfully online on every development machine before going to an event. Keep the JSON in source control. ./gradlew build --offline can use cached artifacts; the JSON alone does not contain the JAR. There is no BertLib offline installer supplied by this scaffold.

Install a local development build

This path does not require remote publishing or Forgejo credentials.

1. Build BertLib and its local Maven repository

Clone the library if necessary:

git clone https://forge.bert133.dev/bert/bertlib.git
cd bertlib

With mise installed:

mise trust
mise install
mise run package

Without mise, use an installed JDK 17 (the WPILib JDK is suitable):

./gradlew build publishMavenJavaPublicationToLocalRepository generateVendordep

Windows users can substitute .\gradlew.bat for ./gradlew. The wrapper supplies Gradle; no global Gradle installation is needed for normal builds.

The local repository is build/repos/releases/. It contains the thin JAR, sources, Javadoc, POM, and Gradle module metadata.

2. Generate a descriptor pointing at the local repository

Run this in the BertLib checkout, replacing the example URI with the absolute location of build/repos/releases on your machine:

./gradlew generateVendordep -PvendordepMavenUrl=file:///home/you/bertlib/build/repos/releases/

With mise, prefix it with mise exec --. On Windows, for example:

.\gradlew.bat generateVendordep -PvendordepMavenUrl=file:///C:/Users/you/bertlib/build/repos/releases/

Use a valid file URI, including percent-encoding spaces (%20) if necessary. Copy the generated build/vendordeps/BertLib.json into your robot project's vendordeps/ directory. Do not copy the committed descriptor for this step: that one points at the remote registry. Then build the robot project normally.

This development descriptor is machine-specific. Do not commit it to your team's shared robot repository or distribute it as a public release. An online vendordep update replaces it with the remote descriptor. Avoid having both a local and remote BertLib JSON installed; they identify the same library UUID.

After changing BertLib, republish locally and rebuild the robot project. During local iteration with the same version, ./gradlew build --refresh-dependencies in the consumer can refresh its cached artifact. Return to immutable, unique versions for public releases.

To restore the normal generated descriptor in the library checkout, run ./gradlew generateVendordep without the URL override. The library's check task verifies that this default descriptor matches vendordeps/BertLib.json.

Develop and test the library

mise run build
mise run test
mise run package

Equivalent wrapper commands are ./gradlew build, ./gradlew test, and ./gradlew build publishMavenJavaPublicationToLocalRepository generateVendordep.

Production Java sources live in src/main/java/dev/bert133/bertlib/; tests live in src/test/java/dev/bert133/bertlib/. Tests cover menu navigation and Preferences, breaker command control and diagnostic latching, rumble arbitration/pulses, speed caps, and command activity, plus WPILib geometry resolution, desktop HAL, and simulated digital input behavior. It does not need a roboRIO or connected robot hardware.

WPILib is compileOnly for production sources and testImplementation for tests. GradleRIO downloads desktop JNI libraries and configures the test JVM to load them. Keep this wiring when adding HAL-backed tests; Java JARs alone are insufficient. If future code uses the command framework, add its compile/test dependency explicitly and document the requirement for consumers.

Test results: build/reports/tests/test/index.html. Published library artifacts: build/libs/ and build/repos/releases/. Generated release descriptor: build/vendordeps/BertLib.json.

Publish a release (maintainers)

Publishing is a separate, explicit operation. This scaffold does not create automatic releases, upload packages during build, or push Git changes.

1. Choose a new immutable version and update libraryVersion in gradle.properties. Do not overwrite a public release version.

2. Run ./gradlew generateVendordep with no local URL override. Copy its build/vendordeps/BertLib.json output to vendordeps/BertLib.json.

3. Run ./gradlew clean build publishMavenJavaPublicationToLocalRepository. Check the test report and generated POM/module metadata; WPILib must not appear as a transitive dependency.

4. Use a Forgejo account authorized to publish Maven packages under bert. Supply its access token as the FORGEJO_TOKEN environment variable. With mise, copy .env.example to .env, populate the token locally, and use mise exec -- for the publication command. .env is ignored by Git. Never place a token in the vendordep, README, command-line arguments, or Git.

5. Publish artifacts explicitly:

   mise exec -- ./gradlew publishMavenJavaPublicationToForgejoRepository
   

   Without mise, provide FORGEJO_TOKEN securely in the process environment and run the same wrapper task without the prefix. Avoid plain publish, which targets all configured publication repositories.

6. Verify that the new JAR and POM are anonymously downloadable from:

   https://forge.bert133.dev/api/packages/bert/maven/dev/bert133/bertlib-java/<version>/bertlib-java-<version>.jar
   https://forge.bert133.dev/api/packages/bert/maven/dev/bert133/bertlib-java/<version>/bertlib-java-<version>.pom
   

7. Only after the artifacts are available, commit and push the matching vendordep and version change. Verify the raw JSON URL anonymously. Test installing the hosted descriptor in a fresh 2026 robot project before announcing the release. Publishing packages does not push source code, and pushing source code does not publish packages.

The registry URL is configured for the existing bert organization. Package visibility/permissions are controlled by Forgejo and must be checked before calling a release publicly installable. See Forgejo Maven registry instructions.

No license grant has been selected in this scaffold. Before public redistribution, the repository owner should select a license and add its text and publication metadata.

Troubleshooting

• 404 on the vendordep or JAR: the matching release may not be published. Use a local build, or check that the maintainer published artifacts before updating the online descriptor.
• 401/403 while installing: public installation must not require a token; ask the maintainer to check registry and organization visibility.
• BertLib not on the classpath: verify the JSON is in the robot project's vendordeps/, implementation wpi.java.vendor.java() is present, and a build completed successfully. Reload the Gradle project in your IDE.
• WPILib classes missing: use a normal WPILib robot project with its WPILib dependencies. BertLib deliberately does not supply them transitively.
• UnsatisfiedLinkError in tests: verify desktop JNI configuration, supported OS/architecture, and Java/native WPILib version agreement. This scaffold was exercised on Linux x86-64; other platforms require validation.
• Descriptor verification failure: regenerate the default descriptor and copy it into vendordeps/BertLib.json after version changes. Do not commit a descriptor containing a local file URI.

References

• WPILib vendor library installation
• WPILib 2026 vendor template
• WPILib unit testing