Beginner Advice¶
Some tips from my own Forth Journey that may be of assistance if you are just starting yours. This list constitutes the things that can save you MONTHS of time and serious angst if you sort them out FIRST, before actually doing any embedded Forth.
They can give you a smooth, fun and highly productive Forth development system to rival anything else today.
Note
Updated 21 August 2022
Realise All Forths Are Different¶
Forth by it’s very nature abhors sameness and cries out to be different. Forth’s creator Charles More believed that “standards” reduced Forth’s ability to solve problems.
The Forth taught in the most famous Forth book of all, “Starting Forth” by Leo Brody has major differences to Mecrisp-Sellaris and others. Many examples won’t work.
This in a way is part of the Forth learning cycle, the “hard yards” a beginner must walk.
If an example from a Forth article won’t work for you, don’t immediately assume that you are at fault, look deeper into why, pop onto the IRC channel or Forum and discuss it. No one will criticise you, we have all been there before.
Source Errors¶
Your source code is uploaded to the Forth Cortex-M MCU with a serial terminal usually hosted on a PC.
The speed of the serial data is 115200 BPS by default and so the data scrolls up the screen quite quickly. By default errors in the source just flow past quietly, no alarm, no colours, no halting of the scrolling and a beginner will probably miss them. All of Forth will be unfamiliar territory to the beginner at that stage so fleeting errors probably won’t catch your eye like they didn’t catch mine.
This leads to much confusion as you are at that stage when you don’t know Forth well enough to have confidence in your skillset.
Unhandled Interrupt 00000003 !¶
By default the first indication there has been a error is that the program fails to work, or even worse, the dreaded Unhandled Interrupt 00000003 ! message scrolls endlessly which pushes your original error message off the end of your terminal buffer so you can’t scroll back to find it after you reset the MCU. This was very frustrating for me, but it’s easily fixed, see Unhandled Interrupt 00000003 !
Automatic Error Detection¶
It may not be the “Unhandled Interrupt 00000003 !”, it may just be a typo now scrolled off the screen … soundlessly. Your program doesn’t work and you have no idea why.
What you need to do, right from the start is make sure that all source errors are LOUD AND CLEAR!.
1) Use a Terminal With Error Detection¶
Zeptocomjs¶
If you have Chrome Browser, you can run Zeptocomjs live from this link on your browser right now!
Written by Travis Bemann, this terminal will run in a browser (see list below), providing selectable baud rates, flow control, error alerts and more. This is the easiest choice of all.
Forth Support¶
Is a web Forth serial terminal, which currently supports:
zeptoforth
Mecrisp-Stellaris
STM8 eForth
ESP32Forth.
On all of the supported platforms it makes use of handshaking to control mass uploads of data. It also provides the option to select the newline format used by the terminal, which defaults to CRLF on zeptoforth and ESP32Forth and to LF on Mecrisp and STM8 eForth.
Can edit and append code for upload, either as wholes or (when selected) as parts to the target. It supports multipel tabs, so one can have multiple edit areas at once; note that the edit area related functionality always applies to the current edit area. It also supports expanding any #include lines in an edit area within the edit area itself.
Can strip any uploaded data to the target of initial whitespace, blank lines, and line comments to speed up upload. Note that it does not strip ( or ) comments or \ comments after any non-whitespace content due to the complexities of mixing such with strings, where such should not be stripped out.
Can #include content that is uploaded by any means, whether from the REPL line, from a file, from an edit area, or from another included file. This also applies when expanding content within an edit area. Note that the path of an included file will be relative to the current working directory, and if none is set the user will be prompted to select one.
Can automatically replace symbols in uploaded content and content expanded within an edit area. Symbol files, which are specified either via the global symbol file or via #symbols lines within uploaded or expanded content.
Tested Fully Working on ?¶
Chromium on Debian GNU/Linux bookworm/sid
Chrome and Edge on Microsoft Windows 10
Please let me know if you have Zeptocomjs fully working on other OS’s and versions ? email me as below:
E4thcom¶
Manfred Mahlow’s e4thCOM terminal. e4thCOM is written in Forth and distributed as a executable with no dependencies, just some minor configuration for the Forth you are using. Errors will stop the uploads, there will be colour and learning Forth will be fun, but it ONLY runs on Linux.
If you use Windows and TerrorTerm, then I feel sorry for you, because you will understandably hate Mecrisp-Stellaris. Get Linux, embrace the inevitable!
Advanced¶
For the advanced STM32 user there is SWDCOM which uses the SWD channel, not a USART, making it incredibly fast and mcu clock free. There is flow control but no source-code error detection. Runs on all the Unixes, Linux, FreeBSD, OpenBSD etc,
2) Select the COLOR option * Advanced¶
Mecrisp-Stellaris has BUILD OPTIONS, one of which will color any errors in red and warnings in orange.
This involves adding the line below in mecrisp-stellaris-<your-mcu>.s and recompiling the kernel.
@ -----------------------------------------------------------------------------
@ Swiches for capabilities of this chip
@ -----------------------------------------------------------------------------
.equ color, 1
After you have done this, recompiled and have Mecrisp-Stellaris running again, enter
;
and you should get a red error like below. After that errors will be much easier to spot if you have a terminal which lacks that facility, such as SWDCOM.
Lockups¶
Problem: You’ve just flashed Mecrisp-Stellaris Forth onto a board or chip and your terminal shows the boot up Greetings message, so youre all good to go!
When you hit the “Enter” key a “OK” response is received. However when you upload Forth source code, the terminal locks up after the first few Words requiring the MCU be reset to recover … what’s wrong ??
Answer¶
The Forth MCU has a compiler inside, and when you enter or upload any source ‘Definitions’ (Words) they are compiled, one after the other.
Now the MCU needs time to compile the Definitions and if new Definitions are uploaded while the chip is still compiling the previous Definition it will appear to ‘lock up’. This is a “Flow Control” issue.
Note
Mecrisp-Stellaris won’t generally ‘lock up’ without giving a error message, of course if you were to write code that disabled the USART, or turned of the CLOCK etc, it may appear that Mecrisp has locked up but this is entirely different to the “Flow Control” problem described above.
This is a Flow Control problem and needs either software or hardware flow control. The terminals above will all solve this problem.
See also
Classic Beginner Mistake¶
The “blinky’ program loaded fine, no errors, but the LEDS aren’t blinking, what is wrong ???
A: you haven’t RUN the program yet, enter “blinky” and hit the carriage return …
Why won’t my programs work ?¶
Lots of forth programs may not work for you, even Mecrisp-Stellaris programs but don’t be disheartened, there are many reasons and they can all be fixed.
Definitions¶
Missing Definitions¶
The program will be expecting certain Words that are not in your Dictionary, they are dependencies and should have been put there already. Manfred Mahlow’s e4thCOM terminal can fix this problem also.
Wrong Definitions¶
The definition may have the wrong information, be for another type of chip, variations are many, fix them one at a time.
Stack problems¶
Leaving data on the Stack is a major issue for beginners and cause all kind of weird problems, including the dreaded ‘Unhandled Interrupt 00000003 !’.
Watch your Stack constantly with “.s”, check it after every Word. Make sure that if nothing is supposed to be left on the Stack, that nothing is.
Now you can have a COLOURED PROMPT to show a non empty stack!
Long Words¶
We all write Words that are way too long when we start learning Forth because :
If we came from other programming languages then long programs are common and not a problem.
We erroneously believe that more Words uses more memory and is less efficient. It isn’t. Forth is designed to use lots of short Words for many good reasons. Aim for three short lines of code per Word.
Writing short Words is HARD, it takes Zen Forth Master status! It’s easy to write a 50 line Word, but not so easy to debug or understand it however.
Practice makes perfect, just keep writing Forth code!
