This article contains a short tutorial on setting up the ForthTerm terminal program as a console for an MV4th16 target Propeller chip system. The latest version of the ForthTerm terminal program can be found in the ForthTerm Downloads section of the web site.
ForthTerm options dialog.
Once ForthTerm is installed start the program and select the main menu command "Settings --> Options". This will show the main options dialog. The dialog has a number of tabbed pages, we will examine each of the option setting and provide recommended option values. After changes are made the options will not be saved until the ForthTerm program closes.
Terminal option settings tab page.
Background Color: The color used for the terminal display background color, set to what ever color works best for you.
Text Normal Color: The color used for the terminal display font color, set to what ever color works best for you.
Font Button: Select the font face (family) and font sized used by the terminal display. Only mono-spaced fonts can be used.
Columns: Number of columns displayed by the terminal display. The default is 80 the maximum is 255.
Rows: Number of rows displayed by the terminal display. The default is 200 the maximum is 200.
Tab Size: this setting is use by the terminal display to expand displayed tab characters, the default is 8.
Paste line delay: This setting is used to add a delay after each line of text is pasted in to the terminal display when you use the Paste clipboard or paste file command. If you are pasting Forth source code into the terminal display a value from 120 ms to 200 ms should be used. When the MV4th16 "Fast Find" code is loaded on the target system the delay can be set to 20 ms and on some target systems a value as low as 10 ms will work.
Abort Paste on Forth Error: When enabled ForthTerm attempts to detect an error condition on the target system and will stop sending text to the target system if an error condition is detected. An error condition is assumed to be a line returned from the target system that end is a "?" question mark followed by a CR control char.
Terminal Command Codes settings
ASCII Control Chars: The ForthTerm terminal display responds to an expanded control character command set based on the Parallax serial terminal program. Control characters that are enabled have a green arrow beside them, and disabled control codes have a red arrow beside them. Use your mouse to toggle the state of a given control code character. For normal operation with MV4th16 all control characters except "(0) Clear screen" should be enabled. MV4th16 uses the "(16) Clear screen" control code to clear the terminal display.
Carriage return = New line: When enabled a carriage return (13) control character sent to the terminal will display as though a carriage return and line feed character (13,10) combination was received. When the option is disabled a carriage return will only return the terminal cursor to the start of the same terminal display row. The default for use with MV4th16 is to disable this option.
Erase character on backspace: When enabled a backspace control character will cause the terminal display cursor to reverse one character column and set the character at the new cursor position to a blank/space character. When this option is disabled a backspace control character will move the cursor back one column on the current row leaving the original character displayed. For use with MV4th16 this option should be enabled.
Terminal Com Port Settings
Com Port: Setting is used to select the Windows PC Com Port number (0..255) used when the terminal is connected to a serial port. If you click on the "..." button beside the com port selection box a list of installed serial Com port devices will be shown. Select the com port device connected to the targets RX/TX signal lines on the target Propeller system.
Baud Rate: Used to set the bit rate used when the terminal display is connected to a com port device. The drop down list contains most of the standard baud rate values. The default value for an MV4th16 target system is 115,200 bits per second.
Data bits: Setting is used to set the number of data bits per character sent or received. MV4th16 used a default value of 8 data bits per character.
Stop bits: Setting is used to set the number of stop bits appended to the end of characters sent or received. MV4th16 uses a default value of 1 stop bit per character.
Parity: Setting is used to select if a parity bit is appended to the end of character data bits sent or received. MV4th16 uses a default value of "None" for parity.
Hardware Flow Control, DTR: This setting allows the PC serial port DTR signal to be set. You can "Enable" or "Disable" the com port DTR signal or set the signal to indicate if there is room in the serial com port FIFO for more data, this is "Handshake" mode. This setting should be set to "Disabled" for use with MV4th16 when the target system uses the DTR signal to reset the Propeller chip.
Hardware Flow Control, RTS: This setting allows the PC serial port RTS signal to be set. You can "Enable" or "Disable" the com port RTS signal or set the signal to indicate if there is room in the serial com port FIFO for more data, this is "Handshake" mode. This setting should be set to "Disabled" for use with MV4th16 when the target system uses the RTS signal to reset the Propeller chip.
Hardware Flow Control, DSR Flow: When enabled the serial com port will only transmit data if the com port DSR pin is held low (logic level). This can be used to prevent a connected target device from being over run by data sent out the PC com port to the target serial port. The default setting for use with MV4th16 is to disable this option.
Hardware Flow Control, CTS Flow: When enabled the serial com port will only transmit data if the com port CTS pin is held low (logic level). This can be used to prevent a connected target device from being over run by data sent out the PC com port. The default setting for use with MV4th16 is to disable this option.
Software Flow Control, TX Flow: Use the Xon and Xoff control characters specified in Xon Char and Xoff Char options to control the data flow when transmitting data out the PC serial com port. This option should only be used with ASCII or ANSI data streams. MV4th16 sends/receives binary data so this option should always be disabled.
Software Flow Control, RX Flow: Use the Xon and Xoff control characters specified in Xon Char and Xoff Char options to control the data flow when receiving data from a target system using the serial com port. This option should only be used with ASCII or ANSI data streams. MV4th16 sends/receives binary data so this option should always be disabled.
Set Windows Defaults: Selecting this button will copy the serial com port settings to the Windows registry to be used as the default setting for the selected com port. The windows default com port settings are used when a com port is activated for the first time. ForthTerm will always use the settings configured in the Com port settings page when opening a serial com port.
Code Editor Config Page
Font Button: Select the font face (family) and font size used by the code editor. Only mono-spaced fonts can be used.
Tab Size: Tab Size is used to set the tab size in space characters for the code editor. A setting of 2 works best for me. If the "Auto Indent" feature is enabled in the code editor it will override the Tab Size setting.
Max Numeric Base: Used by the syntax highlighting engine to differentiate between a numeric constant and a forth word token. A value of 16 for base 16 (hex) works best for me.
A word about syntax highlighting: As I found out it is not possible to syntax highlight Forth. Forth source code is composed of a sting of tokens separated by white space. Any token can represent any Forth word and all Forth words can be overridden and redefined. As an example in MV4th16 the number zero, 0 is a built in forth word not a numeric string constant. That being said I find the syntax highlighting useful enough that I leave it enabled. The image above shows the color setting I am currently using. The Use Syntax Highlighting check box can be used to enable and disable syntax code highlighting in the code editor.
Block File Generation Options
The Block File Generation Options control the conversion of a Forth source code text file into a Forth block file.
On many Propeller target boards the Forth block device storage is implemented in the unused portion of the EEPROM boot device. This normally limits the block storage to 32 KB to 48 KB for a normal 64 KB EEPROM device used on many Propeller chip boards. This limited code storage space can be maximized by packing the Forth source code and removing all comments from the source code. This allows you to type properly indented and commented Forth source code into the code editor and have ForthTerm generate a compact Forth block file to be loaded on the target Forth system. The Forth block file is generated when the Forth source code editor contents are saved or you switch from the Code Editor tab to the Block Manager tap in the terminal program.
The settings shown in the above image are my preferred settings for the generation of Forth block files.
ForthTerm terminal Key Mapping dialog.
When using terminal display in ForthTerm the special keyboard keys (Up, Down, Delete, Insert, F1-F11...) can be configured to send simple ASCII codes. This keyboard mapping can be used to control Forth programs that expect control characters for keyboard commands. As an example the Forth block editor uses control characters to implement editor functions such as; home to start of line, cursor movement, change insert mode and many others. By mapping the keyboard special keys to emit these codes the block editor is simpler to use.
ForthTerm Terminal Key Mapping Dialog
The Map Terminal Keys dialog shown above is configured for the Forth block editor.
To set a mapping for a special keyboard key:
- Select the desired Key State in the lower left group box, Ctrl, Shift or normal.
- Select the key you want to map from the list of special keys.
- In the Key Mapping String enter the ASCII string, control characters are prefixed by a "^" character.
- Press the Update button to set ASCII string to the selected special key.
- Repeat for all the keys you want to map.
When the ForthTerm starts up it will look for a keyboard mapping file named "default.kmap". If ForthTerm finds the file it will load the file as the current keyboard mappings. When the ForthTerm program is closed it will save the current keyboard mapping to the "default.kmap" file.
Using the Save button you can save a copy of the current keyboard mappings to a file of your choosing. The saved keyboard mapping files can be loaded as the current keyboard mappings using the Load button.
