This article provides general information on using the current release of MV4th16 Forth for the Parallax Propeller chip. To get started you will require a Parallax Propeller target device such as a Parallax "Proto Board" or a "Proto Board USB" or equivalent. The MV4th16 demo can be configured to use a 64K or 128K I2C eeprom or an SD card as the block device. The console device is implemented as a two wire async serial port using the same pins as the Prop Plug.
Starting Up MV4th16:
The first step is to download the newest version of MV4th16 from the site MV4th16 downloads section Link to MV4th16 Downloads and build the project using the Parallax Spin IDE. Once the MV4th16Demo.spin top object compiles, program the code into the Target Propeller Chip device. The web site article Configure MV4th16 version 0,94 and Higher contains information required to configure and install the most recent version of MV4th16 on your target Propeller Chip device.
I have created a simple serial terminal program called ForthTerm which I would recommend for this project. ForthTerm can also be used to upload and edit forth block files which we will be needed later in this article. I will be using ForthTerm for the examples in this article. You can download the newest version of ForthTerm Terminal program from the ForthTerm downloads section of the site.. See the web site article Configure ForthTerm Terminal for information on using ForthTerm with MV4th16 Forth.
To begin testing the MV4th16 Forth you will need a simple serial terminal program. If you have Hyper Terminal that will do if not , you could use the free "Parallax Serial Terminal" program. If you use the Parallax serial terminal you will need to disable the processing of line feed characters in the "Prefs/Function" tab. Forth sends a CR/LF control character sequence to mark the end of a text line. The Parallax serial terminal treats a single CR control character as a new line character if you do not disable the line feed control character text lines displayed by Forth code will be double line spaced.
What ever terminal program you are using set the terminal port settings to; 115200 baud, 8 data bits, 1 stop bit, no parity, and no hardware flow control. The serial port on your computer will be the same one used by the "Prop Plug" or "Proto Board USB". The image below shows the terminal port settings for ForthTerm.
With the terminal program running and the communication port active reset the target Propeller device, after a couple of seconds the Forth interpreter will start up and display a sign on message followed by "OK". In the Parallax terminal program you can reset the target device by holding down the Ctrl key and clicking on the DTR label displayed on the lower panel. In ForthTerm click the "Pulse DTR" button to reset the target device. The images below show the two possible sign on messages displayed by MV4th16 Forth.
The sign-on screen for an 64K I2C eeprom storage device:
The sign-on screen for an SD card storage device:
If you see one of the sign on messages, congratulations MV4th16 is ready to accept input. For now answer "N" to the prompt.
Since Forth is both a compiler and an interpreter we can enter Forth code directly at the console.
Type the following line and then press the enter key (there is a space between all four characters);
1 2 + .
Forth will respond on the same line with
3 OK
It is beyond the scope of this guide to provide a beginners guide to forth, check the MV4th16 document articles on the site and related links for general forth information.
Forth Code Development:
The interactive nature of Forth is ideal when testing and debugging your code however, it is less then ideal for the development of programs made up of many lines of Forth source code. Under MV4th16 there are two primary methods of code entry; the first method is to enter Forth source into a text editor then copy the text to the Windows clipboard and paste the text to the terminal, the second method involves entering your Forth source into a Forth block file and uploading the block file to the MV4th16 block device. We will look at the text paste method first and later in this guide we will look at using block files.
Entering Forth Code At The Console:
When MV4th16 is active the Forth interpreter reads from the console device until an end of line character (CR, 13) is read or the terminal input buffer is filled. The Forth interpreter will then process the line of text read from the console. In the case of MV4th16 the terminal input buffer is 160 characters in length. This means no single line of text can be over 160 characters in length when entered at the Forth console. Also special care must be taken to assure that any Forth words that expects a name parameter to follow the word is on the same text line as the required name parameter.
The MV4th16 demo uses a simple two wire serial console which affords no form of flow control. The lack of hardware flow control combined with the fact that the Forth interpreter takes a variable amount of time to process each token read from the current console text line can lead to the serial port overflowing. To solve this problem we must use a terminal program that can add a delay after each line of text is sent to the Forth console. From experience this inter-line delay needs to be @ 100 miili-seconds when MV4th16 is run on an 80MHz Propeller chip. If the MV4th16 demo was modified to use a four wire serial port no line delay would be required. Under ForthTerm this inter-line delay is set in the terminal options dialog shown below.
The paste line delay is set to 100ms in the terminal options. Notice that ForthTerm has an option to abort the pasting of text if an error is reported by the Forth Interpreter this should also be checked. We will now go thru the steps required to paste Forth code to MV4th16. The Forth code below calculates the sum of two squared numbers.
: SQUARED DUP * ;
: SUM-OF-SQUARES
SQUARED
SWAP
SQUARED
+ ;
Enter the above forth code into a text editor and then copy it to the Windows clipboard. With your terminal program connected to the target Board paste the windows clipboard to the terminal. MV4th16 should respond with "OK" after each compiled phrase is parsed.
If the test worked type;
2 3 SUM-OF-SQUARES .
then press enter, MV4th16 should respond with;
13 OK
This method of pasting code from the terminal is useful during code development but not of much use in running a Forth program unless you want to connect the MV4th16 system to your computer every time you want to start a forth program. Once you have working Forth source code it is time to use a block file to upload the Forth code to the system block device so it can be loaded by the Forth system when needed.
Entering Forth Code Using Blocks:
Forth supports the idea of a block device. In Forth a block is always 1K bytes (1024) in size. Forth contains words to read and write blocks on a block device. Blocks are referenced by there index number and can be both read and written in a random access manner. The block number index is zero based where the largest possible block number is the number of blocks on the device minus one. In Forth block devices can be used to store any data the Forth program requires. One use of block storage is to hold Forth program code in text form. When a block device is used to hold Forth source code the format for the block data is defined in the Forth standard. In this case the block is treated as a single line of 1024 characters. The block text is made up of only printable ASCII characters, control characters are not allowed. If the text in the block is less then 1024 bytes the remainder of the block is padded with space characters. See the ANS 93 draft Forth standard for more information of the Forth block extension words and there use.
NOTE: For more up to date information on using the Forth block device see the web site article Using the Forth Block Device.
While the ANS Forth standard includes words to compile and display Forth source code stored on a block device there are no Forth words to edit or upload source code to the block device. To solve this problem I created a very simple protocol to upload block data from a host system to the target MV4th16 Forth system. The current version of the Forth block upload source code can be found in the text file "UploadBlock.txt". This file can be found in the folder "forth" included in the MV4th16 demo download. The main dictionary word in this code is "load-blocks". This Forth word requires two parameters on the data stack; first block index and last block index. The upload block data source must be uploaded to the MV4th16 system by entering the source code via the Forth console as described in the prior section of this guide.
When the "load-blocks" Forth word is executed it will display a simple single character prompt, ">" followed by a carriage return to indicate it is ready to receive the next piece of block data to store in the current block. Data is sent sixty four bytes at a time, the data is encoded into a data packet which begins with a colon ":" character followed by sixty four, two character hexadecimal digits per data bye. There are no space allowed between the hex digits. The data packet is terminated by a sixteen bit check-sum sent as a four character hex number. The check-sum is created by adding the byte values of each of the sixty four data bytes that makeup the data packed. The end of the packet is terminated by a single "<" character followed by a carriage return character. The data packet upload sequence is repeated untill all data has been sent to the MV4th16 system. Note that block data uploads must send sixteen data packets per block. If the upload data does not fill the entire last block the protocol requires that the upload host pad the last block by sending enough data packets to fill the last block. When the data being uploaded contains Forth source code the padding should be done withspace characters. After the last data packet is sent the MV4th16 system will respond with "OK" instead of the send next packet prompt.. If an error occurs during the upload the Forth system will respond with a line of text that ends in a question mark "?" character.
To ease the task of uploading and creating block files I have added support for block files to ForthTerm. ForthTerm is also able to read Forth source code from a simple text file and generate a block file. Using the ForthTerm upload feature both Forth block files and COG binary files can be uploaded to the MV4th16 block storage. COG binary files saved to the block device allow MV4th16 to start up Propeller COGs running COG assembler code.
To upload a Forth block file using ForthTerm make sure the MV4th16 system is running ten select the "Upload Block File" command in the communications menu. A standard file open dialog will be shown. Navigate to the location of the MV4th16 project files then into the forth folder and select the "TOOLS.blk" file to upload.
ForthTerm will check to see if the UploadBlock.txt source file has been loaded by MV4th16 by checking for the word "load-blocks" in the Forth dictionary. If the upload words are not on the MV4th16 system you will see the following dialog appear on the ForthTerm program;
If you click the OK button ForthTerm will attempt to transfer the UploadBlock.txt file to the MV4th16 console. 
If you get an error close the dialog and try again. It should take a few seconds to transfer the source code to the Forth console and for Forth to compile the source code. Once the upload source code is accepted by MV4th16 or the required Forth word is found in the dictionary the following block upload dialog will be displayed by ForthTerm;
Before pressing the Upload button we need to make sure are settings are correct. The "Pad Block" setting is used to select if a partially filled last block should be padded with space characters or null (0) characters. If you are uploading a Forth block file make sure this setting is set to pad with space characters. The "First Block" setting should be set to the first block index to upload to. In ANS Forth the block index 9 can not be used to hold Forth source code. Block index 0 is reserved for system comments, The first block setting can not be set to a starting block index greater then will allow the entire upload to fit. When the settings are correct click the "Upload" button to start the transfer. If all goes well with the block upload the Transfer Blocks dialog will close. If the transfer failed an error dialog will appear.
If the transfer worked the source code for the tools word set should now occupy blocks 1 through 5. To load the tools word set type the following command at the forth console;
1 5 THRU. then press the enter key.
It will take about five seconds for MV4th16 to read each of the blocks and compile the new words into the dictionary. To test that the words have been compiled type the following command in MV4th16;
0 128 DUMP then press enter.
MV4th16 should display a HEX/ASCII dump starting a global memory location 0 and display 128 bytes of memory.
Over the next few weeks I hope to add a number of examples on using MV4th16 to this site.
