Copyright (C) 2013-2015 Manfred Mahlow
The latest release is e4thcom 0.5.3, with the following improvements:
md5sum: 559cc0a5112eee79c3b83bafa0388f7b e4thcom-0.5.3.tar.gz
The program description on this page is deprecated. You will find an updated one in the doc-directory in the e4thcom-0.5.3.tar.gz archive file.
e4thcom is a terminal program for embedded Forth Systems that supports conditional and unconditional uploading of source code. It runs on 32 Bit Linux Systems, X86 and Raspberry/Raspbian. The latest version e4thcom 0.4.4, released in January 2015, comes with a number of modifications and extensions:
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.
e4thcom is a minimalistic terminal program for 32 Bit Linux Systems (X86 and Raspberry Pi/Raspbian). 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 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/mcu: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-forth-specific in cwd/target, hardware-specific in cwd/mcu and target-, mcu- 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.
Source code files are read 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 read 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.
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 adequate - the name of a prominent word, defined in a file, as the name for that file.
e4thcom is distributed as a tar.gz archive. For testing or as a user without admin rights unpack the archive in a directory of your choise, e.g. in your home directory or on the desktop. You will then find the e4thcom binary and related files in a new directory named e4thcom-xyz. The e4thcom binary in this directory is the one for X86 Linux Systems.
When installing e4thcom on a Raspberry Pi with Raspbian OS please copy the binary from the Raspbian subdirectory to the e4thcom directory.
As an admin you can make e4thcom available to all system users by unpacking the archive to the
/opt directory, changing owner and group with
chown -R root:root /opt/e4thcom-xyz and creating links named e4thcom and forthbox in
/usr/local/bin to the coresponding files in the
To start the e4thcom terminal program, open a terminal window in a (project) folder of your choice and enter the command
The following options are supported:
|-t [4e4th, amforth, mecrisp, noforth]||the target system to connect to (option changed)|
|–xas||enables the cross assembler (new)|
|-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 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.
Fig. 1: e4thcom -t noforth -d ttyACM0 –xas in a terminal
All target systems have some peculiarities in their transmission protocol concerning the messages returned after processing a line of uploaded code.
Up to version 0.3.4 e4thcom was split in an executable file and a number of target specific image files, named after the targets. Starting with version 0.4 there is only one image file for all targets. The target specific code was factored out and is now loaded as a plug-in at program start.
The target specific plug-in files are small Forth Source Code Files so that support for other targets can be easily added by experienced Forth Users.
Starting with version 0.4 e4thcom comes with a cross assembler interface. A target specific cross assembler, written in Forth, can be included by the target specific plugin at program start. e4thcom must be called with the
–xas option to enable the assembler interface. Using the cross assembler requires that the words
end-code are defined in the targets dictionary. Both do not need to have any e4thcom related properties.
e4thcom 0.4.4 comes with a MSP430 cross assembler for noForth that is based on the file aux430ass.f from noForth1210.
When a cross assembler is loaded and enabled, the words
\xas are interpreted as terminal directives (in source code files only, not when entered at the terminal command line).
A line of source code, that starts with
\xas is not uploaded to the target but interpreted by the cross assembler (the terminals internal Forth interpreter). This can be used to extend the cross assembler, e.g.
to define short macros or identifiers for MCU resources
\xas 021 equ P1OUT 01 equ BIT0
or to load identifiers with MCU:name from a file name.efr
\xas MCU: MSP430G2553
The search order to find name.efr is project-dir:e4thcom-dir.
A line of source code starting with the phrase
code name enables the terminals cross assembler mode. The phrase “code name” is then forwarded to the target to create a header in its dictionary and the following source code up to
end-code is then assembled into a buffer in the terminals memory.
end-code disables the cross assembler mode, comma-compiles the assembled code into the targets memory and is then send to the target to close the code definition.
code led1.on ( -- ) BIT0 # P1OUT & .b bis next end-code
The terminals number base in the cross assembler mode is hex. Its Forth interpreter is case sensitive. So is the cross assembler. I prefere lower case for operators and upper case for register and bit identifiers.
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 Philosophy, one can combine it with a tool, that adds missing capabilities. Such a tool is 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.
Fig. 2 : The ForthBox Preferences Dialog
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 baudrate for the serial link.
To start the e4thcom terminal program in a ForthBox one of the following commands can be used:
/path/to/e4thcom/e4thcom -i forthbox
The preferences dialog pops up immediately after 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.
Fig. 3 : e4thcom -t noforth –xas in a ForthBox
The ForthBox has not yet been released on its own and documentation is still missing. So some hints are given here:
When starting the ForthBox on the Raspberry you may see a number of GLib warnings. Ignore it. The ForthBox works as expected. (The same phenomenon occures with other Gtk applications.)
When connecting to the Raspberry via ssh -X and starting the ForthBox for the first time it may fail with an error message from the X-server. Reset the terminal with
reset [Enter] and try again. You will then succeed.
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.
Adding more targets and cross assemblers.
You can do it yourself and/or contribute. The new plug-in structure should make it easy. The plug-in files and the cross assembler file that come with this release should be useful examples.
e4thcom comes with ABSOLUTELY NO WARRANTY. Thats also true for the ForthBox. 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 Duemilanove : amforth 5.1 //Test results for newer versions are welcome.//
TI MSP430 Launchpad : 4e4th 0.34, mecrisp 1.1, noForth V&C 141218
Questions, error notes and suggestions for improvements or additional targets are welcome and should be forwarded to email@example.com.
Thanks to Andreas Knochenhauer for creating MINFORTH, which was a great platform to create my Forth Environment MINFORTH Plus.
Thanks to Albert Nijhof and Willem Ouwerkerk for supporting me to make e4thcom ready for noForth and for agreeing that the noForth cross assembler could be adapted to and can be distributed with e4thcom.