Programming Tips for the FRC 2017 season - SteamWorks

From a Grumpy Old Programmer

Quick Reference

The Full On Rant

I have been programming for 45 years. If you tell me you are a programmer, I have a certain idea of what that means. It is NOT knowing how to wrestle with Windows. It is NOT being an expert at configuring an IDE or getting the JRE and JDK working. It is NOT having a lot of experience hacking around the internet. It does NOT mean mastering only one language or creating web pages. Programming is the "art" of understanding a very complex problem well enough to break it down into small, solveable problems. Then choosing the appropriate hardware platform and language with which to implement the solution. You then have to use the chosen language to express the solution's concepts using data structures and procedures which take advantage of the hardware and libraries (API) that are available. Googling and Pasting other people's code is NOT programming no more than downloading a song from iTunes and pushing the play button makes you a musician.

In FIRST Robotics, we have no choice in the main control hardware we are allowed to use. We are also limited in the choice of programming languages and hardware accessories. However, sometimes that is the way it happens in real life. The choice of platforms and languages may be determined by accountants rather than engineers. But i'm not bitter...

Rant Over...Let's get your robot rolling.

There are many tutorials and step-by-step instructions on how to install the development environment for this year's control system so I won't duplicate that effort. I will provide links to authoratative resources as I find them (in the Quick Reference). No forums to wade through (everyone complaining about the same thing with no answers). What I will be offering is a way to break down complex control concepts into simpler solveable challenges that a motivated high school student with little or no experience should be able to implement with help from a mentor (because that is how it works in FIRST... RIGHT?).

First, you must define the problem, then solve it.

The very definition of Engineering. You've probably already heard this if you attend any "Strategy Dictates Design" sessions. You don't start building your competition robot on day one or even week one. You and your team analyze the game, come up with a winning stategy, do some experiments, then start designing a robot to implement your strategy. Then you build it.

It's obviously the same practice in "software engineering". Well, kinda..

The Development Environment

You need to set up your development system just like setting up the CAD software for mechanical design. However, you can design and build a robot without CAD. Not so for programming. Ultimately, in software development, all you are doing is editing a text file, converting it to machine code, transferring the code to the controller (RoboRio), debugging it, rinse, repeat... Sounds simple. Well it is. Back in my day - we had 3 programs running on our computer (and before 1984, not at the same time). An editor which allowed us to create the text files. A compiler or assembler to convert the human-readable text files to machine-executable binary files. And a serial transfer utility to upload those binary files to the microprocessor (or EEPROM Burner - LOL!). Those same 3 steps still occur in that order as they did in 1979. But now, they are hidden in the IDE (Integrated Development Environment). So instead of spending your first week of build season writing code to test prototypes, you spend it installing the IDE and trying to wade thru endless configuration options (none of which apply to FRC) and becoming a master of Eclipse. With Monk-like devotion you will eventually gain a foothold and start to become proficient. Imagine if sending a selfie or cute cat picture required the mastery of PhotoShop. OMG! Sorry, a little rant occured. Back to business...

The Programming Language

Of the hundreds of programming languages both current and dead, I'll claim to be proficient in about 20 of them (but i've hacked around with about 50). And although i'm writing this web page with the same simple editor I use for code, HTML is NOT a programming language! So when I look at the options for developing robot code for FIRST, I choose C++. Java would be my second choice. Based on how fast I can teach it to High School students and how fast it deploys to the Robot (under 10 seconds). While both C++ and Java are very similar, Java requires a special development kit (JDK) and runtime environment (JRE). Two more things to go wrong when you are in the pits with 5 minutes before your next match, the robot is dead, and the code is not deploying. The simplest run time environment is C++ but requires a slightly deeper understanding of fundamental programming principles. In other words, you have to pay attention and practice this skill.

Data Types, Structures, and Processes

From here on, both languages look pretty much the same. Sort of like speaking English and dealing with American, British, and Australian dialects. "Well that's thrown a spanner in the works!" If the IDE (Eclipse) is set up correctly, it will "help" you select the proper API procedures (methods) for the given object. So if you want to set the power of a drive motor to 80% of the battery voltage, it would look like this:

	leftMotor->Set(0.8);      // C++
	leftMotor.set(0.8);       // Java

So yeah, the languages are case sensitive. I feel your pain.

If you are not clear what the above data types, statements, and structures mean (especially the switch/case), I would suggest spending some time practicing fundamental programming using an online compiler and tutorial. The best i've found so far are the ones at  C++ or Java editor and compiler. It does not hide the compilation (build) or execute (run) processes. You simply type some code, compile it, run it and see the results live. Another good one is SoloLearn. You don't need to download nor install anything.

