A Programming Tutorial

From Team1370

Revision as of 17:39, 18 March 2006 by Admin (Talk | contribs)

Getting Started with the Professional Method

There are easier ways to program your robot controller, including Easy C (new for 2006), however, I am far more familiar with the classic, more complicated method using MPLAB IDE. This perhaps more complicated system is the one which I describe below, but do consider that there are other options and other tutorials available on the web. As this will be outdated soon, it may be useful in the future as an overview of all the tools involved and what they generally do. This tutorial can also be used as a reference on a short topic you may not be fully familiar with, in particular I suggest checking out the section Getting a Serial Terminal Without IFI Loader even if you are an experienced programmer. -Pierce Lopez

Contents

Collecting Your Tools

The system I use requires the use of a few different tools which work together (more or less). Here's what you'll need:

  • A Laptop running Windows A laptop will make connecting to the robot immeasurably easier and more convenient, and most tools I use are only available for windows, and have no counterparts for other OSs (unfortunately).
  • ... with a serial port. You're laptop might already have one, it's like a rounded-corner trapeziod with two rows of pin-holes. My newer laptop does not have one, so I got a usb-serial adapter cable for $40 at RadioShack.
  • MPLAB IDE v7.20 Newer versions don't work, according to the source code documentation. Download this version here.
  • MPLAB C18 Compiler Student Edition v2.40 Newer versions of this will apparently not work either, and this older version is pretty difficult to find online. I found a download link for it here. If that link doesn't still work, search for it.
  • IFI_Loader v1.0.12 Can be found at the bottom of this page. But don't get the robot default code from there, if you intend to use the camera with your robot, as we will in this guide.
  • The Default Robot+Camera Code Download "frc_camera.zip", the "bells-and-whistles version", from this page.
  • CMUcam2_workbook.pdf This document contains very useful diagrams and specific sets of instructions which I'll reference, get it on the same page as the robot code.
  • puTTY For later, when we're sending adjustment commands to the camera. You just need "putty.exe", get it here.
  • COM/Telnet Bridge For use with puTTY, get the "tsb.exe" package from this page.

Getting it all set up

