WPILib as volunteer-run project

The problem is that we barely have enough volunteers to document and maintain WPILib. We absolutely do not have the resources to update/maintain our examples and use-case documentation to work with all CAN motor controller APIs as well. We can’t just document one and be done, as that shows vendor favoritism. And vendors like to fully own their documentation to guide people through their custom tools, unique API approach, sister products, etc, in a way that’s incompatible with a multi-vendor single site. One approach could be to have greater cross-linkage between the various doc sites, but that comes with its own UX downsides.

23 Likes

This season I sat down to try and sort out how to modify and deploy code to a robot in the vain attempt to support our programmer(s). I spent several hours reading, trying, and failing.

I know I’m just a dumb ole mechanical guy, but the whole process felt nigh unapproachable.

A refocus or priority from new and changing features to volunteer recruitment and documentation/accessibility might be the best way to serve FRC as a whole.

12 Likes

Note while we can and do set broad project priorities, we can’t simply direct our current volunteers to work on documentation instead of code, people are going to contribute and spend time where their interests are. We also have a fair amount of volunteers regularly going inactive due to life changes. And we have major upcoming changes that are required and will consume a lot of the team’s time and energy (the 2027 control system change).

So yes, we really need to recruit new volunteers for all aspects of the project, but that call typically goes out to deafening silence, particularly on the documentation front. Speaking for myself, my involvement in WPILib came out of doing control system beta testing and a personal motivation to “scratch an itch” and fix things, not being explicitly recruited to do it. What we need is folks who care enough about fixing/improving documentation to spend many hours of their free time doing exactly that—the door is open to make a positive impact on the entire FRC community!

One of the challenges is we actually have too much documentation—there’s so much that it’s hard to find stuff and it makes it a very big project to reorganize it to make things more approachable. If someone reading this is interested in taking ownership in this area, please reach out!

5 Likes

Agreed; paid workers should take up the slack in areas that self-motivated volunteers aren’t interested in covering as a donation of their time and talent. This pattern matches various other aspects of FRC (e.g. Senior Mentors receive stipends to participate in marketing and outreach events to grow the program).

5 Likes

Just a note that there are no paid workers on the WPILib development team—it’s effectively entirely volunteer for all of the major contributors. There is also no current funding source/model to pay anyone. WPI has generously covered some travel expenses for manning the WPILib booth at champs the last couple of years, and has donated some of our server hosting, but that’s not the same as paying people for development or documentation work. There are a couple of paid people in oversight/interface roles, where WPILib is just a very small part of their overall job responsibilities—Amanda is a WPI employee involved at a top level with overall project direction/goals and Kevin is a FIRST employee who occasionally works on critical documentation and reviews major changes for consistency with FIRST requirements.

In the past, there have been some summer WPI student contributors and I think they might have had small stipends, but it’s been several years since the last one of those. FIRST had a summer intern one recent year that worked on a bit of documentation. We are hopeful that at least we may get more summer student contributions again in the future. One of the challenges with summer students is ensuring adequate supervision and mentoring; our adult volunteers are generally willing to provide that but it needs to be structured a bit better than it has in the past I think.

5 Likes

I was a new-in-March mentor this year and I felt like the quality (including quantity of examples) of WPILib docs was quite high, especially as compared to actual, sold commercially software that charges large sums of money for licensing and “we recommend professional services to help you implement”.

Is it perfect? Surely not, but I felt like it was way better than I expected it to be.

13 Likes

Id love to contribute to WPILIB’s, how do I sign up/ get started?

1 Like

Great! The best way to get started is to engage via GitHub and/or on the unofficial FIRST Discord’s programming-discussion channel, which mostly serves as an informal public discussion channel for WPILib development. For specific projects, there are many open issues and project boards on both the frc-docs and allwpilib GitHub repos, but it’s often good to just chat about the kinds of things you want to work on and make sure we are in alignment and you’re not unknowingly duplicating work someone else is doing. We have a number of issues on GitHub that are labeled “Good first issue” that are more low-hanging fruit to get started and familiar with the process of contributing (e.g. building locally, opening a PR, etc).

12 Likes

That’s awesome, Ill take a look into it all when I get home, Ill probably stick more to the frc-docs side of things for now.

2 Likes

I think the WPILIB documentation has been decent, I’ve seen a lot worse. But this again highlights the point that FIRST has a sustainability problem.

