readme.txt

example of communication between the Cerebellum 16f877 pic board and the CMUcam

****Note, this readme file is meant for users at CMU.  Those of
you at CMU have access to not only the cerebv?.c and cerebv?.h files,
but also to install disks of C2C, Fpp, and other programs.  If you
are outside CMU and have downloaded this zip file, you will have to
get these installations mentioned below yourself.  You will also
have to work out your own license key for C2C.****


CerebDist4.1 July 16, 2003
Added (thanks to Rashmi Patel and Tom Lauwers) i2c support!

CerebDist2.4 April 25, 2003
Updated cerebv2 to create cerebv3.c. Same .h file, but
serial receive non-block now does the right thing if there
is an overflow or framing error. The earlier version (cerebv2)
had the problem that, given a very large number of input characters,
overflow could cause blocking receive to block indefinitely
after several receive non-block actions. This is fixed now.
In addition, the lights YELLOW and GREEN were accidentally 
swapped and are fixed now.


CerebDist2.3 April 2, 2003
Updated Diagnostic program example, which had software
errors causing only 1 motor to work and swapping the two
LEDs

CerebDist2.2 March 2003
This version provides a useful Diagnostic program.


This README will describe how to install the Microchip MPLAB 
free software- because we want its assembler; then how to 
install the C2C shareware compiler- because we want to code in c.
Finally, I'll describe how to set up C2C for our sample project,
view the API I provide, and start hacking PIC code from there.

INSTALLING MPLAB

The installer is in the Microchip Assembler folder. Double
click to unzip and then launch the EXE program. On the
Select Components window, you need the
MPASM assembler, so you can un-check all else if you are low
on memory.  On the Select Language Components leave all
checked.  The rest of the selections are up to your own
preference.

Once installation is finished, the key information you need
is the complete location of mpasm.exe. For instance in my
installation: C:\Program Files\MPLAB\Mpasm.exe

INSTALLING FPP

FPP is your downloader program.  A folder in this zip
contains the FPP installer.  Look also for the document
called "FPPSetup."  It will teach you how to set up FPP
so that it works.  Note especially that you must change
the value in one of the fields of FPP.exe if this is the
first time you are downloading to a particular Cerebellum.

INSTALLING C2C

The installer is in the C2CCompiler directory. Double
click to unzip then launch the EXE program. Click through 
to do a normal installation.  I recommend you just use
the version 4.1.7e of C2C.

SETTING UP C2C

Launch the C2C-plus IDEA, C2Cw. You can reach it from
your START/C2C launcher for example.
From the Menubar select Project..Target (or Settings..Target)
and select PIC16F877
Now select Options..Options (or Options..Tools)
and note the default Assembler
call.  Change only the executable name (not the options!)
from mpasmwin.exe to the complete path of mpasm.exe on
your machine, then click OK.

If you've lost the assembler options, here they are:


c:\program files\mplab\mpasm.exe /aINHX8M /p16F877 /rHEX /w2 /q

(this is for my particular XP machine, for instance...)

If you are in a class at the RI using C2C educationally (i.e.
as part of the REL) we have a site license you can use for
your C2C installation.  In separate mail you should get the
site license key for our courses.  If in doubt, contact Illah
Nourbakhsh.

THE CEREB API

Now that C2C is all set up, you can try compiling the
Cereb API and a simple demo program. In the folder,
SimpleSample you will find three files: cerebv41.h, 
cerebv1.c and samplecereb.c.  Copy all three to a folder
on your computer.  Note that you will always want
to have copies of cereb.c and cereb.h in the same 
folder as your working program. Make sure you
select all these files, right-click, and ensure
that they are *not* read-only files.

Inside C2C open samplecereb.c and cerebv41.c.

Scroll to the top of samplecereb.c. Note that this explicitly
includes cerebv41.h and cerebv41.c using "include" directives.

These files implement the
API that is described in cerebv41.c.  And this
API implements the functions you will be using to program
Cerebellum.  You should virtually never need to modify
the contents of cerebv41.h or cerebv41.c.

