---------------------------------------------------------------------------
Anonymous FTP server:	cher.media.mit.edu (18.85.0.47)
This file:		pub/interactive-c/README
Last updated:		Fri Jul 29 14:20:28 1994
Maintained by:          Randy Sargent (rsargent@media.mit.edu)
---------------------------------------------------------------------------

INTRODUCTION TO IC:

This directory 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.

The currently available free version of IC is 2.850.

Status of binaries for different platforms, as of 7/29/94:

IBM PC:                2.851 beta test.  (Please send bugs to 
	                                rsargent@media.mit.edu)
Macintosh:             2.850 will be available some time the week of 8/1/94.
                       Currently available is a port of 2.6x 
                           from folks on the net.
Sparc running SunOS:   2.850
Sparc running Solaris: 2.850
DECstation:            2.850
NeXT:                  2.850 will be available some time the week of 8/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

First, 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


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 <int> 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: *
******************************

Will arrive the week of 8/1/94


*******************************
* 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 <int> 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