WPILIB is a critical resource, and documentation challenges disproportionately affects young teams.

6 Likes

The amount of free labor that has gone into WPILib is staggering and unfortunately there’s no way HQ could afford to pay the majority of the team at market rate.

One of my current interests is trying to figure out how to leverage some of the work put into WPILib for things other than FIRST, because the code quality is so high.

11 Likes

I think this highlights a lot of the gripes I’ve seen about WPILib in various private chats. If WPILib is such a critical resource and, at this point, completely integral to FRC, why is it still a fully community/volunteer driven effort?

Through the lens of a standalone open source project, I don’t think anyone questions that WPILib has grown into quite a high quality price of software. It has made advanced concepts like path planning and following much, much more accessible to more teams. I think the software capabilities of the certainly the median team, and maybe even the 30th percentile team are much much stronger than they were a few short years ago.

That being said, I think we are leaving the 0-30th percentile teams behind. WPILib has gotten much too complex for teams that, frankly, have no idea how to program. The problem is that:

a. Writing an API to be effectively used by people that barely know how to program is really, really hard.
b. Developing an API assuming a very, very low level of user knowledge is probably a frustrating experience.
c. The design decisions that lead an API to being code blocks level of simple probably fly in the face of good software engineering practice and make it hard to create something that is also flexible and powerful enough for higher level teams to use.

Maybe at one point LabVIEW was what was supposed to serve this segment of the FRC market, but I don’t think it ever did a great job of it and at this point has fallen hopelessly behind.

If WPILib continues to be a fully volunteer-driven effort, it’s no wonder that this segment of the market is underserved. It’s frankly not something that many, if any people who want to do open source development would be motivated to work on. This is not the fault of the current volunteers, but a byproduct of the incentives of WPILIb’s current development model.

Given how critical WPILib is to the program, it makes sense to me that HQ should put more money and personnel directly towards it, and someone paid by HQ should take a supervising PM role for the project. That being said, if a lot of the development is still done by volunteers, you can’t really force them to work on things that they don’t want to work on without compensation.

15 Likes

WPILib offers many advanced features, yes, but that doesn’t mean the “basics” have disappeared. You can still drive a (PWM) motor controller with a joystick with just a couple lines of periodic code, or a tank drive robot with less than 5 lines of code. Those same WPILib library classes that existed in 2009 for joysticks and motors still exist today, it’s just that in the last few years, teams have transitioned to vendor-specific CAN motor controller APIs which are more complex to use and have a higher barrier for entry (and more complex setup), because they’re more complex devices with many more features. Simultaneously, the broad floor of FRC robots have grown in complexity (how many robots, even in the bottom 30%, are still doing tank drive? How many are using PWM motor controllers? How many are still doing “drive forward for 3 seconds” auto modes?). Swerve in particular demands greater software complexity–how many of those bottom 30% teams have a mentor that buys/builds a swerve base without considering the programming complexity of swerve? WPILib also needs to help serve the needs of those teams.

There are many tradeoffs here… for example, WPILib’s command-based programming has a somewhat higher barrier to entry than pure timed robot, but once learned, those bottom 10-20% teams can actually create a more sophisticated auto mode rather than being “stuck” when they want something more than the bare basics.

WPILib has never offered a “blockly” type development environment where no coding experience is required. WPILib started as a C++ library; Java was added later. The closest thing WPILib has to a guided “build your robot program” experience is RobotBuilder, but very few teams use it (a few dozen), and it just generates the robot structure, the actual code was always something teams had to write. RobotBuilder 2 (currently in early development) may be closer to what you’re looking for, in that it’s less focused on robot structure generation and more on guided writing of individual subsystems.

One of the benefits I’m hoping for with the 2027 controller change is bringing the FTC development team and WPILib development teams together and hopefully finding the best of both worlds. FTC does provide an on-robot blockly style development environment (On Bot Java) and we know that’s going to be important to FTC teams, so it’s a must-have there, but that doesn’t mean that it can’t be used by the lower percentile teams in FRC as well, since the controller and software stack will be common to both programs.

9 Likes

100% agree with…except I think the number is higher than 30% at the high end.

If we’re to follow through on “the homework”….

We need to rethink everything on how FIRST is funded and operated. The current model isn’t sustainable and certainly isn’t setup for massive growth.

