Category Archives: Software

Software Documentation

Have you thought about documenting your software? Are you even doing it?!? You use the  NXT comments capability, which looks like a little thought bubble.  Write yourself notes to remind yourself what your code does, which way is forward (up or down), and helps you to make changes later. Also, it helps the judges read your code.

Well, here are some of our “Documentation Standards” that we use for EVERY piece of software we use.

Here are the things we think are important to note: Run number, Filename, Myblocks used, Robot Start Position, Assumptions, Sensor requirements, robot end position, and attachments needed. Below is an example:

  • Filename:  “2 Corn”
  • Run: 2
  • Mission: Corn harvestor,  yellow ball,  pink bacteria, yellow truck
  • Start Position:Base. Facing east. Aligned in corner near bacteria
  • Assumptions: Raise and unlock bar attached to B motor
  • Uses Myblocks:  “CMtoDEG” for converting centimeter distances into rotational degrees
  • Sensor requirements: Touch, light
  • End Position: Base
  • Attachments needed: Folding truck pusher, corn catching tray, bacteria dropping arm

If you follow all these documentation tips, you will be sure to succeed in the software department.

Happy Documenting!


Kevin F.

Leave a comment

Posted by on December 1, 2011 in Software


Source Code Control, and QR Tattoos.

This is totally unrelated. We found QR code tattos! And they really scan! They link right here, to this blog.

Have you ever changed a robot program file, only to find out later that your change did not work? Or worse, broke something else?

Did you ever lose a file?

Did you ever have to compare two files, and figure out which one was the current one?

Have you thought about what you would do if your computer crashed and lost all your data?

Has the owner of the laptop with your current code on it ever forget his computer at home?

Well we struggle with all of this stuff. So we have some advice and rules that we follow.

I’ve tried to teach the kids a little about being organized and about source code control, but it is hard problem! Whenever someone asks me how often they should back up their files, I always laugh and say — only once. But you have to back them up *right* before your computer crashes! HA HA HA

The kids have come up with some conventions that they use, and I’ll summarize them for you.

1) Naming conventions – we plan our robot runs, then number them consecutively so that when the operator is selecting the program they will come up in numeric order. Keep the name short and descriptive. “1Rats” or “2germs” works. When the code is in progress, and many changes are being made, I often have them put in their initials and a revision as well. So a working file might look like “1RatsKF4”.

2) Dropbox – since we have two or three laptops at any given meeting, we have standardized on using Dropbox for our save directory. That way, all the code is available to all the users, no matter what computer is in use.

Our team has a gmail address that we all know the password to, and this is what we use for the Dropbox account as well (again, with a shared password.)

3) Saving locations – Each time someone works on code, a new directory is made in the Dropbox with the date as the directory name. Then all of the code from yesterday is copied into today’s directory. This is a way to have a backup snapshot if today’s code breaks yesterday’s — you can go back in time.

4) Backups – USB sticks work great for these. Take one with you to the competition. You can use them also for sharing files with a competitor who likes something cool that you did….

5) Just a note about MYBLOCKS. They are loaded into your software runtime from your user preferences. Take special care to make sure you have these backed up by copying over the user files from your login account to a dropbox folder somewhere. Also, it is very easy to make a change in a MYBLOCK on one computer and forget to propagate it to the other computers. At some point in our development, we migrate to doing all final work on our game-day computer to avoid these issues.

6) Documentation. I wish I could say that we were better about this one. It is easy to do the first time using the comment feature of the software, but it is hard to keep the comments in sync as changes inevitably happen. I try to give the kids an outline of what is most important to document.

a) Starting requirements (“in base, lined up at the 4 line)
b) Hardware requirements (“tow arm on motor c”)
c) Any assumptions about variables or calibration.

Those are all things to help the reader know what they are reading. But mostly, I am thrilled if I don’t have to remind them to comment, comment, comment!

Thanks for reading, and good luck!

– Written by Coach Renze

1 Comment

Posted by on November 17, 2011 in Software

%d bloggers like this: