




                        F1 Controller Software Library
                            for Imagecraft's ICC11
                               'C' Compiler V4.0+

                               by Pete Dunster

                        Adapted from Miniboard Library
                           written by Chuck McManis

                                 1st Feb 1999

Introduction

This is a library of software routines for the F1 controller board to be used
with ICC11 v4.0 or later. There are routines to control most of the features of
the board and its interface boards and includes set-up files to allow
generation of code to run in RAM or to be burned into EPROM. All the source
code is provided, as well as the means to re-build the library. I have also
included several test programs, both in source code and in .s19 compiled form,
to serve as examples of  how the software used, as well as to test the
hardware.

Installation

This installation assumes you have already installed ICC11 on your hard disk in
a directory called ICC11, if you have installed it to a different directory
substitute your directory for "ICC11" in the following.
To install the library, create a directory called LIBF1 in the ICC11 directory
and into it copy the libf1v4.zip file. You can now unzip the file with Pkunzip,
but be sure to use the "-d" option to re-create the directories:
          pkunzip -d libf1
This will create several sub-directories and fill them with files. To complete
the installation type "instalf1", this will copy the files into the correct
directories and it will be ready for use. 
If you wish to do it manually you should do the following:

1)    Copy the LIBF1\SRC\*.h files to the INCLUDE directory.
2)    Copy the STARTUP.O and LIBF1\SRC\*.a files to the LIB directory
3)    Copy ICCF1SET.BAT and ICCEPSET.BAT files to ICC11 directory.
4)    For DOS usage modify the batch files in 3) to reflect your icc11 directory (if other 
	than c:\icc11).

Using under DOS,

You are now almost ready to start compiling programs, the final step is to set
up the linker directives, and must be done before each session with the
compiler. This is done by running either of the batch files just copied into
the ICC11 directory. If you want to compile programs to run in RAM run the
ICCF1SET.BAT file, or if you want to compile the programs to put into EPROM you
should run the ICCEPSET.BAT file. These files set the linker to compile the
code and reset vectors for the correct areas for the respective options.

Compiling programs

As previously mentioned, the first thing to do on starting a new session with
the compiler is to set up the linker environment for the correct device, this
is done n the ICC11 root directory. If you are compiling programs to run in the
RAM area type ICCF1SET, conversely, if you want to compile your program to burn
into an EPROM you should type ICCEPSET.
When you compile your program you have to include the F1 library, this is done
by including it in the options at the command line, and differs for RAM and
EPROM versions. If you are compiling for ram you use the -lf1 option, for EPROM
use -lfe. For example:
    For RAM ...type ICC11 [prog.c] -lf1
    For EPROM ...type ICC11 [prog.c] -lfe
This will create a file in your directory of the same name but with a .s19
extension, which is ready for downloading to your F1 board or EPROM.

Windows version

To get started in the Windows IDE you will need to set the Compiler, Linker and 
target options. Firstly go to the Options menu and select "Compiler", then select
the Linker options. In this section set the Text area to 0x2000, Stack to 0xfff
and no Heap. Uncheck the "No Startup File" option and write "libf1" in the Other 
Libraries field. Finally write "bss:0x00 reset_vectors:0x7e00" in the space for
"Other Sections Addresses"
In the Target menu click on Terminal, this will allow you to download programs
via the terminal instead of bootstrap programming modes. You are now ready to write
and compile your programs.

Downloading Programs

DOS

For normal RAM operation the linker will generate code starting at address
0x2000, so once you have compiled the program and have the .s19 file this can
be downloaded to the board with any terminal emulation program, Telix (Dos) or
Terminal(Windows) are the most common. You should set your program to 9600
Baud, 8 data, 1 stop and No parity. Do NOT use dlm.exe for this as this was
designed for the 68HC811E2FN chip and will not work on the F1 board. Once the
terminal program is running and talking to the F1 board's BUFFALO monitor, i.e.
you have a ">" prompt, you can tell the F1 to accept the new program. This is
done by typing "load t" (Load from terminal) and pressing enter, you can now
send the file as a normal ASCII transfer. Once the program is downloaded type
"G 2000" to run the program.

Windows

Once you have finished your program and compiled it without any errors you can
download your program by invoking the terminal. With the terminal window open you 
should press the reset button on the F1 board to get the usual Buffalo message, 
then press Enter to get the > prompt. From here just type "load t" and press the 
ASCII Download button below the terminal window. If you have not previously downloaded
a program before it will allow you to browse for the file to download, otherwise it
will immediately download your program with a progress indicator displayed. When this
is complete you should see Done appear on the terminal, just type "G 2000" and your
program will run.
 

Credits

A great deal of thanks are due to  Chuck McManis, for doing such a great job in
writing the miniboard library for ICC11, and for giving me permission to adapt
it for the F1 board. To Fred Martin of the MIT on whose concept as well as a
lot of the hardware and software of this work was based, as well as for giving
me an ftp site by making space for me on cherupakha.  Also to Richard Mann for
making such a good  'C' compiler available at such reasonable cost, and to
Phillip Musumeci for giving me an Australian ftp site on mirriwinni.adfa.oz.au.



                                  The Library