That was a lot of stuff to download, now let's get it set up.

  1. Install MPLAB IDE: Extract the files from the zip file you downloaded into a folder, and run "MPLAB v270 Install". You don't need to install support for any fancy debuggers or devices which are mentioned, we just need the basic program.
  2. Install MPLAB C18: Extract the installer from the zip file you downloaded and run it. During the install process, select the option which register the C18 compiler and linker with MPLAB IDE, but you don't need to select the options which "Add the compiler/linker/etc. to the system path." You should almost definitely install C18 to the default location, to prevent headaches later, and save som configuration work.
  3. Install IFI_Loader: Extract the folder from the zip file, and run "setup.exe".
  4. Unzip the code: You need to put the folder which contains the code close to the root of your drive; in simpler terms, just extract the frc_camera folder from frc_camera.zip right to your C: drive, so the files it contains are in C:\\frc_camera\\(files here). (You need to do this because the C18 compiler simply can't handle a long directory name.)
  5. Start MPLAB IDE (you can do this by clicking the icon that has been created on your desktop). Click on the Project menu along the top, and click Open... in the menu shown. Browse to the folder you just put the code in, which might be C:\\frc-camera\ (if you can't find it, click the icon with folder with the up-arrow until you see your C: drive, and go from there). Only one file should be shown in the window, camera.mcp, so select it and open it. You will have to reopen this project file every time you start MPLAB IDE. A couple of windows should have opened, including at least a long list of files on the left side. If this hasn't happend, something might have gone wrong already.
  6. Now click the Project menu, click the Build Options... submenu, and click Project at the bottom of that submenu. In the window which appears, make sure that Include Path is set to C:\\mcc18\\h, and Library Path is set to C:\\mcc18\\lib. If you installed MPLAB C18 to the default location, everything should be set. (If you changed the install location of C18, you'll have to change these settings, as well as those under Project/Set Language Tool Locations)
  7. Now click the Project menu, and click Build All. If a window titled Output pops up and Build Succeeded eventually appears at the bottom of the text there, the default code just compiled, and your coding environment is fully set up! If not, try to figure out what went wrong before continuing.
  8. Now we're going to set up some of the other little tools which we'll use later.
    1. Create a folder you'll put the last two little utilities in, for example a folder Robot Tools/ on your desktop. Open the tsb.zip archive you downloaded, and put the folder tsb it contains, or all the files, into the folder you created.
    2. Open example.bat, which came in the tsb archive, with Notepad (a plain text editing tool found in the Accessories submenu of the Start menu). In the very last line of the file, change the number 9600 to 115200. Also, if the com port you'll be using to communicate with the robot isn't COM1, you'll need to change the lone zero in that last line to the number of the COM port you plan to use, minus one. That's why COM1 is represented by the 0.
    3. Also put putty.exe into that folder you created, possibly called Robot Tools/, possibly located on your desktop.
    4. Now, click on putty.exe with the right mouse button, hold it down, drag it over the desktop, and release. Click Create shortcut in the menu which pops up next to your pointer when you do this.
    5. Do the same right click drag / create shortcut operation to example.bat in the tsb folder.

We'll use these last couple of programs to communicate with our robot while it's running, mainly to view messages which will help you to diagnose problems, and to adjust the camera settings.

Setting-Up the Robot and Connecting

The Robot

Before we can interact with the camera or begin to test code on the robot, we need to get the robot's electronics wired to a very basic minimum. The Robot Controller needs a charged backup battery and should have a charged main battery hooked up to it (see the appropriate FIRST documentation for help with that stuff). The Operator Interface needs to be getting power from the power adapter that came with it, and needs to be connected to the Robot Controller, either with a tether or with the radio set-up.

The Camera

The camera needs to be built into its pan-and-tilt mechanism. All the parts needed are included in the Robot Kit, and instructions can be found in the first part of CMUcam2_Workbook.pdf. Also in the workbook are instructions for how to wire the camera to the Robot Controller. In fact, much of what I'm about to describe is also in that workbook, so you can always go back to it as a reference. However, to prevent confusion between the instructions for various different tasks found in the workbook, I'll specify here what exactly needs to be connected. Just open the workbook to the diagram (p. 17) so you can identify the pins and ports I specify.

Make sure you match up the black wire of the pwm cables with a B where they plug in.

  • Make sure that there is a jumper on External Power To Servos, and not on Internal Power To Servos (look in the diagram to the left of the power switch at the top)
  • Connect Power Input (also to the left of the power switch) to a free pwm out on the robot, for example pwm03, with a pwm cable
  • Connect RS232 PORT (3-PIN) (next to the massive serial connection) to the 3 pin connection of the little extra chip which came with the camera (the TTL-232 Adapter, a picture of it is below the picture of the camera on page 13) with a pwm cable.
  • Plug the 4-pin plug attached to the TTL-232 Adapter directly into the 4 pin plug on the Robot Controller which is labeled TTL Serial Port and is right next to the reset button. Match up the Bs.
  • Attach the pwm cable coming out of the pan servo on the camera assembly to pwm01 on the robot controller (you will probably have to use a pwm cable as an exention cord)
  • Attach the pwm cable coming out of the tilt servo on the camera assembly to pwm02 on the robot controller (again, use an extra pwm cable if you need to)
  • Go ahead and switch on the camera and carefully take the lens cap off

Connecting to a Computer

Have the main battery and the backup battery connected. Then, hold the PROG button (at the bottom of the Robot Controller, next to the RESET button) until the Program State LED turns orange. Have your computer connected to the robot via a serial cable, from a serial port on your computer to the Program serial port on the right side of the Robot Controller. Start IFI Loader on your computer, click Port Settings in the upper left of the IFI Loader window, and make sure the correct serial port on you computer has a check mark next to it, COM1 (selected by default) is correct if you only have one serial port. Next click the Browse button in the middle-right of the IFI Loader program, and browse to the folder which contains your robot code, if you followed the directions above to the letter, browse to the folder C:\\frc_camera. You should see only one file available for selection there, camera.hex, which is the file that was generated when we compiled the code earlier. Click on it and open it. Then click the Download button on the IFI Loader program, and (hopefully) watch the progress bar that appears at the bottom fill up as the code is loaded into the Robot Controller. When IFI Loader is done loading the code, a white window which I will refer to as a serial terminal will open.

Troubleshooting

If loading the code doesn't work and you get an error message from IFI Loader, make sure that a path to a .hex file is in the text box labeled "Current Hex File", that the correct serial port is selected (as described above), that a good quality serial cable (prefferable just one to start) is well connected to both the Program port of the Robot Controller and your computer, and that the Program LED on the Robot Controller is orange, indicating that it is in program mode. You might also want to make sure the settings of your serial port are all right; to do this, right click on My Computer on the Desktop or the Start menu and click Properties, click the Hardware tab, click the Device Manager button, expand the Ports (COM and LPT) section (which may be different on Windows versions which are not XP), and double click the COM port you use. Click the Port Settings tab, and make sure that Bits per second is set to 115200, Data bits is set to 8, Parity is set to none, Stop bits is set to 1, and Flow control is set to none.

Running the Robot Code

As soon as the Robot Controller becomes connected to the Operator Interface, it will begin to run the code which is loaded onto it (unless it doesn't have power or is in Program Mode etc). The Operator Interface can be connected to it either with a serial cable which connects the Tether ports on the Robot Controller and the Operator Interface, or with the radio link, in which case the Operator Interface needs its power brick connected to it.

When the Robot Code is running, the camera should start panning to the side in steps, and then panning up a step after a full sweep. When a green light which it is properly calibrated for comes into its view, it should stop panning around and follow that green light. This is all already set up in the robot code.

Communication Using the Serial Terminal

The white box which appeared on the computer screen when IFI Loader finished loading the code is a Serial Terminal, it can transfer text to and from the robot. Wherever printf() statements appear in the robot code, they will send a text string (like a sentence) to this serial terminal. You also use this serial terminal to send commands to the robot controller, which adjust the camera's settings.

When the camera is panning around looking for the green light, "Searching..." should repeatedly be printed to the serial terminal, while it is properly connected. When the light source is found, the robot should no longer send "Searching..." to the serial terminal. While the camera is searching or locked on, you can enter the Tracking Menu by typing t in the small box at the bottom of the serial window and hitting the Enter button on your keyboard or clicking the Send button. A list of possible further commands should come up in the serial terminal, and next to each one is the letter in parenthensis you need to send to give that command or modify that setting. The setting presented here are self-explanatory. The camera will not track while you are in a menu. Another menu you can access is the color calibration menu. Send the robot a c while it is not in another menu (you may have to exit out of the tracking menu first). How to find the correct settings to input to the calibration menu is detailed in the CMUcam2_workbook.pdf, and involves use of other software included with the robot kit.

Getting a Serial Terminal Without IFI Loader

You can only get IFI Loader's Serial Terminal to appear after you have loaded code onto the robot using it. However, there is another way to get a serial terminal to the robot running, which is usefull if you don't want to spend the time to load the code, or you don't have the latest version of the code on your computer. First, get the robot fully running and connected to the computer's serial port via its program port. Then, double-click the shortcut to example.bat (which you can rename) on your desktop. A black window with some text should come up, leave it up. Next, double-click the shortcut to putty.exe icon on your desktop. In the Session subsection of the configuration which appears (should be already shown, and is the first on the list on the left), select Telnet, input localhost for Hostname:, and 23 for Port. Then click the Open button at the bottom. If the (black in this case) terminal doesn't fully work like the other one does, you may have to adjust the settings in the Connection > Telnet subsection in the left column of the configuration dialog.

Introduction to Programming

I've actually become lazy at this point, and won't go into the detail I once intended on the matter. However, a couple of quick pointers to help you out: You only need to edit user_routines.c, user_routines_fast.c, and user_routines.h, to do about anything with the programming. Try to learn from example from the code. Another note: Default_Routine() is never called in the camera-capable code I ask you download, because it's commented out in the process_data_from_master_uP() (or whatever it's called) routine.

Well, here's a good C tutorial to get you up to speed on the syntax of the language: [1] Feel free to look for more on your own.

Programming Resources

Here is a link to the current version of our Robot Code 2006, which is a good example of various programming techniques we use.

Retrieved from "http://editthis.info/team1370/A_Programming_Tutorial"
Personal tools