SwerveIO/README.md

SwerveIO

The Open Source Swerve Drive Library

SwerveIO is an open-source swerve drive library written for FRC in Java. It is pronounced "Swerve - ee - oh", which rhymes with "Oreo".

You are currently viewing the developer documentation. The upstream user documentation is available as JavaDoc documentation in the source tree and can be easily generated using the javadoc Gradle task. The change log is available below.

Project Status

I am no longer on an FRC team, and my old FRC team refuses to use SwerveIO anymore. Suffice it to say that SwerveIO's future doesn't look too good. That being said, if you are interested in SwerveIO, please reach out to me and let me know. I am more than happy to keep working on SwerveIO, but right now I don't see a lot of interest, so I don't want to waste my time on it.

This project is as good as dead, but it doesn't have to be! Seriously, an email telling me you want to see this thing going again is all it would take. Until I get that email though, you likely won't see any changes to this code. This message was written on February 17, 2022.

Project Layout

This project is a standard Gradle project with multiple subprojects. It strives to follow the Gradle-prescribed file system hierarchy as closely as possible.

Building

SwerveIO can be built using a simple ./gradlew build. Documentation can be built with ./gradlew javadoc. If you don't have an internet connection or are at a competition, you can specify the --offline Gradle flag. This will speed up builds dramatically because a lot of non-essential functionality will be disabled.

Contributing

The contribution workflow for SwerveIO may be different from what you might be used to. Please see my homepage for instructions.

SwerveIO is a highly specialized library designed to meet the programming standards enforced by the style recommendations for the Java language. The Google Style Guide is a good guide to follow, however exact standards enforced in this library will be at the discretion of its maintainers. I personally just use my IDE's formatting tool call it good. I do, however, have the following rules specific to this project:

• Always explicitly declare the type of a variable, even in lambda expressions. In other words, don't use the var keyword, and if you have a lambda that looks like this: (param) -> doSomethingWith(param), change it to this: (String param) -> doSomethingWith(param), where String is the actual type of param.

The goal for SwerveIO is to be the best possible library that can be used by the most people. Contributors should write their highest quality code. This means that SwerveIO should be:

• Stable: SwerveIO should work consistently no matter what. Whenever possible, the public-facing API should be preserved so that users can upgrade without much difficult. Additionally, every individual release should perform consistently every time.
• Standardized: All the Java sandards should be followed. This is a Java library, it should look and work like one.
• Efficient: Code should be clean and efficient.
• Versatile: Remember that the design goals of SwerveIO intend to cater to the most swerve drive users as possible. Code should not be specialized or dependent on any hardware or 3rd-partly library behavior when possible. Great care has been taken to ensure the library is abstract enough that new hardware can be easily added.
• Documented: Always keep the documentation up to date and write comments wherever they are needed. Currently, there are more lines of comment in SwerveIO than there are lines of code. I am proud of that.

Before contributing to the development of SwerveIO, please be sure of the following:

• You accept the terms of the license that your contributions will be released under. See the LICENSE file.
• You agree to the contributor code of conduct, detailed below.
• You took a look at the TODO file. That file contains what's planned for the future of SwerveIO, so maybe you can help out with some of the items listed there.

When making your changes, be sure to add an appropriate entry to the changelog.

Environment Setup

You need the following pieces of software to develop and contribute to SwerveIO:

• A Java Development Kit (JDK), version 11 or greater
• CVS
• An IDE or text editor

I don't have any hard requirements for the IDE or text editor you use, but I would highly recommend using VSCode or IntelliJ because I have both configurations bundled to set up the project automatically for you.

Code of Conduct

SwerveIO's development code of conduct is simple:

• Be human. We're all people here and we may all be different and at different stages of life. Be understanding of others and know that they may be going through something you aren't aware of.
• Don't get political. There is a place for politics, and if you know me personally, you know I am quite opinionated. But SwerveIO's development cycle is not the place for politics. The focus should just be on writing code with fellow programmers and helping to create the best library possible.

Release Checklist

This is just to help me when I'm releasing new versions of SwerveIO.

• Increment version in build.gradle
• Add changelog entry to this readme.
• Tag the release with the version number and publish it to my website.

Release Model

SwerveIO may be under heavy development during robotics seasons. Because of this, it featured an aggressive release model in its early days that wasn't afraid to break existing code. However, as I want SwerveIO to be stable, and I have grown more conservative over the years, I want to slow things down and keep things stable. I am open to the idea of maintaining long term support (LTS) releases along side the primary development cycle. I want SwerveIO to work for its users, so please contact me so we can discuss SwerveIO's release model.

SwerveIO strives to adhere to Semantic Versioning:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

Change Log

8.0.2

• Updated the contributing instructions to note the usage of CVS instead of Git.
• Added a notice to this README announcing the deprecation of SwerveIO. I'm sad to see this project go, and maybe I'll revive it at some point later in life, but if nobody expresses any interest in what I've done here, then I'll lay this project to rest. I'll of course still host all the source code here, and if you're considering forking SwerveIO, I'd say reach out to me and email me because I want to be involved!