Structure

This library has been set up so as to only include those sections of the code
as is specifically needed, both to cut down on the size of the final program
and the compile time. However it is up to the user to define which part of the
library are to be included. This is done with a series of "WANT_xxxx"
statements to be defined at the start of your program. These statements are as
follows:
    WANT_LCD        Include LCD screen functions
    WANT_KEYBD      Include Keypad handlers and set up interrupts.
    WANT_MOTORS     Include motor drivers and set up interupt routines.
    WANT_SERVOS     Include Servo-motor routines and set up interrupts
    WANT_PACKET     Implement "packet protocol" software and set up SCI
                    interupt.
    DO_USERINT Allows for user defined routine to be called every 1msec.
These are used with the #define compiler directive, i.e.
     #define WANT_LCD         /* include LCD functions  */
and should be placed at the start of your program before any #include
statements.

Following the #define statements must come the header files for the F1 library,
these are:
     #include <f1board.h>
     #include <f1intsvc.h>
To use the F1 library both these lines must be used. After these can start your
program with the "main()" function. For further examples look at any of the C
programs in the LIBF1\PROGS directory.


LCD routines

Enabled with  #define WANT_LCD

To enable the output to the LCD screen I included an output switch select in
software to enable the user to use the various print functions either to the
SCI port or the LCD screen. This switch is set with a command called io_sel(),
io_sel(0) selects the SCI port as an output device and io_sel(1) selects the
LCD. This function may be called as many times in a program as desired.
The included LCD screen functions are:

    init_lcd() Initialise the LCD screen
    cls_lcd()  LCD clear screen function.
    io_sel(int)     A 0 or a 1 sent to this function switch the output between
               the SCI (serial port) and the LCD screen respectively, enabling
               all output functions such as printf(), puts() etc. to use the
               LCD for display.
    cursoron() Turn on blinking cursor
    cursor_off()    Turn off blinking cursor


Keypad routines

Enabled with #define WANT_KEYBD

The keypad routines implemented here use an interupt routine to detect the
keypress, read the value of the keypress and then get the required character
from a lookup table.
Functions available are:

    kbhit()         Returns non-zero if a key has been pressed.
    getkey()   Returns the keypad character pressed and resets the kbhit()
    function.



Motor routines

Enabled with   #define WANT_MOTORS
and       #define MOTOR_ADR  0x18XX

If you have a motor board hooked up to your F1 you will no doubt want to use
the motor drivers. The motor functions are identical to those used on the
miniboard, the only exception being the address of the motor drivers which on
the miniboard are fixed, not so on the F1. To use the motor drivers therefore
you must also include its address as another #define statement. This is done
with a #define MOTOR_ADR 0xXXXX instruction, also at the start of your program.
The address of the motor driver depends on the position of the jumper used for
address selecting, this table should help:
     JP3       0x180B
     JP4       0x1814
     JP5       0x1824
     JP6       0x1844
     JP7       0x1804
Once that is done the rest is easy, the functions are:

    motor(m, s)          sets motor m to run at speed s. Speed range  -16 to
    +16.
    motoroff(m)          Turns motor m off.


Servo Motors

Enabled with   #define WANT_SERVOS

These functions control up to 3 servo motors connected to the extended Port A
pins PA5-PA7on JP1 of the motor board, or just from the Port A socket on the F1
controller board. Small servo motors can connect directly on to JP2 of the
motor board, from the F1 controller the 5v and Gnd must be supplied separately.
The functions for controlling the servos are:

    servo(m, p)          Move servo number m to position p, where p is -100 to
    100.
    servo_off(m)         Turn off servo number m.


Packet handler

Enabled with   #define WANT_PACKET

 I have had several applications now in which I have needed to implement a
simple means to receive instructions or parameters from a host computer without
stopping the running program, or spend time watching the SCI status register As
it has proved to be so useful to me I thought it could well be useful to
others, so I have included it here. When WANT_PACKET is defined the SCI
interupt is enabled, the interupt routine receives all the characters and puts
them  into a 100 char array called inbuffer, all the while checking for a CR
(0x0d) character. When it receives a CR it sets a flag in the form of a global
variable called "packet". When this system is implemented, to handle the packet
all you need is:

     if(packet) {
           ...read packet ....
           ...clrbuff()} 

After you have finished with the packet you must call the function clrbuff() to
reset the flags and pointers ready for the next packet.  Check out the program
packtest.c in the libf1\progs directory.


Analog inputs

This routine is taken straight from the miniboard and does not need any define
statements to be able to use it ....yet! (I am thinking of implementing it so
the A/D system can normally be turned off if not needed, saving current) This
routine just returns the value present at the specified port pin:

     analog(n)      Read the value of analog n, where n = Port E pins 0-7 .



Eeprom writing

As the programs on the F1 do not reside in the Eeprom it can be used for any
other long term memory storage applications. Reading the Eeprom is easily done
with peek and peekw, but writing is another matter. These functions will get
over that.

     ewrite(a, n)        Write byte n into address a.
     ewritew(a, n)       Write word n into address a & a+1.

*





