- A 16-bit Forth on an 8-bit chip
- Contains over 200 words for everything from memory management to drawing pixels, decompilation, and even playing sounds over the I/O port.
- Support for writeback (persistent data across program runs). Use
SIMG(save image) andLIMG(load image) to save the words you've defined in a session. - Highly readable and customizable implementation, see
forth.asm.
Download the latest binary from the Releases page or get the bleeding edge output from the GitHub Actions CI.
- A TI-84+ calculator!
- TI Connect CE
- (Optional) A 2.5 mm to 3.5 mm audio cable to connect the I/O port with a speaker.
Flash forth.8xp to your calculator. Make sure there's enough space
and that you have backed up your calculator! An easy way to back up
RAM contents is by creating a group, refer to the manual on how to do
this.
This is a calculator that is more or less ubiquitous among high school and university students throughout the world. It's not going extinct anytime soon (except perhaps to newer models such as the TI-84 CE). But let's face it. TI-BASIC is not a nice language; it's slow and suffers from lack of low-level bindings. There's no REPL. We want a language that gives the programmer the full power of the calculator—treating it as the computer it is. In fact, people already do, by writing assembly programs, but assembly has its share of disadvantages.
Assembly is painful to program in. Programs crash at the slightest hint of error. Development is a slow process, and you have to keep reinventing the wheel with each program.
Wouldn't it be great to have a programming language on the TI-84+
that's much faster than TI-BASIC but easier to understand and as low
level as assembly? Forth is just that. (Read Starting FORTH for an
excellent introduction to Forth). It's low level, it's simple, but
also easy to type, especially when you're on a calculator with a
non-QWERTY keyboard. It is a very powerful language, allowing you to
do things like change the syntax of the language itself. IF,
WHILE, CONSTANT etc. statements are all implemented in Forth!
Think of it as an untyped C with a REPL and the power of Lisp macros.
It's also easy to implement incrementally through continuous testing. In fact, once the base REPL was implemented, most of the programming and testing happened on the calculator itself!
nix build- spasm-ng Z80 assembler
- If you're on a Mac, you will need to install
opensslas a dependency, for instance on Homebrew:
- If you're on a Mac, you will need to install
brew install openssl
cd /usr/local/include
ln -s ../opt/openssl/include/openssl .- Compile the assembler with
make(check required packages for your system).
Copy forth.asm into the cloned folder. Then run:
./spasm forth.asm forth.8xpThe implementation is regression-tested with headless TilEm and a TI-84 Plus
OS 2.55MP ROM. ROM images are copyrighted and are not included. To launch the
assembly payload correctly, load both FORTH.8xp and a BASIC wrapper whose
body is Asm(prgmFORTH); running the assembly variable as BASIC produces
ERR:SYNTAX.
Run the program with Asm(prgmFORTH), hit 2nd then ALPHA to enter
alpha lock mode, and now you can type the characters from A-Z. Here
are a couple of things to keep in mind.
- Left and right arrows are bound to character delete and space insert respectively.
- Hitting
CLEARclears the current input line. - Hitting
ENTERsends it to the interpreter, including while alpha mode or alpha lock is active. - Input lines contain at most 63 characters. Longer keypresses are ignored so the 64-byte buffer always remains NUL-terminated.
okis printed when the interpreter needs a new input line, not after every individual word on a line.
If you want to see the keymap, find key_table in forth.asm. KEY returns
the cooked TI OS _GetKey code; AKEY, GETS, and TO_ASCII use the table to
map supported codes to ASCII. KEYC is the nonblocking raw-scan-code interface
provided by _GetCSC and must not be passed to TO_ASCII.
See the 2nd or ALPHA key combos (in blue on the calculator) for
information on how to type the following characters: []{}"?:.
| Character | Key Sequence |
|---|---|
; |
2nd . |
! |
2nd PRGM |
@ |
2nd APPS |
= |
2nd MATH |
' |
2nd + |
< |
2nd X,T,Θ,n |
> |
2nd STAT |
\ |
2nd ÷ |
_ |
2nd VARS |
Type BYE and hit ENTER.
Use the provided fmake.py script to convert Forth source files to the TI-84+ executable format.
Run the script to generate the assembly file:
python3 fmake.py hello.fsTo also assemble it to a .8xp executable, add the --assemble flag:
python3 fmake.py hello.fs --assemblespasm must be on PATH for --assemble (the Nix development shell supplies
both Python and spasm-ng). spasm-ng intentionally exports these byte streams as
protected program variables; FBLK and LOAD accept both normal and protected
programs. TI names are limited to eight characters, so keep the source basename
to eight alphanumeric characters. The source variable must be in RAM; unarchive
it before loading because the current input stream does not page archived data
into the address space. Transfer the .8xp with TI Connect CE and run LOAD HELLO in the Forth REPL.
See programs/ for program samples, including practical ones.
See DOCUMENTATION.md for the supported interfaces and their
nonstandard details. WORDS prints the live dictionary on the calculator.
Commented-out experiments in forth.asm (including floating-point and MD5
code) are not available words.
Combine low-level memory words with drawing words and user input words
to create an arrow-key scrollable screen for viewing RAM memory. See
the 20 (or less) lines of code at programs/memview.fs.
Simple unfinished modal text editor with a scrollable screen.
Judicious use of macros has greatly improved the readability of the code. This was directly inspired by the jonesforth implementation (see Reading List).
One notable feature of this Forth is the use of a register to keep track of the top element in the stack.
| Z80 Register | Forth VM Register |
|---|---|
| DE | Instruction pointer (IP) |
| HL | Working register (W) |
| BC | Top of stack (TOS) |
| IX | Return stack pointer (RSP) |
| SP | Parameter stack pointer (PSP) |
- The OS copies the assembly payload to
userMem($9D95). The current build hasdata_start=$BA3Banddata_end=$BB9D, leaving$0463(1,123) bytes before$C000. That headroom is build-dependent and is not part of the persistent 350-byte reservation.$C000is the execution-protection boundary for the normal TI-84 Plus RAM mapping, not a claim that RAM ceases to exist. - The parameter stack uses the OS stack. The return stack uses 294 bytes at
$91DC..$9301, immediately belowplotSScreen; this is OS scratch workspace and is safe only while the assembly program owns the machine. SCR/HEREstarts atdata_start. Exactly 350 bytes are reserved for user dictionary data, followed by the two-byte savedLATESTand two-byte savedHEREfields. ConsequentlyWB,SIMG, andLIMGpersist 354 bytes—not 400. Dictionary-space exhaustion is not currently checked.ABSisappBackUpScreen($9872, 768 bytes),PLOTSSisplotSScreen($9340, 768 bytes), andUALTredirectsHEREtoappBackUpScreen. These regions are OS scratch buffers, not permanent storage.
The active OS calls are standard TI-83+/84+ bcalls: _GetKey, _GetCSC,
_PutC, _PutS, _NewLine, _ClrLCDFull, _ChkFindSym, _CreateProg, and
the writeback/variable routines. Their equates match the TI-84 Plus include
tables and were dynamically exercised on OS 2.55MP.
Documentation can vary from very well-documented to resorting to
having to read the source code of spasm-ng to figure out how
#macro worked. See examples such as defcode and defword. I
couldn't make defconst or defvar, however, but this was fixed by
writing it out manually.
- General Z80 guide
- Moving Forth
- Learn TI-83 Plus Assembly In 28 Days
- KnightOS Kernel
- Starting FORTH
- Jonesforth
- Ability to read/write programs
-
WBword to write back the 354-byte persistent data segment bytes of data starting from the address ofSCRATCH. - Ability to "execute" strings (so that programs can be interpreted).
-
- User input
- String reading routines
- Number reading routines (possible with
programs/number.fs)
- Output
- Displaying strings
- Proper support for compile/interpret mode
- Assembler to convert Forth words into
.dwdata segments to be pasted into the program. - Ability to switch to a "plot"
- REPL
- Basic Read/Eval/Print/Loop
- Allowing more than one word at a time input
- Respect hidden flag to avoid infinite looping. (
:makes the word hidden). - Reading unsigned decimal numbers modulo 16 bits
- Document Forth words (partially done)
- Add Z80 assembler in Forth (so ASM programs can be made!)
- Implement
DOES> - Implement
SIMG(save image) andLIMG(load image) to save and load sessions. - Add sound capabilities
- Add a way to put data on the screen as pixels (for export via screenshots).
- Add computer program to allow the user to select the words for a custom Forth system.
- Implement
extract.pyto extract and decode binary data from a PNG image, allowing analysis and debugging of the stored image data.
- Dictionary allocation has no bounds check. The reserved persistent scratch
area is 350 bytes and the current image has additional headroom before
$C000, but compiled threaded code must remain below the protected boundary. - Comparisons and division are unsigned.
WITHINincludes both endpoints, and+LOOPterminates on equality rather than standard boundary crossing. QUITresets the parameter stack and resumes the terminal; it does not unwind or validate arbitrary return-stack corruption.



