--------------------------------------------------------------------------- Anonymous FTP server: cher.media.mit.edu (18.85.0.47) This file: pub/interactive-c/README.IC Last updated: December 12, 1994 Maintained by: Randy Sargent (rsargent@media.mit.edu) --------------------------------------------------------------------------- IMPORTANT FOR RUG WARRIOR USERS: If you are using IC for the Rug Warrior and are having trouble getting your board to boot, try the beta copy of pcoderwl.s19 (version 2.860) from msdos/beta/pcoderwl.s19. Some people have reported an interaction between the newly designed LCD circuit, and battery voltage(!) at startup. This pcode is believed to fix the bug, but please let me know if you try it out either way. IMPORTANT FOR MS-DOS USERS: If you use IC for MSDOS, you might try out msdos/beta/ic.exe and msdos/beta/dl.exe. These are beta versions of IC 2.860 and DL 7.860. The IC recompile is believed to fix several minor bugs, and a major one in which IC ran out of memory unexpectedly. The DL recompile gives better diagnostics for when your board isn't correctly hooked up. If you do use these beta versions, please send me a short note letting me know if they worked OK for you. Thanks! INTRODUCTION TO IC: This directory (cher.media.mit.edu:pub/interactive-c) contains source code and executables for the Interactive C (ic) 6811 C compiler system. IC is a C compiler/interpreter for use with 6811 boards. It is designed to be easy and fun to use -- just type C expressions in and they are run immediately. (The underlying implementation compiles on the fly to a fairly effient pseudocode interpreter). In addition to interactivity, IC is multitasking, and has drivers for a wide variety of I/O sources, including motors, various analog sensors, servos, infrared in and out, a simple beeper, and LCD screen. Libraries for IC are currently available for the MIT Rev 2.21 robot controller board, or for the Rug Warrior from Mobile Robots: Inspiration to Implementation by Joe Jones and Anita Flynn (a great book!). You are free to use, copy, and modify IC, so long as you don't remove our names, and leave this README file (README.IC) with the distribution. The currently available free version of IC is 2.850. Status of binaries for different platforms, as of 7/29/94: IBM PC: libraries: 2.853 executables: 2.851 beta test. (Please send bugs to rsargent@media.mit.edu) Macintosh: libraries: 2.853 executables: 2.852 beta test (Please send bugs to rsargent@media.mit.edu) Sparc running SunOS: libraries: 2.853 executables: 2.850 Sparc running Solaris: libraries: 2.853 executables: 2.850 DECstation: libraries: 2.853 executables: 2.850 NeXT 68K: can be uploaded if there is demand Linux: probably before 9/1/94 I may be willing to aid ports to other UNIX machines if people give me access over the net to their machine (but no promises! It depends on how much time I have...) The source online currently is pretty old. I'll bring source to 2.850 online soon (probably the week of 8/9/94, once all the ports are done and the code is more together). -- Randy Sargent. rsargent@media.mit.edu ======================================================================== More info follows, on newer versions of IC, as well as a quick jumpstart to help with installation and first use of IC. Readme file for Interactive C, version 2.850 Randy Sargent Anne Wright July 29, 1994 The IC software system was written by Randy Sargent (rsargent@media.mit.edu) and Anne Wright (anarch@ai.mit.edu) It makes use of a pcode interpreter and drivers that live on the robot board, which were written by Randy Sargent, Fred Martin, and Anne Wright. This version of IC is freeware and unsupported. It is provided as a service to hobbyists and educators. This version does continue to be updated and have reported bugs fixed, but most of our effort now goes into a newer IC (version 3.0+), which includes features such as structs, multidimensional arrays, and a built-in preprocessor. Versions 3.0 and above are sold by Anne and Randy in hopes we can support ourselves doing cool robotics hardware and software; it is not freeware (sorry), but at least it does come with support :) This free version IC is still very functional, having been used for years by the MIT LEGO Robot Design contest. Updates to free IC (versions < 3.0) are available by anonymous FTP to cher.media.mit.edu in pub/interactive-c. Version 3.0 of IC is available from Randy Sargent and Anne Wright for $75 + $5 S/H ($50 + $5 S/H for students) at the following address: Randy Sargent Imachinations 2 Newton St. Apt. 1 Cambridge, MA 02139 (617) 547-6664 PLEASE SPECIFY -one- of IBM PC, Macintosh, SPARC SunOS, SPARC Solaris, DECstation, or NeXT 68K. Otherwise, IBM PC will be assumed. (Available 9/1/94.) (Checks, Mastercard, and Visa accepted.) International orders please pay $15 S/H. RECOMMENDATIONS ON HARDWARE: This software was designed to be compatible with the 6811-based Rev 2.x robot controller designed at MIT for the LEGO Robot Design Competition. (designed by Randy Sargent and Fred Martin). It also works with the Rug Warrior from Mobile Robotics: Inspiration to Implementation, by Joe Jones and Anita Flynn (highly recommended reading!) Our experience founding the MIT LEGO Robot Design Competition suggests that only about 50% of boards assembled from kit work the first time. For this reason, Anne and Randy strongly recommend that you buy completed and tested hardware. We get lots of messages from folks saying "Nothing works. What's wrong?" Future versions of the software may come with more diagnostics (currently there's only testbrd.c), but we regret that we really can't help people debug their hardware remotely. Perhaps the folks who sold you the kit can offer some support; but debugging hardware problems over e-mail or the phone can be challenging. We have had some requests from people who are desperate to get their boards up, and they have sent us their boards and had them repaired, for a fee. Hopefully other people (maybe students) can offer this service cheaper than we can; but if you want us to fix your board, you can send it, along with $100 for Rev 2 + expansion board, or $75 or Rev 2 without expansion, or Rug Warrior, to the above address. I really wish I could do it cheaper, but it takes some time and I have to pay rent :( We hope you are successful in playing with robotics, and hope that IC is useful to you! Randy Sargent and Anne Wright July 29, 1994 ========================================================================== QUICK START GUIDE ========================================================================== There are 3 sections: The first is for PC users, second is for Mac users, and third is for UNIX users. Please find the appropriate section before starting :) ***************************** * QUICK START FOR PC USERS: * ***************************** 1. Installation If you're installing from floppy, simply xcopy the files to a directory "\ic" on your hard drive (c:) like so: C:\>xcopy a:*.* c:\ic Does IC specify a file name or directory name on the target (F = file, D = directory)?d (you type the "D") If you've just done this, now skip to step 2. Otherwise, find the appropriate ic zip file. Files are of the form: icVVVVr2.zip for MIT Rev 2.X LEGO Robot board OR icVVVVrw.zip for Rug Warrior VVVV is the version #. For example, ic2850r2.zip is version 2.850. The executables in the Rev 2.X vs Rug Warrior zipfiles are actually the same; just the libraries are different. If you're FTPing these files (probably from cher.media.mit.edu in pub/interactive-c), be sure to use binary mode (type "binary" if you're using a standard text-based client; other clients may have other ways of setting binary mode). Otherwise, the .zip file will probably be corrupt and won't unzip. To unzip one of these files, once it's on your PC: a) Copy the zip to the top level of your hard drive a) Type pkunzip -d ic2850rw.zip (or ic2850r2.zip) The -d is important to pkunzip to preserve the directory structure. Copy the contents of the floppy onto your hard drive, into a directory called \ic: xcopy a:\ic c:\ic /s Does BAR specify a file name or directory name on the target (F = file, D = directory)? D (you type the "D") The directory structure, when you're done, should look like this: c:\ic contains binaries (ic.exe and dl.exe) c:\ic\libs contains library files specific to your robot 2. Instructions for installing IC for use in Microsoft Windows If you want to use Microsoft Windows, be sure to copy the .pif files from \ic to your windows directory (probably \windows) like so. (Do this after step 1). copy c:\ic\*.pif c:\windows It is very important that you have the .pif correctly installed. If you have to write your own, be sure it runs in full-screen mode, with the "Exclusive" option set and "Background" option NOT set. Otherwise you will lose synchronization with the board. (You can still swap between IC and other programs, such as your editor, using Alt-Tab). 3. Getting started with IC 3.1 Downloading Pcode: You must first download the pcode interpreter to your robot board. Connect it to the computer's serial port, and type: dl pcoder22.s19 (for Rev 2.X board) OR dl pcoderwl.s19 (for Rug Warrior) If you need DL to talk to a serial port other than com1, do it like this: dl pcoder22.s19 -port com3 (You can reconfigure dl to use a different port by default by cd'ing to /ic and typing dl -config. DL will prompt you to change different parameters. This actually mutates the executable, so be sure to back up dl.exe before doing this. Just press RETURN for options you don't want to change.) DL has built-in help, if things aren't clear or aren't working. If DL doesn't work, probably your board doesn't work or the serial cable is configured improperly. The built-in help has some hints for diagnostics if you're using the MIT Rev 2.X LEGO Robot board. Once DL finishes, press the reset button and your board should beep and display a message on the LCD screen. (If you hear a beep but see no message, try adjusting the LCD contrast knob or try resetting again). 3.2 Starting IC Probably the most convenient way to run IC is under Microsoft Windows. Be SURE to read the above installation instructions for getting the pif right. You have to have a special pif installed to run IC full-screen and in exclusive mode without background processing, or you will get lose synchronization with your board. When you run under windows, you can type Alt-Tab to switch between different applications (such as your editor). Before starting IC, be sure your board is connected, and running pcode (the LCD is on and the heart is beating). By default, IC will use com1. If you need IC to use a different serial port, you can run it with arguments like so: ic -port com2 or you can cd to /ic and run "ic -config" to reconfigure ic.exe (read the earlier description for reconfiguring dl.exe). To start IC under windows, you can choose "Run" from the "File" menu in the program manager, and type IC in the dialog box. Be sure your board is already hooked up, and running pcode. If you are in plain DOS, just type "ic". If everything goes well, you should see libraries load, and get a prompt like so: C> (not to be confused with the DOS prompt) You can type any expression: C> 2+2; Returns 4 C> beep(); -- should make the board beep if it has a buzzer C> printf("Hello world!\n"); -- should print Hello world! on the LCD screen C> load music.c -- loads the music library C> { pp(); looney_tune(); } -- plays pink panther on the buzzer, followed by a cartoon song If you don't have it, you should get a copy of the IC manual. It is should have come with this software; if not, you can get a copy from cher.media.mit.edu in pub/interactive-c Your next steps might be to try some of the motor and sensor primitives, and then to start writing functions. You need to use an editor to create and edit a .c file; you can use the standard "edit" that comes with your PC, or you might have a better time with an editor which automatically indents C code and shows matching parenthesis (like the freely available emacs, or the pay software epsilon or brief). If you're in Windows, you can switch between IC and your editor using Alt-Tab; otherwise, you'll need to quit IC to enter your editor. To load (or reload) files you've written in your editor, simply type C> load filename.c from IC. Good luck using IC! Randy Sargent Anne Wright ****************************** * QUICK START FOR Mac USERS: * ****************************** 1. Installation If you're installing from a floppy distribution, simply copy it to your hard drive. Otherwise, if you have found the .sea.hqx archive file from the network, you'll need to expand it using commonly available decompression software, such as Stuffit Expander. If you're looking for the archives online, look for: ic-V.VVV-rev2.sea.hqx for MIT Rev 2.X LEGO Robot board OR ic-V.VVV-rug-warrior.sea.hqx for Rug Warrior (V.VVV is the version #) 2. Getting started with IC 2.1 Downloading Pcode: You must first download the pcode interpreter to your robot board. Connect it to the computer's serial port (modem or printer), and double click on: Init board Rev2 VVV (modem) for downloading pcode to a Rev 2.X 6.270 board connected to the modem port Init board Rev2 VVV (printer) for downloading pcode to a Rev 2.X 6.270 board connected to the printer port Init board RW VVV (modem) for downloading pcode to a Rug Warrior connected to the modem port Init board RW VVV (printer) for downloading pcode to a Rug Warrior connected to the printer port DL has built-in help, if things aren't clear or aren't working. If DL doesn't work, probably your board doesn't work or the serial cable is configured improperly. The built-in help has some hints for diagnostics if you're using the MIT Rev 2.X LEGO Robot board. Once DL finishes, press the reset button and your board should beep and display a message on the LCD screen. (If you hear a beep but see no message, try adjusting the LCD contrast knob or try resetting again). 2.2 Starting IC Before starting IC, be sure your board is connected, and running pcode (the LCD is on and the heart is beating). To start IC, double click on the appropriate application for your system: IC Rev2 VVV (modem) for running IC on ae Rev 2.X 6.270 board connected to the modem port IC Rev2 VVV (printer) for running IC on a Rev 2.X 6.270 board connected to the printer port IC RW VVV (modem) for running IC on a Rug Warrior connected to the modem port IC RW VVV (printer) for running IC on a Rug Warrior connected to the printer port If you don't have it, you should get a copy of the IC manual. It is should have come with this software; if not, you can get a copy from cher.media.mit.edu in pub/interactive-c Your next steps might be to try some of the motor and sensor primitives, and then to start writing functions. You need to use an editor to create and edit a .c file; you can use the standard "edit" that comes with your PC, or you might have a better time with an editor which automatically indents C code and shows matching parenthesis (like the freely available emacs, or the pay software epsilon or brief). If you're in Windows, you can switch between IC and your editor using Alt-Tab; otherwise, you'll need to quit IC to enter your editor. To load (or reload) files you've written in your editor, simply type C> load filename.c from IC. Good luck using IC! Randy Sargent Anne Wright ******************************* * QUICK START FOR UNIX USERS: * ******************************* 1. Installation If your platform already has binaries, you're in luck. Look in the "unix" directory, and see if there's an appropriate tar file for your host platform. The tar files contain executables, as well as libraries for both the MIT Rev 2.X LEGO Robot board and the Rug Warrior. The ic binaries tar filenames are of the form: ic-Hosttype-Versionnum.tar.Z Hosttype could be things like decstation, next-68k, sparc-sunos, etc. Versionnum is the version of IC #. For example, ic-decstation-2850.tar.Z is version 2.850 of IC. If you can't find binaries for your UNIX machine, you may be stuck trying to port IC to your UNIX platform. (If you do this and make working binaries, please send me a note and we can install them, along with the configuration files you write). Look in the "source/unix" directory and you can grab the latest source if you wish to do this. Porting shouldn't be very hard for someone with a lot of C experience. If you're FTPing these files (probably from cher.media.mit.edu in pub/interactive-c), be sure to use binary mode (type "binary" if you're using a standard text-based client; other clients may have other ways of setting binary mode). Otherwise, the .zip file will probably be corrupt and won't unzip. Assuming you've found the right binary set, and brought the .tar.Z file to your UNIX machine, do the following: (please replace ic-xxxx with the name of the file you actually got) a) uncompress ic-xxxx.tar.Z b) tar xvf ic-xxxx.tar You now have the following directory structure: ic-xxxx/bin: has ic binaries: ic: Interactive C, for both Rug Warrior and Rev 2.X boards (initially configured for rug warrior) dl : .s19 downloader for both Rug Warrior and Rev 2.X mon : monitor for 6811-based boards ic-xxxx/lib/ic: has libraries for Rev 2.X and Rug Warrior boards The next step is to put these directories in their final resting place. If you have priveliges on your machine, the best thing is probably to put the binaries in /usr/local/bin and the libraries in /usr/local/lib/ic. (The binaries come configured to expect libraries in this location). Otherwise, if you want to put the binaries and libraries somewhere else (such as in your home directory), you'll need to re-configure the ic and dl executables (but don't worry, this is quick and easy). TO INSTALL IC IN /usr/local/bin and /usr/local/lib/ic: (if you have the priveleges to do this, you probably don't need these instructions :) ) % mkdir /usr/local/lib/ic % cd ic-xxxx % cp -p bin/* /usr/local/bin % cp -rp lib/ic/* /usr/local/lib/ic TO INSTEAD INSTALL IC SOMEWHERE ELSE, SUCH AS YOUR HOME DIRECTORY: (these instructions are for putting ic in ~/bin and ~/lib/ic. If you want a different root directory, just type your directory in place of ~ for the following lines) % mkdir ~/bin (Only needed if this directory doesn't alread exist) % mkdir ~/lib (Only needed if this directory doesn't alread exist) % mkdir ~/lib/ic % cd ic-xxxx % cp -p bin/* ~/bin % cp -rp lib/ic/* /usr/local/lib/ic You'll need to read the next section on configuring ic, dl, and mon. 2. CONFIGURATION You'll want to re-configure ic and dl (and possibly mon) if you want to do any of the following things: *) Use a different default library directory *) Use a different default library file (do this if you're only using the Rug Warrior, for example). *) Use a different default serial port than the one ic and dl come with Note that all of these options can be changed with command line arguments instead; reconfiguration simply saves you from having to give arguments that are the same every time. To reconfigure these executables: cd to the directory containing the executable % cd /usr/local/bin (or ~/bin or wherever they are) % ic -config You will now be prompted to change various configuration strings in ic. You can backspace the old and change it, or simply press RETURN to keep an option the same. Here are the different options, and what they do: Default editor: emacs This option is for an old feature and no longer has any effect. Directory where libraries reside: /usr/local/lib/ic/ This is the location of your library files. If you put the libraries somewhere other than /usr/local/lib/ic, change this. Note that the path should keep a trailing '/' ! Also note that home directory expansion isn't done on this path; if you put ic in your home dir, be sure to type your entire path. That is, type "/u/username/lib/ic/" rather than "~/lib/ic/". Default library file (blank for none): /usr/local/lib/ic/lib_r22.lis This is the default library file to load. lib_r22.lis is the default library for the MIT 2.X LEGO Robot board, while lib_rw10.c is the default library for the rug warrior. Change the path on this file if you changed the location of the libraries. Default serial device name (in the form /dev/*): /dev/ttya Change this to the default serial port you'll want to use. (If you might use different ones at different times, you can just give the "-port /dev/xxx" command line argument to ic when you run it). Next, reconfigure dl: % dl -config Directory where libraries reside: /usr/local/lib/ic/ Same as for ic above. This is where dl looks for pcodexxx.s19 Default serial device name (in the form /dev/*): /dev/ttya Same as for ic above. Value to initialize config register to (hexadecimal value. 0C turns off eeprom and rom: 0C You should leave this as 0C unless you know what you're doing. Bootstrap downloader (in .s19 format): SABC .... XYZ (about 500 characters of hexadecimal). Don't change this unless you know what you're doing. This is the .s19 representation of the default initial 256-byte bootstrap string. 3. SETTING UP SERIAL PORTS Most UNIX machines are shipped with serial ports that are not, by default, readable by mere users. This is for security, in the case you connect a serial terminal (or modem) to the serial port and people log in to it. You don't want people reading what other people type in. However, for the IC system to work, the user needs to have complete access to the serial port connected to the board. Presumably, if you're connecting that serial port to the board, a terminal or other device won't be connected to that same port. To find out the security on your serial port, see if the port device is world readable and writable. (Try ls -l /dev/xxxx where you got xxxx from the configuration step above). If the port isn't world readable and writable, someone with root privelege will need to fix it. 4. Getting started with IC 4.1 Downloading Pcode: You must first download the pcode interpreter to your robot board. Connect it to the computer's serial port, and type: dl pcoder22.s19 (for Rev 2.X board) OR dl pcoderwl.s19 (for Rug Warrior) If you need DL to talk to a serial port other than the default, do it like this: dl pcoder22.s19 -port /dev/xxxx (where /dev/xxxx is the serial port you want to use) DL has built-in help, if things aren't clear or aren't working. If DL doesn't work, probably your board doesn't work or the serial cable is configured improperly. The built-in help has some hints for diagnostics if you're using the MIT Rev 2.X LEGO Robot board. Once DL finishes, press the reset button and your board should beep and display a message on the LCD screen. (If you hear a beep but see no message, try adjusting the LCD contrast knob or try resetting again). 4.2 Starting IC Before starting IC, be sure your board is connected, and running pcode (the LCD is on and the heart is beating). To start IC, type ic If you need IC to use a different serial than its default, you can run it with arguments like so: ic -port /dev/xxxx If your IC is configured for the Rev 2.X board, but you want to use it for the Rug Warrior instead, you can either reconfigure it as described above, or simply call ic with the following arguments: ic -lib /usr/local/lib/lib_rw10.c If everything goes well, you should see libraries load, and get a prompt like so: C> You can type any expression: C> 2+2; Returns 4 C> beep(); -- should make the board beep if it has a buzzer C> printf("Hello world!\n"); -- should print Hello world! on the LCD screen C> load music.c -- loads the music library C> { pp(); looney_tune(); } -- plays pink panther on the buzzer, followed by a cartoon song If you don't have it, you should get a copy of the IC manual. It is should have come with this software; if not, you can get a copy from cher.media.mit.edu in pub/interactive-c Your next steps might be to try some of the motor and sensor primitives, and then to start writing functions. You'll want to use an editor; emacs or vi are common choices. To load (or reload) files you've written in your editor, simply type C> load filename.c from IC. Good luck using IC! Randy Sargent Anne Wright