Terminal Emulator Code

[Jake M]

Somewhere in Sophomore year, I discovered that you could communicate with the robot via the program port and IFI_Loader's Terminal Window. I said to myself, "I wish there was an easy way to use this feature." Well, over the offseason Junior year, I wrote this code. At this year's 2008 competition, this terminal is what enabled me to modify or completely disable our autonomous routine in about 30 seconds before each match.

I hope Kevin Watson won't get angry at me for "borrowing" his .c/.h/_reamdme format. With the terminal files, I've included a file called calibration.c, which is a piece of this year's code. It contains my own implementation of the terminal.c code, to serve as an example. It's huge and overwhelming at first glance and you won't be able to run and test it, but at the moment, it's the only example I have. Making an actual, runnable, simplified example version is on my To-Do List.

The files are uploaded here as a Whitepaper. In the true Kevin Watson fashion, here's the readme.

****************************************************************

You are free to use this source code for any non-commercial
use. Please do not make copies of this source code, modified
or un-modified, publicly available on the internet or
elsewhere without permission. Thanks.

Copyright (I wish) 2007-2008 by Jake Meiergerd, of FRC Team 1178

****************************************************************
The source code in terminal.c/.h contains software to emulate an
interactive, DOS-style computer terminal in the background of
the FIRST Robot Controller. It enables the user to very easily
make modifications to software and software parameters at
runtime, both before and after compiling. What I mean by that is
that setting up a sequence of terminal menus in code is designed
to be just as quick and self-explanatory as using the actual
terminal during runtime. 

This software makes the assumption that when it's running, it 
solely controls the serial port software and hardware. 

This source code will work with any robot controller that has
similar software routines for handling serial communication.

****************************************************************

Nine things must be done before this software will work 
correctly with your robot controller:

1) A #include statement for the terminal.h header file must be 
included at the beginning of each source file that calls the 
functions in terminal.c. The statement should look like this: 
#include "terminal.h".

2) Reset_Terminal() must be called somewhere within your code, 
so that it will be called once during each program loop. It
should be placed so that within each loop, it is the first
terminal.c/.h routine to be called. I place it within
Process_Data_From_Master_uP(), right after the call to
Getdata().

3) You must define TERMINAL_PORT as SERIAL_PORT_ONE or
SERIAL_PORT_TWO. If you don't use Kevin Watson's serial port
code, or if you have more than two ports available and want to
use them, you will have to modify terminal.h slightly. Scroll
down to the #if TERMINAL_PORT == SERIAL_PORT_ONE statement and
read the comments there. It should be self-explanatory.

3) Somewhere within Initialization, you must ensure that the
standard output or default output serial channel is set to the
same serial channel that you're using for the terminal. With
Kevin's serial port code, this simply involves the line
stdout_serial_port = TERMINAL_PORT;
somewhere in initialization. With other serial communication
handlers, you probably do not want to use TERMINAL_PORT the
way it is used above.

4) You must set the number of times that your code will call
a routine that reads from the serial port (T_Read() or
T_Read_Int()), through the definition of READ_CALLS within
terminal.h. Ideally this defined number is the exact number of
times you call either T_Read() or T_Read_Int() within your
code. Practically, I would set it at a very high number (such
as 100) while you are in development stages. When you are 
satisfied that you won't be adding many more reading calls, 
go through and count exactly how many there are. READ_CALLS
can be more than the actual number of calls, but if it is less
the terminal code will malfunction, though you may not notice
it.

****************************************************************


Here's a description of the functions in terminal.c:

void Reset_Terminal(void);

This routine might make more sense if it was named
Terminal_Handler(), but I named it Reset_Terminal() based on how
the terminal actually runs interally. Reset_Terminal() actually
resets the iterator that walks through an array of bools as the
terminal progresses through whithin your code. Take a closer look
at the source code itself for more details.


bool T_IsWaiting(void);

Returns a boolean value, 1 if the terminal is waiting on input
somewhere, 0 if it is not. Used by Writing routines to determine
if it is okay to send output to the terminal, and can be used by
you, the user, to decide if you should progress to the next menu
in your terminal. See my example terminal for details.


void T_Exit(void);

Forces the terminal to completely reset and start over from
scratch. Good for switching between two different terminals, say
one for normal operation and one for autonomous mode.


void T_Read(byte*);

Reads a single byte of data from the terminal port.


void T_Read_Int(int*);

Empties the terminal port buffer and interprets whatever's there
as an interger value.


void T_Flush(void);

Empties the terminal port. Period.


void T_Write(byte data);

Sends a single byte of data to the terminal port.


void T_Write_Int(int data);

Writes an interger value to the terminal port.


#define T_Print(a) if(!T_IsWaiting()) {printf((char*)a);}

Designed to function just like printf(). Use it so.


void T_Separator(void);

Just a simple way to send a separating line to the port.


Jake Meiergerd, of FRC Team 1178
jakenveina@yahoo.com