Here is a document that provides step by step instructions to write JAVA code for basic gamepad driving, basic autonomous code (shaft encoder, gyro, rangefinder), and LED lights. This document supports the WPI2 library and the robotContainer.java file.
This is complete re-write of a document which we use for new programmers to give them early success in writing code.
All feedback is welcome.
Team 1895, Lambda Corps, Manassas, VA
Out of curiosity, what encourages teams to use your PDF over the frequently updated frc-docs? I noticed several bad practices in your PDF that shouldn’t be encouraged. Is this mainly for members of your team or actually meant for the general public.
Here are a couple of issues with your tutorial besides the above
Numerous grammar and spelling issues
Several bad practices are encouraged here. I’d rather teach how to learn to code, and not how to copy code.
I wouldn’t recommend using the online method of importing dependencies, as it’s not as flexible as using the vendor provided installers. This allows you to easily manage dependencies offline and between projects.
Your wrapping the raw Joystick interface, but WPILib (not WPI2) offers a Gamepad and XBoxController classes.
Your declarations are quite confusing on where they are initialized leaving the viewer likely to create null pointers.
And more, I honestly couldn’t get much more than skimming due to the formatting of the document.
I understand your hard work for putting together such things. Might I interest you in contributing to frc-docs? It’s not difficult and we need great individuals to write articles.
I disagree with this. Using the online dependencies is really nice because it allows Gradle to handle them easily. By using these I can have a robot code repository that is git friendly which can be cloned and easily setup in 5 minutes without having to run any WPI installers. I didn’t even have VSCode installed on my computer this year.
You could argue that for beginners using the offline installers might be better, but I think having reproducible builds is really important so your team can use multiple computers without having to run a bunch of installers if you need to switch computers for some reason. Also, I’ve never had the problem of Gradle randomly requiring an Internet connection like some have claimed.
Either method gets you a repository that can be cloned and have reproducible builds. If you choose an online install, the vendor library json file is downloaded from the site and copied to your project. If you choose offline install, the vendor library json file is copied from your hard drive to your project. The contents of the vendor library json file are identical.
If you do an offline install, the library is cached on your hard drive so it doesn’t need to be downloaded the first time you build.
If you do an offline install and then someone clones the repository, the next time they build it will download the library.
The behavior is identical for an online build except that dependencies are cached on first build in either case in that scenario.
I’ve personally never seen the point of the JSON vendordeps system as it seems like a needless abstraction over Gradle’s already excellent dependency management. Why are vendors not just publishing simple Gradle plugins to add an easy way to pull in their dependencies?
The main reason to not use plugins is Gradle build files are not machine readable. So manual parsing would have to be done to have a UI to add and remove vendor libraries, and then hope we get it right. Since the Json files are separate per vendor, we don’t have to worry about the parsing problem at all, and users are not expected to know how to modify a build script file or what exactly to modify.
Remember, most teams have 0 knowledge of what a build system is, and we have to have a UI and easy abstractions for everything in the build system. It needs to be transparent to our users, because we don’t want it getting in the way of teams getting code running.
Also, the Json files really are not that much different then what a custom plugin per vendor would give. Behind the scenes it’s still using gradles dependency management, it’s just an easily parsable way to add new dependencies.
Finally, the behavior is not identical between online and offline installs. Back in 2018, Gradle made a change where they started removing unused artifacts from the local cache if they have not been touched for 30 days. An online install causes artifacts to be put in that cache, putting them at risk of being deleted. An offline install puts the artifacts in a special cache we made that is never subject to that deletion policy.
I definitely echo above - the document focuses strongly on the “what”, rather than the “why”. This is good if you have folks coming in who already know the basics of how to design software and control systems, but aren’t yet familiar with the FRC ecosystem of tools and API’s.
Poking a bit at @Daltz3’s comment - Definitely agree - to produce this topic for a wider audience, definitely consider making PR’s in the frc-docs repo. Over the past two years it has definitely become a central repository for stuff like this. I still owe a PR with the PID simulator stuff I’d put together a while back.
I think I kinda disagree too. My blue dot goal every year is that students should be able to take a “blank”, fresh windows install, clone the repo, click “deploy” and get the latest code built and onto the robot. Any extra step has to be documented, and is undesirable. From that perspective, being able to fully define all external robot library dependencies in Gradle or some JSON abstraction of it was my second favorite thing of recent developments.
Additionally, I want to have the ability for a student to do an activity where they update the version of a library, fix any code incompatibilities, test, and push their changes… and then are done. Everyone who subsequently picks up their branch or a merged version of it gets the updated library. The worst-case scenario is having to go to every development computer, un-install and re-install a tool to a later version. That’s an utter waste of time, and about the last thing I’d want to be doing during the season.
Above and beyond this, since internet connectivity is not guaranteed, a local cache system works fine by me. I need to go research how to create a “mini-maven” instance on a usb drive, such that we can ensure that in case a student blasts away their cache during competition, we won’t be left high and dry being able to build the content. But that’s the pathological case. The vast majority of builds are done at our warehouse, where internet exists.
TL;DR - The Robot Code’s API’s and dependent libraries need to be described machine-readable format, and be archived at network-accessable locations, but with some provision to allow builds without network.
Separately, for vendor-provided tools, I’m fine installing/uninstalling these. No need to bloat the robot codebase with anything not required for building robot code. If all of them built in an auto-updater, even better in my mind.
There’s nothing special about the offline maven repo, it’s just a folder. Go into C:\Users\public\wpilib\2020 and copy the maven folder to a flash drive. If a user blows it up, just copy it back. You could also add the flash drive directly as a repo manually in build.gradle, but I wouldn’t recommend it for a few reasons, mostly performance, and some bugs in Gradle that could be triggered by having a half working local cache.
What i appreciate about this document is that it provides a single end-to-end place to see the whole process for getting started with robot code, presuming that the robot is wired & RIO is imaged. That isn’t obvious on frc-docs.
@Daltz3, do you think you could re-name the link “Getting Started with a Benchtop Robot” to something more like “Hello Robot”? Programmers would get that. They have no idea that “Benchtop Robot” is meant for them.
Looking back on my original message, I realize that the tone of it is a bit harsh. Your effort in creating this document is enormous and it definitely has numerous great points. Your document goes into CTRE motor controllers, something that frc-docs unfortunately cannot do.
My original intention was to portray a couple of issues and point you in the direction of contributing to the FIRST documentation. The documentation team really is comprised of roughly 4 core contributors, so individuals like you writing articles would be a fantastic boon!
Thank you for the feedback on the process document. I’ll work to improve it over time.
My motivation for the document is to support “rookie” students. I have found that students like to see immediate gratification, like a robot moving in a short time. Our team starts recruiting in the early fall to start building skills. This document provides a way for the students to work independently and have one of our simple, practice robots moving within an hour. Once the robot moves, they get a BIG SMILE on their face and their hooked. The FRC documents are great but our students don’t have the patience to read the 241 page “Getting started” or the 1023 page “FRC docs”. Once their hooked, I refer the students to these documents or the numerous FRC-related YouTubes on the web.
We have been considering rewriting the getting started section to be more cohesive and relevant for some time. I recently opened an issue in the frc-docs repository that way it’s a higher priority. Hopefully the changes will be more useful to rookie teams.