User Documentation for ON-BOARD 1. Introduction ON-BOARD is a software tool which supports the development of programs on the family of EMAC single board computers. It provides a sophisticated environment which allows the programmer to use the full capabilities of a personal computer in the development and testing of applications for the target machines. Unlike other programs of similar function, ON-BOARD does not consume valuable memory space on the target machine, so that all of its memory resources are available for programs, and not for support tools. The two main components of ON-BOARD are the Terminal program and the Editor program. The Terminal is a general purpose program which is intended to communicate with the EPAC boards, but which can be used for other communications needs. The parameters of the terminal are fully programmable, and it supports communications at baud rates up to 19200. The Editor is a full featured FORTH screen editor. This editor may be used interchangeably on screens held in the EPAC ramdisk or on screens kept in screen files on the PC. The operation of the editor in either mode is identical. It is the sophistication of the editing capabilities on the EPAC screen files which provides one of the greatest boosts to programming ease and productivity. In addition to the Terminal and Editor modes of ON-BOARD, there are numerous service functions which are provided to assist in program development. These include printer and file logging, access to DOS services, and programmable function keys. 2. Getting Started 2.1 Connecting to the board The Terminal program requires the use of only three lines on the communications port of the PC - the send line, receive line, and ground line. Consult your EPAC documentation for the proper pinouts on the board. Make sure that the transmit line of the PC is connected to the receive line of the EPAC, and vice versa. Also consult the documentation to determine how to set the default baud rate on the board. The normal setting for the word length is 7 bits, and the parity setting is normally even. 2.2 Starting the OB program The ON-BOARD program is provided on the program disk as OB.COM. Also on the program disk is a data file, KEYS.DAT for the programmable function key definitions. These programs may be run from the floppy disk drive or they may be copied to the system hard disk. To run the program, type OB. The program will load and display the introductory screen. It will also attempt to find the KEYS.DAT file and load it. Striking any key will take the program into the Terminal mode. If the default settings are correct, the EPAC system prompt will appear. If the default communications settings are not correct, it will be necessary to enter the configuration menu to set them properly. 2.3 Program restart The Ctrl-Break key combination may be used to reset the ON-BOARD program to the Terminal mode if it becomes locked into some mode. 3. The Terminal Program The Terminal program is the primary operating mode of the ON- BOARD program, and it is from this mode that all other modes of the program are entered. From the ON-BOARD terminal mode you can communicate with the EPAC board using a variety of communications parameters. Characters typed at the keyboard appear highlighted to distinguish them from characters sent from the EPAC board. At the top of the screen is a help line which identifies options which may be used at this level of the program. Each of these options is invoked using the combination of the ALT key and the first capitalized letter in the option. For instance, the exit option is invoked using Alt-X. There are two control key combinations which may be important to the user. The first is Ctrl-HOME which can be used to clear the screen. The second combination is Ctrl-@ which can be used to send a null character ( 00H ) to the EPAC board. 3.1 Alter menu In most cases, the first optional mode which should be invoked is the system configuration mode. It is referred to as the Alter mode and is invoked with the ALT-A key combination. Using this mode, you should establish the default settings which you wish to use to communicate with the EPAC board. These settings will include baud rate, word length, and parity. You should also select which COM port you will be using to communicate with the board. The size of the EPAC ramdisk should be set to the number of screens of storage on the board. Another parameter which is related to the EPAC hardware is the address of the buffer used in the downloading of text files to the board. Consult your EPAC documentation describing the DLOAD command for this value. The XON/XOFF setting is used to toggle the use of this control flow protocol. Color selection for the characters and background is performed using the cursor control keys. It should be noted that there is one default parameter, the color settings for the Editor, which are not set in the Alter menu. These colors are set in Editor mode. However, the Alter menu SAVE option will save the Editor color selections, once they have been made. The settings for the function keys is also performed from the Alter menu. The function key definitions are kept on FORTH screens and are edited using the normal FORTH editor. Details of the function keys and editing will be covered in later sections. Once all default system parameters have been set, they may be saved using the SAVE option on the menu. Finally, the ESCape key can be used to exit the Alter menu and return to Terminal mode. 3.2 DOS entry The DOS option is selected using the ALT-D key combination. It is used to return temporarily to the DOS system level. Once at this level, any normal DOS function can be performed, such as listing the directory, performing a disk format, changing the currently logged directory, etc. The terminal program can be re-entered by typing "EXIT". 3.3 EDITOR The FORTH screen editor is invoked by typing ALT-E. The editor can then be used to view, modify, or create any disk screen files or the screen files on the EPAC ramdisk. Operation of the editor will be detailed in a later section 3.4 Intel HEX dump The ALT-I key combination invokes the creation of an Intel hex dump file of the compiled program on the EPAC board. Consult the EPAC documentation for details of this operation. The user is prompted for the name of a disk file into which the hex dump will be placed. This file can later be used to burn ROM devices for the target application. 3.5 Printer logging The printer log can be activated using the ALT-P key combination. This function can be toggled on and off, and its current state is shown on the help line. When the print log is on, all data shown on the screen is also sent to the printer. Make sure that the printer is on, selected, and has paper when using this option. 3.6 Receive File The data sent to the screen can also be sent to a disk file. In some cases, this may be preferable to logging to the printer. This option is invoked using the ALT-R key combination. The user is prompted for the name of the file. The logging operation is indicated on the help line, and it may be turned off by again pressing the ALT-R key combination. 3.7 Send File Files may also be sent to the EPAC board. This option can be used to create FORTH programs using a normal text editor, and then download the files into the board. This option is invoked using the ALT-S key combination. The user is prompted for the file name. When the file is sent, no syntax checking is performed. However, normal FORTH comments are stripped out, as are any unnecessary blank spaces. The normal FORTH word for next screen, "-->", should not be included in the file. In effect, the file is loaded into memory and then compiled as if it had been typed in from the keyboard. The EPAC commands DLOAD and DLOAD/ are used to invoke the compilation once the file transfer is complete. Consult the EPAC documentation for more information on this subject. 3.8 Exit ON-BOARD Exiting the terminal program to return to DOS is performed by typing ALT-X. 4. The Screen Editor Menu When the editor menu is entered from the terminal program, the screen is logically divided into three sections. The upper left section shows status information such as the file currently selected for editing. The upper right shows the command line awaiting selection of a function. The lower part of the screen shows the available commands, using a format similar to the Alter menu. The "U" function is usually first chosen to select the file you wish to edit. A helpful command in remembering what files are available is the "D" command, which lists files in the currently logged directory. The file used to select the EPAC ramdisk screen file is "BOARD". The editor can then be entered with the "E" function, which will prompt the user for the first screen to be edited. On the EPAC board, screen 1 is the lowest screen available; on normal screen files, screen 0 is also available. Consult your EPAC documentation on the use of ramdisk screen files. Following is a brief description of the functions available from the editor menu: 4.1 Color selection The cursor keys are used to select the colors used for foreground and background while in the editor. Once these colors have been selected, they may be saved as default colors by using the SAVE function available in the Alter menu. 4.2 Copy single screen The COPY function allows the contents of a screen to be copied to another screen in the file. 4.3 Disk directory The DIRECTORY function will display all files currently in the logged directory. 4.4 Edit screen The EDIT function places you in the FORTH screen editor. The commands available in the editor can be displayed using the F1 key. These commands group logically into nine groups. The functions are generally self-explanatory. The nine groups include: 4.5 Transfer screens from board to disk The TRANSFER command is used to copy screens from the EPAC ramdisk to a screens file on the PC. The user must currently be USING the disk file to which the screens are to be transferred. 4.6 Transfer screen to board from disk The FROM command is used to copy screens to the EPAC ramdisk from a screens file on the PC. The user must currently be USING the disk file from which the screens are to be transferred. 4.7 Index to screen file The INDEX function provides a shorthand notation for viewing the contents of the screens in the file. It displays a portion of the first line in each screen. This line is traditionally used as a comment line, and it describes what is on the screen. 4.8 Multi-screen transfer The MULTI-SCREEN TRANSFER function operates similarly to the COPY command except that multiple screens will be moved. The user is prompted for source and destination information. 4.9 Auto date/time stamp The AUTO function is used to provide an automatic stamp on each screen as it is edited. The top line of the screen is stamped with a comment field that includes time and date. The user is also prompted for up to three alphanumeric initials which are also put in the stamp. The autostamp feature may be toggled on and off with this command. 4.10 Use new screen file The USE function selects the file to be edited. The special file "BOARD" is reserved to refer to the EPAC ramdisk file. For normal disk files, if no file extension is used, the default extension .SCR will be used. 4.11 Printing screens The PRINT commands will print screens of the currently selected file to the system printer. The user is prompted for which screens to print. Printing is available in two formats. The "3" function will print three screens to a page. The "6" function will print six compressed screens to a page on those printers, such as EPSON, which have a compatible compressed print mode command. 4.12 ESCape to TERMINAL mode The ESCape function is used to return to the terminal mode of ON- BOARD. 5. Editing commands The editor provided in ON-BOARD is a full featured FORTH screen editor, originally developed by Laboratory Microsystems, which operates identically on EPAC ramdisk screens and PC screen files. It includes numerous editing commands including search and replace, automatic date & time stamping, etc. It also provides numerous support services such as screen printing, screen moving, etc. Once in the editor, movement through the screens can be accomplished with the PGUP and PGDN keys on the keyboard. While in the editor, you may type input in INSERT mode or OVERTYPE mode. The selection is made with the INS key, and the current status is shown in the upper right section of the screen. At the bottom of the screen is a help line showing the current settings of the function keys. Help is available using the F1 function key. It is important to understand the fundamentals of how the editor modifies screens. Once a screen has been modified, if the editor is exited using the ESCape key or if another screen is selected, the current screen is automatically updated! If you have changed a screen and wish to leave it as you found it, the F10 key will restore it to its original condition - but only if you use the F10 key before you leave that screen. If you are prone to changing screens and then changing your mind, it would probably be a good idea to backup your ramdisk screens to a file on the PC. This is done using the "F" function on the editor menu. There is one exception to the operation of editor commands on the EPAC board and disk files. The insert/delete screens functions have been disabled on the board. This is because they are fairly time consuming and are better handled in a disk screen file. In fact, it may be speedier for you to develop your applications on a disk file and then transfer it to the EPAC board using the "T" command of the editor. Following is a description of the various editing commands which are available: 5.1 Cursor control functions ARROW KEYS move the cursor as they indicate HOME go to start of screen END go to end of line Ctrl-END to to end of screen 5.2 Tabbing commands TAB/Shift-TAB move to next (previous)tab stop. if at last stop on line,move to next line (previous line) Ctrl-L/R ARROW move to next (previous) word 5.3 Search & Replace commands F7 search for specified string. interrupt search by pressing any key F8 find and replace string. replacement string must not be longer than search string. interrupt replace operation by pressing any key. Ctrl-L repeat previous search 5.4 Delete commands for characters, words, and lines DEL delete character under cursor, move rest of line left BKSPC destructive backspace - back up and erase char Ctrl-T delete word to right of cursor Ctrl-Y delete line, moving up subsequent lines 5.5 Erase commands for clearing parts of lines and screens F9 erase entire screen Alt-F9 erase from cursor position to end of screen Ctrl-U erase all text on current line Alt-U erase from cursor position to end of line 5.6 Insert commands INSert toggle insert/overtype mode Ctrl-N insert a blank line moving subsequent lines down. last line is lost Alt-N split line at cursor and push right half down to next line Ctrl-W insert space at cursor shifting other characters right. only current line affected 5.7 Screen control commands PgUp write current screen and go to previous screen PgDn write current screen and to to next screen Ctrl-PgUp go to start of file Ctrl-PgDn go to end of file 5.8 Line Stack commands F3 copy current line to line stack. stack will hold 16 lines. top line of stack and depth are displayed. cursor moves to next line F4 push current line on stack and delete from screen F5 pop top line on stack to line where cursor is. current screen line is overwritten F6 pop top line on stack to line where cursor is, but push down current and subsequent lines. Ctrl-K delete contents of line stack 5.9 Special commands Ctrl-J join lines. bring as many words as possible from next line onto current line, then left align the next line. If next line is blank, delete it. Alt - delete current screen ( screen files only ) Alt n insert n blank screens. n is 1-9. ( screen files only ). F1 help screen. display editor commands F2 date/time stamp current screen. works independent of auto-stamp command F10 restore screen, discarding all changes ESCape exit editor to edit command menu 6. Function Key Programming The function keys may be programmed for use within the terminal mode of ON-BOARD. There are two program modes, one which sends commands to the EPAC board and one which executes DOS commands. The first set of commands is activated using the function keys and the second set is activated using the Ctrl key with the function keys. Each screen may be used to program ten function keys, F1-F10, using lines 1 through 10 of each screen. The user programmed data for the function key definitions is kept in a special screen file called KEYS.DAT. This file is edited from the Alter menu. Editing is performed using the FORTH screen editor. The definitions for the commands to be sent to the EPAC board are kept on screen 1 and the DOS commands are kept on screen 2. Screen 0 of this file is used for instructions. As an example of how these keys may be used, the function key F1 might be programmed to send the string "VLIST" to list the words in the vocabulary. Another use might be the string " FORGET TASK 1 LOAD ", which could be used in recompiling a set of screens. The special character "~" may be used on the line containing the function key definition to indicate a carriage return. For example the string " : TEST ." hello there" ; ~ 1 2 + . ~ TEST " could be used to compile the definition for TEST, print the sum of 1 and 2, and then execute the word TEST. In the case of the DOS commands, Ctrl-F1 might be programmed as " PCWRITE " to start up a word processor.