Note: This release makes no code or build changes. It simply bumps the version number so that I could update this README. For that reason, I have no idea if SwerveIO still builds with current tooling, but I know that if for some reason it doesn't, we can get it going again in no time, just send me an email.

8.0.1

• Updated CTRE Phoenix to the latest kickoff release. This fixes a build error that some Windows users were encountering when trying to build against the local Maven repository.

8.0.0

Welcome to the 2022 Kickoff! This release includes all the changes from 8.0.0-rc1 and 8.0.0-rc2, so if you're upgrading from SwerveIO 7x, make sure to read the release notes for those too!

• Updated WPILib to '2022.1.1', the kickoff release of WPILib.
• Upgraded the SparkMax API to REVLib 2022.
  • The SparkMaxEncoder class constructors were updated to reflect the changes made to how REV does encoders. Some breaking changes were made for users that weren't using the default constructor. If you were using the default constructor, you should notice no changes.
• Removed the LegacySpeedController class introduced in -rc1 because all vendors now support WPILib's SpeedController.

8.0.0-rc2

• Updated WPILib to 2022.1.1-rc-1.
• Updated OpenCV to 4.5.2-1.
• Made some internal variables final.

SwerveIO 8.0.0 will be released when WPILib 2022.1.1 is, which will most likely occur before or during the 2022 kickoff. At this time, I am considering breaking all WPILib support off into a separate Gradle subproject, because of the recent breaking changes. SwerveIO will still fully support WPILib, but will also provide all its own interfaces so that it can be used entirely separate if necessary.

8.0.0-rc1

SwerveIO 8x brings SwerveIO up to date with WPILib 2022.x. This release should look a lot like the previous releases. However, WPILib made a lot of breaking user-facing API changes. This update is simply to reflect those changes and make SwerveIO compatible with future releases of WPILib and vendor libraries.

Note: This release of SwerveIO is not compatible with WPILib 2021 or earlier. It requires WPILib 2022.1.1 or later.

The breaking changes are as follows:

• Replaced all references to the deprecated SpeedController with the new MotorController. All interfaces and implementations were adjusted accordingly.

Other non-breaking changes are also included in this release:

• Replaced a reference to the deprecated DriverStation.getInstance() with just DriverStation.
• Added the LegacySpeedController class to support vendor APIs that haven't updated their APIs to use the latest WPILib. Note that this class is already deprecated and schedule for removal as soon as all supported hardware vendors update their APIs or WPILib removes the SpeedController interface, whichever happens first.
• Cleaned up this README document to reflect the current state of SwerveIO.
• Updated the copyright headers throughout the code.

7.0.4

• Updated the IntelliJ configuration to use the system's JDK instead of a hard-coded JDK.
• Updated Gradle from 7.2 to 7.3.3.
• Updated WPILib to 2022.1.1-beta-4.
• [vendor/kauai] Updated NavX library to 4.0.435.
• As far as I can tell, it looks like CTRE Phoenix is working again. As of the date of this release, SwerveIO can be built normally.

7.0.3

• Added an IntelliJ .idea folder for developing SwerveIO with IntelliJ. Since I'm no longer on the robotics team, I don't use VS Code much anymore, so I've become much more familiar with IntelliJ. Obviously IntelliJ cannot be used by students, because students require the WPILib VS Code plugins, but since I'm not going to be directly deploying SwerveIO to a robot, I can use IntelliJ.
• Updated Gradle from 7.1.1 to 7.2.
• Updated CTRE Phoenix from 5.19.4 to 5.20.0. Note that at this time, neither version will build with SwerveIO because the CTRE Maven repository is broken. It does not match what is in the vendor JSON description file, and indexing is not allowed, so I'm unable to troubleshoot. If anyone knows what's up with this, or has a fix, please contact me at jordan@bancino.net.
• Documented the LogIO classes.

7.0.2

Updated Gradle from 7.0.1 to 7.1.1, and fixed some broken links.

7.0.1

Fixed some errors in the Javadoc home page that prevented the documentation from building correctly on JDK 11.

7.0.0

SwerveIO 7.0.0 cleans up a lot of the API, making for neater and less fragmented code. This release also simplifies the build system and documentation, and attempts to decouple both from Jordan Bancino's infrastructure so that SwerveIO is fully self-contained.

• Removed all methods and classes that were deprecated as of the previous release.
• Removed all kit module constructors that referenced angle offsets, because angle offsets are now handled at the SwerveDrive level using saveAngleOffsets() and loadAngleOffets()
• Merge LogIO directly into the SwerveIO source tree. LogIO is now a part of SwerveIO Core, instead of being it's own artifact. The package name will stay the same and this change will be reversed if LogIO becomes needed for future projects.
• Update dependencies:
  • Gradle: 7.0 -> 7.0.1

6.1.2

This release doesn't make any changes directly to SwerveIO; it is simply a dependency update:

• WPILib: 2021.2.2 -> 2021.3.1
• Gradle: 6.8.3 -> 7.0
  • JCenter is being shut down, so now certain dependencies are loaded from Maven Central.