As most of you hopefully already know, WPILib provides an array of example projects to give teams a reference for how to program various types of common mechanisms and behaviors for their robots.
These example projects are super valuable - but, as you can probably tell from a quick glance at the link above, they are also somewhat disorganized and there are too many of them.
I’ve been pushing for a consolidation/removal of outdated examples for a while now. With the major changes to our recommended usage patterns for Command-based from 2023 onwards (see the Rapid React Command Bot example if you’re unfamiliar), many of the old Command-based examples no longer reflect what we consider best-practice usage of the framework and are likely to mislead teams more than help them.
However, removal of example projects can’t be done lightly, because we do not want to lose “feature coverage” by removing the only example showing how to perform an important functionality.
In service of this, I’m making this thread to get some feedback on which example projects teams have used the most. Please respond below listing which example projects you’ve found important, and whose content you want to make sure is preserved in any pending consolidation work.
Feel free, also, to reply with any suggestions or concerns you have regarding such an update to the WPILib example project list.
Which content in the HatchBot examples, particularly, do you find most-helpful? Is it the side-by-side comparison of two different usage patterns, or the choice of mechanisms that those projects include, or something else?
Every year I see rookie teams show up to competitions with drivetrains that do not have external encoders wired on their drivetrain. There should be a basic example of a autonomous movement routine using time based movement. If there is one already, I can’t find it.
This one exists. I just think one should also exist for command based.
I used them as a template for structuring season code while learning the command based model. While the default project templates are nice, they’re barebones compared to season code in my mind. It was nice to be able to compare my code with a “complete” project and get a sense for if I was doing things the right way.
Have you checked out RapidReactCommandBot, linked from the OP? It was intended to be a direct replacement for that purpose - it shows a similarly-scoped robot, but with a more modern usage pattern.
I think you’ll find that the Promise-like chaining syntax is way easier than using Command classes, once you get past the initial unfamiliarity. It also reads almost like English, if you do it carefully.
The inline/builder approach has some advantages, but some people do find the full class-based style to be more discoverable/maintainable/teachable and I see it as an equally valid way of programming a robot.
One of the powerful things about WPILib in general–and this applies to the command-based framework as well–is it is multi-paradigm, and allows implementing robot code successfully in different ways (eg periodic or command based, command classes or builders, running motors from commands or from subsystem periodic). I think having full robot / complex auto examples coded in different styles would be best to help give teams examples of the different ways of solving the same problems so people can compare the approaches themselves and pick which one they feel most comfortable with.
I think the biggest improvement we could make to examples is clearly categorizing them (e.g. when teams select one to create) into broad groups, e.g.:
Single device examples (here’s how to hook up to a gyro or motor controller)
Single mechanism examples (here’s an arm/elevator/intake, or different drivetrain variants)
Whole complex robot examples (here’s what a whole robot program looks like, including auto modes, for the various programming styles, including variants of command based)
The first group can use a simple periodic structure. The third group is showing the different structures. The biggest challenge is the second group. Because to avoid a N * M problem, you have to pick a programming structure, and that’s tricky because teams are definitely going to use one of the drivetrain ones as a starting point for their whole robot program. I’m not sure exactly how to solve this (split drivetrains out and accept doing the N * M thing for those?).
I agree that documenting a few different design patterns, with examples, would be super helpful. I think the “servo” (Subsystem periodic does most of the work) style in particular is underappreciated.
Peter I think the N * M thing you raise touches on an issue that we’ve struggled with a bit, which is composability. What’s the best way for a student to work on a small separate project for awhile, focused on a particular technical problem, without involving the whole code base? And what’s the best way to reintegrate this work when it’s ready? I think if there were a good answer for that, then you could use that solution for the examples.
When you give people (students) with limited experience multiple choices they often won’t be able to pick the one that is actually best for them in the long term. Having multiple examples is fine but they need to come with strong recommendations on which is the path of least resistance for most teams and the one that will be easiest to support when teams run into problems.
Theoretically each subsystem could use a different structure, but that’s a maintenance challenge post integration. It’s much better to picks structure, and have the separate developments follow it for consistency post integration… but doing that across the mechanism examples creates the N * M problem if we want to support teams doing this for any of the potential code structures they might use.
Good point from both a documentation and support perspective. We could clearly label a specific framework as “(recommended)” and set up the documentation to guide people into it? I just worry about giving people no examples of the traditional class-based commands (as an example) when some people will really want to go that path, even if our recommended approach is builder based.
I don’t object to keeping a class-based example around for historical purposes, but I really feel that the only people strongly preferring it at this point are veteran mentors with a heavy familiarity bias.
The more modern API pattern is visibly easier for students to learn, especially for those without substantial practice with OOP features. It’s also much closer to what they’re likely to encounter in industry.
I totally agree it’s useful to do a cross-comparison of a class-inheritance-based representation of a simple robot, and a functional composition representation of the same. I think the default for the rest of the command-based documentation should be the latter pattern, though - there isn’t a need to cross-represent every bit of content.
Yes. Please keep examples of Command classes, and not just for historical purposes.
The fluent style is convenient and quick, but for students it’s definitely introducing “magic”. Writing complete classes teaches the full capabilities of Commands, and how the actual command mechanism works.
I strongly disagree. There’s nothing more or less “magical” about the functional representation of the same set of semantics. The point of all of this is not to learn Java in particular.
Having taught both to students ranging from complete beginners to experts, I have not encountered a single situation where a student learned faster in the OOP-centric model.
Yeah, I think you’ve found a key issue: for us, the point of all this is definitely to teach Java in particular. it’s the language used by the school CS curriculum. You can think of robotics as an extended CS lab. I want the students to become experts in Java in particular so they can contribute at a high level to any part of the code.
it’s the language used by the school CS curriculum. You can think of robotics as an extended CS lab. I want the students to become experts in Java in particular so they can contribute at a high level to any part of the code.