2 Likes

Especially after the kitbot (and it’s associated code) was done this year, I’m not sure I agree with this at face value.

Do you have more on what you see missing? Are you saying there’s a need for WPILib to be the way that students learn the toolboxes that the programming languages themselves provide? Or guides on how to break down large programming problems into smaller ones?

3 Likes

Notably for this discussion, the kitbot code is a case where a paid FIRST employee did the work of writing and fully documenting it (while being built on top of / based on WPILib’s examples and docs), so it perhaps proves the broader point?

1 Like

I will say I’m mostly paraphrasing concern’s I’ve seen repeatedly brought up in other forums; I haven’t been on a team at this level and Indiana being such a small district means there’s more support for the bottom tier of teams than other areas.

I will quote the post that sort of started this tangent that eventually caused the split thread:

I’m not sure documentation is the solution here, but I think the underlying concern is valid: there are teams that simply do not have anyone with any amount of real programming experience and the current implementation of Command-based WPILib projects is jumping into the deep end a bit too fast.

I see concerns like this as well:

I think many who frequent this forum know that JCH is a talented engineer in his own right, and if he can’t figure out the basics, I think that’s a sign that there is a bit of a usability problem.

It’s hard for me to point to specific issues because, as a software engineer, there’s a lot about WPILib that does just make sense to me. Something I’ve seen transitioning between the software and the business world is that tooling built by programmers often just makes sense to other programmers. And it’s not that other people are completely lost on it, but it takes them considerably longer to come up to speed.

If someone asked you or I how to deploy code to a robot, I’m sure we’d both point them to the appropriate docs page/quick start guide. If someone came to us and said that a team was brand new to programming and struggling with the OOP aspects of Command-based, we’d know to inform them that TimedRobot exist and may offer them a simpler, albeit more rudimentary framework. I’ve just heard enough concerns from people I respect that the teams who need that guidance don’t often arrive at those solutions on their own. Figuring out why is not a trivial amount of work, and is the type of work that is hard to find someone to accomplish in an open source project.

FRC should be accessible to teams who have little coding experience or knowledge. One solution is for there to be built-in resources in FRC to get students/teams up to speed on programming enough to utilize the current tools, but this is more or less “teaching a student how to code”. There are thousands of other organizations, programs, etc. that tackle this problem in a more targeted manner than FRC. I don’t think reinventing entire existing curriculums plays to the strengths of FIRST.

The other solution is that there is some sort of greatly simplified framework to be accessible to these teams. I don’t know what the right solution is, but it seems like it’s somewhere on the spectrum between FTC’s On Bot Java and TimedRobot (with RobotBuilder being somewhere in the middle).

The lack of vendor code in examples really hurts teams. Even low level teams are almost all on CAN motor controllers. I know the vendors have and update their own examples. I know WPILib can’t control vendor API changes. I know that maintaining examples supporting all vendors is an unreasonable amount of work for the current volunteer base and that only supporting some vendors is favoritism. All that being said, the current status quo is still woefully unpragmatic and makes the team experience worse. I don’t have hard numbers but I will go out on a limb and say that REV and CTRE make up the large, large majority of motor controller market share. Having REV and CTRE vendor code in the examples would make life easier for teams.

7 Likes

The thing is, all examples (as far as I can tell) use motor controllers which implement MotorController. Both CTRE’s TalonFX and REV’s CANSparkMax implement MotorController, along with basically any other motor controller you’d use. Then it’s just mostly a drop-in replacement. This is why the interface exists; it makes it easy to use any motor controller because they all have the same API contract.

This feels like a dogfooding problem.

Most of the people who are writing the docs are likely people who are interested in programming… and as you point out they’re more likely to understand the docs because that’s the perspective they’re written from.

What we need are more non-programmers trying to do the various tasks, then updating the documentation based on what they found confusing. Even better, pair people who know what they’re doing with non-programmers to watch what mistakes they make and update the docs according to that.

3 Likes

One experience I did have as a student trying to start working on docs for wpilib-docs was getting my (relatively small) change stuck in a PR without a clear path forward once the reviewer stopped responding to me. This did somewhat stifle my enthusiasm for working on wpilib-docs (not to disparage the all important review process, but waiting a few months for a re-review is not very fun).

2 Likes