BotLoader v 1.21 *Formerly PICLoader* README.TXT 12/8/2003 Pete Skeggs --------------- Introduction ------------ BotLoader and BotLdrCmd are programs used to upload Intel Hex files to PIC microcontrollers that are running Rick Farmer's PICLoader program. They do so over an RS232 serial port connection. A version that runs on Windows CE machines is also available; it was rewritten for Windows CE by Andrew Welch at Apex Robotics: www.apexrobotics.com. These programs were developed specifically for PARTS' MiniSumoMarkIII kit, to make it very easy for begineers to upload their robot programs to the PIC microcontroller. Hyperterminal is not needed. Both programs can automatically test all serial ports on the system and find the PICLoader. This works as long as the PIC controller board (such as a PARTS' MiniSumoMarkIII) is connected to an unused port with a straight- through serial cable, and the power switch is turned on to the board. Both programs will remember the last known good port number that worked, so you won't need to specify it again. If you connect later to a different port, you can force them to scan for the PICLoader by checking the "Scan All Ports" checkbox on BotLoader or by specifying /p 0 on either program's command line. Alternatively, if you know the COM port number, you can specify it directly on the command line using /p n, where n is the port number. Both programs can also continuously scan for the board, or wait for a manual scan. Use the "Auto Scan" checkbox to control this mode in BotLoader, or use the /c (enable) or /c0 (disable) parameters on either program's command line. You can combine the various parameters too. With /a /c /j file.hex, PicLdrCmd will automatically scan for the board; when it is turned on or reset, it will automatically upload file.hex; then when the upload is complete, it will start your code running. You can do the same thig with BotLoader by checking the boxes next to "Auto Scan", "Scan All Ports", "Auto Jump", and "Auto Start." BotLoader.exe is a 32 bit Windows interactive graphical program for uploading files. It is useful for beginners as the user interface is self-explanatory. There are a lot of ways BotLoader can be launched. BotLoader (version 1.21) registers itself with Windows so that you can double click on any .hex file in Windows Explorer and it will automatically launch BotLoader. Further, an option (Auto Start), if set, causes BotLoader to automatically start uploading the file you double-clicked. This also occurs if you drag-n-drop a file from Explorer onto the icon of BotLoader or into a running copy of BotLoader. You can even Select All -> Copy a .hex file in Notepad or other editor, and paste it into BotLoader using the menu command Edit->Paste. The simplest way is to just double click on BotLoader itself from Windows Explorer or from a short cut which you have created. Finally, you can also just launch BotLoader and browse to the file by clicking on the Browse... button. BotLdrCmd.exe is very similar to BotLoader, but runs in 32 bit Windows console (command line) mode. This means it can run in a "DOS Box" or "Command Prompt" under Windows 95, Windows 98, Windows Me, Windows NT, Windows 2000, or Windows XP. It does not work under Windows 3.1 or plain DOS. BotLdrCmd is useful for calling from a make file or batch file that would automate the whole build -> upload -> run cycle. Both programs take the following command line options. They also both store the previous values of various options (port number, baud rate, filename, user code rev string) in the Windows Registry. This means that once you get either program to work right, you can run them again with no command line options and will be able to re-upload the same file to the same serial port. Command Line Options -------------------- BotLdrCmd v. 1.21 Command Line PIC Boot Loader Uploader, (c) 2002 Portland Area Robotics Society Command Line Help: BotLdrCmd /p Port /b Baud /s RevStr /a[0,1] /v /q /h /j[0,1] /t[0,1] /e[0,1] /r /f filename.hex Example: C:\>BotLdrCmd /p 1 /b 38400 servo.hex /p Port - select serial port 'Port', where 'Port' is a number from 1 to 8 /p 0 - scan all ports /b Baud - select baud rate 'Baud', where 'Baud' is a number /s RevStr- set the user code rev string (if not at end of hex file) to RevStr /a - turns autostart on (automatically uploads when you double click a .hex file) /a0 - turns autostart off (default) /c - turns autoscan on (automatically detects board turn on) /c0 - turns autoscan off (default) /j - jump to user code (execute your program) /j0 - no jump (default) /t - terminal mode; use after /j to interact with your program, or with /f to interact with the bootloader itself /t0 - no term (default) /e - terminal echo on /e0 - terminal echo off (default) /r - prompt for reset of board if no board found /f - no file -- don't upload (useful with /j or to just test things) /v - verbose /q - quiet /h - this help text filename.hex = the file to upload All parameters are optional. The previous values are stored in the registry and used as defaults. The exit code of either program is set to 0 on a successful upload, and values greater than 0 to indicate various errors. This is useful in a make file or batch file to check for error during upload. Note that BotLoader does not need, but will accept, command line options. BotLoader is interactive, so the various things that can be set using the command line can also be set interactively on the screen. How to Upload Code ------------------ 1. first, build the code using whatever development tools you plan to use: CHBasic, MPLAB assembler language, JAL, CCS C, etc. This should result in a file whose name ends in .hex. A .hex file can be opened and viewed with Notepad, and looks something like this (yours will contain similar formatting but different numbers): :0A000600042883018A110A124D2814 :10001000A1010830A30003108A110A12201C122823 :100020002408A107A10CA00C8A110A12A30B0B280B :100030002008A4000034A1010830A300A00DA10DE8 .... 2. connect your PIC board (or robot) to your PC using a 9 pin straight through serial cable. These are available from Radio Shack, CompUSA, and other stores. This cable will have a 9 pin male connector to connect to the robot and a 9 pin female connector to connect to the PC. If you don't have an empty 9 pin serial port on the back of your PC, you may need to either remove some other device that uses serial, such as a Palm Pilot cradle. In that particular case, be sure to turn off the HotSync software as it keeps ahold of the serial port and will prevent BotLoader (or any other serial program) from accessing the port. In other cases, turn off or disable whatever software connects to the device. If you cannot free up a serial port, you may need to try a different PC, or buy a USB-to-Serial converter, or an add-in ISA or PCI serial port card. 3. turn the power on to the PIC board, making sure that there are batteries installed. 4. launch BotLoader with no command line options. It should scan all ports and report something like: "COM2: Found PICLoader". For the MiniSumoMarkIII, leave the baud rate to 38400. 5. enter the full path and filename of your .hex file in the "Select Hex File:" box, or browse for it using the "Browse..." button. 6. enter a revision string in the "Enter Revision String:" box; the PIC loader will display this to you right before it is executed. This is optional. 7. hit "Upload!" to send your file into the PIC. 8. optionally, if the upload is successful, hit the "Jump to Code" button or press reset on the PIC board to make your program run! What does it look like if it works? Here's a sample of what you should see in the big window at the bottom of BotLoader (you will also see it printed in text by BotLdrCmd). My comments start at the left and are marked with brackets []. PIC> PIC>u Are you sure? [y/N]>y y Erasing [this part takes about 15 seconds] ######################## Ready :1000000000308A00172800002430840000080319FB #:1000100016280630F800F701F70B0C28F80B0B2810 #:100020007B30F700F70B1228800B0928003484017D #:100030001F3083059F30840007308000FF30A2000E [snipped for brevity of this readme.txt file] #:100170008518BC280610BD280614831606108312A5 #:040180006B28630085 #:02400E00F23F7F #:00000001FF Upload succesful Enter a rev string>TESTER Setting rev string. TESTER Current image = TESTER PIC>Upload complete Terminal Mode ------------- One much-requested feature has been added to BotLoader: a terminal mode so that one can interact with ones program without exiting BotLoader. This is useful for testing and debugging your program by printing characters to the serial port or receiving input from the serial port. Note that terminal mode uses the same baud rate as Rick's PICLoader, so please configure the serial port in your test program to 38400 baud, no parity, 8 data bits, and 1 stop bit. Pressing the "Term Mode" button on the BotLoader dialog or specifying /t on the BotLoader or BotLdrCmd command line causes the program to enter an interactive terminal mode after any requested uploads and jumps to user code are performed. You can even skip uploading and jumping and just directly enter terminal mode with /f /j0. The /e or /e0 options control whether characters you type are printed before being sent to the robot. Note that Rick's PICLoader echos characters it receives, so echo should be off when you wish to interact with PICLoader; if echo is on, whatever you type will appear twice on the screen (a benign but perhaps confusing situation). PICLoader has a number of commands you can issue manually; type '?' followed by enter to see what commands it offers. Multiple Compile->Upload->Test Iterations ----------------------------------------- If you want to change your program and upload it again, you can do it. First, change your program and compile a new .hex file. The file name can stay the same. Then, either turn the power to the robot off and on again or hit the reset button to get it to run Rick's PICLoader again. Either hit Scan Ports to resync BotLoader and PICLoader, or in the terminal window, hit Enter before the PICLoader timeout period. Then, hit Upload! again to send your new program version to the robot. Hit Jump To Code to try it out. In other words: 1. change your program 2. compile it 3. hit reset on the robot 4. hit Scan Ports or type enter in the terminal window 5. hit Upload! 6. hit Jump To Code For BotLdrCmd, hit Ctrl-C to exit terminal mode and reexecute the upload/jump to code operations. This means that you must leave BotLdrCmd in terminal mode while you compile any fixes to your program and generate a new .hex file of the same name as before, then hit Ctrl-C to cause it to be uploaded again. If you just want to exit BotLdrCmd, hit Ctrl-Break or close the Command Prompt / Dos Box window. Troubleshooting --------------- You may receive a variety of errors if things don't go right. In BotLoader, these will pop up in a small message box; hit OK once you've read what they say. Examples are: "Error opening file ..." -- the file you specified does not exist, or is open in another program and cannot be read. "No upload confirmation detected" -- the PICLoader did not respond with "Are you sure". This often happens if you hit "Upload!" when the power to the PIC board is off or when the PIC has been told to Jump to User Code. Turn on the power and/or hit reset to try again. "No erasure completion detected" -- the PICLoader did not respond with "Ready" after starting the erasing process. Check your batteries and serial cable. "Error writing hex file to PICLoader" -- serial problem during upload. "Error writing EOL to PICLoader" -- serial problem during upload. "Line x contains an invalid record type" -- this occurs most often when you specify the wrong kind of file instead of a valid .hex file, e.g., if you were to try to upload the basic language source code file (something.bas). "The startup code at location 0002h is incorrect" -- Rick Farmer's PICLoader requires certain modifications to the low areas of memory. You will need to look elsewhere for how to do this. "Line x contains a checksum error" -- the .hex file is corrupted. Try building it again. "Line x contains a non-hex character" -- the .hex file is corrupted. Try building it again. "FLASH programming error during line x" -- there was a serious problem when trying to program your PIC. Use fresh batteries and try again. If the error persists, you may have a soldering problem on your board, or you may have a bad PIC. Report it online at http://www.yahoogroups.com/group/minisumomarkiii "Memory protection error" -- the program you are uploading references a memory location that does not exist in the PIC you are using. Perhaps the code was built for the wrong kind of PIC. Known Issues ------------ Strange colors from BotLdrCmd in Win9x; hey, it works great on my development system under Windows 2000! Synchronization loss: If you launch BotLoader and successfully connect to the PIC board, then later turn off the power to the robot with BotLoader still running, and then later turn it back on and hit "Upload!", you will get a "No upload confirmation detected" message. If you then hit "Upload!" again, you might get another such message as the program and the PIC board are still out of sync. You can either hit "Upload!" a third time, which will work, or better yet, just hit "Scan Ports..." or hit the Enter key in the terminal window right after turning the power back on. This gets the program back in sync and prevents the appearance of the error message. Release Notes ------------- v1.0, 2/11/2002 -- first release v1.01 (development version) v1.02 2/18/2002 - fixed bugs added many features: - drag-n-drop support - paste support - registration of file type with Windows - compatibility with Bootloader Reloader 1.01 - menu added - auto start and auto jump options added - removed extra blank lines in log window v1.10 9/17/2002 - renamed to BotLoader to be consistent with WinCE version by Andrew Welch (www.apexrobotics.com) (and as suggested by Tim Rohaly) - added interactive terminal mode! - added /j0 option to turn off jump mode if it was set in the registry v1.20 10/18/2003 - added /c and /c0 options to automatically detect when a board is turned on v1.21 12/8/2003 - updated BotLdrCmd to also support /c and /c0; (thanks to Giuseppe Marullo for finding this bug) when used in conjunction with /r, expect the following behavior: /c0 - scan all serial ports(*) once for a PicLoader, then stop if not found /c0 /p n - try port n once, then stop if not a PicLoader /c - scan all ports(*) repeatedly until one responds; hit q to quit /r - scan all ports(*) repeatedly, prompting you each time; q to quit /c /p n - automatically try port n repeatedly until found or q hit to quit /r /p n - try port n repeatedly, prompting each time; q to quit Note (*): this will actually only scan the one port that has worked in the past, under the assumption that you will probably always use that same serial port from then on; use the new /p 0 option to force a full scan of all serial ports. - updated BotLoader to do the same; fixed memory leak - added /p 0 option to force scanning of all serial ports - increased maximum serial port number to COM8: - added "Scan All Ports" checkbox to BotLoader; used to toggle between default port (the one either specified on the command line or saved in the registry as the last known good port) and all available ports License ------- Freeware for now. Source belongs to Pete Skeggs until done researching various licenses such as GPL, LGPL, Mozilla, etc.