OK, here's the second part, asking for specific criticisms.
Firstly, I apologize for using the term "mess". I admit that it's not specific. I'll try to correct that here.
There are two general problems that apply to the whole FRC software experience. Again, this is from a rookie team's perspective.
The first is way too much unnecessary complexity. Though this may be difficult to quantify, my subjective feel is that the FRC software is roughly 2 orders of magnitude more complex than it needs to be.
The second is very poor documentation. The documentation that is available doesn't show up on google searches, there is no detailed documentation in the kit of parts, nor a list of links to online documentation. Neither is there links to, for example, this chat room. The only resource that seems to show up on google searches is the Chief Delphi site. Everything else appears to be carefully hidden. It very much comes across as "that's for us to know, and you to find out" kind of attitude.
As to the complexity, a good counter example is the Arduino. The experience using the Arduino is that it very easy to quickly get it up and running on any platform. The IDE is very easy to use. It is extremely easy to program. In short, it's FUN! The FRC software experience is quite the opposite on all levels. From our team's experience, at the beginning of the project, when asked what part of the robot they wanted to work on, nearly all of our (~8) students said "software". Even though we had our software ready, but the robot not completely built by bag day, only one of our students was still interested in software at the end of the build. What the other students saw was that the FRC software is complete can of worms that they want nothing to do with. Even moving to the new Python environment, which I think is two orders magnitude easier to use, they are still very reluctant to have anything to do with software. The 2013 build season left a very bad taste in their mouths.
Let's compare FRC to the Arduino:
- Arduino runs on any platform. FRC only on Windows.
- Arduino installs easily and works straight out of the box. FRC seems to take the attitude that "we gave you this grossly underpowered Classmate computer, so we don't need to write documentation and you're on your own if you want to install this on a reasonably capable computer". The FRC software is very brittle. We'd bang our heads against the wall to get it running on one of the school's laptops and think we had it figured out; only to find when we tried to install it on one of the student's laptops that there were very subtle differences between the two laptops that would cause it to fail on the second machine. So back to banging our heads against the wall. 64-bit vs 32-bit, Windows XP vs 7, firewall settings, etc, etc. Time and time again when the software mentors (myself being one of two) thought we'd show the kids how this or that worked, we'd discover that the software was broken again and would take the whole class period to get it back running so that we never managed to walk them through it.
- We chose Java, thinking that would be the easiest programming language for the kids to pick up. None of our kids had any prior programming experience, so the three choices of programming languages, all being complicated languages, is a real barrier to actually teaching these kids how to program. It's just way too complicated. Unnecessary protected/private/public, all of the java boilerplate code, all of the synchronization logic in nearly every WPILib class, so that we can't really show them that code as an example. The IDEs for all three languages are all very complicated. Bring any of the FRC IDEs up, and bring up the Arduino IDE side by side. You're going to be writing 50-100 lines of actual executable code. Which IDE would you like to train a brand new programmer on? Here's our code statistics for the java program that went to the 2013 competition: 18 source files, totaling 1058 lines of code. Going through this code quickly, there are about 78 lines of code directly related to telling the robot what to do. The remaining 980 lines of code are object initialization and boilerplate. Comparing this to the Python version of the same program; we have 1 source file that is automatically generated from a programming UI. It has 329 lines of code, of which 35 lines are directly related to telling the robot what to do. The remaining 294 lines of code were generated automatically (to initialize the 20 RobotLib objects and 4 constants used in the program), so that the student's only need to write 35 lines of executable code to duplicate what we took to the competition. Even if this code size triples in later years to 100 lines of code; do I really need NetBeans or Eclipse to manage 100 lines of code? The Arduino IDE manages 100 line programs just fine. So that take-aways here are:
- The all of these IDEs are far, far more complicated than what's need to manage 100 lines of executable code.
- All of these programming languages are far more complicated than what's needed to write 100 lines of executable code.
- I agree that these kind of tools are required for large projects with > 20 developers and several hundred thousand lines of code. I've worked in those environments. But these robot programs are three orders of magnitude smaller than what these tools were designed for and make the programming task much more laborious and error prone than it needs to be.
- Again, comparing to the Arduino, they choose C++, a very complicated language. But then they went through each and every language feature and asked themselves: "Do we really need this feature to write Arduino programs?". Pointers? no. References? no. Public/protected/private? no. Virtual functions? no. Abstract classes? no. New/delete? no. So they managed to greatly simplify the language by very deliberately avoiding 80% of the language that they really didn't need for these kind of projects. (I might add; I'm very much more impressed with the programming skill exhibited in the Arduino libraries than the WPILib; it's not easy to make things that simple).
- The WPILib is again a study in complexity. Where's the documentation? Who knows? It's not in the kit of parts. It doesn't come up on google. All that is available is a few very high-level overviews. So we look at the code. What's all this synchronization code that is EVERYWHERE in the WPILib? When is it creating threads underneath my code, so that the code I write will be running in multiple threads? How am I to know what parts of my code need to be thread safe, and what parts not? No mention of where threads are used, or thread safety anywhere. Again, "it's for us to know, and you to find out". As an example, the RobotLib encoder class in Python is 103 lines of code compared to the WPILib C++ Encoder.cpp of 548 lines code. The Python version reports motor rpm, %no_load rpm, vehicle distance traveled, vehicle speed and direction of rotation. The WPILib version reports vehicle distance, vehicle speed and direction of rotation. The Python joystick_button class is 121 lines of code; WPILib Joystick.cpp is 302 lines of code. The Python version will run functions or launch tasks when a button is pressed or released, optionally kill the launched task when the button is released can be activated or deactived. Again, more functionality with far fewer lines of code.
- The final point is the operating system. I would ask whether we really need an operating system. Again, to compare to the Arduino. And if so, does it have to be one that there is no documentation on (again, google searches come up empty; no operating system manual, or even links to online manuals in the kit of parts -- another example of "that's for us to know and you to find out"), and no public forums to get information or questions answered?
The documentation, I think I've covered. Nothing comes up on google searches. Most of the programmers that I know go to google for everything. Even if a site has its own search capability, they've learned that the google search is far better at finding the answers than the search engines used by any of the sites. So you just go to google for everything. It will find the source documentation, related forum discussions, you name it. This works for all of the software packages I use. It works for the appliances in my house. I can google my washing machine and get any information I want. But I can't google the FRC software. The documentation is not online in any public form that google can index. This forum is not publicly available for google to index. The vxworks documentation is not publicly available. I have no idea if there are vxworks forums. If there are, they are not indexed by google. The only thing that we have is Chief Delphi. Why, because another team set up a publicly available forum for us. Why couldn't National Instruments do this? Nothing comes in the kit of parts. No printed manuals. No CDs. No list of links. Good luck rookies!
Recommendations:
Simplify, simplify, simplify. Simple is FUN! Complicated is tedious and error prone. Use simple programming languages that have some support for simple co-routines so that you don't need the synchronization logic. You don't need the formality of trying to protect code from unknown idiot developers with these small projects. Use simple IDEs. Greatly simplify the WPILib. Using a dynamically typed programming language helps a lot to simplify the code. Our RobotLib sends all of the robot's sensor readings and actuator settings for each driver station packet over a TCP connection to a program on the PC that writes this information to a .csv file. The .csv files for every run of the robot are put into a mongo database, so that we can store every sensor reading and actuator setting for every 20 msec that the robot is ever turned on. We use ipython, pandas and matplotlib (these are an integrated toolset written in Python) to mine this data for information. Unlike the Network Tables, where certain information is flashed on the screen and then forgotten, we keep all data for all runs, permanently. This has already been a big help to understanding how the robot accelerates and decelerates. You can see the exponential motor braking curves, and see how the remaining stopping distance is directly proportional to the speed of the robot. You can find out why the robot acted funny, after the fact without having to enable any debugger and without having to reproduce the problem. And there are no options to select about which data to capture. It simply captures everything. All of the time. So the RobotLib programmer doesn't have to concern themselves with this feature. It's just built-in. You get it for free.
Our programming UI is something like the robotbuilder program, except that all programming is done through the UI. The generated Python program is treated as an object file that the programmer doesn't have to look at or understand. If any change is made to the program through the UI, it has all of the information that it needs and simply regenerates the whole program. Much simpler than the robotbuilder model of generating complicated template files with "insert your code here" comments; which forces the programmer to wade through all of this generated initialization and boilerplate code to find his 38 lines of code. And, guess what, the robotbuilder doesn't work. It doesn't generate legal code. Why? Because it's too complicated.
Other suggestions:
Make your code open source. Making a zip file of the source code available isnot open source. Open source projects not allow anybody to get a copy of the source code, but also allow anybody to contribute changes/fixes/enhancements back to the project. I'd recommend using the mercurial source code control system over git because mercurial is about an order of magnitude simpler than git:
$ git help commit | wc -l
433
$ hg help commit | wc -l
41
Also teams should be able to fork the project without getting any permission from you to do so. They can then make their forks of your project available to other teams and everybody benefits. There are enough teams out there to make this work.
Same thing with the documentation. Put it on a wiki. Don't require any sign on to view this, so that google can index it. I hit a problem with the documentation explaining how to set up the electronics on the robot. We weren't getting any voltage reading on the Driver Station. A mentor on another team pointed out that a jumper is required on the Analog Extension board. There is no mention of this jumper in the documentation. Had it been a wiki, I would have fixed this so that the next team doesn't fall into the same hole. As it is I have no idea of who maintains this documentation, or how to contact. All "for us to know, and you to find out".
Well, that wraps it up. Hope this helps. If you're genuinely interested in profiting from any of this and need more information, I would be happy to help.
