FIRST Robotics Competition Discussions

cancel
Showing results for 
Search instead for 
Did you mean: 

Where is the documentation on low-level C++ routines?

In the WPILib for C++, there are two directories: NetworkCommunications and ChipObject that only contain header files.  I'm trying to write routines to call these and would like the documentation for these routines.  Where can I find that?

0 Kudos
Message 1 of 12
(7,966 Views)

There is no public documentation for these methods.  The best documentation you have is to look at how WPILib uses these entry-points.

Just curious, but what is your goal with calling these functions directly?  Is WPILib too easy?

0 Kudos
Message 2 of 12
(4,655 Views)

That's what I was afraid of.

IMHO, the WPILib is a mess.  We're taking on RobotPy, but instead of just wrapping the WPILib to make it callable from Python, we're throwing it out completely and re-writing our own library in Python (called RobotLib).

Our project includes a web-based application builder (something like robotbuilder, but done right so that you can go back and make changes easily) and our own logging facility that logs all sensor and actuator values related to each 20msec DS packet to a mongo database to preserve a complete history of everything that ever happened on that robot.  We're planning on using the Python projects: pandas,matplotlib and ipython notebook to view this log data (I'm just now working on the connection from mongo to pandas to let this happen).

Our code is on google code in two repositories, erl-builder and erl-frc, if anybody wants to take a look.  ERL stands for Easy Robot Language.  The erl-builder project sets up the framework for the programming interface trying to allow re-use for multiple purposes.  The erl-frc is one use; and, for example, erl-arduino might be another use (erl-builder is written in python, but is not limited to generating python code).

2013 was our first year.  I'm planning on keeping our RobotLib very lean, just what we need for 2014, pending the new 2015 control system.  I hope more than anything that the new control system will be linux based.  It would make this so much easier!

-Bruce Frederiksen, mentor FRC Team 4769

0 Kudos
Message 3 of 12
(4,655 Views)

If you have specific questions about a function I may be able to help you figure it out.

Brad Miller and I are always interested to know what people don't like about WPILib so we can make it better for everyone.  What are your specific criticisms, beyong being a mess?

Thanks!

0 Kudos
Message 4 of 12
(4,655 Views)

Your posts are emailed to me.  They include a line at the bottom that says that I can reply to the email to post a response on the group.  The first time I tried this, I got several failed email delivery messages, but it finally went through.  So I assumed that there was a temporary problem with your email server.  I tried replying again to your second post and the emails never made through.

So it looks like you have some kind of problem with your email/forum server that replying to emails of posts doesn't work.  I don't know how to report these kind of problems, so hopefully you can send this to whoever needs to know...

I'll repost my responses through the web interface... 

-Bruce

0 Kudos
Message 5 of 12
(4,655 Views)

OK, sorry for the delay, I've been very busy working on the RobotLib for RobotPy...

In your last post, you offer to help and ask for feedback on the "WPILib mess".  I'll split my responses to these two items to make it easier to track...

So this response is how you might help.  I must first apologize because I don't know who you are or what your area of expertise is, so I may ask questions that you aren't qualified to answer?

  1. My biggest concern with the RobotPy project is that I'll get it working just fine on the lab, but will hit some unforeseen problem at the competition when trying to run it through the FMS.  This could be addtional NetworkCommunication or ChipObject calls that the FMS needs that the lab environment doesn't require, or calls required to meet the FRC rules that the Driver Station application doesn't validate.  Do you know:
    1. of anything related to the FMS/competition environment that could cause us a problem?
    2. of any way to test our system with the FMS/competition environment prior to the competition?
  2. Looking at the available TCP/UDP ports at the competition (from the Arena Game Manual), it doesn't look like the netConsole application can be used during the competition.  Is this correct?
  3. With the new 2015 control system coming out, do you know if there will be some way to get access to this code (perhaps a beta version) prior to the 2015 competition in order to have the time get our project ported over to it?

At this time, these are all of the questions that I have.  I believe that I'll be able to wend my way through the WPILib code to determine how to call the NetworkCommunication/ChipObject functions to get this working in the lab.

Many thanks!

0 Kudos
Message 6 of 12
(4,655 Views)

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:

  1. Arduino runs on any platform.  FRC only on Windows.
  2. 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.
  3. 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:
    1. The all of these IDEs are far, far more complicated than what's need to manage 100 lines of executable code.
    2. All of these programming languages are far more complicated than what's needed to write 100 lines of executable code.
    3. 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.
    4. 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).
  4. 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.
  5. 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.

0 Kudos
Message 7 of 12
(4,655 Views)

A couple more suggestions...

If you feel that you must use vxworks, could you provide an option to use linux?  In other words, in addition to supporting multiple programming languages also support multiple operating systems?  Not all languages would have to run on all operating systems.

Getting the network set up is also a trouble spot.  Is it really required that the robot be on a separate network, rather than connecting to the local wifi?  Maybe the robot could run a simple server that responds to UDP broadcasts with its DHCP assigned IP address?  The UDP broadcast could include the team number to support multiple robots on the same network.  Then the Driver Station issues this UDP broadcast to get the IP address of the robot, rather than using static IP addresses.

0 Kudos
Message 8 of 12
(4,655 Views)

dangyogi wrote:

If you feel that you must use vxworks, could you provide an option to use linux?  In other words, in addition to supporting multiple programming languages also support multiple operating systems?  Not all languages would have to run on all operating systems.

The 2015 controller, as announced today, runs linux rather then vxworks.

dangyogi wrote:

  1. Looking at the available TCP/UDP ports at the competition (from the Arena Game Manual), it doesn't look like the netConsole application can be used during the competition.  Is this correct?
  2. With the new 2015 control system coming out, do you know if there will be some way to get access to this code (perhaps a beta version) prior to the 2015 competition in order to have the time get our project ported over to it?

Not only is the port blocked, but when the robot is connected to FMS, it stops broadcasting netconsole data.

It was stated today that they were trying to make the new WPILib library compatible with the old one. However, I suspect that is only at the highest levels, as given its a different OS, processor architecture, and FPGA, the lower level interfaces will change.

Going back to the original question, the following question was tweeted today, but the panel did not include it.

Message was edited by: sciencewhiz

0 Kudos
Message 9 of 12
(4,655 Views)

sciencewhiz wrote:

Going back to the original question, the following question was tweeted today, but the panel did not include it.

I'm not aware of any plans to document the low-level interfaces.  They are low-level and insulated from the user by WPILib.  They are not guarenteed not to change.  The FPGA documentation that is available is meant to provide information about the specs and behaviors of the FPGA that leak though the WPILib abstraction.  They are not meant to be a roadmap for implementing WPILib.

0 Kudos
Message 10 of 12
(4,655 Views)