Tera Term macro for Forth

A macro that paces uploads by waiting for ‘ok.’ at the end of each line, before continuing.

When uploading files to Forth running on a microcontroller (Mecrisp is a good choice for the MSP430 chips), the characters can’t just be spurted out at a constant, say, 115200 baud – the Forth compiler can’t keep up, so its input buffer fills and characters are lost, causing errors.

The traditional solution, with Tera Term, was to specify inter-character delays (not usually needed) or end of line delays. Determining the necessary end of line delay is an empirical process – upload a complicated-to-compile file, and adjust the delay to be as low as possible without causing any errors. Problem is, you have to set the delay high enough for the worst case, maybe 200mS, and then it slows down the whole upload, even though 99% of the time, the Forth compiler can easily keep up.

Forths generally echo back ‘ok.’ after they compile each line, so by waiting for that after each line (and possibly some other error messages or timeouts) there’s no need for any delays, and the upload happens as fast as possible.

Tera Term has a macro language – you create files with the extension .ttl (for Tera Term Language), and put them in the same folder as the Tera Term executable. I wrote one named upload.ttl. You can call macros from the menu, but you can also assign a key (such as Ctrl+u) to invoke the upload macro. You specify the key to use by editing KEYBOARD.CNF, which is another file in Tera Term’s executable directory.

Here’s the file, upload.ttl

filenamebox 'Select file to upload'
if result=0 goto end
fileopen fhandle inputstr 0
timeout = 1

:loop
filereadln fhandle line
if result goto fclose
sendln line
wait 'not found.' 'ok.'
if result=0 goto timedout
if result=1 goto fclose
goto loop

:timedout
messagebox 'Upload aborted' 'Timed out'
:fclose
fileclose fhandle
:end

Here’s the addition to put at the end of your KEYBOARD.CNF file

[User keys]
; Ctrl + u key: upload a Forth file (wait for 'ok.' after each line)
User1=1046,2,upload.ttl

When you press Ctrl + u, a file requester pops up allowing you to select the Forth file, e.g. myfile.fth, to ‘include’. Tera Term remembers the folder you selected your Forth file from, even between sessions.

There are better alternatives to Tera Term for this job (e.g. Escom, which is a Windows port of the excellent Linux E4thcom), but some Windows users love Tera Term, which is a great terminal program for many other tasks besides just interacting with a Forth microcontroller.