Scroll further and examine the two functions in samplecereb.c.
Main() performs initialization and then goes on to call
button_sample.  You will usually use Main as-is, subject
to what the API description says about commenting out
initializations you do not need.

Button_sample blinks the yellow light always, and also
blinks the green light whenever Button2 is held down.
In addition, when the button is held down, it servoes
Servo 1 (not Servo 0!) from position 100 gradually to
lower and lower values.  Additionally, it reads
Analog input ADC7 (labeled E2 on the Cerebellum board,
as described in the API) and prints out the result.
Finally, it tries to read a character from the serial
port, non-blocking, and lets you know if it succeeded
or not.

Now let's compile and assemble.  Be sure the window 
you've selected is samplecereb.c (not cerebv41.c-- it does not
have a Main()). Select Compile..Build.
Build both compiles and assembles (if compilation was
successful).  YOu will get some warning messages and,
if Build is successful, you now have samplecerebv2.hex in
the same directory, ready for fpp - download to
your Cerebellum.  It may be necessary to first 
create a project comprised of the primary .c file
in order for compiling to work.

Now you can download (using FPP), and then watch the 
button_sample code in action; 
Translation: plug a servo into D1 on Cerebellum (remember,
ground is out) and execute this program, then hold down
button 2 and watch the servo creep.

Remember, if you want to try out the serial port also,
you should close the fpp program (it is using Com1)
and open up Hypertrm, Teraterm or some other program at
115200 baud.


DIAGNOSTIC EXAMPLE

In the folder CerebDiagnostics you will find a project,
diag.c, that implements a nice menu-driven ascii interface
on Cerebellum for testing and measuring using all of its
I/O.  This is an extremely good way of testing the analog
inputs, identifying ranges for servoes you wish to use, and
even identifying desirable ranges for duty cycles to the
motors you wish to use.  In the folder, you will find a
.rtf (rich text format) file that you can open from
Word.  This instructions file provides instructions for
you on how to run the code.  This compiles just fine using
C2Cw, version 4.1.7e.

I2C COMMUNICATION

In the folder "Sonari2cSample" you will find a sample
program that talks to a Devantech sonar ranger using
i2c communication.  This is a good way to begin exploring
the use of i2c devices.  Look at comments at the top of the
sample file, sonar.c.


CMUCAM COMMUNICATION

In the folder "CMUCamSample" there is a source file,
fisheyev3.c, that demonstrates Cerebellum communicating
with CMUcam rapidly.  This program is designed for execution
on a CMUcam-based robotic sculpture that consists of pan and
tilt axes for CMUcam, plus a Sharp infrared rangefinder 
mounted just above CMUcam.  When the rangefinder goes short
ordinarily, the CMUcam jiggles.  It also does so when the
lighting changes significantly (i.e. someone turns on the 
lights).  At other times, when it is "awake," the sculpture
searches for a color that can be tracked, then tracks that
color with CMUcam and servoes its head to follow it around.

To connect CMUcam to Cerebellum, build a serial cable that
swaps Transmit and Receive (pins 2 and 4 I believe) or use a 
null modem converter.  This is important since CMUcam and 
Cerebellum both ordinarily talk to a computer; so to talk 
to one-another you must deal with the null modem issue.

In "fisheyev3.c" you will find certain functions 
particularly educational and useful in your own work:

setupCam() resets CMUcam and then sets parameters like
gain and white balance appropriately.  Note the try-again
mentality in the code, and the fact that the response is
checked for "ACK" using the 'A' (as opposed to "NCK"). 
This function is robust because it keeps trying again and
again, and provides good feedback in the end by turning on
the green LED.

The functions start_gm(), gm_parse() and stop_stream() 
show how you can start a non-poll-mode stream from CMUcam
and make use of it in Cerebellum. This works equally well
for tracking objects, not just for get-mean calls.  Also,
take a look at clamp() and autogainon().