A serial terminal for Forth targets (built against Mecrisp-Stellaris). It works like tio, plus:
- uploads that send line by line and wait for the target's
ok.before the next line, stopping at the first error withfile:line #include/#requireresolved on the host- macros and config written in Forth, running on the host
- a control socket so neovim or another tmux pane can push files into the open session
nix run . # or: just run
fterm -p /dev/ttyACM0 -b 115200
fterm send dcf77.fs # through the running session, or directly if none runs
fterm eval 'flash' # run host Forth in the running sessionfterm send exits non-zero on error and prints file:line: message to stderr, so it works as a neovim makeprg:
set makeprg=fterm\ send\ %
set errorformat=%f:%l:\ %m# flake inputs
fterm.url = "https://github.com/slaxor/fterm.git";
# home configuration
imports = [ inputs.fterm.homeManagerModules.default ];
programs.fterm = {
enable = true;
init = ''
2 timestamps
: reboot s" reset" run 2000 delay ;
' reboot bind F6
'';
};init is written to ~/.config/fterm/init.fs. It is used when there's no project .fterm.fs, or when a project config says include-global. The package is built against your own pkgs, and overlays.default provides pkgs.fterm. For the serial port your user needs to be in the dialout group (users.users.<you>.extraGroups on NixOS).
Lines are edited locally, readline style, and sent with Enter:
| Key | Action |
|---|---|
up/down, ctrl-p/ctrl-n |
history |
ctrl-r |
reverse history search (ctrl-r again for older, Enter runs, Esc cancels) |
ctrl-a/ctrl-e, home/end |
line start / end |
ctrl-b/ctrl-f, left/right |
char back / forward |
alt-b/alt-f, ctrl-left/ctrl-right |
word back / forward |
ctrl-w, ctrl-u, ctrl-k, ctrl-y |
kill word / to start / to end, yank |
ctrl-c |
discard the line |
After Enter, keys go raw to the target until it prompts with ok. (or reports an error), so words that loop until a keypress (log, decode) keep working. History is shared by target lines, # directives and host Forth. It is saved to $XDG_STATE_HOME/fterm/history (~/.local/state/fterm/history), or to the file you give history in .fterm.fs.
| Key | Action |
|---|---|
ctrl-t q |
quit |
ctrl-t : |
host Forth prompt |
ctrl-t u |
upload a file (prompt); Tab there opens the file picker |
ctrl-t r |
repeat last upload |
ctrl-t e |
edit the last error location (or last upload) |
ctrl-t c |
forget the #require list (after a target reset) |
ctrl-t l |
toggle raw passthrough (no local editing) |
ctrl-t h |
help |
ctrl-t ctrl-t |
send a literal ctrl-t |
ctrl-t <c>, F1..F12 |
macros bound with bind |
ctrl-c, Esc |
abort a running upload or macro; while the target runs a line they are forwarded, and if no ok. follows within 0.5 s you get the line editor back |
A single-line paste goes into the line editor. A multi-line paste goes through the upload path, with flow control.
Lines starting with # are handled by fterm itself:
| Directive | Action |
|---|---|
#i file, #include file |
upload |
#r file, #require file |
upload once per session |
#e [file] |
$VISUAL/$EDITOR (fallback nvim) at +LINE; with no argument it opens the last error |
#f forth |
run host Forth |
Tab after #i, #r or #e opens the file picker and fills in the argument.
A full-screen list of the Forth sources (.fs .fth .4th .f .forth) below the working directory and the path directories, skipping hidden dirs, target/ and result. Typing filters fuzzily (word starts and consecutive letters rank first), up/down/Tab/ctrl-n/ctrl-p move, PgUp/PgDn page, ctrl-u clears, Enter chooses and Esc cancels. Terminals at least 100 columns wide get a preview of the selected file. From the upload prompt the choice is uploaded right away and recorded in history as #i file. Target output that arrives while the picker is open is held back and shown when it closes.
Any other # line (#s, # 42) goes to the target unchanged.
The same #include / #require lines work inside uploaded files. They are resolved relative to the including file, then the path directories.
fterm loads the file given with -c, or else the nearest .fterm.fs found upwards from the working directory. Only if there is none does it load ~/.config/fterm/init.fs ($XDG_CONFIG_HOME). A project config pulls the global one in with include-global, usually as its first line. Relative paths in it resolve against its directory. See example.fterm.fs.
Host words on top of a small core Forth (stack, arithmetic, if else then, begin until/again/while repeat, do loop i j, variable constant create , @ !, s" ." ' execute recurse, words see list):
| Word | Stack | |
|---|---|---|
port |
( a u -- ) |
serial device |
baud |
( n -- ) |
|
timeout |
( ms -- ) |
per-line prompt timeout, default 3000 |
eol |
( c -- ) |
13 CR (default), 10 LF, 0 CRLF |
prompt |
( a u -- ) |
success suffix, default ok. |
error / no-errors |
( a u -- ) / ( -- ) |
add an error pattern / clear the defaults |
path |
( a u -- ) |
add an include search directory |
history |
( a u -- ) |
history file, relative to the config; empty string: none |
send |
( a u -- ) |
send a line, wait for ok., throw on error |
run |
( a u -- ) |
send a line, don't wait (for words that loop) |
raw |
( a u -- ) |
send bytes as they are |
dtr / rts |
( f -- ) |
set a modem line, e.g. a hard reset if RUN is wired to DTR: : kill 0 dtr 100 delay -1 dtr ; |
upload |
( a u -- ) |
upload a file |
upload? |
( a u -- ) |
upload a file if it exists, otherwise do nothing |
exists |
( a u -- f ) |
true if the file exists (working dir, then config dir) |
expect |
( a u ms -- f ) |
wait for text in the output (includes the reply to the last send) |
delay |
( ms -- ) |
wait, showing output |
bind |
( xt "key" -- ) |
' w bind F5, ' w bind p (ctrl-t p) |
include |
( "file" -- ) |
load more host Forth (~/ expands) |
included |
( a u -- ) |
same, taking a string |
include-global |
( -- ) |
load ~/.config/fterm/init.fs, if it exists |
forget-required |
( -- ) |
clear the #require list |
see |
( "name" -- ) |
decompile a host word |
list |
( "name" -- ) |
show a colon definition's source with file:line |
bye |
( -- ) |
quit |
If you define on-connect, it runs after every (re)connect, e.g. : on-connect s" autoexec.fs" upload? ;.
Default error patterns (Mecrisp-Stellaris): not found., Stack underflow, Stack not balanced, Structures don't match, Jump too far.
lib/: core library and public API (source preprocessing, line protocol, host Forth, session, control socket)cli/: thin binary that only useslib's public API
nix developjust build
just test
just lint
just doc # cargo doc --openGPLv3, see LICENSE.