"Hello World!" is the quintessential first program. Meaning every programmer tries to implement it in whatever new language or platform they are learning.

0.  /*   My first program in C   */
1.  #include <stdio.h>
3.  int main(void) {
4.     printf("Hello World!\n");
5.     return(0);
6.  }

If you understand everything on every line of the above example, then you can skip to implementing C++ on your FIRST Robot. Otherwise, please go thru the following quick reference on C (it applies to Java as well). If you thought the line numbers are actually part of the code or you don't understand why we start counting from 0, then you definitely need to read through the following paragraphs. ;-)

The line numbers are simply there so I can refer to them in the following descriptions. Column 1 of the code is 4 characters to the right of the number.

Line 0 - /* My first program in C */

This is a comment. Anything between the /* and the */ is only for us humans. The compiler ignores it ( although for some reason the Eclipse IDE highlights syntax errors in commented code ??). The block comment can span multiple lines.

Line 1 - #include <stdio.h>

The "#" in column 1 indicates a special command to the compiler that is not directly related to the language itself. Words that start with this are called compiler directives. This particular one inserts the text from the file named "stdio.h" into the body of the main file before compiling it into machine code. It "INCLUDES" the header file (indicated by the ".h" extension. The < and > indicate that the compiler should look in the "usual" library directory for the file. The "usual directory" is one of those many configuration parameters I mentioned earlier.

Line 2 - a blank line

White Space is free to be used by the human programmer any way they desire in order to make the code more readable. If things seem too crowded, then by all means, give yourself some breathing room.

	/*               My first program in C               */
	#include <stdio.h>

	int main(void) 

		printf("Hello World!\n");



Or, if you want to be a total jerk, get rid of all of the free whitespace.

	#include <stdio.h>
	int main(void){printf("Hello World!\n");return(0);}

If you notice in the compressed version of the program, there are 3 whitespace characters that are syntactically necessary. There is a "new line" character after the comment which is necessary to start the #include in column 1. There is also a newline after the name of the included file because "directives" require a line to themselves. And the space between int and main (otherwise it would be intmain). There has to be at least one whitespace character but there is no maximum number of characters. Whitespace is a space, tab, or new line character or any combination thereof.

So you thought there was not much going on the first 3 lines eh? Again, if you take the time to understand everything in this short program, your FIRST Robotics programming life will be less painful.

Line 3 - int main(void) {

This is actually the first line of user code. It introduces a function called main and the int indicates that it will return an integer (whole number) value to the caller. The values passed from the caller to main would go inside the parentheses. In this case, the word void indicates that main does not expect any information passed to it ( called "parameters" or "arguments"). The opening brace '{' is the start of a block of code which represents the body of the function called main. A function is like using a calculator. You enter a number, press a function, the result shows up in the display. Let's use the SIN function as an example. Type 30, press sin, the result is 0.5 ( or 0.5 = sin(30) ). If written as an expression in C:

	result = sin(degrees);
	   0.5 = sin(30)

You pass the degress to the sin function inside the parentheses and get a result returned to you (the caller) which can then be stored in a container named result. This is not an "equation" as in Math. It is an "expression" in code. Meaning it is evaluated from right to left and the '=' is an assignment operator. You can only have one term on the left side and it will receive the result of the right side. So the following is a perfectly legal software expression but would get you an 'F' in Math Class.

	result = result + sin(30);		// Mind Blown!
Line 4 - printf("Hello World!\n");

Yeay! A line of code that actually does something we can see. printf is the name of a function that resides in the stdio (standard input/output) Library. It takes whatever you pass it in the parentheses and displays it on the computer screen (if by "screen" you mean a terminal window). The text between the " " is called a string - A sequence of printable and control characters as defined by the ASCII chart. The '\n' represents the newline character. But wait, what's with the ';' ? The semicolon marks the end of a C statement. As I mentioned, whitespace is free to be used to make things more readable. So simply using the end of a line to mark the end of a statement would not allow us to do this:

   printf (
            "A really , really, long string would have run off the right side of the page by now\n"
Line 5 - return(0);

The definition of the main function says that it returns an integer to the calling routine. In this case, main is called from the shell or command line. The operating system launches the program, calls main and expects an error code when main terminates. Returning 0 tells the shell that main terminated with no errors. Note the ';' indicating the end of the return statement.

Line 6 - }

This is the closing brace which ends the block of code that is the body of the main function.

Finally - The Robot Code

OK, let's get the poor robot moving. You've probably learned by listening to your coaches and mentors that the most important thing for your robot to do is MOVE! FIRST Robotics is not a science fair it's a competitive sport. Once you get the robot moving, then you can worry about manipulators, shooters, and intakes.

It is almost ready to post, please be patient...