e4thcom - A Terminal for Embedded Forth Systems

Copyright (C) 2013 Manfred Mahlow Abstract e4thcom is a terminal program for embedded Forth Systems that supports conditional and unconditional uploading of source code. Uploading is controled by terminal directives that can be entered at the commend line or included in source code files. Forth on Embedded Systems Forths interactivity is an importand advantage on embedded systems. Any simple terminal program can be used to get in touch with the system and explore its structure and functionality. But - as soon as the first program is written and ready for testing - an easy way to upload the source code files is missing. A tool to overcome this deficiency is the e4thcom terminal program. The e4thcom Terminal e4thcom is a minimalistic terminal program for x86 Linux Systems. It sends terminal input without a local echo to the connected target (Forth System) and displays characters received from the target in the terminal window. This is the terminal-mode of the program. Entering the character # as the first one of a new line, activates the control-mode of the program. Terminal input is then not forwarded to the target system but catched until the enter key is pressed and then interpreted as terminal directive. Terminal Direktives Terminal directives temporarily change the operational mode of the terminal. Two directives are defined for uploading of source code files. They are modelled after the coressponding words include and require from the Forth Standard and named #include and #require. Both expect to get the name of a source code file as the only parameter: #include <file name> \ unconditional uploading #require <file name> \ conditional uploading Both directives can also be included in source code files - one directive per line, the rest of the line is silently discarded - so that a file can include additional code from other files. The file name lookup is done at the path cwd:cwd/target:cwd/lib. cwd is the directory, that was the active one (current working directory) at program start. The underlaying concept is, to store project-specific source code in the cwd directory, target-specific in cwd/target and target- and project-independent code in cwd/lib. When directives are entered at the terminal, the shortened forms #i and #r can be used. There may be defined more directives, depending on the addressed target system. Related information can be found in the help text for the particular target. Uploading of Source Code Source code files are red line by line and the text is interpreted as a terminal directive or uploaded to the target. After sending a character to the target, the terminal waits for the echo and displays it in the terminal window. The transmission is aborted with an error message, if no echo is received. At the end of a line, the terminal waits for the target to process that line and return an ok-message. If an ok is recieved, the next line is red from the source. Otherwise the transmisson is aborted with an error message. Pure comment lines - those that start with a \ char - are not uploaded but only displayed in the terminal window. When the end of a source code file is reached, the file is closed and control is given back to the calling level. Finally, when the last file is closed, the terminal mode is activated again. Conditional Uploading of Source Code The conditional uploading of source code was implemented with respect to the demands that all required information about loaded files have to be stored on the target, not on the terminal, and that as less as possible resources should be used for it:

• Before uploading a file, the terminal checks, whether a word, that equals the file name, already exists in the targets dictionary. The upload directive is ignored, if that is the case. Otherwise the file is uploaded.
• After uploading a file, the terminal again checks if now a word exists in the target dictionary, that equals the file name. If that is not the case, a NOOP-Word with that name is created in the target dictionary.

With this approach, the number of dictionary entries for file names can be minimized, by using - whenever adaquate - the name of a prominent word, defined in a file, as the name for that file. Starting e4thcom To start the e4thcom terminal program, open a terminal window in a project folder of your choice and enter the command /path/to/e4thcom [-i target [options]] The following options are supported: -i [amforth, mecrisp, 4e4th] the target system to connect to -b [B1200, B2400, B4800, B9600, B19200, B38400, B57600, B115200] the baudrate to be used -d [device] the serial device, e.g. ttyS0, ttyUSB0, ttyACM0 -h displays the terminals help text The default values for this options are defined in the program, and will be overwritten by those given on the command line. The connection to the target system is established during the program start. This may fail if the chosen device is not available or used by another process (e.g. by the modem manager). The program is then terminated with an error message. After fixing the cause of failure or waiting for the modem manager to give up, a successful start of the program should be possible. Babel ... The terminal program is split in an executable file, named e4thcom, and a number of target specific image files, named after the targets. The reason for this is, that all target systems have some peculiarities in their transmission protocols concerning returned messages. With a little help ... e4thcom does not have a command line history and does not support extended command line editing. It's intentionally designed minmalistic. But, in accordance with the UNIX Philosophie, one can combine it with a tool, that adds missing capabilities. Such a tool is the ForthBox. The ForthBox The ForthBox is a GTK+ GUI for Forth Interpreters and Forth Terminals. It is a virtual terminal emulator with some additional tools to make editing and uploading/execution of Forth source code files a bit more comfortable. A preferences dialog lets the user chose the client to be started in the terminal emulator, the project folder to be used, the (external) editor and the parameters for the serial link. To start the e4thcom terminal program in a ForthBox the following command must be used: /path/to/e4thcom -i forthbox The preferences dialog pops up immediately after the program start. After chosing the required options and pressing the OK-Button e4thcom is started in the ForthBox terminal window. If the e4thcom client aborts with an error message, consider the hints given earlier concerning the possible reasons and try again. It's the first time, that the ForthBox is given to the public and documentation is still missing. So some hints are given here:

• The toolbar allows the user to choose a file for editing or uploading by means of the Edit- resp. the Execute-Button.
• On the left side of this two buttons there is a Menu-Button, that gives access to the global list of recently used files, which is managed by the OS. All files recently chosen for editing are also listed hier.
• A file, chosen for editing, is forwarded to the external editor, that was chosen in the preferences dialog.
• With the first entry in the recent files menu of the Execute-Button, the terminal client (in this case e4thcom) can be restartet if required.
• A separate command line with text selection and text completion can be activated underneath the terminal window by clicking on the check-button in the lower right corner of the ForthBox window.

What's left to do : Adding device locking to prevent concurrent device access from different processes. If another process uses the same device as the e4thcom terminal, it may snap away received chars so that the communication with the target will not work properly. The problem here seems to be, that not all programs, that use serial devices, use device locking or do it in the same way. Annotation: e4thcom comes with ABSOLUTELY NO WARRANTY. It is free software under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or any later version, see http://www.gnu.org/licenses . e4thcom was implemented with MINFORTH Plus, a MINFORTH derivative, and was tested with the following target systems: Arduino Duemilanive : amforth 4.9 and 5.1 TI MSP430 Launchpad : mecrisp 1.0, 4e4th 0.34 Questions,error notes and suggestions for improvements or additional targets are welcome and should be forwarded to the following e-mail address: manfred.mahlow@forth-ev.de . Thanks to Andreas Knochenhauer for creating MINFORTH, which was a great platform to create my Forth development environment MINFORTH Plus. Last Revision: MM-131201