WPILibJ is a library used for FIRST robotics code when programming in Java. Helping the Stuypulse team gave me the opportunity to look at some of the code. In honor of ship date this year, I decided to blog some thoughts on the library. You can see the JavaDoc to follow along.
Good design point #1
The class names have strong ties to the “business.” Class names like Joystick , DigitalInput and SpeedController are very clear and provide a mapping to a good concept. They also encourage good object oriented code.
Good design point #2
For the most part the documentation is good and the classes logical. Many classes have useful comments and tips on usage.
Good design point #3
There are patches released through the competition season. Care is taken for changes to be backward compatible and not break existing code. Much appreciated on a six week project.
Surprise #1
In the Image class, care appears to be taken for immutability (classes that cannot be changed.) It has a package private constructor. Only getters are provided. The object can be written to a file, but you need to create a new object if you want to read from a file. Then comes the surprise. The image instance field is public! And that public field is of type Pointer – a wrapper to native memory. Eek. Memory leak if you mess with it without being careful?
Surprise #2
The CANJaguar class had the biggest surprise. When you instantiate an object, you pass the control mode. Straightforward. I expect the code to behave differently when different modes are passed. Then you try to call setVoltageRampRate. The JavaDoc clearly states what it does:
Set the maximum voltage change rate. When in percent voltage output mode, the rate at which the voltage changes can be limited to reduce current spikes. Set this to 0.0 to disable rate limiting.
Then there is what it does in reality. If the control mode is kPercentVBus or kVoltage, a formula is used to set the ramp rate. For the other three modes, the method does nothing. That’s right nothing. It doesn’t throw an exception or set it to zero or log an error or anything. Which means you don’t realize it doesn’t do anything without reading the code.
Surprise #3
I can’t really call this a surprise as I’ve known about it since beta testing. But I was surprised then. Last year, there was a Dashboard class for custom output. It was hard to use and they added a SmartDashboard class this year. And logically, they added an interface IDashboard for the commonalities between them. There aren’t many commonalities, but that’s not what I find surprising about the interface.
To use the old Dashboard, you write:
Dashboard d = DriverStation.getInstance().getDashboardPackerLow()
d.addXXX();
To use the new SimpleDashboard, you write:
SmartDashboard.init();
SmartDashboard.logXXX();
That’s right – the new one uses statics. This is where the interface becomes confusing. If we are calling static methods, an interface doesn’t make sense.
The worst bug
The worst bug we encountered wasn’t actually in the WPILib code. It was in the underlying National Instruments code and affected all three wrapper APIs (Java, C++ and LabView.) The Encoder class works in an illogical manner. In particular, it only lets you use the first, third, fifth and eighth encoders to get the rate of movement. (No, that isn’t a typo. It is a seemingly random collection of orders rather than every other.) That’s if you are in one mode. In another mode, the working encoders change. We have to fool the low level code by creating dummy ones to the “real” encoders get the proper constructor call ordering. While this was documented on chief delphi (the unofficial FIRST robotics forums), we wasted a lot of time assuming we were doing something wrong.
Conclusion
The longer text for the surprises doesn’t mean that the code is bad. Just that there is more to write about unexpected things. All in all, I appreciate all the API gives us. Congratulations to team #694 (Stuypulse) on a great build season and for completing an awesome robot on time!
